{"openapi":"3.1.0","info":{"title":"AuraStack Reseller API","version":"1.0.0","description":"Sell AuraStack products from your own shop, app or bot, paid from your prepaid euro balance.\n\nUse your **sandbox key** (`sk_sandbox_…`) on this page: sandbox orders are never charged and use a sandbox balance. A live key (`sk_live_…`, older keys `sk_aura_…`) places real, charged orders.\n\nAmounts are strings in euros with two decimals. Errors return `{ \"error\": { \"message\", \"type\" } }`. Guide: https://aurastack.link/docs/api"},"servers":[{"url":"https://aurastack.link/api/v1"}],"security":[{"apiKey":[]}],"tags":[{"name":"Balance"},{"name":"Products"},{"name":"Quotes"},{"name":"Orders"},{"name":"Sandbox"}],"paths":{"/balance":{"get":{"tags":["Balance"],"summary":"Get your balance","description":"A sandbox key sees the sandbox balance (starts at 1000.00, goes down with each sandbox order).","responses":{"200":{"description":"Your balance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Balance"}}}},"401":{"description":"Missing or invalid key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/products":{"get":{"tags":["Products"],"summary":"List products","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"next_cursor from the previous page"}],"responses":{"200":{"description":"A page of products. A page can hold fewer items than limit; keep following next_cursor until it is null.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"next_cursor":{"type":["string","null"]}}}}}},"401":{"description":"Missing or invalid key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/products/{id}":{"get":{"tags":["Products"],"summary":"Get a product","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The product","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"401":{"description":"Missing or invalid key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not sold here","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"Product not found","type":"invalid_request_error"}}}}},"500":{"description":"Unexpected error, or an id that does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/quotes":{"post":{"tags":["Quotes"],"summary":"Quote a quantity","description":"The current price. Quote right before ordering and send the quoted unit_price as expected_unit_price. A quote does not reserve the price or the stock.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteRequest"},"example":{"product_id":"prd_IQCRJMV8ww5aozXi","quantity":1}}}},"responses":{"200":{"description":"The quote","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Quote"}}}},"400":{"description":"Missing or invalid field","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not sold here","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many sandbox requests (sandbox keys: 120 writes per minute)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/orders":{"post":{"tags":["Orders"],"summary":"Create an order","description":"Buys from your balance. With a sandbox key nothing real is charged (the sandbox balance goes down); use `AuraStack-Sandbox-Outcome` to force a case.","parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":255},"example":"my-order-1001","description":"One unique key per customer purchase. Retry with the same key: you are never charged twice."},{"name":"AuraStack-Sandbox-Outcome","in":"header","schema":{"type":"string","enum":["delivered","processing","on_hold","refunded","insufficient_balance","price_changed","out_of_stock"],"default":"delivered"},"description":"Sandbox keys only, read on creation (not on replays). Ignored for live keys."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderRequest"},"example":{"product_id":"prd_IQCRJMV8ww5aozXi","quantity":1,"expected_unit_price":"23.22","billing":{"country":"FR"}}}}},"responses":{"200":{"description":"The order (delivered, processing or payment pending)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"400":{"description":"Missing or invalid field, or billing rejected (for example a VAT number VIES does not confirm)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Balance too low. Nothing was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"Insufficient balance","type":"payment_error"}}}}},"409":{"description":"Price changed (error.unit_price has the new price) or out of stock. Nothing was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"Price changed, re-quote and retry","type":"price_changed","unit_price":"23.59"}}}}},"422":{"description":"Idempotency-Key reused for a different product or quantity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Company orders: 30 per 10 minutes per server IP. Sandbox keys: 120 writes per minute, 2000 orders per 24 hours.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error, or a product id or quantity the product does not accept. Retry with the same Idempotency-Key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The order failed or was refunded. Read status and failure_code: you may have been charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"503":{"description":"Payment outcome not confirmed. Retry with the same Idempotency-Key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/orders/{id}":{"get":{"tags":["Orders"],"summary":"Get an order","description":"Poll a processing order every 10 to 30 seconds. A sandbox key reads sandbox orders only; a live key, live orders only.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"401":{"description":"Missing or invalid key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not one of your orders","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/sandbox/reset":{"post":{"tags":["Sandbox"],"summary":"Reset the sandbox","description":"Sandbox keys only. Sets the sandbox balance back to 1000.00 and clears your sandbox orders (previous order ids return 404, Idempotency-Keys can be reused). Call it at the start of each end-to-end test run.","responses":{"200":{"description":"Sandbox reset","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxReset"}}}},"401":{"description":"Missing or invalid key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Only a sandbox key can reset the sandbox","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many sandbox requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","bearerFormat":"sk_sandbox_… or sk_live_…"}},"schemas":{"Money":{"type":"string","pattern":"^\\d+\\.\\d{2}$","example":"23.22"},"Error":{"type":"object","required":["error"],"additionalProperties":false,"properties":{"error":{"type":"object","required":["message","type"],"additionalProperties":false,"properties":{"message":{"type":"string"},"type":{"type":"string","enum":["invalid_request_error","authentication_error","payment_error","price_changed","idempotency_error","rate_limit_error","api_error","internal_error"]},"unit_price":{"$ref":"#/components/schemas/Money","description":"On price_changed only: the current unit price"}}}}},"Balance":{"type":"object","additionalProperties":false,"properties":{"client_id":{"type":"string"},"available_balance":{"$ref":"#/components/schemas/Money"},"reserved_balance":{"$ref":"#/components/schemas/Money"},"currency":{"type":"string","example":"EUR"},"sandbox":{"type":"boolean"}}},"Product":{"type":"object","description":"Ignore fields not listed here.","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"unit_price":{"$ref":"#/components/schemas/Money","description":"Per unit, euros, before VAT"},"currency":{"type":"string","example":"EUR"},"available_stock":{"type":["integer","null"],"description":"null when stock is not tracked"},"minimum_quantity":{"type":"integer"},"maximum_quantity":{"type":"integer"},"updated_at":{"type":"string","format":"date-time"}}},"QuoteRequest":{"type":"object","required":["product_id","quantity"],"properties":{"product_id":{"type":"string"},"quantity":{"type":"integer","minimum":1,"maximum":100}}},"Quote":{"type":"object","description":"Ignore fields not listed here. A quote does not reserve the price or the stock.","properties":{"product_id":{"type":"string"},"quantity":{"type":"integer"},"unit_price":{"$ref":"#/components/schemas/Money"},"total_amount":{"$ref":"#/components/schemas/Money","description":"Before VAT"},"currency":{"type":"string"},"available_stock":{"type":["integer","null"]},"can_purchase":{"type":"boolean"},"quoted_at":{"type":"string","format":"date-time"},"sandbox":{"type":"boolean"}}},"OrderRequest":{"type":"object","required":["product_id","quantity","expected_unit_price","billing"],"properties":{"product_id":{"type":"string"},"quantity":{"type":"integer","minimum":1,"maximum":100,"description":"Also within the product's minimum_quantity and maximum_quantity"},"expected_unit_price":{"$ref":"#/components/schemas/Money","description":"The quote's unit_price (euros, before VAT)"},"billing":{"type":"object","required":["country"],"description":"Your own billing details (you are our customer).","properties":{"country":{"type":"string","pattern":"^[A-Za-z]{2}$","example":"FR","description":"2-letter ISO 3166-1 code"},"is_company":{"type":"boolean","description":"JSON boolean true (the string \"true\" counts as false)"},"company_name":{"type":"string"},"vat_number":{"type":"string","description":"EU VAT numbers start with the country prefix and are checked with VIES"}}}}},"OrderVat":{"type":"object","additionalProperties":false,"properties":{"rate":{"type":"number","example":20},"amount":{"$ref":"#/components/schemas/Money"},"country":{"type":"string"}}},"Order":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","example":"api_3f9c2a71d0b84e6a5c1d7e02","description":"api_… for live orders, api_sbx_… for sandbox orders"},"product_id":{"type":"string"},"quantity":{"type":"integer"},"status":{"type":"string","enum":["pending_payment","payment_captured","processing","delivered","failed","refunded"]},"unit_price":{"$ref":"#/components/schemas/Money"},"total_amount":{"$ref":"#/components/schemas/Money","description":"Charged to your balance, VAT included"},"vat":{"oneOf":[{"$ref":"#/components/schemas/OrderVat"},{"type":"null"}]},"currency":{"type":"string","description":"EUR (orders before October 2026: USD)"},"delivery":{"type":["object","null"],"additionalProperties":false,"properties":{"items":{"type":"array","items":{"type":"string"}}}},"failure_code":{"type":["string","null"]},"failure_message":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"delivered_at":{"type":["string","null"],"format":"date-time"},"sandbox":{"type":"boolean"}}},"SandboxReset":{"type":"object","additionalProperties":false,"properties":{"available_balance":{"$ref":"#/components/schemas/Money"},"currency":{"type":"string"},"sandbox":{"type":"boolean"}}}}}}