REST API / v1
Build with Sellix.
Connect your products, orders, customers and integrations to the rest of your business.
Authentication & shop access
An API key is a password for your integration. Create one in your dashboard, choose the shops it can access and give it only the permissions it needs. Each endpoint below lists its required permission.
- Open Create API key.
- Choose one shop or all shops in your account. Keep the key secret.
- Send it in the
Authorizationheader, or paste it into the playground.
Base URL: https://api.sellix.gg/v1. Authentication: Authorization: Bearer YOUR_SELLIX_API_KEY. Send Accept: application/json and Content-Type: application/json for JSON bodies.
Keys are scoped to their tenant and optionally a single shop. Revocation, expiry, account suspension, shop binding and endpoint scopes are enforced on every request. An account-wide key can read across its account; create operations that need a shop require the appropriate shop binding.
Keep merchant API keys on your server. The playground is a testing tool for the person who owns the key; do not embed a merchant key in a public storefront or client bundle.
Browser origins and deployment
The first-party main and dashboard origins may call the API with bearer authentication. Additional trusted documentation origins can be listed in API_ALLOWED_ORIGINS, separated by commas. MCP also enforces MCP_ALLOWED_ORIGINS. Rebuild the application configuration cache after changing these settings. Requests use no session cookies, and API authorization remains mandatory.
After updating the canonical YAML contract, regenerate its JSON companion with php scripts/build-api-contract.php in a development environment. The contract tests verify that both files and the routed operations agree.
Requests, money & pagination
GET reads information. POST, PATCH and DELETE can change your account. Amounts ending in _cents use the smallest currency unit: 1299 means 12.99 USD. Payout amounts instead use decimal strings in the asset’s units.
A list is one page of results. If has_more is true, pass the returned next_cursor as your next request’s cursor.
Lists return object: list, data, has_more and next_cursor. Cursor pagination uses limit between 1 and 100, default 25. Treat cursors as opaque values.
Write operations require an Idempotency-Key. Reuse the same key only for an identical retry. Different data with the same key returns 409 idempotency_conflict. The playground keeps the key between retries; use New ID after editing a request.
Understand errors
A failed request includes a readable message. A 401 usually means your key needs attention; 403 means it lacks permission. A 422 points to fields to fix. A 429 means wait before trying again.
| Status | Meaning / next step |
|---|---|
400 | Check the request format and Idempotency-Key. |
401 | Supply a valid, unexpired, unrevoked bearer key. |
403 | Check the required scope and shop access. |
404 | Check the resource ID and whether it belongs to the key’s shop. |
405 | Use the method documented for this endpoint. |
409 | Resolve an idempotency or resource-state conflict before retrying. |
422 | Correct error.details.errors using the field names returned. |
429 | Respect Retry-After before retrying. |
500 | Save error.trace_id / X-Request-Id for support. Avoid blindly repeating a write. |
502 | An upstream provider did not complete the request. Inspect the recorded result before retrying. |
Error response shape
{"error":{"type":"unprocessable","message":"The request data is invalid.","trace_id":"request-uuid","details":{"errors":{"name":["The name field is required."]}}}}Rate limits & live testing
Per-key rate limits apply, with an additional API route ceiling. A limited request returns 429 and Retry-After. Keep concurrency small and use exponential backoff for transient failures.
These are real requests.
The playground talks directly to https://api.sellix.gg. It does not simulate success or bypass permissions. A test shop is a real shop dedicated to your test data; the public REST API has no separate sandbox. Writes require you to acknowledge their effect before sending.
The connection suite only reads health, products, orders and MCP discovery. It distinguishes missing permissions from network errors and displays the actual HTTP status, latency and request ID.
ENDPOINT REFERENCE
Products
GET
/v1/productsList products
See the products available to this API key. This reads your catalog without changing it.
List products
Required scope products:read
| Field | What to send |
|---|---|
limitquery · Optional | How many results to show on one page.How many results to show on one page.integer · min: 1 · max: 100 · default: 25 |
cursorquery · Optional | Paste next_cursor from the previous response to get the next page.Opaque next_cursor value from the previous response.string · max characters: 2048 |
statusquery · Optional | The current state. Use one of the allowed values below.The current state. Use one of the allowed values below.string Allowed: draft, active, hidden, archived |
typequery · Optional | The kind of product and how it is delivered.The kind of product and how it is delivered.string Allowed: license_key, account, file_download, service, dynamic, physical |
Full response contract & request schema
HTTP 200 · Cursor-paginated product list.
{
"allOf": [
{
"type": "object",
"required": [
"object",
"has_more",
"next_cursor",
"data"
],
"properties": {
"object": {
"type": "string",
"const": "list"
},
"has_more": {
"type": "boolean"
},
"next_cursor": {
"type": [
"string",
"null"
]
},
"data": {
"type": "array",
"items": []
}
}
},
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"object",
"id",
"name",
"slug",
"type",
"price_cents",
"currency",
"stock",
"status",
"created_at",
"updated_at"
],
"properties": {
"object": {
"type": "string",
"const": "product"
},
"id": {
"type": "string",
"pattern": "^prod_[a-z0-9]+$"
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"license_key",
"account",
"file_download",
"service",
"dynamic",
"physical"
]
},
"description": {
"type": [
"string",
"null"
]
},
"price_cents": {
"type": "integer",
"minimum": 0
},
"currency": {
"type": "string",
"minLength": 3,
"maxLength": 3
},
"stock": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"status": {
"type": "string",
"enum": [
"draft",
"active",
"hidden",
"archived"
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
}
}
}
]
}HTTP 401 · Missing, invalid, expired, or revoked API key.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 403 · API key lacks the required scope.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 422 · Request validation failed.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 429 · Per-key or route rate limit exceeded.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}POST
/v1/productsCreate a product
Add a real product to your shop. Choose its name, delivery type, price and shop currency.
Create a product
Required scope products:write Changes live data
| Field | What to send |
|---|---|
Idempotency-Keyheader · Required | A unique request label. Reuse it when retrying the exact same change; use a new one for a different change.Unique key for this mutation. Exact replays return the stored response for 24 hours.string · min characters: 8 · max characters: 255 |
namebody · Required | The name people see.The name people see.string · min characters: 2 · max characters: 120 |
typebody · Required | The kind of product and how it is delivered.The kind of product and how it is delivered.string Allowed: license_key, account, file_download, service, dynamic, physical |
price_centsbody · Required | The price in the currency’s smallest unit: 1000 means 10.00 for USD.The price in the currency’s smallest unit: 1000 means 10.00 for USD.integer · min: 0 |
currencybody · Required | The three-letter currency code. Use the currency configured for your shop.The three-letter currency code. Use the currency configured for your shop.string · min characters: 3 · max characters: 3 |
slugbody · Optional | The URL-friendly product name.The URL-friendly product name.string · min characters: 2 · max characters: 80 |
descriptionbody · Optional | The product description.The product description.string or null · max characters: 20000 |
statusbody · Optional | The current state. Use one of the allowed values below.The current state. Use one of the allowed values below.string Allowed: draft, active, hidden, archived |
stockbody · Optional | The stock amount; null means there is no fixed stock limit.The stock amount; null means there is no fixed stock limit.integer or null · min: 0 |
dynamic_webhook_urlbody · Optional | Send this field using the format and limits listed below.Send this field using the format and limits listed below.string or null · uri |
Example JSON body · replace sample values
{
"name": "Example product",
"type": "license_key",
"price_cents": 1000,
"currency": "USD"
}Full response contract & request schema
Request JSON Schema
{
"type": "object",
"required": [
"name",
"type",
"price_cents",
"currency"
],
"properties": {
"name": {
"type": "string",
"minLength": 2,
"maxLength": 120
},
"type": {
"type": "string",
"enum": [
"license_key",
"account",
"file_download",
"service",
"dynamic",
"physical"
]
},
"price_cents": {
"type": "integer",
"minimum": 0
},
"currency": {
"type": "string",
"minLength": 3,
"maxLength": 3
},
"slug": {
"type": "string",
"minLength": 2,
"maxLength": 80
},
"description": {
"type": [
"string",
"null"
],
"maxLength": 20000
},
"status": {
"type": "string",
"enum": [
"draft",
"active",
"hidden",
"archived"
]
},
"stock": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"dynamic_webhook_url": {
"type": [
"string",
"null"
],
"format": "uri"
}
}
}HTTP 201 · Product created.
{
"type": "object",
"required": [
"object",
"id",
"name",
"slug",
"type",
"price_cents",
"currency",
"stock",
"status",
"created_at",
"updated_at"
],
"properties": {
"object": {
"type": "string",
"const": "product"
},
"id": {
"type": "string",
"pattern": "^prod_[a-z0-9]+$"
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"license_key",
"account",
"file_download",
"service",
"dynamic",
"physical"
]
},
"description": {
"type": [
"string",
"null"
]
},
"price_cents": {
"type": "integer",
"minimum": 0
},
"currency": {
"type": "string",
"minLength": 3,
"maxLength": 3
},
"stock": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"status": {
"type": "string",
"enum": [
"draft",
"active",
"hidden",
"archived"
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}HTTP 400 · Missing or malformed Idempotency-Key header.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 401 · Missing, invalid, expired, or revoked API key.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 403 · API key lacks the required scope.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 409 · Resource state conflict or idempotency key reuse with different request data.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 422 · Request validation failed.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}GET
/v1/products/{id}Fetch a product
Look up one product. Copy its ID from the product list first.
Fetch a product
Required scope products:read
| Field | What to send |
|---|---|
idpath · Required | The resource ID returned by a list or create request.The resource ID returned by a list or create request.string Pattern: ^prod_[a-z0-9]+$ |
Full response contract & request schema
HTTP 200 · Product details.
{
"type": "object",
"required": [
"object",
"id",
"name",
"slug",
"type",
"price_cents",
"currency",
"stock",
"status",
"created_at",
"updated_at"
],
"properties": {
"object": {
"type": "string",
"const": "product"
},
"id": {
"type": "string",
"pattern": "^prod_[a-z0-9]+$"
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"license_key",
"account",
"file_download",
"service",
"dynamic",
"physical"
]
},
"description": {
"type": [
"string",
"null"
]
},
"price_cents": {
"type": "integer",
"minimum": 0
},
"currency": {
"type": "string",
"minLength": 3,
"maxLength": 3
},
"stock": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"status": {
"type": "string",
"enum": [
"draft",
"active",
"hidden",
"archived"
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}HTTP 401 · Missing, invalid, expired, or revoked API key.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 403 · API key lacks the required scope.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 404 · Resource does not exist within the key's tenant and shop scope.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}PATCH
/v1/products/{id}Update a product
Change only the product fields you send. Leave other fields out to keep them as they are.
Update a product
Required scope products:write Changes live data
| Field | What to send |
|---|---|
idpath · Required | The resource ID returned by a list or create request.The resource ID returned by a list or create request.string Pattern: ^prod_[a-z0-9]+$ |
Idempotency-Keyheader · Required | A unique request label. Reuse it when retrying the exact same change; use a new one for a different change.Unique key for this mutation. Exact replays return the stored response for 24 hours.string · min characters: 8 · max characters: 255 |
namebody · Optional | The name people see.The name people see.string · min characters: 2 · max characters: 120 |
slugbody · Optional | The URL-friendly product name.The URL-friendly product name.string · min characters: 2 · max characters: 80 |
price_centsbody · Optional | The price in the currency’s smallest unit: 1000 means 10.00 for USD.The price in the currency’s smallest unit: 1000 means 10.00 for USD.integer · min: 0 |
descriptionbody · Optional | The product description.The product description.string or null · max characters: 20000 |
statusbody · Optional | The current state. Use one of the allowed values below.The current state. Use one of the allowed values below.string Allowed: draft, active, hidden, archived |
stockbody · Optional | The stock amount; null means there is no fixed stock limit.The stock amount; null means there is no fixed stock limit.integer or null · min: 0 |
dynamic_webhook_urlbody · Optional | Send this field using the format and limits listed below.Send this field using the format and limits listed below.string or null · uri |
Example JSON body · replace sample values
{
"name": "Example product"
}Full response contract & request schema
Request JSON Schema
{
"type": "object",
"minProperties": 1,
"properties": {
"name": {
"type": "string",
"minLength": 2,
"maxLength": 120
},
"slug": {
"type": "string",
"minLength": 2,
"maxLength": 80
},
"price_cents": {
"type": "integer",
"minimum": 0
},
"description": {
"type": [
"string",
"null"
],
"maxLength": 20000
},
"status": {
"type": "string",
"enum": [
"draft",
"active",
"hidden",
"archived"
]
},
"stock": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"dynamic_webhook_url": {
"type": [
"string",
"null"
],
"format": "uri"
}
}
}HTTP 200 · Updated product.
{
"type": "object",
"required": [
"object",
"id",
"name",
"slug",
"type",
"price_cents",
"currency",
"stock",
"status",
"created_at",
"updated_at"
],
"properties": {
"object": {
"type": "string",
"const": "product"
},
"id": {
"type": "string",
"pattern": "^prod_[a-z0-9]+$"
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"license_key",
"account",
"file_download",
"service",
"dynamic",
"physical"
]
},
"description": {
"type": [
"string",
"null"
]
},
"price_cents": {
"type": "integer",
"minimum": 0
},
"currency": {
"type": "string",
"minLength": 3,
"maxLength": 3
},
"stock": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"status": {
"type": "string",
"enum": [
"draft",
"active",
"hidden",
"archived"
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}HTTP 400 · Missing or malformed Idempotency-Key header.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 401 · Missing, invalid, expired, or revoked API key.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 403 · API key lacks the required scope.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 404 · Resource does not exist within the key's tenant and shop scope.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 409 · Resource state conflict or idempotency key reuse with different request data.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 422 · Request validation failed.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}DELETE
/v1/products/{id}Archive a product
Archive a product so it stops being available for new purchases. Existing orders remain available.
Archive a product
Required scope products:write Changes live data
| Field | What to send |
|---|---|
idpath · Required | The resource ID returned by a list or create request.The resource ID returned by a list or create request.string Pattern: ^prod_[a-z0-9]+$ |
Idempotency-Keyheader · Required | A unique request label. Reuse it when retrying the exact same change; use a new one for a different change.Unique key for this mutation. Exact replays return the stored response for 24 hours.string · min characters: 8 · max characters: 255 |
Full response contract & request schema
HTTP 200 · Product archived.
{
"type": "object",
"required": [
"id",
"deleted"
],
"properties": {
"id": {
"type": "string"
},
"deleted": {
"type": "boolean",
"const": true
}
}
}HTTP 400 · Missing or malformed Idempotency-Key header.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 401 · Missing, invalid, expired, or revoked API key.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 403 · API key lacks the required scope.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 404 · Resource does not exist within the key's tenant and shop scope.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 409 · Resource state conflict or idempotency key reuse with different request data.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}POST
/v1/products/{id}/keysImport account credentials
Add real license keys or credentials to an eligible product’s stock. These values can be delivered to paying customers.
Only account products use an imported credential pool. License-key products generate keys automatically.
Required scope products:write Changes live data
| Field | What to send |
|---|---|
idpath · Required | The resource ID returned by a list or create request.The resource ID returned by a list or create request.string Pattern: ^prod_[a-z0-9]+$ |
Idempotency-Keyheader · Required | A unique request label. Reuse it when retrying the exact same change; use a new one for a different change.Unique key for this mutation. Exact replays return the stored response for 24 hours.string · min characters: 8 · max characters: 255 |
keysbody · Required | The real credentials or license keys you want to add to stock.The real credentials or license keys you want to add to stock.array · min items: 1 · max items: 5000 |
Example JSON body · replace sample values
{
"keys": [
"EXAMPLE-KEY-REPLACE-ME"
]
}Full response contract & request schema
Request JSON Schema
{
"type": "object",
"required": [
"keys"
],
"properties": {
"keys": {
"type": "array",
"minItems": 1,
"maxItems": 5000,
"items": {
"type": "string",
"maxLength": 10000
}
}
}
}HTTP 201 · Credential import result.
{
"type": "object",
"required": [
"imported",
"duplicates",
"stock_after"
],
"properties": {
"imported": {
"type": "integer",
"minimum": 0
},
"duplicates": {
"type": "integer",
"minimum": 0
},
"stock_after": {
"type": "integer",
"minimum": 0
}
}
}HTTP 400 · Missing or malformed Idempotency-Key header.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 401 · Missing, invalid, expired, or revoked API key.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 403 · API key lacks the required scope.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 404 · Resource does not exist within the key's tenant and shop scope.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 409 · Resource state conflict or idempotency key reuse with different request data.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 422 · Request validation failed.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}ENDPOINT REFERENCE
Orders
GET
/v1/ordersList orders
See your orders, including whether payment and delivery have completed.
List orders
Required scope orders:read
| Field | What to send |
|---|---|
limitquery · Optional | How many results to show on one page.How many results to show on one page.integer · min: 1 · max: 100 · default: 25 |
cursorquery · Optional | Paste next_cursor from the previous response to get the next page.Opaque next_cursor value from the previous response.string · max characters: 2048 |
statusquery · Optional | The current state. Use one of the allowed values below.The current state. Use one of the allowed values below.string Allowed: pending, awaiting_payment, paid, delivering, completed, failed, expired, cancelled, refunded |
fromquery · Optional | Only results created on or after this date.ISO-8601 lower bound for created_at.string |
toquery · Optional | Only results created on or before this date.ISO-8601 upper bound for created_at.string |
Full response contract & request schema
HTTP 200 · Cursor-paginated order list.
{
"allOf": [
{
"type": "object",
"required": [
"object",
"has_more",
"next_cursor",
"data"
],
"properties": {
"object": {
"type": "string",
"const": "list"
},
"has_more": {
"type": "boolean"
},
"next_cursor": {
"type": [
"string",
"null"
]
},
"data": {
"type": "array",
"items": []
}
}
},
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"object",
"uuid",
"status",
"customer_email",
"total_cents",
"currency",
"created_at",
"paid_at"
],
"properties": {
"object": {
"type": "string",
"const": "order"
},
"uuid": {
"type": "string",
"format": "uuid"
},
"status": {
"type": "string",
"enum": [
"pending",
"awaiting_payment",
"paid",
"delivering",
"completed",
"failed",
"expired",
"cancelled",
"refunded"
]
},
"customer_email": {
"type": "string",
"format": "email"
},
"total_cents": {
"type": "integer",
"minimum": 0
},
"currency": {
"type": "string",
"minLength": 3,
"maxLength": 3
},
"created_at": {
"type": "string",
"format": "date-time"
},
"paid_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"email": {
"type": "string",
"format": "email",
"deprecated": true
},
"total": {
"type": "integer",
"minimum": 0,
"deprecated": true
}
}
}
}
}
}
]
}HTTP 401 · Missing, invalid, expired, or revoked API key.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 403 · API key lacks the required scope.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 422 · Request validation failed.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 429 · Per-key or route rate limit exceeded.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}GET
/v1/orders/{uuid}Fetch an order
Open the details and purchased items for one Order ID.
Fetch an order
Required scope orders:read
| Field | What to send |
|---|---|
uuidpath · Required | The full Order ID, including its hyphens.The full Order ID, including its hyphens.string · uuid |
Full response contract & request schema
HTTP 200 · Order with line items.
{
"allOf": [
{
"type": "object",
"required": [
"object",
"uuid",
"status",
"customer_email",
"total_cents",
"currency",
"created_at",
"paid_at"
],
"properties": {
"object": {
"type": "string",
"const": "order"
},
"uuid": {
"type": "string",
"format": "uuid"
},
"status": {
"type": "string",
"enum": [
"pending",
"awaiting_payment",
"paid",
"delivering",
"completed",
"failed",
"expired",
"cancelled",
"refunded"
]
},
"customer_email": {
"type": "string",
"format": "email"
},
"total_cents": {
"type": "integer",
"minimum": 0
},
"currency": {
"type": "string",
"minLength": 3,
"maxLength": 3
},
"created_at": {
"type": "string",
"format": "date-time"
},
"paid_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"email": {
"type": "string",
"format": "email",
"deprecated": true
},
"total": {
"type": "integer",
"minimum": 0,
"deprecated": true
}
}
},
{
"type": "object",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"product_id": {
"type": "integer"
},
"product_name": {
"type": "string"
},
"quantity": {
"type": "integer",
"minimum": 1
},
"unit_price_cents": {
"type": "integer",
"minimum": 0
},
"subtotal_cents": {
"type": "integer",
"minimum": 0
}
}
}
}
}
}
]
}HTTP 401 · Missing, invalid, expired, or revoked API key.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 403 · API key lacks the required scope.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 404 · Resource does not exist within the key's tenant and shop scope.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}POST
/v1/orders/{uuid}/refundRefund an order in full
Request a real refund for an eligible paid order. The payment provider must confirm the result.
Partial refunds are not supported. amount_cents, when supplied, must equal the order total.
Required scope orders:write Changes live data
| Field | What to send |
|---|---|
uuidpath · Required | The full Order ID, including its hyphens.The full Order ID, including its hyphens.string · uuid |
Idempotency-Keyheader · Required | A unique request label. Reuse it when retrying the exact same change; use a new one for a different change.Unique key for this mutation. Exact replays return the stored response for 24 hours.string · min characters: 8 · max characters: 255 |
amount_centsbody · Optional | Send this field using the format and limits listed below.Send this field using the format and limits listed below.integer · min: 1 |
reasonbody · Optional | Send this field using the format and limits listed below.Send this field using the format and limits listed below.string Allowed: requested_by_buyer, duplicate, fraud, other |
notebody · Optional | Send this field using the format and limits listed below.Send this field using the format and limits listed below.string or null · max characters: 2000 |
Example JSON body · replace sample values
{}Full response contract & request schema
Request JSON Schema
{
"type": "object",
"properties": {
"amount_cents": {
"type": "integer",
"minimum": 1
},
"reason": {
"type": "string",
"enum": [
"requested_by_buyer",
"duplicate",
"fraud",
"other"
]
},
"note": {
"type": [
"string",
"null"
],
"maxLength": 2000
}
}
}HTTP 200 · Persisted refund state.
{
"type": "object",
"required": [
"object",
"id",
"order_id",
"status",
"amount_cents",
"currency",
"created_at"
],
"properties": {
"object": {
"type": "string",
"const": "refund"
},
"id": {
"type": "string",
"pattern": "^rf_[0-9a-f-]+$"
},
"order_id": {
"type": "string",
"format": "uuid"
},
"status": {
"type": "string",
"enum": [
"processing",
"submitted",
"succeeded",
"failed",
"requires_review"
]
},
"amount_cents": {
"type": "integer",
"minimum": 1
},
"currency": {
"type": "string",
"minLength": 3,
"maxLength": 3
},
"reason": {
"type": [
"string",
"null"
]
},
"note": {
"type": [
"string",
"null"
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}HTTP 400 · Missing or malformed Idempotency-Key header.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 401 · Missing, invalid, expired, or revoked API key.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 403 · API key lacks the required scope.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 404 · Resource does not exist within the key's tenant and shop scope.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 409 · Resource state conflict or idempotency key reuse with different request data.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 422 · Request validation failed.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 502 · An upstream payout, refund, or mail provider rejected the operation.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}POST
/v1/orders/{uuid}/resendResend the confirmation or delivery email
Send another confirmation or delivery email for this order. The customer receives a real email.
Resend the confirmation or delivery email
Required scope orders:write Changes live data
| Field | What to send |
|---|---|
uuidpath · Required | The full Order ID, including its hyphens.The full Order ID, including its hyphens.string · uuid |
Idempotency-Keyheader · Required | A unique request label. Reuse it when retrying the exact same change; use a new one for a different change.Unique key for this mutation. Exact replays return the stored response for 24 hours.string · min characters: 8 · max characters: 255 |
Full response contract & request schema
HTTP 200 · Email accepted by the configured mail transport.
{
"type": "object",
"required": [
"sent_at",
"recipient",
"message_type"
],
"properties": {
"sent_at": {
"type": "string",
"format": "date-time"
},
"recipient": {
"type": "string",
"format": "email"
},
"message_type": {
"type": "string",
"enum": [
"confirmation",
"delivery"
]
}
}
}HTTP 400 · Missing or malformed Idempotency-Key header.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 401 · Missing, invalid, expired, or revoked API key.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 403 · API key lacks the required scope.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 404 · Resource does not exist within the key's tenant and shop scope.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 409 · Resource state conflict or idempotency key reuse with different request data.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 502 · An upstream payout, refund, or mail provider rejected the operation.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}ENDPOINT REFERENCE
Invoices
GET
/v1/invoicesList invoices
Read the same order list using the invoice-compatible address.
Compatibility alias for GET /orders. Returns the same order objects.
Required scope orders:read
| Field | What to send |
|---|---|
limitquery · Optional | How many results to show on one page.How many results to show on one page.integer · min: 1 · max: 100 · default: 25 |
cursorquery · Optional | Paste next_cursor from the previous response to get the next page.Opaque next_cursor value from the previous response.string · max characters: 2048 |
statusquery · Optional | The current state. Use one of the allowed values below.The current state. Use one of the allowed values below.string Allowed: pending, awaiting_payment, paid, delivering, completed, failed, expired, cancelled, refunded |
fromquery · Optional | Only results created on or after this date.ISO-8601 lower bound for created_at.string |
toquery · Optional | Only results created on or before this date.ISO-8601 upper bound for created_at.string |
Full response contract & request schema
HTTP 200 · Cursor-paginated order list.
{
"allOf": [
{
"type": "object",
"required": [
"object",
"has_more",
"next_cursor",
"data"
],
"properties": {
"object": {
"type": "string",
"const": "list"
},
"has_more": {
"type": "boolean"
},
"next_cursor": {
"type": [
"string",
"null"
]
},
"data": {
"type": "array",
"items": []
}
}
},
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"object",
"uuid",
"status",
"customer_email",
"total_cents",
"currency",
"created_at",
"paid_at"
],
"properties": {
"object": {
"type": "string",
"const": "order"
},
"uuid": {
"type": "string",
"format": "uuid"
},
"status": {
"type": "string",
"enum": [
"pending",
"awaiting_payment",
"paid",
"delivering",
"completed",
"failed",
"expired",
"cancelled",
"refunded"
]
},
"customer_email": {
"type": "string",
"format": "email"
},
"total_cents": {
"type": "integer",
"minimum": 0
},
"currency": {
"type": "string",
"minLength": 3,
"maxLength": 3
},
"created_at": {
"type": "string",
"format": "date-time"
},
"paid_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"email": {
"type": "string",
"format": "email",
"deprecated": true
},
"total": {
"type": "integer",
"minimum": 0,
"deprecated": true
}
}
}
}
}
}
]
}HTTP 401 · Missing, invalid, expired, or revoked API key.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 403 · API key lacks the required scope.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 422 · Request validation failed.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 429 · Per-key or route rate limit exceeded.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}GET
/v1/invoices/{uuid}Fetch an invoice
Read one order using its invoice-compatible address and full Order ID.
Compatibility alias for GET /orders/{uuid}.
Required scope orders:read
| Field | What to send |
|---|---|
uuidpath · Required | The full Order ID, including its hyphens.The full Order ID, including its hyphens.string · uuid |
Full response contract & request schema
HTTP 200 · Order with line items.
{
"allOf": [
{
"type": "object",
"required": [
"object",
"uuid",
"status",
"customer_email",
"total_cents",
"currency",
"created_at",
"paid_at"
],
"properties": {
"object": {
"type": "string",
"const": "order"
},
"uuid": {
"type": "string",
"format": "uuid"
},
"status": {
"type": "string",
"enum": [
"pending",
"awaiting_payment",
"paid",
"delivering",
"completed",
"failed",
"expired",
"cancelled",
"refunded"
]
},
"customer_email": {
"type": "string",
"format": "email"
},
"total_cents": {
"type": "integer",
"minimum": 0
},
"currency": {
"type": "string",
"minLength": 3,
"maxLength": 3
},
"created_at": {
"type": "string",
"format": "date-time"
},
"paid_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"email": {
"type": "string",
"format": "email",
"deprecated": true
},
"total": {
"type": "integer",
"minimum": 0,
"deprecated": true
}
}
},
{
"type": "object",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"product_id": {
"type": "integer"
},
"product_name": {
"type": "string"
},
"quantity": {
"type": "integer",
"minimum": 1
},
"unit_price_cents": {
"type": "integer",
"minimum": 0
},
"subtotal_cents": {
"type": "integer",
"minimum": 0
}
}
}
}
}
}
]
}HTTP 401 · Missing, invalid, expired, or revoked API key.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 403 · API key lacks the required scope.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 404 · Resource does not exist within the key's tenant and shop scope.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}ENDPOINT REFERENCE
Customers
GET
/v1/customersList customers
Read the customers this key can access, without changing their accounts.
List customers
Required scope customers:read
| Field | What to send |
|---|---|
limitquery · Optional | How many results to show on one page.How many results to show on one page.integer · min: 1 · max: 100 · default: 25 |
cursorquery · Optional | Paste next_cursor from the previous response to get the next page.Opaque next_cursor value from the previous response.string · max characters: 2048 |
Full response contract & request schema
HTTP 200 · Cursor-paginated customer list.
{
"allOf": [
{
"type": "object",
"required": [
"object",
"has_more",
"next_cursor",
"data"
],
"properties": {
"object": {
"type": "string",
"const": "list"
},
"has_more": {
"type": "boolean"
},
"next_cursor": {
"type": [
"string",
"null"
]
},
"data": {
"type": "array",
"items": []
}
}
},
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"object",
"id",
"email",
"orders_count",
"lifetime_cents"
],
"properties": {
"object": {
"type": "string",
"const": "customer"
},
"id": {
"type": "string",
"pattern": "^cus_[a-z0-9]+$"
},
"email": {
"type": "string",
"format": "email"
},
"orders_count": {
"type": "integer",
"minimum": 0
},
"lifetime_cents": {
"type": "integer",
"minimum": 0
}
}
}
}
}
}
]
}HTTP 401 · Missing, invalid, expired, or revoked API key.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 403 · API key lacks the required scope.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 422 · Request validation failed.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}GET
/v1/customers/{id}Fetch a customer
Read one customer’s details using their customer ID.
Fetch a customer
Required scope customers:read
| Field | What to send |
|---|---|
idpath · Required | The resource ID returned by a list or create request.The resource ID returned by a list or create request.string Pattern: ^cus_[a-z0-9]+$ |
Full response contract & request schema
HTTP 200 · Customer metrics and up to 100 recent orders.
{
"allOf": [
{
"type": "object",
"required": [
"object",
"id",
"email",
"orders_count",
"lifetime_cents"
],
"properties": {
"object": {
"type": "string",
"const": "customer"
},
"id": {
"type": "string",
"pattern": "^cus_[a-z0-9]+$"
},
"email": {
"type": "string",
"format": "email"
},
"orders_count": {
"type": "integer",
"minimum": 0
},
"lifetime_cents": {
"type": "integer",
"minimum": 0
}
}
},
{
"type": "object",
"properties": {
"name": {
"type": [
"string",
"null"
]
},
"country": {
"type": [
"string",
"null"
]
},
"first_seen_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"last_seen_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"orders": {
"type": "array",
"maxItems": 100,
"items": {
"type": "object"
}
}
}
}
]
}HTTP 401 · Missing, invalid, expired, or revoked API key.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 403 · API key lacks the required scope.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 404 · Resource does not exist within the key's tenant and shop scope.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}ENDPOINT REFERENCE
Payouts
GET
/v1/payoutsList payouts
See existing payout requests and their current state.
List payouts
Required scope payouts:read
| Field | What to send |
|---|---|
limitquery · Optional | How many results to show on one page.How many results to show on one page.integer · min: 1 · max: 100 · default: 25 |
cursorquery · Optional | Paste next_cursor from the previous response to get the next page.Opaque next_cursor value from the previous response.string · max characters: 2048 |
statusquery · Optional | The current state. Use one of the allowed values below.The current state. Use one of the allowed values below.string Allowed: processing, pending, broadcast, confirmed, failed, cancelled |
Full response contract & request schema
HTTP 200 · Cursor-paginated payout list. Destination addresses are omitted.
{
"allOf": [
{
"type": "object",
"required": [
"object",
"has_more",
"next_cursor",
"data"
],
"properties": {
"object": {
"type": "string",
"const": "list"
},
"has_more": {
"type": "boolean"
},
"next_cursor": {
"type": [
"string",
"null"
]
},
"data": {
"type": "array",
"items": []
}
}
},
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"object",
"id",
"status",
"chain",
"asset",
"amount",
"created_at"
],
"properties": {
"object": {
"type": "string",
"const": "payout"
},
"id": {
"type": "string",
"pattern": "^po_[a-z0-9]+$"
},
"status": {
"type": "string",
"enum": [
"processing",
"pending",
"broadcast",
"confirmed",
"failed",
"cancelled"
]
},
"chain": {
"type": "string"
},
"asset": {
"type": "string"
},
"amount": {
"type": "string",
"pattern": "^(?=.*[1-9])(?:0|[1-9]\\d{0,17})(?:\\.\\d{1,18})?$"
},
"tx_hash": {
"type": "string"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"submitted_at": {
"type": "string",
"format": "date-time"
},
"confirmed_at": {
"type": "string",
"format": "date-time"
}
}
}
}
}
}
]
}HTTP 401 · Missing, invalid, expired, or revoked API key.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 403 · API key lacks the required scope.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 422 · Request validation failed.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}POST
/v1/payoutsSubmit a BlockPN payout
Request a real transfer through your connected BlockPN account. Check the network, asset, amount and recipient carefully.
amount is a decimal string in asset units, not fiat cents.
Required scope payouts:write Changes live data
| Field | What to send |
|---|---|
Idempotency-Keyheader · Required | A unique request label. Reuse it when retrying the exact same change; use a new one for a different change.Unique key for this mutation. Exact replays return the stored response for 24 hours.string · min characters: 8 · max characters: 255 |
chainbody · Required | The blockchain network for this payout.The blockchain network for this payout.string · min characters: 2 · max characters: 32 |
assetbody · Required | The asset you want to send.The asset you want to send.string · min characters: 2 · max characters: 16 |
amountbody · Required | The amount as a decimal string, rather than a rounded floating-point number.The amount as a decimal string, rather than a rounded floating-point number.string Pattern: ^(?=.*[1-9])(?:0|[1-9]\d{0,17})(?:\.\d{1,18})?$ |
destination_addressbody · Required | The recipient address. A payout sends real funds.The recipient address. A payout sends real funds.string · min characters: 8 · max characters: 255 |
memobody · Optional | An optional destination memo or tag.An optional destination memo or tag.string or null · max characters: 255 |
Example JSON body · replace sample values
{
"chain": "ethereum",
"asset": "USDT",
"amount": "0.01",
"destination_address": "REPLACE_WITH_YOUR_DESTINATION"
}Full response contract & request schema
Request JSON Schema
{
"type": "object",
"required": [
"chain",
"asset",
"amount",
"destination_address"
],
"properties": {
"chain": {
"type": "string",
"minLength": 2,
"maxLength": 32
},
"asset": {
"type": "string",
"minLength": 2,
"maxLength": 16
},
"amount": {
"type": "string",
"pattern": "^(?=.*[1-9])(?:0|[1-9]\\d{0,17})(?:\\.\\d{1,18})?$"
},
"destination_address": {
"type": "string",
"minLength": 8,
"maxLength": 255
},
"memo": {
"type": [
"string",
"null"
],
"maxLength": 255
}
}
}HTTP 201 · Payout accepted by BlockPN and persisted locally.
{
"allOf": [
{
"type": "object",
"required": [
"object",
"id",
"status",
"chain",
"asset",
"amount",
"created_at"
],
"properties": {
"object": {
"type": "string",
"const": "payout"
},
"id": {
"type": "string",
"pattern": "^po_[a-z0-9]+$"
},
"status": {
"type": "string",
"enum": [
"processing",
"pending",
"broadcast",
"confirmed",
"failed",
"cancelled"
]
},
"chain": {
"type": "string"
},
"asset": {
"type": "string"
},
"amount": {
"type": "string",
"pattern": "^(?=.*[1-9])(?:0|[1-9]\\d{0,17})(?:\\.\\d{1,18})?$"
},
"tx_hash": {
"type": "string"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"submitted_at": {
"type": "string",
"format": "date-time"
},
"confirmed_at": {
"type": "string",
"format": "date-time"
}
}
},
{
"type": "object",
"required": [
"destination_address"
],
"properties": {
"destination_address": {
"type": "string"
}
}
}
]
}HTTP 400 · Missing or malformed Idempotency-Key header.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 401 · Missing, invalid, expired, or revoked API key.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 403 · API key lacks the required scope.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 409 · Resource state conflict or idempotency key reuse with different request data.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 422 · Request validation failed.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 502 · An upstream payout, refund, or mail provider rejected the operation.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}ENDPOINT REFERENCE
Webhooks
GET
/v1/webhooksList webhook endpoints
See the webhook receivers you have registered.
List webhook endpoints
Required scope webhooks:read
Full response contract & request schema
HTTP 200 · Webhook endpoint list. Signing secrets are never returned.
{
"type": "object",
"required": [
"object",
"data"
],
"properties": {
"object": {
"type": "string",
"const": "list"
},
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"object",
"id",
"url",
"events",
"status",
"created_at"
],
"properties": {
"object": {
"type": "string",
"const": "webhook_endpoint"
},
"id": {
"type": "string",
"pattern": "^wh_[a-z0-9]+$"
},
"url": {
"type": "string",
"format": "uri"
},
"events": {
"type": "array",
"items": {
"type": "string",
"enum": [
"order.paid",
"order.failed",
"order.refunded",
"delivery.completed",
"delivery.failed"
]
}
},
"description": {
"type": [
"string",
"null"
]
},
"status": {
"type": "string",
"enum": [
"active",
"disabled"
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
}
}HTTP 401 · Missing, invalid, expired, or revoked API key.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 403 · API key lacks the required scope.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}POST
/v1/webhooksCreate a webhook endpoint
Register an HTTPS address that will receive the events you select. Save its returned signing secret.
Create a webhook endpoint
Required scope webhooks:write Changes live data
| Field | What to send |
|---|---|
Idempotency-Keyheader · Required | A unique request label. Reuse it when retrying the exact same change; use a new one for a different change.Unique key for this mutation. Exact replays return the stored response for 24 hours.string · min characters: 8 · max characters: 255 |
urlbody · Required | Your publicly reachable HTTPS webhook receiver.Your publicly reachable HTTPS webhook receiver.string · uri · max characters: 500 |
eventsbody · Required | The events you want this receiver to receive.The events you want this receiver to receive.array · min items: 1 |
descriptionbody · Optional | The product description.The product description.string or null · max characters: 255 |
Example JSON body · replace sample values
{
"url": "https://your-app.example/webhooks/sellix",
"events": [
"order.paid"
]
}Full response contract & request schema
Request JSON Schema
{
"type": "object",
"required": [
"url",
"events"
],
"properties": {
"url": {
"type": "string",
"format": "uri",
"maxLength": 500
},
"events": {
"type": "array",
"minItems": 1,
"uniqueItems": true,
"items": {
"type": "string",
"enum": [
"order.paid",
"order.failed",
"order.refunded",
"delivery.completed",
"delivery.failed"
]
}
},
"description": {
"type": [
"string",
"null"
],
"maxLength": 255
}
}
}HTTP 201 · Webhook endpoint and one-time signing secret.
{
"allOf": [
{
"type": "object",
"required": [
"object",
"id",
"url",
"events",
"status",
"created_at"
],
"properties": {
"object": {
"type": "string",
"const": "webhook_endpoint"
},
"id": {
"type": "string",
"pattern": "^wh_[a-z0-9]+$"
},
"url": {
"type": "string",
"format": "uri"
},
"events": {
"type": "array",
"items": {
"type": "string",
"enum": [
"order.paid",
"order.failed",
"order.refunded",
"delivery.completed",
"delivery.failed"
]
}
},
"description": {
"type": [
"string",
"null"
]
},
"status": {
"type": "string",
"enum": [
"active",
"disabled"
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
},
{
"type": "object",
"required": [
"signing_secret"
],
"properties": {
"signing_secret": {
"type": "string",
"pattern": "^whsec_[A-Za-z0-9]{40}$"
}
}
}
]
}HTTP 400 · Missing or malformed Idempotency-Key header.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 401 · Missing, invalid, expired, or revoked API key.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 403 · API key lacks the required scope.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 409 · Resource state conflict or idempotency key reuse with different request data.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 422 · Request validation failed.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}POST
/v1/webhooks/{id}/testQueue a signed test event
Queue a signed test event to an existing receiver. A queued response means the delivery job was accepted, not that your receiver has received it yet.
Queue a signed test event
Required scope webhooks:write Changes live data
| Field | What to send |
|---|---|
idpath · Required | The resource ID returned by a list or create request.The resource ID returned by a list or create request.string Pattern: ^wh_[a-z0-9]+$ |
Idempotency-Keyheader · Required | A unique request label. Reuse it when retrying the exact same change; use a new one for a different change.Unique key for this mutation. Exact replays return the stored response for 24 hours.string · min characters: 8 · max characters: 255 |
eventbody · Optional | Send this field using the format and limits listed below.Send this field using the format and limits listed below.string Allowed: order.paid, order.failed, order.refunded, delivery.completed, delivery.failed |
Example JSON body · replace sample values
{}Full response contract & request schema
Request JSON Schema
{
"type": "object",
"properties": {
"event": {
"type": "string",
"enum": [
"order.paid",
"order.failed",
"order.refunded",
"delivery.completed",
"delivery.failed"
]
}
}
}HTTP 202 · Test event queued for normal delivery and retries.
{
"type": "object",
"required": [
"queued",
"event_id",
"delivery_id"
],
"properties": {
"queued": {
"type": "boolean",
"const": true
},
"event_id": {
"type": "string",
"format": "uuid"
},
"delivery_id": {
"type": "integer"
}
}
}HTTP 400 · Missing or malformed Idempotency-Key header.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 401 · Missing, invalid, expired, or revoked API key.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 403 · API key lacks the required scope.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 404 · Resource does not exist within the key's tenant and shop scope.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 409 · Resource state conflict or idempotency key reuse with different request data.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 422 · Request validation failed.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}DELETE
/v1/webhooks/{id}Delete a webhook endpoint
Remove a webhook receiver so new events are no longer sent to it.
Delete a webhook endpoint
Required scope webhooks:write Changes live data
| Field | What to send |
|---|---|
idpath · Required | The resource ID returned by a list or create request.The resource ID returned by a list or create request.string Pattern: ^wh_[a-z0-9]+$ |
Idempotency-Keyheader · Required | A unique request label. Reuse it when retrying the exact same change; use a new one for a different change.Unique key for this mutation. Exact replays return the stored response for 24 hours.string · min characters: 8 · max characters: 255 |
Full response contract & request schema
HTTP 200 · Webhook endpoint deleted.
{
"type": "object",
"required": [
"id",
"deleted"
],
"properties": {
"id": {
"type": "string"
},
"deleted": {
"type": "boolean",
"const": true
}
}
}HTTP 400 · Missing or malformed Idempotency-Key header.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 401 · Missing, invalid, expired, or revoked API key.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 403 · API key lacks the required scope.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 404 · Resource does not exist within the key's tenant and shop scope.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 409 · Resource state conflict or idempotency key reuse with different request data.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}ENDPOINT REFERENCE
Api-keys
GET
/v1/api-keysList API key metadata
Inspect API key metadata. Existing secret tokens are not returned.
List API key metadata
Required scope admin
Full response contract & request schema
HTTP 200 · API key metadata without plaintext secrets.
{
"type": "object",
"required": [
"object",
"data"
],
"properties": {
"object": {
"type": "string",
"const": "list"
},
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"object",
"id",
"name",
"prefix",
"abilities",
"rate_limit_per_minute",
"created_at"
],
"properties": {
"object": {
"type": "string",
"const": "api_key"
},
"id": {
"type": "string",
"pattern": "^apik_[a-z0-9]+$"
},
"name": {
"type": "string"
},
"prefix": {
"type": "string"
},
"abilities": {
"type": "array",
"items": {
"type": "string",
"description": "Granular abilities are required for new resources. Legacy read/write values retain Orders-only compatibility; admin grants every ability.",
"enum": [
"read",
"write",
"admin",
"products:read",
"products:write",
"orders:read",
"orders:write",
"customers:read",
"payouts:read",
"payouts:write",
"webhooks:read",
"webhooks:write",
"mcp:read",
"mcp:write",
"mcp:publish",
"shops:create"
]
}
},
"rate_limit_per_minute": {
"type": "integer",
"minimum": 10,
"maximum": 600
},
"last_used_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expires_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"revoked_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
}
}HTTP 401 · Missing, invalid, expired, or revoked API key.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 403 · API key lacks the required scope.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}POST
/v1/api-keysCreate an API key
Create a real API key with the selected permissions. Copy its secret from the response when it is shown.
Create an API key
Required scope admin Changes live data
| Field | What to send |
|---|---|
Idempotency-Keyheader · Required | A unique request label. Reuse it when retrying the exact same change; use a new one for a different change.Unique key for this mutation. Exact replays return the stored response for 24 hours.string · min characters: 8 · max characters: 255 |
namebody · Required | The name people see.The name people see.string · max characters: 80 |
abilitiesbody · Required | Which actions this new API key may perform.Which actions this new API key may perform.array · min items: 1 |
expires_in_daysbody · Optional | How long the new API key should remain usable.How long the new API key should remain usable.integer · min: 1 · max: 90 · default: 90 |
rate_limit_per_minutebody · Optional | The maximum requests this key can make per minute.The maximum requests this key can make per minute.integer · min: 10 · max: 600 · default: 60 |
Example JSON body · replace sample values
{
"name": "Example product",
"abilities": [
"products:read"
]
}Full response contract & request schema
Request JSON Schema
{
"type": "object",
"required": [
"name",
"abilities"
],
"properties": {
"name": {
"type": "string",
"maxLength": 80
},
"abilities": {
"type": "array",
"minItems": 1,
"uniqueItems": true,
"items": {
"type": "string",
"description": "Granular abilities are required for new resources. Legacy read/write values retain Orders-only compatibility; admin grants every ability.",
"enum": [
"read",
"write",
"admin",
"products:read",
"products:write",
"orders:read",
"orders:write",
"customers:read",
"payouts:read",
"payouts:write",
"webhooks:read",
"webhooks:write",
"mcp:read",
"mcp:write",
"mcp:publish",
"shops:create"
]
}
},
"expires_in_days": {
"type": "integer",
"minimum": 1,
"maximum": 90,
"default": 90
},
"rate_limit_per_minute": {
"type": "integer",
"minimum": 10,
"maximum": 600,
"default": 60
}
}
}HTTP 201 · API key with one-time plaintext secret.
{
"allOf": [
{
"type": "object",
"required": [
"object",
"id",
"name",
"prefix",
"abilities",
"rate_limit_per_minute",
"created_at"
],
"properties": {
"object": {
"type": "string",
"const": "api_key"
},
"id": {
"type": "string",
"pattern": "^apik_[a-z0-9]+$"
},
"name": {
"type": "string"
},
"prefix": {
"type": "string"
},
"abilities": {
"type": "array",
"items": {
"type": "string",
"description": "Granular abilities are required for new resources. Legacy read/write values retain Orders-only compatibility; admin grants every ability.",
"enum": [
"read",
"write",
"admin",
"products:read",
"products:write",
"orders:read",
"orders:write",
"customers:read",
"payouts:read",
"payouts:write",
"webhooks:read",
"webhooks:write",
"mcp:read",
"mcp:write",
"mcp:publish",
"shops:create"
]
}
},
"rate_limit_per_minute": {
"type": "integer",
"minimum": 10,
"maximum": 600
},
"last_used_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expires_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"revoked_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
},
{
"type": "object",
"required": [
"secret"
],
"properties": {
"secret": {
"type": "string",
"pattern": "^sk_[A-Za-z0-9]{40}$"
}
}
}
]
}HTTP 400 · Missing or malformed Idempotency-Key header.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 401 · Missing, invalid, expired, or revoked API key.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 403 · API key lacks the required scope.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 409 · Resource state conflict or idempotency key reuse with different request data.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 422 · Request validation failed.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}DELETE
/v1/api-keys/{id}Revoke an API key
Revoke this API key. Requests using it will stop working.
Revoke an API key
Required scope admin Changes live data
| Field | What to send |
|---|---|
idpath · Required | The resource ID returned by a list or create request.The resource ID returned by a list or create request.string Pattern: ^apik_[a-z0-9]+$ |
Idempotency-Keyheader · Required | A unique request label. Reuse it when retrying the exact same change; use a new one for a different change.Unique key for this mutation. Exact replays return the stored response for 24 hours.string · min characters: 8 · max characters: 255 |
Full response contract & request schema
HTTP 200 · API key revoked.
{
"type": "object",
"required": [
"id",
"revoked"
],
"properties": {
"id": {
"type": "string",
"pattern": "^apik_[a-z0-9]+$"
},
"revoked": {
"type": "boolean",
"const": true
}
}
}HTTP 400 · Missing or malformed Idempotency-Key header.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 401 · Missing, invalid, expired, or revoked API key.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 403 · API key lacks the required scope.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 404 · Resource does not exist within the key's tenant and shop scope.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}HTTP 409 · Resource state conflict or idempotency key reuse with different request data.
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message",
"trace_id"
],
"properties": {
"type": {
"type": "string"
},
"message": {
"type": "string"
},
"trace_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}