One key. Every endpoint.
Generate in Telegram. Valid until you revoke it.
THE TRUSTEDTOOLS API
Your store.
Powered by our API.
Bring premium digital products to your customers. Connect your bot, use your existing wallet and deliver orders through one simple integration.
BASE URL
https://bot.csvplanet.com/reseller/v1Your main wallet.
Fund once. API orders use the same balance.
Built for your bot.
Products, purchases and delivery in one API.
01 / GET CONNECTED
From API key to your first order.
- Open Reseller API in the Telegram bot and generate your key.
- Add funds to your main wallet. Your API account activates automatically.
- Keep the key on your server and send it in the
Authorization: Bearer YOUR_API_KEYheader. - Fetch products, place an order and retrieve delivery through the endpoints below.
Keys stay valid until revoked. Use a stable idempotency key for every order, and keep the same key when retrying.
Requests
API base URL: https://bot.csvplanet.com/reseller/v1
This is a public documentation page. Purchases run on the VPS API, not this static host. Create your key in the Telegram bot and keep it on your server.
Use the API address below, even when this documentation is hosted on another website. These examples are safe reads:
curl https://bot.csvplanet.com/reseller/v1/me \ -H "Authorization: Bearer $TRUSTEDTOOLS_API_KEY" curl https://bot.csvplanet.com/reseller/v1/wallet \ -H "Authorization: Bearer $TRUSTEDTOOLS_API_KEY" curl 'https://bot.csvplanet.com/reseller/v1/products?after=0' \ -H "Authorization: Bearer $TRUSTEDTOOLS_API_KEY"
GET /me returns your API account, status and permitted read scopes. GET /wallet returns spendable balance_minor, settled posted_minor and reserved_minor. All amounts are USD cents: 350 means $3.50. Reservations reduce spendable balance without charging it.
GET /products returns up to 50 explicitly published, visible and active products. Pass the returned next_cursor as after on the next request. An empty cursor ends pagination. Changes during traversal can alter results; periodically refresh the complete catalog. Descriptions are untrusted plain text. Prices and stock are informational snapshots. stock_observed_at is when the API observed local stock, not proof of a fresh upstream supplier sync. can_purchase and availability_reason reflect purchasing controls and availability; acceptance revalidates price, funds and stock.
Fetch GET /categories for published hierarchy/counts. Poll GET /catalog/changes?after=0, then continue from the last event cursor. A product event instructs GET /products/ID; remove the item locally when it returns 404. A null product ID instructs a full catalog refresh. Image paths point to protected managed assets: fetch them using the same key, never expose that key in a public image URL.
Purchase safely
One product per order. Use a durable customer reference and one stable retry key. The example below spends real funds if run with a purchase-enabled key; use /sandbox/orders with synthetic product ID 1 to test first.
POST /reseller/v1/orders
Authorization: Bearer YOUR_PURCHASE_KEY
Idempotency-Key: your-stable-order-request-123
Content-Type: application/json
{"product_id":123,"quantity":1,"client_order_id":"your-customer-order-123","max_total_minor":350}
The server-calculated total must not exceed max_total_minor. Alternatively create POST /quotes with product_id and quantity, then pass its quote_id. Quotes last 60 seconds and reserve price only, never stock or funds. Using both a quote and maximum enforces the maximum too. Exact retries recover the accepted order even after quote expiry or API-key rotation. Changing data with the same key or client reference returns 409; do not replace the key/reference after a timeout.
Read GET /orders/ID after acceptance. Local reusable/pool inventory can deliver immediately. Manual delivery remains awaiting_manual with funds reserved. Supplier work goes through queued and processing. needs_review can mean the supplier already charged; wait for support rather than buying again. Funds are captured only with durable delivery. Definitive no-purchase cancellation releases the hold. Supplier quantities are currently limited to one and automatic products without custom inputs; unsupported/deferred product modes are rejected or returned for review before purchase.
Fetch GET /orders/ID/delivery using delivery:read after delivery becomes available. Responses contain unit numbers, immutable delivery versions and private content. Repeated reads never allocate more stock. Delivery is encrypted at rest. Treat responses as secrets and never include them in logs or public support tickets.
Cancel queued or awaiting-manual orders using POST /orders/ID/cancel, an empty JSON object and a stable Idempotency-Key. An upstream attempt, delivered order, or review state cannot be cancelled by the reseller. GET /orders?before=ID and GET /claims?before=ID return up to 50 newest records; continue before the last ID.
Claims, replacements and refunds
Open POST /orders/ID/claims with unit, category (access, warranty or other) and a description. One open claim per unit; automatic warranty eligibility uses the coverage configured when the order was accepted and begins at delivery. A display label alone grants no automatic warranty. Support can review general access issues separately.
Read claim details and post follow-ups to /claims/ID/messages. Evidence accepts JPG, PNG and TXT (maximum 80,000 decoded bytes, five files) as base64 JSON at /claims/ID/evidence. Evidence is encrypted, private and downloaded only after ownership checks. Support can replace a unit with a new delivery version or refund it once to the main wallet. A refunded credential never returns to sellable stock. Your refund to your own customer does not automatically authorize a TrustedTools refund.
Sandbox
/sandbox/products, /sandbox/wallet, /sandbox/orders and synthetic order/delivery reads never use real balances, inventory or suppliers. Product ID 1 costs 100 test cents. The fixture balance is fixed at 10,000 test cents; synthetic orders are bounded per account and reset on server restart. Sandbox IDs start with sbx_ and cannot be used as real order IDs. This tests the client contract; it does not simulate every production failure.
Signed webhooks
Existing optional webhooks remain supported; contact the admin for help. New integrations can simply poll GET /orders/{id}. The owner controls global dispatch. Events contain stable IDs, type, order ID, state snapshot, timestamp and schema_version; they never contain delivery credentials. Polling remains authoritative.
Verify X-TrustedTools-Signature: t=TIMESTAMP,v1=HEX using HMAC-SHA256 over the exact bytes TIMESTAMP + "." + raw_body, keyed by the signing secret as its UTF-8 text. Compare in constant time, allow a small timestamp window (for example five minutes), deduplicate the event ID, and tolerate retries/out-of-order events. Fetch the current order/delivery separately. Secret rotation signs future attempts with the new secret.
Callbacks require public HTTPS on port 443. Private/metadata IPs, non-public DNS results, redirects and proxy environment routing are blocked. Each connection resolves and validates its destination before dialing the validated IP. Attempts have bounded time/response limits, exponential backoff, at most 12 tries and a 24-hour event window. Notification failure never repeats or refunds a purchase. Account security and low-wallet changes can also generate events.
Errors and limits
Errors have {"error":{"code":"...","request_id":"..."}}. Every response includes X-Request-ID; provide that ID to support. Never send your API key to support.
| HTTP | Meaning |
|---|---|
| 401 | Missing, invalid or revoked key, or inactive account. |
| 403 | Insufficient scope or purchasing paused or disabled. |
| 404 | Unknown/unowned resource or API access disabled. |
| 409 | State/idempotency conflict, changed price, unavailable stock, insufficient funds or spending/concurrency limit. |
| 415/422 | JSON required or invalid/ambiguous data. Unknown and duplicate members are rejected. |
| 429 | Rate limit. Observe Retry-After. |
| 503 | Temporary unavailability. Retry an accepted purchase using exactly the same request identity. |
Read limit: one request per second per account with a burst of ten. Keys for the same account share this limit. A global capacity limit can also return 429. Back off on 429/503; do not loop immediately. The service never returns supplier costs, upstream API keys or delivery credentials in its catalog. Account suspension blocks all keys; closing an account revokes its keys and preserves the ordinary wallet.
API writes are bounded to 128 KB JSON. Account daily spending and concurrent open-order limits persist across restarts and keys. Accounts activate automatically; default purchase limit is $100 per UTC day and two open orders, with quantity configurable up to 100 for local products. The owner may lower limits or pause buying without removing order history.
Download the versioned OpenAPI contract. No reseller web login is needed. Generate your key in Telegram. For support use your order/request IDs, never your API key or plaintext credentials.
EXPLORE THE API
Endpoint reference
24 endpoints
No matching endpoints. Try another search.
All paths below use https://bot.csvplanet.com/reseller/v1. Requests use a private Bearer key. This page does not execute purchases.
GET/me
Own API account and effective purchasing status Required scope: catalog:read.
{
"operationId": "getAccount",
"description": "Own API account and effective purchasing status Required scope: catalog:read.",
"parameters": [],
"responses": {
"200": {
"description": "Successful result",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "integer",
"format": "int64"
},
"store_name": {
"type": "string"
},
"status": {
"type": "string"
},
"scopes": {
"type": "array",
"items": {
"type": "string"
}
},
"purchases_enabled": {
"type": "boolean"
}
}
}
}
}
},
"201": {
"description": "Resource accepted or existing resource replayed",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "integer",
"format": "int64"
},
"store_name": {
"type": "string"
},
"status": {
"type": "string"
},
"scopes": {
"type": "array",
"items": {
"type": "string"
}
},
"purchases_enabled": {
"type": "boolean"
}
}
}
}
}
},
"default": {
"$ref": "#/components/responses/Error"
}
}
}GET/wallet
One shared main wallet. Integer USD cents; spendable = posted minus reserved Required scope: wallet:read.
{
"operationId": "getWallet",
"description": "One shared main wallet. Integer USD cents; spendable = posted minus reserved Required scope: wallet:read.",
"parameters": [],
"responses": {
"200": {
"description": "Successful result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Wallet"
}
}
}
},
"201": {
"description": "Resource accepted or existing resource replayed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Wallet"
}
}
}
},
"default": {
"$ref": "#/components/responses/Error"
}
}
}GET/products
At most 50 products. Pass next_cursor as after; empty ends pagination. Prices and stock are revalidated at purchase. Required scope: catalog:read.
{
"operationId": "listProducts",
"description": "At most 50 products. Pass next_cursor as after; empty ends pagination. Prices and stock are revalidated at purchase. Required scope: catalog:read.",
"parameters": [
{
"name": "after",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 0
}
}
],
"responses": {
"200": {
"description": "Successful result",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Product"
}
},
"next_cursor": {
"type": "string"
},
"revision": {
"type": "integer",
"format": "int64"
}
}
}
}
}
},
"201": {
"description": "Resource accepted or existing resource replayed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Product"
}
},
"next_cursor": {
"type": "string"
},
"revision": {
"type": "integer",
"format": "int64"
}
}
}
}
}
},
"default": {
"$ref": "#/components/responses/Error"
}
}
}GET/products/{id}
Current published product; a removed/hidden product returns 404 Required scope: catalog:read.
{
"operationId": "getProduct",
"description": "Current published product; a removed/hidden product returns 404 Required scope: catalog:read.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"minimum": 0
}
}
],
"responses": {
"200": {
"description": "Successful result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Product"
}
}
}
},
"201": {
"description": "Resource accepted or existing resource replayed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Product"
}
}
}
},
"default": {
"$ref": "#/components/responses/Error"
}
}
}GET/products/{id}/image
{
"operationId": "getProductImage",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"minimum": 0
}
}
],
"responses": {
"200": {
"description": "Protected managed JPG/PNG image",
"content": {
"image/jpeg": {
"schema": {
"type": "string",
"format": "binary"
}
},
"image/png": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
},
"default": {
"$ref": "#/components/responses/Error"
}
}
}GET/categories
Published category hierarchy and product counts Required scope: catalog:read.
{
"operationId": "listCategories",
"description": "Published category hierarchy and product counts Required scope: catalog:read.",
"parameters": [],
"responses": {
"200": {
"description": "Successful result",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"201": {
"description": "Resource accepted or existing resource replayed",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"default": {
"$ref": "#/components/responses/Error"
}
}
}GET/catalog/changes
Refresh changed IDs using GET /products/{id}; remove on 404. A null product_id instructs a full refresh. At most 50 events; continue from last cursor. Required scope: catalog:read.
{
"operationId": "catalogChanges",
"description": "Refresh changed IDs using GET /products/{id}; remove on 404. A null product_id instructs a full refresh. At most 50 events; continue from last cursor. Required scope: catalog:read.",
"parameters": [
{
"name": "after",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 0
}
}
],
"responses": {
"200": {
"description": "Successful result",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"201": {
"description": "Resource accepted or existing resource replayed",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"default": {
"$ref": "#/components/responses/Error"
}
}
}POST/quotes
A 60-second price quote; reserves_stock=false and no wallet reservation. Required scope: quotes:create.
{
"operationId": "createQuote",
"description": "A 60-second price quote; reserves_stock=false and no wallet reservation. Required scope: quotes:create.",
"parameters": [],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"product_id": {
"type": "integer",
"format": "int64"
},
"quantity": {
"type": "integer",
"minimum": 1,
"maximum": 100
}
}
}
}
}
},
"responses": {
"200": {
"description": "Successful result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Quote"
}
}
}
},
"201": {
"description": "Resource accepted or existing resource replayed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Quote"
}
}
}
},
"default": {
"$ref": "#/components/responses/Error"
}
}
}GET/orders
Own orders, newest first, maximum 50. Continue before the last returned id. Required scope: orders:read.
{
"operationId": "listOrders",
"description": "Own orders, newest first, maximum 50. Continue before the last returned id. Required scope: orders:read.",
"parameters": [
{
"name": "before",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 0
}
}
],
"responses": {
"200": {
"description": "Successful result",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Order"
}
}
}
}
}
}
},
"201": {
"description": "Resource accepted or existing resource replayed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Order"
}
}
}
}
}
}
},
"default": {
"$ref": "#/components/responses/Error"
}
}
}POST/orders
Require a stable Idempotency-Key and client_order_id. Use a valid quote_id or max_total_minor. Exact retries recover the same order after quote expiry and key rotation. Changed request data conflicts. Accepted work survives HTTP disconnects. Delivery is fetched separately. Required scope: orders:write.
{
"operationId": "createOrder",
"description": "Require a stable Idempotency-Key and client_order_id. Use a valid quote_id or max_total_minor. Exact retries recover the same order after quote expiry and key rotation. Changed request data conflicts. Accepted work survives HTTP disconnects. Delivery is fetched separately. Required scope: orders:write.",
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 120
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Purchase"
}
}
}
},
"responses": {
"200": {
"description": "Successful result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Order"
}
}
}
},
"201": {
"description": "Resource accepted or existing resource replayed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Order"
}
}
}
},
"default": {
"$ref": "#/components/responses/Error"
}
}
}GET/orders/{id}
Own order state. needs_review may represent an upstream purchase: never create a replacement order to retry it. Required scope: orders:read.
{
"operationId": "getOrder",
"description": "Own order state. needs_review may represent an upstream purchase: never create a replacement order to retry it. Required scope: orders:read.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"minimum": 0
}
}
],
"responses": {
"200": {
"description": "Successful result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Order"
}
}
}
},
"201": {
"description": "Resource accepted or existing resource replayed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Order"
}
}
}
},
"default": {
"$ref": "#/components/responses/Error"
}
}
}GET/orders/{id}/delivery
Private versioned per-unit delivery. Repeated reads never allocate stock. Pending delivery returns 409. Required scope: delivery:read.
{
"operationId": "getDelivery",
"description": "Private versioned per-unit delivery. Repeated reads never allocate stock. Pending delivery returns 409. Required scope: delivery:read.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"minimum": 0
}
}
],
"responses": {
"200": {
"description": "Successful result",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"unit": {
"type": "integer",
"format": "int64"
},
"version": {
"type": "integer",
"format": "int64"
},
"content": {
"type": "string"
}
}
}
}
}
}
}
}
},
"201": {
"description": "Resource accepted or existing resource replayed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"unit": {
"type": "integer",
"format": "int64"
},
"version": {
"type": "integer",
"format": "int64"
},
"content": {
"type": "string"
}
}
}
}
}
}
}
}
},
"default": {
"$ref": "#/components/responses/Error"
}
}
}POST/orders/{id}/cancel
Only before an upstream attempt or while awaiting manual delivery. Idempotent; releases reserved funds. Processing/review/delivered orders conflict. Required scope: orders:cancel.
{
"operationId": "cancelOrder",
"description": "Only before an upstream attempt or while awaiting manual delivery. Idempotent; releases reserved funds. Processing/review/delivered orders conflict. Required scope: orders:cancel.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"minimum": 0
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 8
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {}
}
}
}
},
"responses": {
"200": {
"description": "Successful result",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"201": {
"description": "Resource accepted or existing resource replayed",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"default": {
"$ref": "#/components/responses/Error"
}
}
}POST/orders/{id}/claims
One open claim per owned delivered unit. Warranty claims require snapshotted, unexpired coverage; other access issues can be reviewed by support. Required scope: claims:write.
{
"operationId": "openClaim",
"description": "One open claim per owned delivered unit. Warranty claims require snapshotted, unexpired coverage; other access issues can be reviewed by support. Required scope: claims:write.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"minimum": 0
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"unit": {
"type": "integer",
"format": "int64"
},
"category": {
"enum": [
"access",
"warranty",
"other"
]
},
"description": {
"type": "string",
"minLength": 5,
"maxLength": 4000
}
}
}
}
}
},
"responses": {
"200": {
"description": "Successful result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Claim"
}
}
}
},
"201": {
"description": "Resource accepted or existing resource replayed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Claim"
}
}
}
},
"default": {
"$ref": "#/components/responses/Error"
}
}
}GET/claims
Own claims, maximum 50, newest first. Required scope: claims:read.
{
"operationId": "listClaims",
"description": "Own claims, maximum 50, newest first. Required scope: claims:read.",
"parameters": [
{
"name": "before",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 0
}
}
],
"responses": {
"200": {
"description": "Successful result",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"201": {
"description": "Resource accepted or existing resource replayed",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"default": {
"$ref": "#/components/responses/Error"
}
}
}GET/claims/{id}
Owned claim and latest 50 protected conversation messages. Required scope: claims:read.
{
"operationId": "getClaim",
"description": "Owned claim and latest 50 protected conversation messages. Required scope: claims:read.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"minimum": 0
}
}
],
"responses": {
"200": {
"description": "Successful result",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"201": {
"description": "Resource accepted or existing resource replayed",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"default": {
"$ref": "#/components/responses/Error"
}
}
}POST/claims/{id}/messages
Reply to an open owned claim. Required scope: claims:write.
{
"operationId": "replyClaim",
"description": "Reply to an open owned claim. Required scope: claims:write.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"minimum": 0
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"body": {
"type": "string",
"minLength": 1,
"maxLength": 4000
}
}
}
}
}
},
"responses": {
"200": {
"description": "Successful result",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"201": {
"description": "Resource accepted or existing resource replayed",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"default": {
"$ref": "#/components/responses/Error"
}
}
}GET/claims/{id}/evidence
List evidence metadata. Add ?file=ID to download one attachment; no public file URL. Required scope: claims:read.
{
"operationId": "getClaimEvidence",
"description": "List evidence metadata. Add ?file=ID to download one attachment; no public file URL. Required scope: claims:read.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"minimum": 0
}
},
{
"name": "file",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 0
}
}
],
"responses": {
"200": {
"description": "Successful result",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"201": {
"description": "Resource accepted or existing resource replayed",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"default": {
"$ref": "#/components/responses/Error"
}
}
}POST/claims/{id}/evidence
JPG, PNG or plain text, at most 80000 decoded bytes and five files per claim. Files are private and encrypted. Required scope: claims:write.
{
"operationId": "addClaimEvidence",
"description": "JPG, PNG or plain text, at most 80000 decoded bytes and five files per claim. Files are private and encrypted. Required scope: claims:write.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"minimum": 0
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"mime": {
"enum": [
"image/jpeg",
"image/png",
"text/plain"
]
},
"data": {
"type": "string",
"contentEncoding": "base64"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Successful result",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"201": {
"description": "Resource accepted or existing resource replayed",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"default": {
"$ref": "#/components/responses/Error"
}
}
}GET/sandbox/products
Synthetic test product id=1, price=100 cents. Never contacts suppliers. Required scope: catalog:read.
{
"operationId": "sandboxProducts",
"description": "Synthetic test product id=1, price=100 cents. Never contacts suppliers. Required scope: catalog:read.",
"parameters": [],
"responses": {
"200": {
"description": "Successful result",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"201": {
"description": "Resource accepted or existing resource replayed",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"default": {
"$ref": "#/components/responses/Error"
}
}
}GET/sandbox/wallet
Fixed synthetic test balance 10000 cents; never reads or debits the main wallet. Required scope: wallet:read.
{
"operationId": "sandboxWallet",
"description": "Fixed synthetic test balance 10000 cents; never reads or debits the main wallet. Required scope: wallet:read.",
"parameters": [],
"responses": {
"200": {
"description": "Successful result",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"201": {
"description": "Resource accepted or existing resource replayed",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"default": {
"$ref": "#/components/responses/Error"
}
}
}POST/sandbox/orders
Synthetic process-local fixture. Data resets on restart; bounded to 100 orders/account. Uses stable request keys and references; never creates real orders. Required scope: catalog:read.
{
"operationId": "sandboxPurchase",
"description": "Synthetic process-local fixture. Data resets on restart; bounded to 100 orders/account. Uses stable request keys and references; never creates real orders. Required scope: catalog:read.",
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"product_id": {
"type": "integer",
"format": "int64"
},
"quantity": {
"type": "integer",
"format": "int64"
},
"client_order_id": {
"type": "string"
},
"max_total_minor": {
"type": "integer",
"format": "int64"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Successful result",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"201": {
"description": "Resource accepted or existing resource replayed",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"default": {
"$ref": "#/components/responses/Error"
}
}
}GET/sandbox/orders/{id}
Synthetic order id (sbx_ prefix) Required scope: catalog:read.
{
"operationId": "sandboxOrder",
"description": "Synthetic order id (sbx_ prefix) Required scope: catalog:read.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful result",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"201": {
"description": "Resource accepted or existing resource replayed",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"default": {
"$ref": "#/components/responses/Error"
}
}
}GET/sandbox/orders/{id}/delivery
Synthetic demo credentials only. Required scope: catalog:read.
{
"operationId": "sandboxDelivery",
"description": "Synthetic demo credentials only. Required scope: catalog:read.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful result",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"201": {
"description": "Resource accepted or existing resource replayed",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"default": {
"$ref": "#/components/responses/Error"
}
}
}Shared request and response schemas
{
"securitySchemes": {
"bearerKey": {
"type": "http",
"scheme": "bearer",
"description": "Digest-only server key, valid until revoked. Read-only or purchase/delivery/claims scopes. Never put keys in URLs/browser code."
}
},
"responses": {
"Error": {
"description": "401 invalid_key; 403 insufficient_scope/access_denied; 404 not_found; 409 state_conflict/price_changed/limit_reached/insufficient_funds/out_of_stock; 415 json_required; 422 invalid_request/invalid_json; 429 rate_limited (Retry-After); 503 unavailable.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"error": {
"type": "object",
"additionalProperties": false,
"properties": {
"code": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
}
}
}
},
"schemas": {
"Wallet": {
"type": "object",
"additionalProperties": false,
"properties": {
"currency": {
"const": "USD"
},
"wallet": {
"const": "main"
},
"balance_minor": {
"type": "integer",
"format": "int64"
},
"posted_minor": {
"type": "integer",
"format": "int64"
},
"reserved_minor": {
"type": "integer",
"format": "int64"
},
"restricted_minor": {
"type": "integer",
"format": "int64"
},
"purchases_enabled": {
"type": "boolean"
}
}
},
"Product": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "integer",
"format": "int64"
},
"category_id": {
"type": "integer",
"format": "int64"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"price_minor": {
"type": "integer",
"format": "int64"
},
"currency": {
"const": "USD"
},
"stock": {
"type": "integer",
"format": "int64"
},
"delivery_mode": {
"type": "string"
},
"quantity_max": {
"type": "integer",
"format": "int64"
},
"can_purchase": {
"type": "boolean"
},
"availability_reason": {
"type": "string"
},
"image_path": {
"type": "string"
},
"stock_observed_at": {
"type": "string",
"format": "date-time"
}
}
},
"Quote": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string"
},
"product_id": {
"type": "integer",
"format": "int64"
},
"quantity": {
"type": "integer",
"format": "int64"
},
"total_minor": {
"type": "integer",
"format": "int64"
},
"currency": {
"const": "USD"
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"reserves_stock": {
"const": false
}
}
},
"Purchase": {
"type": "object",
"additionalProperties": false,
"properties": {
"product_id": {
"type": "integer",
"format": "int64"
},
"quantity": {
"type": "integer",
"minimum": 1,
"maximum": 100
},
"client_order_id": {
"type": "string",
"minLength": 1,
"maxLength": 80
},
"max_total_minor": {
"type": "integer",
"minimum": 0,
"maximum": 100000000
},
"quote_id": {
"type": "string"
}
},
"required": [
"product_id",
"quantity",
"client_order_id"
],
"anyOf": [
{
"required": [
"quote_id"
]
},
{
"required": [
"max_total_minor"
]
}
]
},
"Order": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "integer",
"format": "int64"
},
"client_order_id": {
"type": "string"
},
"product_id": {
"type": "integer",
"format": "int64"
},
"product_name": {
"type": "string"
},
"quantity": {
"type": "integer",
"format": "int64"
},
"total_minor": {
"type": "integer",
"format": "int64"
},
"captured_minor": {
"type": "integer",
"format": "int64"
},
"refunded_minor": {
"type": "integer",
"format": "int64"
},
"state": {
"enum": [
"queued",
"processing",
"awaiting_manual",
"needs_review",
"delivered",
"cancelled",
"failed",
"refunded"
]
},
"error_code": {
"type": "string"
},
"warranty": {
"type": "string"
},
"warranty_days": {
"type": "integer",
"format": "int64"
},
"warranty_expires_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
},
"Claim": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "integer",
"format": "int64"
},
"order_id": {
"type": "integer",
"format": "int64"
},
"unit": {
"type": "integer",
"format": "int64"
},
"status": {
"type": "string"
},
"category": {
"type": "string"
},
"description": {
"type": "string"
},
"resolution": {
"type": "string"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
}