{"openapi":"3.1.0","info":{"title":"Paysum Public API","version":"1.0.0","description":"The Store API (products, orders, customers, coupons and theme code) plus checkout sessions, cryptocurrency withdrawals and customer balances. Every key is locked to one store. Dashboard session endpoints are not part of the public API."},"servers":[{"url":"https://paysum.io"}],"tags":[{"name":"Store"},{"name":"Products"},{"name":"Orders"},{"name":"Customers"},{"name":"Coupons"},{"name":"Theme"},{"name":"Checkout sessions"},{"name":"Withdrawals"},{"name":"Customer balance"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"Store API key","description":"A secret sk_ key with the permission required by the endpoint. Keep it on your server."}}},"paths":{"/api/store-api/store":{"get":{"operationId":"api_store_get_store","tags":["Store"],"summary":"Get store","description":"Returns the store the key belongs to, its storefront URL and currency, and the scopes on the key. A good first call to check a key.","security":[{"bearerAuth":[]}],"x-required-permission":"store:read","x-rate-limit":"1,000 requests / hour","parameters":[],"responses":{"200":{"description":"The store.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"url":{"type":"string"},"description":{"type":"string"},"currency":{"type":"string"},"logo_url":{},"favicon_url":{},"accent_color":{"type":"string"},"is_published":{"type":"boolean"},"product_count":{"type":"number"},"created_at":{"type":"string"},"api_key":{"type":"object","properties":{"id":{"type":"string"},"permissions":{"type":"array","items":{"type":"string"}}}}}},"example":{"id":"0218cf3c-954d-4a65-8f6e-e4b5857bf76c","name":"Acme Keys","slug":"acme","url":"https://acme.paysum.io","description":"","currency":"USD","logo_url":null,"favicon_url":null,"accent_color":"#6571FF","is_published":true,"product_count":12,"created_at":"2026-01-02T09:00:00.000Z","api_key":{"id":"d6bcc287-6e19-45f2-97a1-53bcee0662d9","permissions":["store:read"]}}}}},"401":{"description":"Missing, malformed, disabled or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"unauthorized","message":"Missing or invalid Authorization header. Use: Bearer sk_..."}}}},"403":{"description":"The key lacks the `store:read` permission.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"permission_denied","message":"API key does not have store:read permission. Create a new key with this permission."}}}}}}},"/api/store-api/products":{"get":{"operationId":"api_products_list_products","tags":["Products"],"summary":"List products","description":"Lists products, newest first.","security":[{"bearerAuth":[]}],"x-required-permission":"products:read","x-rate-limit":"1,000 requests / hour","parameters":[{"name":"limit","in":"query","required":false,"description":"Number of results to return, between 1 and 100.","schema":{"type":"integer","description":"Number of results to return, between 1 and 100.","default":20}},{"name":"offset","in":"query","required":false,"description":"Number of results to skip.","schema":{"type":"integer","description":"Number of results to skip.","default":0}},{"name":"search","in":"query","required":false,"description":"Matches the product title.","schema":{"type":"string","description":"Matches the product title."}},{"name":"category","in":"query","required":false,"description":"Exact category name.","schema":{"type":"string","description":"Exact category name."}},{"name":"active","in":"query","required":false,"description":"Only active or inactive.","schema":{"type":"boolean","description":"Only active or inactive."}}],"responses":{"200":{"description":"A page of products.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"category":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"price":{"type":"number"},"compare_at_price":{"type":"number"},"image":{"type":"string"},"images":{"type":"array","items":{}},"stock":{"type":"number"},"limited_stock":{"type":"boolean"},"use_product_keys":{"type":"boolean"},"key_count":{"type":"number"},"max_per_order":{"type":"number"},"position":{"type":"number"},"is_active":{"type":"boolean"},"is_featured":{"type":"boolean"},"variants":{"type":"array","items":{}},"seo":{"type":"object","properties":{"title":{},"description":{}}},"created_at":{"type":"string"},"updated_at":{"type":"string"}}}},"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"}}},"example":{"data":[{"id":"448a2454-5f8e-4fc2-8e88-80bb8014a27e","title":"Lifetime license","description":"One key, delivered instantly.","category":"Software","tags":["windows"],"price":19.99,"compare_at_price":29.99,"image":"https://cdn.example.com/license.png","images":[],"stock":0,"limited_stock":false,"use_product_keys":true,"key_count":15,"max_per_order":10,"position":0,"is_active":true,"is_featured":true,"variants":[],"seo":{"title":null,"description":null},"created_at":"2026-03-01T10:00:00.000Z","updated_at":"2026-03-04T18:30:00.000Z"}],"total":1,"limit":20,"offset":0}}}},"401":{"description":"Missing, malformed, disabled or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"unauthorized","message":"Missing or invalid Authorization header. Use: Bearer sk_..."}}}},"403":{"description":"The key lacks the `products:read` permission.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"permission_denied","message":"API key does not have products:read permission. Create a new key with this permission."}}}}}},"post":{"operationId":"api_products_create_product","tags":["Products"],"summary":"Create product","description":"Creates a product in the key’s store. It appears on the storefront right away unless `is_active` is false, and fires the `product.created` webhook.","security":[{"bearerAuth":[]}],"x-required-permission":"products:write","x-rate-limit":"1,000 requests / hour","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","description":"Product name."},"price":{"type":"number","description":"Price in the store currency."},"description":{"type":"string","description":"Shown on the product page. Markdown is supported."},"compareAtPrice":{"type":"number","description":"Original price, shown struck through."},"category":{"type":"string","description":"Category name."},"tags":{"type":"array","items":{"type":"string"},"description":"Search and filter tags."},"image":{"type":"string","description":"Image URL, or a base64 data URL to upload."},"images":{"type":"array","items":{"type":"string"},"description":"Gallery images."},"stock":{"type":"integer","description":"Units in stock."},"limited_stock":{"type":"boolean","description":"Stop selling when `stock` reaches 0."},"use_product_keys":{"type":"boolean","description":"Deliver one key from `digital_keys` per unit sold."},"digital_keys":{"type":"array","items":{"type":"string"},"description":"Keys to deliver. Never returned by the API; responses show `key_count`."},"max_per_order":{"type":"integer","description":"Per-order quantity cap."},"is_active":{"type":"boolean","description":"Listed on the storefront."},"is_featured":{"type":"boolean","description":"Shown in featured sections."},"variants":{"type":"array","items":{"type":"object"},"description":"Variants with their own name, price and stock."}},"required":["title","price"]},"example":{"title":"Lifetime license","price":19.99,"use_product_keys":true,"digital_keys":["AAAA-BBBB-CCCC","DDDD-EEEE-FFFF"]}}}},"responses":{"201":{"description":"The new product.","content":{"application/json":{"schema":{"type":"object","properties":{"product":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"category":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"price":{"type":"number"},"compare_at_price":{"type":"number"},"image":{"type":"string"},"images":{"type":"array","items":{}},"stock":{"type":"number"},"limited_stock":{"type":"boolean"},"use_product_keys":{"type":"boolean"},"key_count":{"type":"number"},"max_per_order":{"type":"number"},"position":{"type":"number"},"is_active":{"type":"boolean"},"is_featured":{"type":"boolean"},"variants":{"type":"array","items":{}},"seo":{"type":"object","properties":{"title":{},"description":{}}},"created_at":{"type":"string"},"updated_at":{"type":"string"}}}}},"example":{"product":{"id":"448a2454-5f8e-4fc2-8e88-80bb8014a27e","title":"Lifetime license","description":"One key, delivered instantly.","category":"Software","tags":["windows"],"price":19.99,"compare_at_price":29.99,"image":"https://cdn.example.com/license.png","images":[],"stock":0,"limited_stock":false,"use_product_keys":true,"key_count":15,"max_per_order":10,"position":0,"is_active":true,"is_featured":true,"variants":[],"seo":{"title":null,"description":null},"created_at":"2026-03-01T10:00:00.000Z","updated_at":"2026-03-04T18:30:00.000Z"}}}}},"400":{"description":"A field is missing or has the wrong type.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"invalid_request","message":"price must be a number"}}}},"401":{"description":"Missing, malformed, disabled or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"unauthorized","message":"Missing or invalid Authorization header. Use: Bearer sk_..."}}}},"403":{"description":"The key lacks the `products:write` permission.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"permission_denied","message":"API key does not have products:write permission. Create a new key with this permission."}}}}}}},"/api/store-api/products/{product_id}":{"get":{"operationId":"api_products_get_product","tags":["Products"],"summary":"Get product","description":"Retrieves one product. Delivery keys are never returned, only `key_count`.","security":[{"bearerAuth":[]}],"x-required-permission":"products:read","x-rate-limit":"1,000 requests / hour","parameters":[{"name":"product_id","in":"path","required":true,"description":"Product ID.","schema":{"type":"string","description":"Product ID."}}],"responses":{"200":{"description":"The product.","content":{"application/json":{"schema":{"type":"object","properties":{"product":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"category":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"price":{"type":"number"},"compare_at_price":{"type":"number"},"image":{"type":"string"},"images":{"type":"array","items":{}},"stock":{"type":"number"},"limited_stock":{"type":"boolean"},"use_product_keys":{"type":"boolean"},"key_count":{"type":"number"},"max_per_order":{"type":"number"},"position":{"type":"number"},"is_active":{"type":"boolean"},"is_featured":{"type":"boolean"},"variants":{"type":"array","items":{}},"seo":{"type":"object","properties":{"title":{},"description":{}}},"created_at":{"type":"string"},"updated_at":{"type":"string"}}}}},"example":{"product":{"id":"448a2454-5f8e-4fc2-8e88-80bb8014a27e","title":"Lifetime license","description":"One key, delivered instantly.","category":"Software","tags":["windows"],"price":19.99,"compare_at_price":29.99,"image":"https://cdn.example.com/license.png","images":[],"stock":0,"limited_stock":false,"use_product_keys":true,"key_count":15,"max_per_order":10,"position":0,"is_active":true,"is_featured":true,"variants":[],"seo":{"title":null,"description":null},"created_at":"2026-03-01T10:00:00.000Z","updated_at":"2026-03-04T18:30:00.000Z"}}}}},"401":{"description":"Missing, malformed, disabled or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"unauthorized","message":"Missing or invalid Authorization header. Use: Bearer sk_..."}}}},"404":{"description":"No product with this ID in the key’s store.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"not_found","message":"Product not found"}}}}}},"patch":{"operationId":"api_products_update_product","tags":["Products"],"summary":"Update product","description":"Updates the fields you send and leaves the rest alone. Adding stock or keys to a sold-out product emails customers who asked to be notified.","security":[{"bearerAuth":[]}],"x-required-permission":"products:write","x-rate-limit":"1,000 requests / hour","parameters":[{"name":"product_id","in":"path","required":true,"description":"Product ID.","schema":{"type":"string","description":"Product ID."}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","description":"Product name."},"price":{"type":"number","description":"Price in the store currency."},"description":{"type":"string","description":"Shown on the product page. Markdown is supported."},"compareAtPrice":{"type":"number","description":"Original price, shown struck through."},"category":{"type":"string","description":"Category name."},"tags":{"type":"array","items":{"type":"string"},"description":"Search and filter tags."},"image":{"type":"string","description":"Image URL, or a base64 data URL to upload."},"images":{"type":"array","items":{"type":"string"},"description":"Gallery images."},"stock":{"type":"integer","description":"Units in stock."},"limited_stock":{"type":"boolean","description":"Stop selling when `stock` reaches 0."},"use_product_keys":{"type":"boolean","description":"Deliver one key from `digital_keys` per unit sold."},"digital_keys":{"type":"array","items":{"type":"string"},"description":"Keys to deliver. Never returned by the API; responses show `key_count`."},"max_per_order":{"type":"integer","description":"Per-order quantity cap."},"is_active":{"type":"boolean","description":"Listed on the storefront."},"is_featured":{"type":"boolean","description":"Shown in featured sections."},"variants":{"type":"array","items":{"type":"object"},"description":"Variants with their own name, price and stock."}}},"example":{"price":17.99,"is_featured":true}}}},"responses":{"200":{"description":"The updated product.","content":{"application/json":{"schema":{"type":"object","properties":{"product":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"category":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"price":{"type":"number"},"compare_at_price":{"type":"number"},"image":{"type":"string"},"images":{"type":"array","items":{}},"stock":{"type":"number"},"limited_stock":{"type":"boolean"},"use_product_keys":{"type":"boolean"},"key_count":{"type":"number"},"max_per_order":{"type":"number"},"position":{"type":"number"},"is_active":{"type":"boolean"},"is_featured":{"type":"boolean"},"variants":{"type":"array","items":{}},"seo":{"type":"object","properties":{"title":{},"description":{}}},"created_at":{"type":"string"},"updated_at":{"type":"string"}}}}},"example":{"product":{"id":"448a2454-5f8e-4fc2-8e88-80bb8014a27e","title":"Lifetime license","description":"One key, delivered instantly.","category":"Software","tags":["windows"],"price":19.99,"compare_at_price":29.99,"image":"https://cdn.example.com/license.png","images":[],"stock":0,"limited_stock":false,"use_product_keys":true,"key_count":15,"max_per_order":10,"position":0,"is_active":true,"is_featured":true,"variants":[],"seo":{"title":null,"description":null},"created_at":"2026-03-01T10:00:00.000Z","updated_at":"2026-03-04T18:30:00.000Z"}}}}},"401":{"description":"Missing, malformed, disabled or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"unauthorized","message":"Missing or invalid Authorization header. Use: Bearer sk_..."}}}},"403":{"description":"The key lacks the `products:write` permission.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"permission_denied","message":"API key does not have products:write permission. Create a new key with this permission."}}}},"404":{"description":"No product with this ID in the key’s store.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"not_found","message":"Product not found"}}}}}},"delete":{"operationId":"api_products_delete_product","tags":["Products"],"summary":"Delete product","description":"Permanently deletes a product. Past orders keep their line items. To hide a product instead, set `is_active` to false.","security":[{"bearerAuth":[]}],"x-required-permission":"products:write","x-rate-limit":"1,000 requests / hour","parameters":[{"name":"product_id","in":"path","required":true,"description":"Product ID.","schema":{"type":"string","description":"Product ID."}}],"responses":{"200":{"description":"Deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"},"id":{"type":"string"}}},"example":{"deleted":true,"id":"448a2454-5f8e-4fc2-8e88-80bb8014a27e"}}}},"401":{"description":"Missing, malformed, disabled or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"unauthorized","message":"Missing or invalid Authorization header. Use: Bearer sk_..."}}}},"404":{"description":"No product with this ID in the key’s store.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"not_found","message":"Product not found"}}}}}}},"/api/store-api/categories":{"get":{"operationId":"api_products_list_categories","tags":["Products"],"summary":"List categories","description":"Lists product categories in display order.","security":[{"bearerAuth":[]}],"x-required-permission":"products:read","x-rate-limit":"1,000 requests / hour","parameters":[],"responses":{"200":{"description":"All categories.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"description":{},"image_url":{},"parent_id":{},"sort_order":{"type":"number"},"is_visible":{"type":"boolean"}}}}}},"example":{"data":[{"id":"9c1e2d3f-4a5b-4c6d-8e7f-0a1b2c3d4e5f","name":"Software","slug":"software","description":null,"image_url":null,"parent_id":null,"sort_order":0,"is_visible":true}]}}}},"401":{"description":"Missing, malformed, disabled or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"unauthorized","message":"Missing or invalid Authorization header. Use: Bearer sk_..."}}}}}}},"/api/store-api/orders":{"get":{"operationId":"api_orders_list_orders","tags":["Orders"],"summary":"List orders","description":"Lists orders, newest first, each with its line items. Amounts are in the store currency. Page with `next_offset` rather than counting: keep passing it as `offset` until it is null.","security":[{"bearerAuth":[]}],"x-required-permission":"orders:read","x-rate-limit":"1,000 requests / hour","parameters":[{"name":"limit","in":"query","required":false,"description":"Number of results to return, between 1 and 100.","schema":{"type":"integer","description":"Number of results to return, between 1 and 100.","default":20}},{"name":"offset","in":"query","required":false,"description":"Number of results to skip.","schema":{"type":"integer","description":"Number of results to skip.","default":0}},{"name":"status","in":"query","required":false,"description":"For example `completed`, `pending`, `expired` or `refunded`.","schema":{"type":"string","description":"For example `completed`, `pending`, `expired` or `refunded`."}},{"name":"email","in":"query","required":false,"description":"Exact customer email.","schema":{"type":"string","description":"Exact customer email."}},{"name":"created_after","in":"query","required":false,"description":"ISO 8601 time, inclusive.","schema":{"type":"string","description":"ISO 8601 time, inclusive."}},{"name":"created_before","in":"query","required":false,"description":"ISO 8601 time, exclusive.","schema":{"type":"string","description":"ISO 8601 time, exclusive."}}],"responses":{"200":{"description":"A page of orders.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"customer_email":{"type":["string","null"]},"payment_method":{"type":["string","null"]},"currency":{"type":"string"},"total":{"type":"number"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"product_id":{"type":"string"},"name":{"type":"string"},"quantity":{"type":"number"},"amount":{"type":"number"}}}},"created_at":{"type":"string"}}}},"limit":{"type":"number"},"next_offset":{"type":"number"}}},"example":{"data":[{"id":"order_1793564288101_6e461f4a","status":"completed","customer_email":"jane@example.com","payment_method":"stripe","currency":"USD","total":19.99,"items":[{"id":"2287a5a9-f919-4a59-802c-8ef0add48390","product_id":"448a2454-5f8e-4fc2-8e88-80bb8014a27e","name":"Lifetime license","quantity":1,"amount":19.99}],"created_at":"2026-03-04T18:20:00.000Z"}],"limit":20,"next_offset":20}}}},"401":{"description":"Missing, malformed, disabled or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"unauthorized","message":"Missing or invalid Authorization header. Use: Bearer sk_..."}}}},"403":{"description":"The key lacks the `orders:read` permission.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"permission_denied","message":"API key does not have orders:read permission. Create a new key with this permission."}}}}}}},"/api/store-api/orders/{order_id}":{"get":{"operationId":"api_orders_get_order","tags":["Orders"],"summary":"Get order","description":"Retrieves one order with its line items and the keys that were delivered.","security":[{"bearerAuth":[]}],"x-required-permission":"orders:read","x-rate-limit":"1,000 requests / hour","parameters":[{"name":"order_id","in":"path","required":true,"description":"Order ID.","schema":{"type":"string","description":"Order ID."}}],"responses":{"200":{"description":"The order.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"customer_email":{"type":["string","null"]},"payment_method":{"type":["string","null"]},"currency":{"type":"string"},"total":{"type":"number"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"product_id":{"type":"string"},"name":{"type":"string"},"quantity":{"type":"number"},"amount":{"type":"number"}}}},"created_at":{"type":"string"},"deliveries":{"type":"array","items":{"type":"object","properties":{"product_id":{"type":"string"},"key":{"type":"string"},"delivered_at":{"type":"string"}}}}}},"example":{"id":"order_1793564288101_6e461f4a","status":"completed","customer_email":"jane@example.com","payment_method":"stripe","currency":"USD","total":19.99,"items":[{"id":"2287a5a9-f919-4a59-802c-8ef0add48390","product_id":"448a2454-5f8e-4fc2-8e88-80bb8014a27e","name":"Lifetime license","quantity":1,"amount":19.99}],"created_at":"2026-03-04T18:20:00.000Z","deliveries":[{"product_id":"448a2454-5f8e-4fc2-8e88-80bb8014a27e","key":"AAAA-BBBB-CCCC","delivered_at":"2026-03-04T18:21:02.000Z"}]}}}},"401":{"description":"Missing, malformed, disabled or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"unauthorized","message":"Missing or invalid Authorization header. Use: Bearer sk_..."}}}},"404":{"description":"No order with this ID in the key’s store.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"not_found","message":"Order not found"}}}}}}},"/api/store-api/customers":{"get":{"operationId":"api_customers_list_customers","tags":["Customers"],"summary":"List customers","description":"Lists customers with their balance, lifetime spend and order count.","security":[{"bearerAuth":[]}],"x-required-permission":"customers:read","x-rate-limit":"1,000 requests / hour","parameters":[{"name":"limit","in":"query","required":false,"description":"Number of results to return, between 1 and 100.","schema":{"type":"integer","description":"Number of results to return, between 1 and 100.","default":20}},{"name":"offset","in":"query","required":false,"description":"Number of results to skip.","schema":{"type":"integer","description":"Number of results to skip.","default":0}},{"name":"search","in":"query","required":false,"description":"Matches email or name.","schema":{"type":"string","description":"Matches email or name."}}],"responses":{"200":{"description":"A page of customers.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"name":{"type":"string"},"balance":{"type":"number"},"total_spent":{"type":"number"},"order_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"}}}},"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"}}},"example":{"data":[{"id":"6f1d3c2a-0b4e-4c8d-9a7f-2e5b1c0d9a8e","email":"jane@example.com","name":"Jane Doe","balance":25,"total_spent":189.5,"order_count":7,"created_at":"2026-01-12T09:30:00.000Z","updated_at":"2026-03-04T18:30:00.000Z"}],"total":1,"limit":20,"offset":0}}}},"401":{"description":"Missing, malformed, disabled or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"unauthorized","message":"Missing or invalid Authorization header. Use: Bearer sk_..."}}}},"403":{"description":"The key lacks the `customers:read` permission.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"permission_denied","message":"API key does not have customers:read permission. Create a new key with this permission."}}}}}}},"/api/store-api/customers/{customer_id}":{"get":{"operationId":"api_customers_get_customer","tags":["Customers"],"summary":"Get customer","description":"Retrieves one customer.","security":[{"bearerAuth":[]}],"x-required-permission":"customers:read","x-rate-limit":"1,000 requests / hour","parameters":[{"name":"customer_id","in":"path","required":true,"description":"Customer ID.","schema":{"type":"string","description":"Customer ID."}}],"responses":{"200":{"description":"The customer.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"name":{"type":"string"},"balance":{"type":"number"},"total_spent":{"type":"number"},"order_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"}}},"example":{"id":"6f1d3c2a-0b4e-4c8d-9a7f-2e5b1c0d9a8e","email":"jane@example.com","name":"Jane Doe","balance":25,"total_spent":189.5,"order_count":7,"created_at":"2026-01-12T09:30:00.000Z","updated_at":"2026-03-04T18:30:00.000Z"}}}},"401":{"description":"Missing, malformed, disabled or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"unauthorized","message":"Missing or invalid Authorization header. Use: Bearer sk_..."}}}},"404":{"description":"No customer with this ID in the key’s store.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"not_found","message":"Customer not found"}}}}}}},"/api/store-api/coupons":{"get":{"operationId":"api_coupons_list_coupons","tags":["Coupons"],"summary":"List coupons","description":"Lists coupons, newest first.","security":[{"bearerAuth":[]}],"x-required-permission":"coupons:read","x-rate-limit":"1,000 requests / hour","parameters":[{"name":"limit","in":"query","required":false,"description":"Number of results to return, between 1 and 100.","schema":{"type":"integer","description":"Number of results to return, between 1 and 100.","default":20}},{"name":"offset","in":"query","required":false,"description":"Number of results to skip.","schema":{"type":"integer","description":"Number of results to skip.","default":0}},{"name":"active","in":"query","required":false,"description":"Only active or inactive.","schema":{"type":"boolean","description":"Only active or inactive."}}],"responses":{"200":{"description":"A page of coupons.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"description":{"type":"string"},"discount_type":{"type":"string"},"discount_value":{"type":"number"},"min_purchase_amount":{"type":"number"},"max_discount_amount":{},"usage_limit":{"type":"number"},"usage_count":{"type":"number"},"usage_limit_per_customer":{"type":"number"},"valid_from":{},"valid_until":{"type":"string"},"is_active":{"type":"boolean"},"applies_to":{},"created_at":{"type":"string"}}}},"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"}}},"example":{"data":[{"id":"1aa49167-eabe-40c3-b89d-215a4e5f6c3a","code":"SPRING10","description":"Spring sale","discount_type":"percentage","discount_value":10,"min_purchase_amount":0,"max_discount_amount":null,"usage_limit":500,"usage_count":42,"usage_limit_per_customer":1,"valid_from":null,"valid_until":"2026-04-30T23:59:59.000Z","is_active":true,"applies_to":null,"created_at":"2026-03-01T10:00:00.000Z"}],"total":1,"limit":20,"offset":0}}}},"401":{"description":"Missing, malformed, disabled or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"unauthorized","message":"Missing or invalid Authorization header. Use: Bearer sk_..."}}}},"403":{"description":"The key lacks the `coupons:read` permission.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"permission_denied","message":"API key does not have coupons:read permission. Create a new key with this permission."}}}}}},"post":{"operationId":"api_coupons_create_coupon","tags":["Coupons"],"summary":"Create coupon","description":"Creates a coupon. Codes are unique per store and stored uppercase.","security":[{"bearerAuth":[]}],"x-required-permission":"coupons:write","x-rate-limit":"1,000 requests / hour","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"What customers type at checkout. Stored uppercase."},"discount_type":{"type":"string","description":"`percentage` or `fixed`."},"discount_value":{"type":"number","description":"Percent off, or the amount off in the store currency."},"description":{"type":"string","description":"Internal note."},"min_purchase_amount":{"type":"number","description":"Minimum cart subtotal."},"max_discount_amount":{"type":"number","description":"Cap for percentage discounts."},"usage_limit":{"type":"integer","description":"Total redemptions allowed."},"usage_limit_per_customer":{"type":"integer","description":"Redemptions allowed per customer."},"valid_from":{"type":"string","description":"ISO 8601 start time."},"valid_until":{"type":"string","description":"ISO 8601 end time."},"is_active":{"type":"boolean","description":"Accepted at checkout."}},"required":["code","discount_type","discount_value"]},"example":{"code":"spring10","discount_type":"percentage","discount_value":10,"usage_limit":500}}}},"responses":{"201":{"description":"The new coupon.","content":{"application/json":{"schema":{"type":"object","properties":{"coupon":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"description":{"type":"string"},"discount_type":{"type":"string"},"discount_value":{"type":"number"},"min_purchase_amount":{"type":"number"},"max_discount_amount":{},"usage_limit":{"type":"number"},"usage_count":{"type":"number"},"usage_limit_per_customer":{"type":"number"},"valid_from":{},"valid_until":{"type":"string"},"is_active":{"type":"boolean"},"applies_to":{},"created_at":{"type":"string"}}}}},"example":{"coupon":{"id":"1aa49167-eabe-40c3-b89d-215a4e5f6c3a","code":"SPRING10","description":"Spring sale","discount_type":"percentage","discount_value":10,"min_purchase_amount":0,"max_discount_amount":null,"usage_limit":500,"usage_count":42,"usage_limit_per_customer":1,"valid_from":null,"valid_until":"2026-04-30T23:59:59.000Z","is_active":true,"applies_to":null,"created_at":"2026-03-01T10:00:00.000Z"}}}}},"400":{"description":"A field is missing or has the wrong type.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"invalid_request","message":"discount_type must be percentage or fixed"}}}},"401":{"description":"Missing, malformed, disabled or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"unauthorized","message":"Missing or invalid Authorization header. Use: Bearer sk_..."}}}},"403":{"description":"The key lacks the `coupons:write` permission.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"permission_denied","message":"API key does not have coupons:write permission. Create a new key with this permission."}}}},"409":{"description":"The code is already used in this store.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"conflict","message":"A coupon with this code already exists"}}}}}}},"/api/store-api/coupons/{coupon_id}":{"get":{"operationId":"api_coupons_get_coupon","tags":["Coupons"],"summary":"Get coupon","description":"Retrieves one coupon, including how often it has been used.","security":[{"bearerAuth":[]}],"x-required-permission":"coupons:read","x-rate-limit":"1,000 requests / hour","parameters":[{"name":"coupon_id","in":"path","required":true,"description":"Coupon ID.","schema":{"type":"string","description":"Coupon ID."}}],"responses":{"200":{"description":"The coupon.","content":{"application/json":{"schema":{"type":"object","properties":{"coupon":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"description":{"type":"string"},"discount_type":{"type":"string"},"discount_value":{"type":"number"},"min_purchase_amount":{"type":"number"},"max_discount_amount":{},"usage_limit":{"type":"number"},"usage_count":{"type":"number"},"usage_limit_per_customer":{"type":"number"},"valid_from":{},"valid_until":{"type":"string"},"is_active":{"type":"boolean"},"applies_to":{},"created_at":{"type":"string"}}}}},"example":{"coupon":{"id":"1aa49167-eabe-40c3-b89d-215a4e5f6c3a","code":"SPRING10","description":"Spring sale","discount_type":"percentage","discount_value":10,"min_purchase_amount":0,"max_discount_amount":null,"usage_limit":500,"usage_count":42,"usage_limit_per_customer":1,"valid_from":null,"valid_until":"2026-04-30T23:59:59.000Z","is_active":true,"applies_to":null,"created_at":"2026-03-01T10:00:00.000Z"}}}}},"401":{"description":"Missing, malformed, disabled or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"unauthorized","message":"Missing or invalid Authorization header. Use: Bearer sk_..."}}}},"404":{"description":"No coupon with this ID in the key’s store.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"not_found","message":"Coupon not found"}}}}}},"patch":{"operationId":"api_coupons_update_coupon","tags":["Coupons"],"summary":"Update coupon","description":"Updates the fields you send. Set `is_active` to false to pause a coupon.","security":[{"bearerAuth":[]}],"x-required-permission":"coupons:write","x-rate-limit":"1,000 requests / hour","parameters":[{"name":"coupon_id","in":"path","required":true,"description":"Coupon ID.","schema":{"type":"string","description":"Coupon ID."}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"What customers type at checkout. Stored uppercase."},"discount_type":{"type":"string","description":"`percentage` or `fixed`."},"discount_value":{"type":"number","description":"Percent off, or the amount off in the store currency."},"description":{"type":"string","description":"Internal note."},"min_purchase_amount":{"type":"number","description":"Minimum cart subtotal."},"max_discount_amount":{"type":"number","description":"Cap for percentage discounts."},"usage_limit":{"type":"integer","description":"Total redemptions allowed."},"usage_limit_per_customer":{"type":"integer","description":"Redemptions allowed per customer."},"valid_from":{"type":"string","description":"ISO 8601 start time."},"valid_until":{"type":"string","description":"ISO 8601 end time."},"is_active":{"type":"boolean","description":"Accepted at checkout."}}},"example":{"is_active":false}}}},"responses":{"200":{"description":"The updated coupon.","content":{"application/json":{"schema":{"type":"object","properties":{"coupon":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"description":{"type":"string"},"discount_type":{"type":"string"},"discount_value":{"type":"number"},"min_purchase_amount":{"type":"number"},"max_discount_amount":{},"usage_limit":{"type":"number"},"usage_count":{"type":"number"},"usage_limit_per_customer":{"type":"number"},"valid_from":{},"valid_until":{"type":"string"},"is_active":{"type":"boolean"},"applies_to":{},"created_at":{"type":"string"}}}}},"example":{"coupon":{"id":"1aa49167-eabe-40c3-b89d-215a4e5f6c3a","code":"SPRING10","description":"Spring sale","discount_type":"percentage","discount_value":10,"min_purchase_amount":0,"max_discount_amount":null,"usage_limit":500,"usage_count":42,"usage_limit_per_customer":1,"valid_from":null,"valid_until":"2026-04-30T23:59:59.000Z","is_active":true,"applies_to":null,"created_at":"2026-03-01T10:00:00.000Z"}}}}},"401":{"description":"Missing, malformed, disabled or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"unauthorized","message":"Missing or invalid Authorization header. Use: Bearer sk_..."}}}},"404":{"description":"No coupon with this ID in the key’s store.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"not_found","message":"Coupon not found"}}}}}},"delete":{"operationId":"api_coupons_delete_coupon","tags":["Coupons"],"summary":"Delete coupon","description":"Permanently deletes a coupon.","security":[{"bearerAuth":[]}],"x-required-permission":"coupons:write","x-rate-limit":"1,000 requests / hour","parameters":[{"name":"coupon_id","in":"path","required":true,"description":"Coupon ID.","schema":{"type":"string","description":"Coupon ID."}}],"responses":{"200":{"description":"Deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"},"id":{"type":"string"}}},"example":{"deleted":true,"id":"1aa49167-eabe-40c3-b89d-215a4e5f6c3a"}}}},"401":{"description":"Missing, malformed, disabled or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"unauthorized","message":"Missing or invalid Authorization header. Use: Bearer sk_..."}}}},"404":{"description":"No coupon with this ID in the key’s store.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"not_found","message":"Coupon not found"}}}}}}},"/api/store-api/theme/files":{"get":{"operationId":"api_theme_list_files","tags":["Theme"],"summary":"List theme files","description":"Returns every file in the theme’s draft project. `source` is `template_files` once drafts exist; before that the files come from the store’s current theme. `sha256` lets you detect changes without downloading content.","security":[{"bearerAuth":[]}],"x-required-permission":"themes:read","x-rate-limit":"1,000 requests / hour","parameters":[{"name":"content","in":"query","required":false,"description":"Set to `false` for paths, sizes and hashes only.","schema":{"type":"boolean","description":"Set to `false` for paths, sizes and hashes only.","default":true}}],"responses":{"200":{"description":"The draft files.","content":{"application/json":{"schema":{"type":"object","properties":{"source":{"type":"string"},"files":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"type":{"type":"string"},"size":{"type":"number"},"sha256":{"type":"string"},"updated_at":{"type":"string"},"content":{"type":"string"}}}}}},"example":{"source":"template_files","files":[{"path":"src/StorePage.tsx","type":"tsx","size":4210,"sha256":"9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08","updated_at":"2026-03-04T18:30:00.000Z","content":"export default function StorePage() { … }"}]}}}},"401":{"description":"Missing, malformed, disabled or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"unauthorized","message":"Missing or invalid Authorization header. Use: Bearer sk_..."}}}},"403":{"description":"The key lacks the `themes:read` permission.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"permission_denied","message":"API key does not have themes:read permission. Create a new key with this permission."}}}}}},"put":{"operationId":"api_theme_write_files","tags":["Theme"],"summary":"Write theme files","description":"Creates or replaces draft files and deletes others in one request. Drafts are not live until you publish. On a store without drafts, the current theme is copied in first, so writing one file never leaves a one-file project.","security":[{"bearerAuth":[]}],"x-required-permission":"themes:write","x-rate-limit":"1,000 requests / hour","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"files":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","description":"Project path. Allowed extensions: tsx, ts, jsx, js, css, json, html, md, svg, txt."},"content":{"type":"string","description":"Full file contents."}},"required":["path","content"]},"description":"Up to 300 files. Each file is at most 512 KB."},"deleted":{"type":"array","items":{"type":"string"},"description":"Paths to delete."}}},"example":{"files":[{"path":"src/styles.css","content":":root { --primary: #6571ff; }"}],"deleted":["src/components/OldBanner.tsx"]}}}},"responses":{"200":{"description":"Saved. `seeded` counts files copied from the current theme.","content":{"application/json":{"schema":{"type":"object","properties":{"saved":{"type":"number"},"deleted":{"type":"number"},"seeded":{"type":"number"}}},"example":{"saved":1,"deleted":1,"seeded":0}}}},"400":{"description":"A field is missing or has the wrong type.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"invalid_request","message":"Provide files to write or paths to delete"}}}},"401":{"description":"Missing, malformed, disabled or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"unauthorized","message":"Missing or invalid Authorization header. Use: Bearer sk_..."}}}},"403":{"description":"The key lacks the `themes:write` permission.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"permission_denied","message":"API key does not have themes:write permission. Create a new key with this permission."}}}}}}},"/api/store-api/theme/file":{"get":{"operationId":"api_theme_get_file","tags":["Theme"],"summary":"Get theme file","description":"Reads one draft file.","security":[{"bearerAuth":[]}],"x-required-permission":"themes:read","x-rate-limit":"1,000 requests / hour","parameters":[{"name":"path","in":"query","required":true,"description":"Project path, for example `src/StorePage.tsx`.","schema":{"type":"string","description":"Project path, for example `src/StorePage.tsx`."}}],"responses":{"200":{"description":"The file.","content":{"application/json":{"schema":{"type":"object","properties":{"path":{"type":"string"},"type":{"type":"string"},"content":{"type":"string"}}},"example":{"path":"src/styles.css","type":"css","content":":root { --primary: #6571ff; }"}}}},"401":{"description":"Missing, malformed, disabled or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"unauthorized","message":"Missing or invalid Authorization header. Use: Bearer sk_..."}}}},"404":{"description":"No file with this ID in the key’s store.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"not_found","message":"File not found"}}}}}}},"/api/store-api/theme/preview":{"post":{"operationId":"api_theme_preview","tags":["Theme"],"summary":"Create preview link","description":"Returns a link that renders the current drafts with your store’s data and reloads itself when the drafts change. Links last four hours and anyone with the link can view them.","security":[{"bearerAuth":[]}],"x-required-permission":"themes:write","x-rate-limit":"1,000 requests / hour","parameters":[],"responses":{"200":{"description":"The preview link.","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"expires_at":{"type":"string"}}},"example":{"url":"https://paysum.io/api/store-api/preview/0218cf3c-….1793654807.nAlYqy…","expires_at":"2026-03-04T22:30:00.000Z"}}}},"401":{"description":"Missing, malformed, disabled or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"unauthorized","message":"Missing or invalid Authorization header. Use: Bearer sk_..."}}}},"403":{"description":"The key lacks the `themes:write` permission.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"permission_denied","message":"API key does not have themes:write permission. Create a new key with this permission."}}}}}}},"/api/store-api/theme/publish":{"post":{"operationId":"api_theme_publish","tags":["Theme"],"summary":"Publish theme","description":"Builds the drafts on the server and makes them the live storefront. Every publish is kept as a version you can restore from the dashboard.","security":[{"bearerAuth":[]}],"x-required-permission":"themes:write","x-rate-limit":"30 publishes / hour","parameters":[],"responses":{"200":{"description":"Published.","content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"number"},"storefront":{"type":"string"},"entry":{"type":"string"},"build_ms":{"type":"number"},"published_at":{"type":"string"}}},"example":{"version":1793640398740,"storefront":"bundle","entry":"src/App.tsx","build_ms":951,"published_at":"2026-03-04T18:30:00.000Z"}}}},"400":{"description":"A field is missing or has the wrong type.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"invalid_request","message":"No saved theme files to publish. Push files first."}}}},"401":{"description":"Missing, malformed, disabled or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"unauthorized","message":"Missing or invalid Authorization header. Use: Bearer sk_..."}}}},"422":{"description":"The theme did not compile. The message lists the first errors.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"build_failed","message":"Build failed with 1 error(s):\nsrc/StorePage.tsx:12:4: Expected \")\" but found \"}\""}}}},"429":{"description":"The hourly limit for this key was reached.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"retry_after":{"type":"number"}}},"example":{"error":"rate_limit_exceeded","message":"Rate limit exceeded. Maximum 30 publishes per hour.","retry_after":1260}}}}}}},"/api/store-api/theme/versions":{"get":{"operationId":"api_theme_list_versions","tags":["Theme"],"summary":"List versions","description":"Lists published versions, newest first, and which one is live.","security":[{"bearerAuth":[]}],"x-required-permission":"themes:read","x-rate-limit":"1,000 requests / hour","parameters":[],"responses":{"200":{"description":"Published versions.","content":{"application/json":{"schema":{"type":"object","properties":{"live_version":{"type":"number"},"versions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"version":{"type":"number"},"published_at":{"type":"string"},"restored_from":{}}}}}},"example":{"live_version":1793640398740,"versions":[{"id":"4ca13b12-73fa-4d0b-afd6-9d7c5cf5e837","version":1793640398740,"published_at":"2026-03-04T18:30:00.000Z","restored_from":null}]}}}},"401":{"description":"Missing, malformed, disabled or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"unauthorized","message":"Missing or invalid Authorization header. Use: Bearer sk_..."}}}}}}},"/api/checkout-api/sessions":{"post":{"operationId":"api_checkout_create_session","tags":["Checkout sessions"],"summary":"Create session","description":"Creates a hosted checkout session and returns the URL to redirect your customer to. Pass either `line_items` (custom priced items) or `product_ids` (products from your store, delivered automatically) - not both.\n\nKeys with no permissions at all are accepted by the Checkout API for backwards compatibility.","security":[{"bearerAuth":[]}],"x-required-permission":"checkout_api","x-rate-limit":"100 requests / hour","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"line_items":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Item name shown at checkout."},"price":{"type":"number","description":"Unit price in the store currency."},"quantity":{"type":"integer","description":"Positive integer.","default":1},"description":{"type":"string","description":"Optional line description."},"image_url":{"type":"string","description":"Optional image shown next to the item."}},"required":["name","price"]},"description":"Custom items with their own name and price. Required unless `product_ids` is set."},"product_ids":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Product ID."},"quantity":{"type":"integer","description":"Positive integer, limited by available stock.","default":1},"variant_id":{"type":"string","description":"Variant ID for products with variants."},"variant_name_or_id":{"type":"string","description":"Alternative to `variant_id`: matches a variant by ID or case-insensitive name."}},"required":["id"]},"description":"Products from your store. Stock is checked and delivery is handled for you. Required unless `line_items` is set."},"customer_email":{"type":"string","description":"Prefills the email field at checkout."},"customer_name":{"type":"string","description":"Prefills the customer name."},"success_url":{"type":"string","description":"Where the customer lands after paying."},"cancel_url":{"type":"string","description":"Where the customer lands if they abandon checkout."},"expired_url":{"type":"string","description":"Where the customer is sent if the session has expired."},"webhook_url":{"type":"string","description":"Receives `checkout.session.*` events for this session."},"expires_in_seconds":{"type":"number","description":"Session lifetime in seconds. Takes precedence over `expires_in_hours`."},"expires_in_hours":{"type":"number","description":"Session lifetime in hours.","default":24},"metadata":{"type":"object","description":"Key/value pairs echoed back in webhooks."},"client_reference_id":{"type":"string","description":"Your own identifier for this checkout, echoed back in webhooks."},"hide_navbar":{"type":"boolean","description":"Hide the store navbar on the checkout page.","default":false},"hide_footer":{"type":"boolean","description":"Hide the store footer on the checkout page.","default":false},"disable_coupons":{"type":"boolean","description":"Prevent coupon codes for this session.","default":false},"disable_gift_cards":{"type":"boolean","description":"Prevent gift card redemption for this session.","default":false}}},"example":{"line_items":[{"name":"Premium License","price":29.99,"quantity":1}],"customer_email":"jane@example.com","success_url":"https://example.com/success","cancel_url":"https://example.com/cancel","webhook_url":"https://example.com/webhooks/checkout","expires_in_seconds":1800,"metadata":{"orderNumber":"ORD-4821"}}}}},"responses":{"201":{"description":"Session created.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"status":{"type":"string"},"total_amount":{"type":"number"},"currency":{"type":"string"},"expires_at":{"type":"string"},"line_items":{"type":"number"}}},"example":{"id":"cs_9f2c4e1a7b3d4c5e8f90a1b2c3d4e5f6","url":"https://your-store.paysum.io/checkout?session=cs_9f2c4e1a7b3d4c5e8f90a1b2c3d4e5f6","status":"pending","total_amount":29.99,"currency":"USD","expires_at":"2026-03-04T18:50:00.000Z","line_items":1}}}},"400":{"description":"Invalid body, unknown product, unavailable product or insufficient stock.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"invalid_request","message":"Either line_items or product_ids is required (as a non-empty array)"}}}},"401":{"description":"Missing, malformed, disabled or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"unauthorized","message":"Missing or invalid Authorization header. Use: Bearer sk_..."}}}},"429":{"description":"The hourly limit for this key was reached.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"retry_after":{"type":"number"}}},"example":{"error":"rate_limit_exceeded","message":"Rate limit exceeded. Maximum 100 requests per hour.","retry_after":1260}}}}}},"get":{"operationId":"api_checkout_list_sessions","tags":["Checkout sessions"],"summary":"List sessions","description":"Returns checkout sessions for the store, newest first.","security":[{"bearerAuth":[]}],"x-required-permission":"checkout_api","parameters":[{"name":"limit","in":"query","required":false,"description":"Number of results to return, between 1 and 100.","schema":{"type":"integer","description":"Number of results to return, between 1 and 100.","default":20}},{"name":"offset","in":"query","required":false,"description":"Number of results to skip.","schema":{"type":"integer","description":"Number of results to skip.","default":0}},{"name":"status","in":"query","required":false,"description":"Filter by status: `pending`, `completed`, `cancelled` or `expired`.","schema":{"type":"string","description":"Filter by status: `pending`, `completed`, `cancelled` or `expired`."}}],"responses":{"200":{"description":"A page of sessions.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"total_amount":{"type":"number"},"currency":{"type":"string"},"customer_email":{"type":["string","null"]},"payment_method":{"type":["string","null"]},"created_at":{"type":"string"},"completed_at":{"type":["string","null"]}}}},"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"}}},"example":{"data":[{"id":"cs_9f2c4e1a7b3d4c5e8f90a1b2c3d4e5f6","status":"pending","total_amount":49.98,"currency":"USD","customer_email":"jane@example.com","payment_method":null,"created_at":"2026-03-04T18:20:00.000Z","completed_at":null}],"total":1,"limit":20,"offset":0}}}},"401":{"description":"Missing, malformed, disabled or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"unauthorized","message":"Missing or invalid Authorization header. Use: Bearer sk_..."}}}}}}},"/api/checkout-api/sessions/{session_id}":{"get":{"operationId":"api_checkout_get_session","tags":["Checkout sessions"],"summary":"Retrieve session","description":"Fetches a single session. Pending sessions past their expiry are marked `expired` when read.","security":[{"bearerAuth":[]}],"x-required-permission":"checkout_api","parameters":[{"name":"session_id","in":"path","required":true,"description":"The `cs_…` ID returned when the session was created.","schema":{"type":"string","description":"The `cs_…` ID returned when the session was created."}}],"responses":{"200":{"description":"The session.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"status":{"type":"string"},"total_amount":{"type":"number"},"currency":{"type":"string"},"customer_email":{"type":["string","null"]},"customer_name":{"type":["string","null"]},"payment_method":{"type":["string","null"]},"metadata":{"type":"object","properties":{"orderNumber":{"type":"string"}}},"client_reference_id":{},"line_items":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"price":{"type":"number"},"quantity":{"type":"number"},"image":{},"metadata":{"type":"object","properties":{}}}}},"expires_at":{"type":"string"},"created_at":{"type":"string"}}},"example":{"id":"cs_9f2c4e1a7b3d4c5e8f90a1b2c3d4e5f6","url":"https://your-store.paysum.io/checkout?session=cs_9f2c4e1a7b3d4c5e8f90a1b2c3d4e5f6","status":"pending","total_amount":29.99,"currency":"USD","customer_email":"jane@example.com","customer_name":null,"payment_method":null,"metadata":{"orderNumber":"ORD-4821"},"client_reference_id":null,"line_items":[{"name":"Premium License","description":"","price":29.99,"quantity":1,"image":null,"metadata":{}}],"expires_at":"2026-03-04T18:50:00.000Z","created_at":"2026-03-04T18:20:00.000Z"}}}},"401":{"description":"Missing, malformed, disabled or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"unauthorized","message":"Missing or invalid Authorization header. Use: Bearer sk_..."}}}},"404":{"description":"No session with that ID belongs to this store.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"session_not_found","message":"Checkout session not found"}}}}}}},"/api/checkout-api/sessions/{session_id}/cancel":{"post":{"operationId":"api_checkout_cancel_session","tags":["Checkout sessions"],"summary":"Cancel session","description":"Cancels a session that has not been paid. Completed sessions cannot be cancelled.","security":[{"bearerAuth":[]}],"x-required-permission":"checkout_api","parameters":[{"name":"session_id","in":"path","required":true,"description":"The session to cancel.","schema":{"type":"string","description":"The session to cancel."}}],"responses":{"200":{"description":"Session cancelled.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"}}},"example":{"id":"cs_9f2c4e1a7b3d4c5e8f90a1b2c3d4e5f6","status":"cancelled"}}}},"400":{"description":"The session is already completed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"session_completed","message":"Cannot cancel a completed session"}}}},"401":{"description":"Missing, malformed, disabled or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"unauthorized","message":"Missing or invalid Authorization header. Use: Bearer sk_..."}}}},"404":{"description":"Unknown session.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"session_not_found","message":"Checkout session not found"}}}}}}},"/api/withdrawal-api/wallets":{"get":{"operationId":"api_withdrawals_list_wallets","tags":["Withdrawals"],"summary":"List wallets","description":"Lists the store’s active crypto wallets with their balances and minimum withdrawal amounts.","security":[{"bearerAuth":[]}],"x-required-permission":"withdrawal_api","parameters":[],"responses":{"200":{"description":"Active wallets.","content":{"application/json":{"schema":{"type":"object","properties":{"wallets":{"type":"array","items":{"type":"object","properties":{"currency":{"type":"string"},"address":{"type":"string"},"balance":{"type":"number"},"pending_balance":{"type":"number"},"min_withdrawal":{"type":"number"}}}}}},"example":{"wallets":[{"currency":"BTC","address":"bc1qexampleaddressxxxxxxxxxxxxxxxxxxxxxx","balance":0.0123,"pending_balance":0,"min_withdrawal":0.0001},{"currency":"LTC","address":"ltc1qexampleaddressxxxxxxxxxxxxxxxxxxxxx","balance":1.5,"pending_balance":0.2,"min_withdrawal":0.001}]}}}},"401":{"description":"Missing, malformed, disabled or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"unauthorized","message":"Missing or invalid Authorization header. Use: Bearer sk_..."}}}},"403":{"description":"The key lacks the `withdrawal_api` permission.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"permission_denied","message":"API key does not have withdrawal_api permission. Create a new key with this permission."}}}}}}},"/api/withdrawal-api/withdrawals":{"post":{"operationId":"api_withdrawals_create_withdrawal","tags":["Withdrawals"],"summary":"Create withdrawal","description":"Requests a withdrawal from one of the store’s wallets. The request is accepted as `pending` and processed in the background; subscribe with `webhook_url` to learn the outcome.\n\nCrypto transfers cannot be reversed. Validate destination addresses on your side before calling this endpoint.","security":[{"bearerAuth":[]}],"x-required-permission":"withdrawal_api","x-rate-limit":"50 withdrawal requests / hour","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"currency":{"type":"string","description":"`BTC`, `LTC` or `ETH`."},"amount":{"type":"number","description":"Amount to withdraw. Minimums: BTC 0.0001, LTC 0.001, ETH 0.001."},"to_address":{"type":"string","description":"Destination address. Must be valid for the currency and differ from the store wallet."},"webhook_url":{"type":"string","description":"Receives `withdrawal.completed` or `withdrawal.failed`."},"metadata":{"type":"object","description":"Key/value pairs echoed back in webhooks."}},"required":["currency","amount","to_address"]},"example":{"currency":"LTC","amount":0.05,"to_address":"ltc1qexampleaddressxxxxxxxxxxxxxxxxxxxxxx","webhook_url":"https://example.com/webhooks/withdrawals"}}}},"responses":{"201":{"description":"Withdrawal accepted for processing.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"amount":{"type":"number"},"fee_amount":{"type":"number"},"net_amount":{"type":"number"},"currency":{"type":"string"},"to_address":{"type":"string"},"created_at":{"type":"string"}}},"example":{"id":"wd_4b8e2f0c9a1d","status":"pending","amount":0.05,"fee_amount":0.002,"net_amount":0.048,"currency":"LTC","to_address":"ltc1qexampleaddressxxxxxxxxxxxxxxxxxxxxxx","created_at":"2026-03-04T18:30:00.000Z"}}}},"400":{"description":"Invalid currency, amount below minimum, bad address or insufficient balance.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"amount_too_small","message":"Minimum withdrawal for LTC is 0.001"}}}},"401":{"description":"Missing, malformed, disabled or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"unauthorized","message":"Missing or invalid Authorization header. Use: Bearer sk_..."}}}},"404":{"description":"The store has no active wallet for that currency.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"wallet_not_found","message":"No active LTC wallet found for this store. Create one in the dashboard first."}}}},"429":{"description":"The hourly limit for this key was reached.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"retry_after":{"type":"number"}}},"example":{"error":"rate_limit_exceeded","message":"Rate limit exceeded. Maximum 50 withdrawal requests per hour.","retry_after":1260}}}}}},"get":{"operationId":"api_withdrawals_list_withdrawals","tags":["Withdrawals"],"summary":"List withdrawals","description":"Returns withdrawals requested through the API, newest first.","security":[{"bearerAuth":[]}],"x-required-permission":"withdrawal_api","parameters":[{"name":"limit","in":"query","required":false,"description":"Number of results to return, between 1 and 100.","schema":{"type":"integer","description":"Number of results to return, between 1 and 100.","default":20}},{"name":"offset","in":"query","required":false,"description":"Number of results to skip.","schema":{"type":"integer","description":"Number of results to skip.","default":0}},{"name":"status","in":"query","required":false,"description":"Filter by status: `pending`, `completed` or `failed`.","schema":{"type":"string","description":"Filter by status: `pending`, `completed` or `failed`."}}],"responses":{"200":{"description":"A page of withdrawals.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"amount":{"type":"number"},"fee_amount":{"type":"number"},"net_amount":{"type":"number"},"currency":{"type":"string"},"to_address":{"type":"string"},"tx_hash":{"type":["string","null"]},"created_at":{"type":"string"},"completed_at":{"type":["string","null"]}}}},"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"}}},"example":{"data":[{"id":"wd_4b8e2f0c9a1d","status":"completed","amount":0.05,"fee_amount":0.002,"net_amount":0.048,"currency":"LTC","to_address":"ltc1qexampleaddressxxxxxxxxxxxxxxxxxxxxxx","tx_hash":"3f6c…e91a","created_at":"2026-03-04T18:30:00.000Z","completed_at":"2026-03-04T18:31:12.000Z"}],"total":1,"limit":20,"offset":0}}}},"401":{"description":"Missing, malformed, disabled or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"unauthorized","message":"Missing or invalid Authorization header. Use: Bearer sk_..."}}}}}}},"/api/withdrawal-api/withdrawals/{withdrawal_id}":{"get":{"operationId":"api_withdrawals_get_withdrawal","tags":["Withdrawals"],"summary":"Retrieve withdrawal","description":"Fetches a single withdrawal, including the transaction hash once it is broadcast.","security":[{"bearerAuth":[]}],"x-required-permission":"withdrawal_api","parameters":[{"name":"withdrawal_id","in":"path","required":true,"description":"The ID returned when the withdrawal was created.","schema":{"type":"string","description":"The ID returned when the withdrawal was created."}}],"responses":{"200":{"description":"The withdrawal.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"amount":{"type":"number"},"fee_amount":{"type":"number"},"net_amount":{"type":"number"},"currency":{"type":"string"},"to_address":{"type":"string"},"tx_hash":{"type":["string","null"]},"created_at":{"type":"string"},"completed_at":{"type":["string","null"]}}},"example":{"id":"wd_4b8e2f0c9a1d","status":"completed","amount":0.05,"fee_amount":0.002,"net_amount":0.048,"currency":"LTC","to_address":"ltc1qexampleaddressxxxxxxxxxxxxxxxxxxxxxx","tx_hash":"3f6c…e91a","created_at":"2026-03-04T18:30:00.000Z","completed_at":"2026-03-04T18:31:12.000Z"}}}},"401":{"description":"Missing, malformed, disabled or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"unauthorized","message":"Missing or invalid Authorization header. Use: Bearer sk_..."}}}},"404":{"description":"Unknown withdrawal.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"withdrawal_not_found","message":"Withdrawal not found"}}}}}}},"/api/customer-balance-api/customers":{"get":{"operationId":"api_customer_balance_list_customers","tags":["Customer balance"],"summary":"List customers","description":"Lists the store’s customers with their balances, newest first.","security":[{"bearerAuth":[]}],"x-required-permission":"customer_balance_api","parameters":[{"name":"limit","in":"query","required":false,"description":"Number of results to return, between 1 and 100.","schema":{"type":"integer","description":"Number of results to return, between 1 and 100.","default":20}},{"name":"offset","in":"query","required":false,"description":"Number of results to skip.","schema":{"type":"integer","description":"Number of results to skip.","default":0}},{"name":"min_balance","in":"query","required":false,"description":"Only customers with at least this balance.","schema":{"type":"number","description":"Only customers with at least this balance."}},{"name":"search","in":"query","required":false,"description":"Case-insensitive match on email or name.","schema":{"type":"string","description":"Case-insensitive match on email or name."}}],"responses":{"200":{"description":"A page of customers.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"name":{"type":"string"},"balance":{"type":"number"},"total_spent":{"type":"number"},"order_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"}}}},"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"}}},"example":{"data":[{"id":"6f1d3c2a-0b4e-4c8d-9a7f-2e5b1c0d9a8e","email":"jane@example.com","name":"Jane Doe","balance":25,"total_spent":189.5,"order_count":7,"created_at":"2026-01-12T09:30:00.000Z","updated_at":"2026-03-04T18:30:00.000Z"}],"total":1,"limit":20,"offset":0}}}},"401":{"description":"Missing, malformed, disabled or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"unauthorized","message":"Missing or invalid Authorization header. Use: Bearer sk_..."}}}},"403":{"description":"The key lacks the `customer_balance_api` permission.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"permission_denied","message":"API key does not have customer_balance_api permission. Create a new key with this permission."}}}}}}},"/api/customer-balance-api/customers/info":{"post":{"operationId":"api_customer_balance_get_customer","tags":["Customer balance"],"summary":"Retrieve customer","description":"Looks up one customer by email. The email goes in the JSON body, never in the URL.\n\nEmails in URL paths (for example `/customers/{email}`) are rejected with `deprecated_endpoint`. Always send the email in the body.","security":[{"bearerAuth":[]}],"x-required-permission":"customer_balance_api","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","description":"Customer email address."}},"required":["email"]},"example":{"email":"jane@example.com"}}}},"responses":{"200":{"description":"The customer.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"name":{"type":"string"},"balance":{"type":"number"},"total_spent":{"type":"number"},"order_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"}}},"example":{"id":"6f1d3c2a-0b4e-4c8d-9a7f-2e5b1c0d9a8e","email":"jane@example.com","name":"Jane Doe","balance":25,"total_spent":189.5,"order_count":7,"created_at":"2026-01-12T09:30:00.000Z","updated_at":"2026-03-04T18:30:00.000Z"}}}},"401":{"description":"Missing, malformed, disabled or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"unauthorized","message":"Missing or invalid Authorization header. Use: Bearer sk_..."}}}},"404":{"description":"No customer with that email in this store.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"customer_not_found","message":"Customer with email jane@example.com not found"}}}}}}},"/api/customer-balance-api/customers/add-balance":{"post":{"operationId":"api_customer_balance_add_balance","tags":["Customer balance"],"summary":"Add balance","description":"Credits a customer’s store balance. Customers that do not exist yet are created.","security":[{"bearerAuth":[]}],"x-required-permission":"customer_balance_api","x-rate-limit":"100 requests / hour","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","description":"Customer email address."},"amount":{"type":"number","description":"Positive amount to add."},"reason":{"type":"string","description":"Shown in the customer’s transaction history.","default":"API balance addition"},"metadata":{"type":"object","description":"Stored with the transaction."}},"required":["email","amount"]},"example":{"email":"jane@example.com","amount":10,"reason":"Referral reward"}}}},"responses":{"200":{"description":"Balance updated.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"customer":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"balance":{"type":"number"}}},"transaction":{"type":"object","properties":{"type":{"type":"string"},"amount":{"type":"number"},"reason":{"type":"string"}}}}},"example":{"success":true,"customer":{"id":"6f1d3c2a-0b4e-4c8d-9a7f-2e5b1c0d9a8e","email":"jane@example.com","balance":35},"transaction":{"type":"credit","amount":10,"reason":"Referral reward"}}}}},"400":{"description":"Invalid email or amount.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"invalid_amount","message":"Amount must be a positive number"}}}},"401":{"description":"Missing, malformed, disabled or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"unauthorized","message":"Missing or invalid Authorization header. Use: Bearer sk_..."}}}},"409":{"description":"The balance changed while updating. Retry the request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"conflict","message":"Balance changed concurrently. Please retry."}}}},"429":{"description":"The hourly limit for this key was reached.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"retry_after":{"type":"number"}}},"example":{"error":"rate_limit_exceeded","message":"Rate limit exceeded. Maximum 100 requests per hour.","retry_after":1260}}}}}}},"/api/customer-balance-api/customers/deduct-balance":{"post":{"operationId":"api_customer_balance_deduct_balance","tags":["Customer balance"],"summary":"Deduct balance","description":"Debits a customer’s store balance. Fails if the customer does not exist or has insufficient balance.","security":[{"bearerAuth":[]}],"x-required-permission":"customer_balance_api","x-rate-limit":"100 requests / hour","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","description":"Customer email address."},"amount":{"type":"number","description":"Positive amount to deduct."},"reason":{"type":"string","description":"Shown in the customer’s transaction history.","default":"API balance deduction"},"metadata":{"type":"object","description":"Stored with the transaction."}},"required":["email","amount"]},"example":{"email":"jane@example.com","amount":5,"reason":"Manual adjustment"}}}},"responses":{"200":{"description":"Balance updated.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"customer":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"balance":{"type":"number"}}},"transaction":{"type":"object","properties":{"type":{"type":"string"},"amount":{"type":"number"},"reason":{"type":"string"}}}}},"example":{"success":true,"customer":{"id":"6f1d3c2a-0b4e-4c8d-9a7f-2e5b1c0d9a8e","email":"jane@example.com","balance":20},"transaction":{"type":"debit","amount":5,"reason":"Manual adjustment"}}}}},"400":{"description":"Insufficient balance or invalid input.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"insufficient_balance","message":"Insufficient balance. Available: $2, Requested: $5"}}}},"401":{"description":"Missing, malformed, disabled or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"unauthorized","message":"Missing or invalid Authorization header. Use: Bearer sk_..."}}}},"404":{"description":"Unknown customer.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"customer_not_found","message":"Customer with email jane@example.com not found"}}}}}}},"/api/customer-balance-api/customers/transactions":{"post":{"operationId":"api_customer_balance_list_transactions","tags":["Customer balance"],"summary":"List transactions","description":"Returns a customer’s balance history. Pagination parameters go in the body for this endpoint.","security":[{"bearerAuth":[]}],"x-required-permission":"customer_balance_api","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","description":"Customer email address."},"type":{"type":"string","description":"Filter by `credit` or `debit`."},"limit":{"type":"integer","description":"Between 1 and 100.","default":20},"offset":{"type":"integer","description":"Number of results to skip.","default":0}},"required":["email"]},"example":{"email":"jane@example.com","limit":20}}}},"responses":{"200":{"description":"A page of transactions.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"amount":{"type":"number"},"reason":{"type":"string"},"metadata":{"type":"object","properties":{}},"created_at":{"type":"string"}}}},"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"}}},"example":{"data":[{"id":"b1e0c9d8-7a6f-4e5d-8c3b-2a1f0e9d8c7b","type":"credit","amount":10,"reason":"Referral reward","metadata":{},"created_at":"2026-03-04T18:30:00.000Z"}],"total":1,"limit":20,"offset":0}}}},"401":{"description":"Missing, malformed, disabled or expired API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"unauthorized","message":"Missing or invalid Authorization header. Use: Bearer sk_..."}}}},"404":{"description":"Unknown customer.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"example":{"error":"customer_not_found","message":"Customer with email jane@example.com not found"}}}}}}}}}