{"openapi":"3.1.0","info":{"title":"Hidden API","version":"1.0.0","description":"REST API for Hidden stores. Public endpoints need no key. Authenticated endpoints take a personal access key as `Authorization: Bearer hsk_live_…` with the scope each operation names (`x-scope`). Every failure has the shape `{ ok: false, error: { code, message, field? } }`. Lists are cursor-paginated (`limit`, `cursor`, `nextCursor`, `hasMore`). POST operations marked `x-idempotency-key` honour an `Idempotency-Key` header. Keys allow 120 requests per minute; every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset.","termsOfService":"https://sellhidden.com/terms","contact":{"name":"Hidden developer support","url":"https://sellhidden.com/support?as=developer"}},"externalDocs":{"description":"Developer documentation","url":"https://docs.sellhidden.com/"},"servers":[{"url":"https://api.sellhidden.com/v1"}],"tags":[{"name":"Public"},{"name":"Products","description":"Your catalogue as the seller sees it: hidden products included, every variation with its deliverables, key pools and order counts. Writes follow the dashboard rules: plan limits, unique slugs, deliverable checks, the 2,000,000-key cap per variation and an audit log entry."},{"name":"Categories","description":"Up to 100 categories per store. Deleting one leaves its products uncategorised."},{"name":"Coupons","description":"Discount codes. The code and the discount are fixed once created (orders keep what they used); every other rule can change."},{"name":"Orders","description":"Orders are created by buyers at checkout. The API reads them and runs the same actions as the dashboard: approve or reject a manual payment, cancel, redeliver, resend the receipt, refund to store balance, keep a private note. Every order has a short reference in `publicRef` (for example `7K2Q-9XHD`, or `NOVA-7K2Q-9XHD` when the store has an order ID prefix): it is what buyers see on their order page and receipts, and it works wherever `{id}` appears in an order path, next to the long `id`."},{"name":"Subscriptions","description":"Buyers of a variation billed per period (weekly to yearly). Renewals are fresh orders the buyer pays from the renewal email or the order page, or from their store balance; after the grace period access ends by itself. The subscription.* webhook events carry the same shape."},{"name":"Customers","description":"Everyone who checked out or signed in on your storefront, with lifetime aggregates."},{"name":"Reviews","description":"Buyer reviews with unmasked emails. Reviews are never deleted: hide spam instead, or answer in public."},{"name":"Tickets","description":"Support threads buyers open from their order or account. Replies email the buyer."},{"name":"Store","description":"Your store as its seller sees it, and the basic settings. Themes, payment methods, payouts and domains stay in the dashboard."},{"name":"Webhooks","description":"Manage the endpoints that receive signed events (the same ones as Developers, Webhooks). The signing secret is returned once, on create and on rotate."},{"name":"Analytics","description":"Revenue and order statistics."},{"name":"Your key","description":""}],"paths":{"/public/products/{storeSlug}":{"get":{"operationId":"public-products","tags":["Public"],"summary":"Products of a store","security":[],"parameters":[{"name":"storeSlug","in":"path","required":true,"schema":{"type":"string"}},{"name":"categorySlug","in":"query","required":false,"description":"Only products in this category.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size. Default 50.","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"description":"nextCursor from the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true}}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public/products/{storeSlug}/{slug}":{"get":{"operationId":"public-product","tags":["Public"],"summary":"One product","security":[],"parameters":[{"name":"storeSlug","in":"path","required":true,"schema":{"type":"string"}},{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true}}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public/categories/{storeSlug}":{"get":{"operationId":"public-categories","tags":["Public"],"summary":"Categories of a store","security":[],"parameters":[{"name":"storeSlug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true}}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public/reviews/{storeSlug}":{"get":{"operationId":"public-reviews","tags":["Public"],"summary":"Visible reviews","security":[],"parameters":[{"name":"storeSlug","in":"path","required":true,"schema":{"type":"string"}},{"name":"productSlug","in":"query","required":false,"description":"Only reviews of this product.","schema":{"type":"string"}},{"name":"rating","in":"query","required":false,"description":"Only this star rating.","schema":{"type":"integer","minimum":1,"maximum":5}},{"name":"limit","in":"query","required":false,"description":"Page size. Default 20.","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"description":"nextCursor from the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true}}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public/recent-sales/{storeSlug}":{"get":{"operationId":"public-recent-sales","tags":["Public"],"summary":"Recent sales","security":[],"parameters":[{"name":"storeSlug","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size. Default 10.","schema":{"type":"integer","minimum":1,"maximum":25}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true}}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/products":{"get":{"operationId":"products-list","tags":["Products"],"summary":"List products","security":[{"bearerKey":["products:read"]}],"x-scope":"products:read","parameters":[{"name":"active","in":"query","required":false,"description":"Only live or only hidden products.","schema":{"type":"boolean"}},{"name":"categoryId","in":"query","required":false,"description":"Only this category.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"Title or slug contains this text.","schema":{"type":"string"}},{"name":"deliveryType","in":"query","required":false,"description":"Primary delivery type (file, text, keys, link, discord, dynamic).","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size. Default 50.","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"description":"nextCursor from the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true},"example":"{ \"ok\": true, \"products\": [ { \"id\": \"clx…\", \"slug\": \"lifetime-license\", \"name\": \"Lifetime license\", \"active\": true, \"displayPriceUsd\": 29, \"stock\": 120, \"variations\": [ … ], … } ], \"nextCursor\": null, \"hasMore\": false }"}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"products-create","tags":["Products"],"summary":"Create a product","description":"A product has at least one variation. Send `variants` (recommended), or the short form `priceUsd` + `deliveryType` + `deliveryData` (+ `keys` for a key product) for a single-price product.","security":[{"bearerKey":["products:write"]}],"x-scope":"products:write","x-idempotency-key":true,"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Replays the stored response for 24 h when the same key and body are sent again."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","description":"Up to 120 characters."},"slug":{"type":"string","description":"URL slug; derived from the title when omitted and made unique."},"description":{"type":"string","description":"Markdown or plain text, up to 20,000 characters."},"imageUrl":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"https URL or an uploaded /media URL."},"categoryId":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"One of your categories."},"variants":{"type":"array","items":{"type":"object"},"description":"Variations (see Variations below). At least one."},"active":{"type":"boolean","description":"Live on the storefront. Default true. Counts against the plan's product limit."},"sortOrder":{"type":"integer","description":"Lower first. Left out: placed after your other products."},"seoTitle":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Up to 70 characters."},"seoDescription":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Up to 200 characters."}},"required":["title"]},"example":{"title":"Lifetime license","description":"One key, forever.","variants":[{"label":"1 device","priceUsd":29,"deliverables":[{"type":"keys","keys":["AAAA-1111","BBBB-2222"]}]}]}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true},"example":"{ \"ok\": true, \"product\": { \"id\": \"clx…\", \"slug\": \"lifetime-license\", \"active\": true, \"variations\": [ { \"id\": \"clx…\", \"label\": \"1 device\", \"priceUsd\": 29, \"stock\": 2, \"unusedKeys\": 2, \"deliverables\": [ { \"type\": \"keys\", \"data\": \"\", \"keyOrder\": \"fifo\" } ] } ], … } }"}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"idempotency_conflict: the Idempotency-Key was used with a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/products/{id}":{"get":{"operationId":"products-get","tags":["Products"],"summary":"Get a product","security":[{"bearerKey":["products:read"]}],"x-scope":"products:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true}}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"products-update","tags":["Products"],"summary":"Update a product","description":"Only the fields you send change. `variants` replaces the whole variation list (variations left out are removed); to change one variation use the Variations endpoints instead.","security":[{"bearerKey":["products:write"]}],"x-scope":"products:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"slug":{"type":"string"},"description":{"type":"string"},"imageUrl":{"oneOf":[{"type":"string"},{"type":"null"}]},"categoryId":{"oneOf":[{"type":"string"},{"type":"null"}]},"active":{"type":"boolean","description":"Activating respects the plan limit; a product removed by the platform stays off."},"sortOrder":{"type":"integer"},"seoTitle":{"oneOf":[{"type":"string"},{"type":"null"}]},"seoDescription":{"oneOf":[{"type":"string"},{"type":"null"}]},"variants":{"type":"array","items":{"type":"object"},"description":"Full list of variations (with `id` for existing ones)."}}},"example":{"active":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true}}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"products-delete","tags":["Products"],"summary":"Delete a product","description":"Deleted for good when it was never ordered; archived (hidden, kept for order history) otherwise. `result` says which.","security":[{"bearerKey":["products:write"]}],"x-scope":"products:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true},"example":"{ \"ok\": true, \"id\": \"clx…\", \"result\": \"deleted\" }"}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/products/{id}/variations":{"get":{"operationId":"variations-list","tags":["Products"],"summary":"List variations","security":[{"bearerKey":["products:read"]}],"x-scope":"products:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true}}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"variations-create","tags":["Products"],"summary":"Add a variation","security":[{"bearerKey":["products:write"]}],"x-scope":"products:write","x-idempotency-key":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Replays the stored response for 24 h when the same key and body are sent again."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string","description":"Shown to buyers. Required when the product has more than one variation."},"priceUsd":{"type":"number","description":"Price in USD."},"compareAtUsd":{"oneOf":[{"type":"number"},{"type":"null"}],"description":"Old price shown struck through."},"stock":{"oneOf":[{"type":"integer"},{"type":"null"}],"description":"Units left; null = unlimited. Ignored for variations that deliver keys (the pool is the stock)."},"description":{"type":"string","description":"Short line under the label."},"active":{"type":"boolean","description":"Hidden variations cannot be bought. Default true."},"minPerOrder":{"type":"integer","minimum":1,"maximum":100,"description":"Fewest units per order. Default 1."},"maxPerOrder":{"oneOf":[{"type":"integer","minimum":1,"maximum":100},{"type":"null"}],"description":"Most units per order; null = no limit."},"billingInterval":{"oneOf":[{"type":"string","enum":["week","month","quarter","year"]},{"type":"null"}],"description":"A subscription billed per period; null (default) = one-time purchase."},"trialDays":{"type":"integer","minimum":0,"maximum":365,"description":"Subscription: free trial days before the first payment. Default 0."},"renewalDelivers":{"type":"boolean","description":"Subscription: deliver again on every renewal (default true); false only extends access."},"deliverables":{"type":"array","items":{"type":"object"},"description":"What the buyer receives: [{ type: file | text | keys | link | discord | dynamic, data, keyOrder?: fifo | lifo | random, keys?: string[] }]. Each type at most once. Omitted on an existing variation = unchanged."}},"required":["label","priceUsd"]},"example":{"label":"5 devices","priceUsd":49,"compareAtUsd":69,"maxPerOrder":3,"deliverables":[{"type":"keys"}]}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true}}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"idempotency_conflict: the Idempotency-Key was used with a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/products/{id}/variations/{variationId}":{"get":{"operationId":"variations-get","tags":["Products"],"summary":"Get a variation","security":[{"bearerKey":["products:read"]}],"x-scope":"products:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"variationId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true}}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"variations-update","tags":["Products"],"summary":"Update a variation","description":"Only the fields you send change. Sending `deliverables` replaces that variation's deliverables.","security":[{"bearerKey":["products:write"]}],"x-scope":"products:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"variationId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string","description":"Shown to buyers. Required when the product has more than one variation."},"priceUsd":{"type":"number","description":"Price in USD."},"compareAtUsd":{"oneOf":[{"type":"number"},{"type":"null"}],"description":"Old price shown struck through."},"stock":{"oneOf":[{"type":"integer"},{"type":"null"}],"description":"Units left; null = unlimited. Ignored for variations that deliver keys (the pool is the stock)."},"description":{"type":"string","description":"Short line under the label."},"active":{"type":"boolean","description":"Hidden variations cannot be bought. Default true."},"minPerOrder":{"type":"integer","minimum":1,"maximum":100,"description":"Fewest units per order. Default 1."},"maxPerOrder":{"oneOf":[{"type":"integer","minimum":1,"maximum":100},{"type":"null"}],"description":"Most units per order; null = no limit."},"billingInterval":{"oneOf":[{"type":"string","enum":["week","month","quarter","year"]},{"type":"null"}],"description":"A subscription billed per period; null (default) = one-time purchase."},"trialDays":{"type":"integer","minimum":0,"maximum":365,"description":"Subscription: free trial days before the first payment. Default 0."},"renewalDelivers":{"type":"boolean","description":"Subscription: deliver again on every renewal (default true); false only extends access."},"deliverables":{"type":"array","items":{"type":"object"},"description":"What the buyer receives: [{ type: file | text | keys | link | discord | dynamic, data, keyOrder?: fifo | lifo | random, keys?: string[] }]. Each type at most once. Omitted on an existing variation = unchanged."}}},"example":{"priceUsd":39,"minPerOrder":1,"maxPerOrder":5}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true}}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"variations-delete","tags":["Products"],"summary":"Remove a variation","description":"A product keeps at least one variation (409 otherwise). A variation that was ordered is archived so its orders still deliver.","security":[{"bearerKey":["products:write"]}],"x-scope":"products:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"variationId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true}}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/products/{id}/keys":{"get":{"operationId":"keys-list","tags":["Products"],"summary":"Pool counts and unused keys","description":"`pool` holds the counts (unused, used, shared pool, per variation); `keys` is one page of unused keys of one pool, oldest first.","security":[{"bearerKey":["products:read"]}],"x-scope":"products:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"variationId","in":"query","required":false,"description":"Which pool. Default: the product's only variation, else the product-wide shared pool.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"Key value contains this text.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size. Default 100.","schema":{"type":"integer","minimum":1,"maximum":1000}},{"name":"cursor","in":"query","required":false,"description":"nextCursor from the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true},"example":"{ \"ok\": true, \"pool\": { \"unused\": 1200, \"used\": 310, \"shared\": 0, \"variations\": { \"clx…\": 1200 } }, \"variationId\": \"clx…\", \"keys\": [ { \"id\": \"k…\", \"value\": \"AAAA-1111\", \"createdAt\": \"…\" } ], \"nextCursor\": \"…\", \"hasMore\": true }"}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"keys-add","tags":["Products"],"summary":"Add keys in bulk","description":"Up to 50,000 keys per request (send big lists in batches); a pool holds up to 2,000,000 unused keys (400 pool_full past that). Keys already in the product's pools and repeats in the list are skipped. Orders that were waiting for keys are delivered, oldest first.","security":[{"bearerKey":["products:write"]}],"x-scope":"products:write","x-idempotency-key":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Replays the stored response for 24 h when the same key and body are sent again."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"keys":{"type":"array","items":{"type":"string"},"description":"1 to 50,000 keys, up to 50,000 characters each."},"variationId":{"type":"string","description":"Which pool. Default: the product's only variation, else the shared pool."}},"required":["keys"]},"example":{"keys":["AAAA-1111","BBBB-2222"]}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true},"example":"{ \"ok\": true, \"added\": 2, \"skipped\": 0, \"skippedExisting\": 0, \"skippedRepeated\": 0, \"inOtherProducts\": 0, \"redelivered\": 0, \"stillWaiting\": 0, \"message\": null, \"pool\": { \"unused\": 1202, \"used\": 310, \"shared\": 0, \"variations\": { \"clx…\": 1202 } } }"}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"idempotency_conflict: the Idempotency-Key was used with a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"keys-remove","tags":["Products"],"summary":"Remove unused keys","description":"Removes up to 500 unused keys by id or by value. Keys already handed to a buyer are never removed.","security":[{"bearerKey":["products:write"]}],"x-scope":"products:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string"},"description":"Key ids from the list endpoint."},"values":{"type":"array","items":{"type":"string"},"description":"Key values."}}},"example":{"values":["AAAA-1111"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true},"example":"{ \"ok\": true, \"removed\": 1, \"pool\": { … } }"}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/products/{id}/stock":{"post":{"operationId":"stock-set","tags":["Products"],"summary":"Set or adjust stock","description":"Sets (`stock`) or shifts (`adjust`, can be negative) the stock of one variation. Variations that deliver keys answer 409 stock_from_keys: add or remove keys instead.","security":[{"bearerKey":["products:write"]}],"x-scope":"products:write","x-idempotency-key":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Replays the stored response for 24 h when the same key and body are sent again."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"variationId":{"type":"string","description":"Default: the product's only variation."},"stock":{"oneOf":[{"type":"integer"},{"type":"null"}],"description":"Absolute units; null = unlimited."},"adjust":{"type":"integer","description":"Relative change, e.g. -3."}}},"example":{"adjust":10}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true}}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"idempotency_conflict: the Idempotency-Key was used with a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/categories":{"get":{"operationId":"categories-list","tags":["Categories"],"summary":"List categories","security":[{"bearerKey":["categories:read"]}],"x-scope":"categories:read","parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true},"example":"{ \"ok\": true, \"categories\": [ { \"id\": \"clx…\", \"name\": \"Software\", \"slug\": \"software\", \"position\": 0, \"productCount\": 12, \"activeProductCount\": 11, \"createdAt\": \"…\" } ] }"}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"categories-create","tags":["Categories"],"summary":"Create a category","security":[{"bearerKey":["categories:write"]}],"x-scope":"categories:write","x-idempotency-key":true,"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Replays the stored response for 24 h when the same key and body are sent again."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Unique in the store, up to 60 characters."},"slug":{"type":"string","description":"Derived from the name when omitted."}},"required":["name"]},"example":{"name":"Software"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true}}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"idempotency_conflict: the Idempotency-Key was used with a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/categories/{id}":{"get":{"operationId":"categories-get","tags":["Categories"],"summary":"Get a category","security":[{"bearerKey":["categories:read"]}],"x-scope":"categories:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true}}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"categories-update","tags":["Categories"],"summary":"Update a category","security":[{"bearerKey":["categories:write"]}],"x-scope":"categories:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"},"position":{"type":"integer","description":"Display position, 0 first."}}},"example":{"name":"Licenses"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true}}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"categories-delete","tags":["Categories"],"summary":"Delete a category","security":[{"bearerKey":["categories:write"]}],"x-scope":"categories:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true},"example":"{ \"ok\": true, \"id\": \"clx…\", \"uncategorisedProducts\": 3 }"}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/categories/reorder":{"post":{"operationId":"categories-reorder","tags":["Categories"],"summary":"Reorder categories","security":[{"bearerKey":["categories:write"]}],"x-scope":"categories:write","x-idempotency-key":true,"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Replays the stored response for 24 h when the same key and body are sent again."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"order":{"type":"array","items":{"type":"string"},"description":"Category ids in display order."}},"required":["order"]},"example":{"order":["clx1","clx2"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true}}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"idempotency_conflict: the Idempotency-Key was used with a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/coupons":{"get":{"operationId":"coupons-list","tags":["Coupons"],"summary":"List coupons","security":[{"bearerKey":["coupons:read"]}],"x-scope":"coupons:read","parameters":[{"name":"active","in":"query","required":false,"description":"Only usable codes (active and not expired), or only unusable ones.","schema":{"type":"boolean"}},{"name":"code","in":"query","required":false,"description":"Code contains this text.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size. Default 50.","schema":{"type":"integer","minimum":1,"maximum":200}},{"name":"cursor","in":"query","required":false,"description":"nextCursor from the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true},"example":"{ \"ok\": true, \"coupons\": [ { \"id\": \"clx…\", \"code\": \"LAUNCH20\", \"type\": \"percent\", \"value\": 20, \"minOrderUsd\": null, \"maxUses\": 100, \"usedCount\": 12, \"active\": true, \"expiresAt\": null, \"createdAt\": \"…\" } ], \"nextCursor\": null, \"hasMore\": false }"}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"coupons-create","tags":["Coupons"],"summary":"Create a coupon","security":[{"bearerKey":["coupons:write"]}],"x-scope":"coupons:write","x-idempotency-key":true,"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Replays the stored response for 24 h when the same key and body are sent again."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"2-40 characters: letters, digits, - and _. Stored upper-case."},"percentOff":{"type":"integer","minimum":1,"maximum":100,"description":"Either this or amountOffUsd."},"amountOffUsd":{"type":"number","description":"Fixed discount in USD."},"maxUses":{"oneOf":[{"type":"integer"},{"type":"null"}],"description":"Total uses; null = unlimited."},"perCustomerLimit":{"oneOf":[{"type":"integer","minimum":1,"maximum":1000},{"type":"null"}],"description":"Uses per buyer email."},"firstOrderOnly":{"type":"boolean","description":"Only buyers who never paid here."},"minOrderUsd":{"oneOf":[{"type":"number"},{"type":"null"}],"description":"Smallest cart subtotal (before the discount)."},"maxDiscountUsd":{"oneOf":[{"type":"number"},{"type":"null"}],"description":"Cap on the discount."},"startsAt":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Not valid before."},"expiresAt":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Not valid after."},"productIds":{"type":"array","items":{"type":"string"},"description":"Only these products (empty = all)."},"categoryIds":{"type":"array","items":{"type":"string"},"description":"Only these categories."},"variantIds":{"type":"array","items":{"type":"string"},"description":"Only these variations."},"paymentMethods":{"type":"array","items":{"type":"string"},"description":"\"crypto\", \"balance\" or a manual payment method id."},"active":{"type":"boolean","description":"Default true."}},"required":["code"]},"example":{"code":"LAUNCH20","percentOff":20,"maxUses":100,"expiresAt":"2026-12-31T23:59:59Z"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true}}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"idempotency_conflict: the Idempotency-Key was used with a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/coupons/{id}":{"get":{"operationId":"coupons-get","tags":["Coupons"],"summary":"Get a coupon","security":[{"bearerKey":["coupons:read"]}],"x-scope":"coupons:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true}}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"coupons-update","tags":["Coupons"],"summary":"Update a coupon","description":"Any rule except code, percentOff and amountOffUsd. null clears a limit or a date; null or [] clears a list.","security":[{"bearerKey":["coupons:write"]}],"x-scope":"coupons:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"active":{"type":"boolean"},"maxUses":{"oneOf":[{"type":"integer"},{"type":"null"}],"description":"Not below the uses so far."},"perCustomerLimit":{"oneOf":[{"type":"integer"},{"type":"null"}]},"firstOrderOnly":{"type":"boolean"},"minOrderUsd":{"oneOf":[{"type":"number"},{"type":"null"}]},"maxDiscountUsd":{"oneOf":[{"type":"number"},{"type":"null"}]},"startsAt":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"expiresAt":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"productIds":{"oneOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"categoryIds":{"oneOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"variantIds":{"oneOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"paymentMethods":{"oneOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]}}},"example":{"active":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true}}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"coupons-delete","tags":["Coupons"],"summary":"Delete a coupon","security":[{"bearerKey":["coupons:write"]}],"x-scope":"coupons:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true}}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/orders":{"get":{"operationId":"orders-list","tags":["Orders"],"summary":"List orders","security":[{"bearerKey":["orders:read"]}],"x-scope":"orders:read","parameters":[{"name":"status","in":"query","required":false,"description":"pending, awaiting_verification, paid, delivered, cancelled, underpaid, oversold, expired, failed, refunded.","schema":{"type":"string"}},{"name":"kind","in":"query","required":false,"description":"Product orders or buyer balance top-ups.","schema":{"type":"string","enum":["product","topup"]}},{"name":"email","in":"query","required":false,"description":"Buyer email contains this text.","schema":{"type":"string"}},{"name":"since","in":"query","required":false,"description":"Created at or after.","schema":{"type":"string","format":"date-time"}},{"name":"until","in":"query","required":false,"description":"Created before.","schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","required":false,"description":"Page size. Default 25.","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"description":"nextCursor from the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true}}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/orders/{id}":{"get":{"operationId":"orders-get","tags":["Orders"],"summary":"Get an order","description":"{id} is the order's `publicRef` (any case, hyphen optional) or its long id.","security":[{"bearerKey":["orders:read"]}],"x-scope":"orders:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true},"example":"{ \"order\": { \"id\": \"clx…\", \"publicRef\": \"7K2Q-9XHD\", \"status\": \"delivered\", … } }"}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/orders/{id}/approve":{"post":{"operationId":"orders-approve","tags":["Orders"],"summary":"Approve a manual payment","description":"Marks the order as paid and delivers it. A manual-method claim is verified (the platform fee is debited from your balance); a crypto order that received part of its total is settled on what arrived; any other payable order is settled as paid outside the platform, which needs `confirmOutsidePlatform: true` while its invoice is still open (409 invoice_open otherwise).","security":[{"bearerKey":["orders:write"]}],"x-scope":"orders:write","x-idempotency-key":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Replays the stored response for 24 h when the same key and body are sent again."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"confirmOutsidePlatform":{"type":"boolean","description":"The buyer paid you directly, outside the platform."}}},"example":{}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true},"example":"{ \"ok\": true, \"credited\": 0, \"feeDebited\": 0.95, \"warning\": null, \"order\": { \"id\": \"clx…\", \"status\": \"delivered\", … } }"}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"idempotency_conflict: the Idempotency-Key was used with a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/orders/{id}/reject":{"post":{"operationId":"orders-reject","tags":["Orders"],"summary":"Reject a manual payment","description":"Cancels a manual-method order with the reason; the buyer is emailed.","security":[{"bearerKey":["orders:write"]}],"x-scope":"orders:write","x-idempotency-key":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Replays the stored response for 24 h when the same key and body are sent again."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","description":"Up to 500 characters, shown to the buyer."}}},"example":{"reason":"No payment received."}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true}}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"idempotency_conflict: the Idempotency-Key was used with a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/orders/{id}/cancel":{"post":{"operationId":"orders-cancel","tags":["Orders"],"summary":"Cancel an order","description":"Pending, awaiting-verification, underpaid or expired orders. An order holding a partial crypto payment answers 409 partial_payment: approve or refund it instead.","security":[{"bearerKey":["orders:write"]}],"x-scope":"orders:write","x-idempotency-key":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Replays the stored response for 24 h when the same key and body are sent again."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","description":"Private, up to 500 characters."}}},"example":{}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true}}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"idempotency_conflict: the Idempotency-Key was used with a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/orders/{id}/redeliver":{"post":{"operationId":"orders-redeliver","tags":["Orders"],"summary":"Run delivery again","description":"For a paid order with items still not delivered (oversold, failed). 409 already_delivered when everything was delivered: resend the receipt instead.","security":[{"bearerKey":["orders:write"]}],"x-scope":"orders:write","x-idempotency-key":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Replays the stored response for 24 h when the same key and body are sent again."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true},"example":"{ \"ok\": true, \"delivered\": 2, \"failed\": 0, \"order\": { … } }"}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"idempotency_conflict: the Idempotency-Key was used with a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/orders/{id}/resend-receipt":{"post":{"operationId":"orders-resend-receipt","tags":["Orders"],"summary":"Resend the receipt","description":"Emails the buyer their receipt and items again. Paid orders only; 3 per order and 60 per store per hour.","security":[{"bearerKey":["orders:write"]}],"x-scope":"orders:write","x-idempotency-key":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Replays the stored response for 24 h when the same key and body are sent again."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true}}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"idempotency_conflict: the Idempotency-Key was used with a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/orders/{id}/refund":{"post":{"operationId":"orders-refund","tags":["Orders"],"summary":"Refund to store balance","description":"The buyer receives store credit. A paid order is refunded in full or for `amountUsd`; an underpaid or expired order with a partial crypto payment hands over everything that arrived.","security":[{"bearerKey":["orders:write"]}],"x-scope":"orders:write","x-idempotency-key":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Replays the stored response for 24 h when the same key and body are sent again."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"amountUsd":{"type":"number","description":"Partial refund of a paid order; default: the full amount."},"reason":{"type":"string","description":"Up to 500 characters."}}},"example":{"reason":"Duplicate purchase."}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true},"example":"{ \"ok\": true, \"creditedUsd\": 29, \"order\": { \"id\": \"clx…\", \"status\": \"refunded\", … } }"}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"idempotency_conflict: the Idempotency-Key was used with a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/orders/{id}/note":{"put":{"operationId":"orders-note","tags":["Orders"],"summary":"Write the private note","description":"A note only you see (API and dashboard, as `order.note`). POST works the same.","security":[{"bearerKey":["orders:write"]}],"x-scope":"orders:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"string","description":"Up to 2,000 characters."}},"required":["note"]},"example":{"note":"Verified by hand on 2026-10-01."}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true}}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"orders-note-delete","tags":["Orders"],"summary":"Remove the private note","security":[{"bearerKey":["orders:write"]}],"x-scope":"orders:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true}}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/subscriptions":{"get":{"operationId":"subscriptions-list","tags":["Subscriptions"],"summary":"List subscriptions","security":[{"bearerKey":["subscriptions:read"]}],"x-scope":"subscriptions:read","parameters":[{"name":"status","in":"query","required":false,"description":"Only this status.","schema":{"type":"string","enum":["trialing","active","past_due","cancelled","expired"]}},{"name":"email","in":"query","required":false,"description":"Buyer email contains this text.","schema":{"type":"string"}},{"name":"product","in":"query","required":false,"description":"Product id.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size. Default 25.","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"description":"nextCursor from the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true},"example":"{ \"ok\": true, \"subscriptions\": [ { \"subscriptionId\": \"clx…\", \"status\": \"active\", \"buyerEmail\": \"jo@example.com\", \"productId\": \"clx…\", \"productTitle\": \"Pro plan\", \"variantId\": \"clx…\", \"quantity\": 1, \"priceUsd\": 9, \"interval\": \"month\", \"currentPeriodStart\": \"…\", \"currentPeriodEnd\": \"…\", \"graceEndsAt\": \"…\", \"cancelAtPeriodEnd\": false, \"autoRenewFromBalance\": false, \"initialOrderId\": \"clx…\", \"renewalOrderId\": null, \"renewals\": 2, \"endedAt\": null, \"createdAt\": \"…\" } ], \"nextCursor\": null, \"hasMore\": false }"}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/subscriptions/{id}":{"get":{"operationId":"subscriptions-get","tags":["Subscriptions"],"summary":"Get a subscription","security":[{"bearerKey":["subscriptions:read"]}],"x-scope":"subscriptions:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true}}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/subscriptions/{id}/cancel":{"post":{"operationId":"subscriptions-cancel","tags":["Subscriptions"],"summary":"Cancel a subscription","description":"By default the buyer keeps access until the period end and nothing more is charged (cancelAtPeriodEnd). With immediate: true access ends now: Discord roles are removed, the pending renewal order is cancelled and subscription.expired is sent with the keys it delivered.","security":[{"bearerKey":["subscriptions:write"]}],"x-scope":"subscriptions:write","x-idempotency-key":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Replays the stored response for 24 h when the same key and body are sent again."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"immediate":{"type":"boolean","description":"End now instead of at the period end. Default false."}}},"example":{}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true}}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"idempotency_conflict: the Idempotency-Key was used with a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/subscriptions/{id}/extend":{"post":{"operationId":"subscriptions-extend","tags":["Subscriptions"],"summary":"Extend by one period","description":"Adds one billing period for free from the current end (or from now when it already ended) and brings an expired or cancelled subscription back, Discord roles included.","security":[{"bearerKey":["subscriptions:write"]}],"x-scope":"subscriptions:write","x-idempotency-key":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Replays the stored response for 24 h when the same key and body are sent again."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true}}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"idempotency_conflict: the Idempotency-Key was used with a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/customers":{"get":{"operationId":"customers-list","tags":["Customers"],"summary":"List customers","security":[{"bearerKey":["customers:read"]}],"x-scope":"customers:read","parameters":[{"name":"email","in":"query","required":false,"description":"Email contains this text.","schema":{"type":"string"}},{"name":"hasAccount","in":"query","required":false,"description":"Only buyers who signed in (or only guests).","schema":{"type":"boolean"}},{"name":"limit","in":"query","required":false,"description":"Page size. Default 50.","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"description":"nextCursor from the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true}}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/customers/{id}":{"get":{"operationId":"customers-get","tags":["Customers"],"summary":"Get a customer","description":"With aggregates and the ten most recent orders.","security":[{"bearerKey":["customers:read"]}],"x-scope":"customers:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true}}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/customers/{id}/balance":{"post":{"operationId":"customers-balance","tags":["Customers"],"summary":"Adjust store balance","description":"Adds (positive) or removes (negative) store credit. The balance never goes below zero (409 balance_too_low). The reason is written to the audit log.","security":[{"bearerKey":["customers:write"]}],"x-scope":"customers:write","x-idempotency-key":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Replays the stored response for 24 h when the same key and body are sent again."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amountUsd":{"type":"number","description":"Positive to credit, negative to debit."},"reason":{"type":"string","description":"Up to 300 characters."}},"required":["amountUsd","reason"]},"example":{"amountUsd":10,"reason":"Goodwill credit for the delayed delivery."}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true},"example":"{ \"ok\": true, \"customer\": { \"id\": \"clx…\", \"email\": \"buyer@example.com\", \"balanceUsd\": 10, … }, \"change\": { \"amountUsd\": 10, \"reason\": \"…\" } }"}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"idempotency_conflict: the Idempotency-Key was used with a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/customers/{id}/ban":{"post":{"operationId":"customers-ban","tags":["Customers"],"summary":"Ban a customer","description":"Blocks the buyer's email at checkout (a blacklist rule you also see under Blacklist in the dashboard).","security":[{"bearerKey":["customers:write"]}],"x-scope":"customers:write","x-idempotency-key":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Replays the stored response for 24 h when the same key and body are sent again."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","description":"Private note, up to 300 characters."}}},"example":{"reason":"Chargeback."}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true},"example":"{ \"ok\": true, \"customer\": { \"id\": \"clx…\", \"email\": \"buyer@example.com\", \"banned\": true }, \"ban\": { \"ruleId\": \"clx…\", \"reason\": \"Chargeback.\", \"createdAt\": \"…\" }, \"alreadyBanned\": false }"}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"idempotency_conflict: the Idempotency-Key was used with a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"customers-unban","tags":["Customers"],"summary":"Lift a ban","security":[{"bearerKey":["customers:write"]}],"x-scope":"customers:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true}}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/reviews":{"get":{"operationId":"reviews-list","tags":["Reviews"],"summary":"List reviews","security":[{"bearerKey":["reviews:read"]}],"x-scope":"reviews:read","parameters":[{"name":"productId","in":"query","required":false,"description":"Only this product.","schema":{"type":"string"}},{"name":"rating","in":"query","required":false,"description":"Only this rating.","schema":{"type":"integer","minimum":1,"maximum":5}},{"name":"visible","in":"query","required":false,"description":"Only shown or only hidden reviews.","schema":{"type":"boolean"}},{"name":"limit","in":"query","required":false,"description":"Page size. Default 50.","schema":{"type":"integer","minimum":1,"maximum":1000}},{"name":"cursor","in":"query","required":false,"description":"nextCursor from the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true}}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/reviews/{id}":{"get":{"operationId":"reviews-get","tags":["Reviews"],"summary":"Get a review","security":[{"bearerKey":["reviews:read"]}],"x-scope":"reviews:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true}}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"reviews-visibility","tags":["Reviews"],"summary":"Hide or show a review","security":[{"bearerKey":["reviews:write"]}],"x-scope":"reviews:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"visible":{"type":"boolean","description":"false hides it from the storefront."}},"required":["visible"]},"example":{"visible":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true}}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/reviews/{id}/reply":{"put":{"operationId":"reviews-reply","tags":["Reviews"],"summary":"Reply in public","description":"Writes or edits the store's reply under the review. The buyer is emailed once per review, on the first reply. Automatic ratings cannot be answered (409 review_automatic). POST works the same.","security":[{"bearerKey":["reviews:write"]}],"x-scope":"reviews:write","x-idempotency-key":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Replays the stored response for 24 h when the same key and body are sent again."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reply":{"type":"string","description":"Up to 1,000 characters."}},"required":["reply"]},"example":{"reply":"Thanks for the kind words!"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true}}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"idempotency_conflict: the Idempotency-Key was used with a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"reviews-reply-delete","tags":["Reviews"],"summary":"Remove the reply","security":[{"bearerKey":["reviews:write"]}],"x-scope":"reviews:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true}}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tickets":{"get":{"operationId":"tickets-list","tags":["Tickets"],"summary":"List tickets","security":[{"bearerKey":["tickets:read"]}],"x-scope":"tickets:read","parameters":[{"name":"status","in":"query","required":false,"description":"","schema":{"type":"string","enum":["open","answered","closed"]}},{"name":"email","in":"query","required":false,"description":"Buyer email contains this text.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size. Default 25.","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"description":"nextCursor from the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true}}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tickets/{id}":{"get":{"operationId":"tickets-get","tags":["Tickets"],"summary":"Get a ticket","description":"With its full thread; `fromBuyer` tells you who wrote each message.","security":[{"bearerKey":["tickets:read"]}],"x-scope":"tickets:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true}}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"tickets-status","tags":["Tickets"],"summary":"Change the status","security":[{"bearerKey":["tickets:write"]}],"x-scope":"tickets:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["open","answered","closed"]}},"required":["status"]},"example":{"status":"open"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true}}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tickets/{id}/messages":{"post":{"operationId":"tickets-reply","tags":["Tickets"],"summary":"Reply to a ticket","description":"The ticket becomes answered and the buyer is emailed. A closed ticket must be reopened first.","security":[{"bearerKey":["tickets:write"]}],"x-scope":"tickets:write","x-idempotency-key":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Replays the stored response for 24 h when the same key and body are sent again."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","description":"Up to 10,000 characters."}},"required":["body"]},"example":{"body":"Sorry about that. A new key is on its way."}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true}}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"idempotency_conflict: the Idempotency-Key was used with a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tickets/{id}/close":{"post":{"operationId":"tickets-close","tags":["Tickets"],"summary":"Close a ticket","security":[{"bearerKey":["tickets:write"]}],"x-scope":"tickets:write","x-idempotency-key":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Replays the stored response for 24 h when the same key and body are sent again."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true}}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"idempotency_conflict: the Idempotency-Key was used with a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/store":{"get":{"operationId":"store-get","tags":["Store"],"summary":"Get the store","security":[{"bearerKey":["store:read"]}],"x-scope":"store:read","parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true},"example":"{ \"ok\": true, \"store\": { \"id\": \"clx…\", \"slug\": \"my-store\", \"name\": \"My Store\", \"url\": \"https://my-store.sellhidden.com\", \"plan\": \"pro\", \"balanceUsd\": 1240.5, \"feeBornBy\": \"seller\", \"support\": { \"email\": \"help@example.com\", \"discord\": null, \"telegram\": null }, \"settings\": { \"maintenanceMode\": false, \"hideOutOfStock\": false, … }, … } }"}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"store-update","tags":["Store"],"summary":"Update basic settings","description":"Only the fields you send change.","security":[{"bearerKey":["store:write"]}],"x-scope":"store:write","parameters":[],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"2-80 characters."},"description":{"type":"string","description":"Up to 500 characters."},"logoUrl":{"oneOf":[{"type":"string"},{"type":"null"}]},"bannerUrl":{"oneOf":[{"type":"string"},{"type":"null"}]},"supportEmail":{"oneOf":[{"type":"string"},{"type":"null"}]},"supportDiscord":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Invite URL."},"supportTelegram":{"oneOf":[{"type":"string"},{"type":"null"}]},"maintenanceMode":{"type":"boolean","description":"Closes the storefront to buyers."},"hideOutOfStock":{"type":"boolean"},"showStockCount":{"type":"boolean"},"showStats":{"type":"boolean"},"recentSalesWidget":{"type":"boolean","description":"Live sale notifications toggle."},"liveSalesCorner":{"type":"string","description":"bottom-left | bottom-right | top-left | top-right (default bottom-left)."},"autoReviews":{"type":"boolean"},"autoCurrency":{"type":"boolean","description":"Deprecated; use currencyMode (\"auto\")."},"currencyMode":{"type":"string","enum":["usd","fixed","auto"],"description":"Default display currency: USD, a fixed one you pick, or the currency of the buyer's location."},"defaultCurrency":{"type":"string","description":"ISO 4217 code used when currencyMode is \"fixed\"."},"showCurrencyPicker":{"type":"boolean","description":"False hides the currency picker everywhere and the shop stays in USD."},"feeBornBy":{"type":"string","enum":["seller","customer"],"description":"Who would pay a platform fee. Every plan has a 0% platform fee, so this has no effect today."},"productsPerPage":{"type":"integer","minimum":4,"maximum":48},"subscriptionReminderDays":{"type":"integer","minimum":1,"maximum":14,"description":"Days before a renewal the reminder email goes out."},"subscriptionGraceDays":{"type":"integer","minimum":0,"maximum":3,"description":"Days a buyer keeps access after a missed renewal."}}},"example":{"maintenanceMode":true}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true}}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks":{"get":{"operationId":"webhooks-list","tags":["Webhooks"],"summary":"List endpoints","security":[{"bearerKey":["webhooks:read"]}],"x-scope":"webhooks:read","parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true},"example":"{ \"ok\": true, \"webhooks\": [ { \"id\": \"clx…\", \"url\": \"https://example.com/hooks\", \"label\": \"Fulfilment\", \"events\": [ \"order.paid\" ], \"active\": true, \"consecutiveFailures\": 0, \"secretHint\": \"whsec_1a2b…\", \"lastDelivery\": { … }, \"deliveryCount\": 42, \"createdAt\": \"…\" } ], \"limit\": 5 }"}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"webhooks-create","tags":["Webhooks"],"summary":"Create an endpoint","description":"Public https URLs only. Counts against the plan's endpoint limit (403 plan_limit).","security":[{"bearerKey":["webhooks:write"]}],"x-scope":"webhooks:write","x-idempotency-key":true,"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Replays the stored response for 24 h when the same key and body are sent again."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"https URL."},"events":{"type":"array","items":{"type":"string"},"description":"Event names (see Webhooks, Events), or wildcards like order.* or *."},"label":{"type":"string","description":"Up to 60 characters."}},"required":["url","events"]},"example":{"url":"https://example.com/hooks/hidden","events":["order.paid","order.delivered"],"label":"Fulfilment"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true},"example":"{ \"ok\": true, \"webhook\": { \"id\": \"clx…\", \"url\": \"…\", \"events\": [ \"order.paid\", \"order.delivered\" ], \"active\": true, \"secret\": \"whsec_…\", … } }"}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"idempotency_conflict: the Idempotency-Key was used with a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/{id}":{"get":{"operationId":"webhooks-get","tags":["Webhooks"],"summary":"Get an endpoint","security":[{"bearerKey":["webhooks:read"]}],"x-scope":"webhooks:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true}}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"webhooks-update","tags":["Webhooks"],"summary":"Update an endpoint","security":[{"bearerKey":["webhooks:write"]}],"x-scope":"webhooks:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"label":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"active":{"type":"boolean","description":"Switch it on again after it was disabled for failures."},"resetFailures":{"type":"boolean","description":"Reset the consecutive failure counter."}}},"example":{"active":true,"resetFailures":true}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true}}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"webhooks-delete","tags":["Webhooks"],"summary":"Delete an endpoint","security":[{"bearerKey":["webhooks:write"]}],"x-scope":"webhooks:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true}}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/{id}/rotate-secret":{"post":{"operationId":"webhooks-rotate","tags":["Webhooks"],"summary":"Rotate the secret","description":"Returns the new secret once. Deliveries are signed with it from now on.","security":[{"bearerKey":["webhooks:write"]}],"x-scope":"webhooks:write","x-idempotency-key":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Replays the stored response for 24 h when the same key and body are sent again."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true}}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"idempotency_conflict: the Idempotency-Key was used with a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/{id}/test":{"post":{"operationId":"webhooks-test","tags":["Webhooks"],"summary":"Send a test event","description":"A signed webhook.test delivery (10 per endpoint per minute). The response carries the delivery row with the status code your endpoint returned.","security":[{"bearerKey":["webhooks:write"]}],"x-scope":"webhooks:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true}}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/{id}/deliveries":{"get":{"operationId":"webhooks-deliveries","tags":["Webhooks"],"summary":"Delivery log","security":[{"bearerKey":["webhooks:read"]}],"x-scope":"webhooks:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"","schema":{"type":"string","enum":["ok","failed"]}},{"name":"limit","in":"query","required":false,"description":"Page size. Default 25.","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"description":"nextCursor from the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true}}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/analytics":{"get":{"operationId":"analytics-get","tags":["Analytics"],"summary":"Revenue and orders","security":[{"bearerKey":["analytics:read"]}],"x-scope":"analytics:read","parameters":[{"name":"period","in":"query","required":false,"description":"Window ending now. Default 30d.","schema":{"type":"string","enum":["24h","7d","30d","90d","365d"]}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true}}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope, ip_not_allowed, store_suspended or plan_limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/me":{"get":{"operationId":"me","tags":["Your key"],"summary":"Inspect the key you are using","description":"Any valid key: its store, scopes, expiry and the rate-limit window. Handy to check a key without touching data.","security":[],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"additionalProperties":true}}}},"400":{"description":"Malformed request or validation_error (field says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Business rule conflict (the code says which).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerKey":{"type":"http","scheme":"bearer","bearerFormat":"hsk_live_…","description":"Personal access key from Developers, API keys. Scopes: products:read, products:write, categories:read, categories:write, coupons:read, coupons:write, orders:read, orders:write, subscriptions:read, subscriptions:write, customers:read, customers:write, reviews:read, reviews:write, tickets:read, tickets:write, store:read, store:write, webhooks:read, webhooks:write, analytics:read."}},"schemas":{"Error":{"type":"object","required":["ok","error"],"properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string","description":"The body field at fault, for validation_error."}}}}}}}}