{"openapi":"3.1.0","jsonSchemaDialect":"https://json-schema.org/draft/2020-12/schema","info":{"title":"Dingyue Product Ordering API","version":"1.0.0","description":"Purchase redemption codes from a shared prepaid API balance.\nAuthenticate with a dy_sk_ key. Catalog and balance access require shop:read; every order endpoint requires shop:order.\nPOST /orders is idempotent on externalOrderId. Retry network failures with the same value and unchanged productId/qty.\nPrices are level-based. Always read GET /products and optionally send expectedUnitPrice to reject silent price changes.\nDeliver every returned code together with redeemUrl."},"servers":[{"url":"https://api.dingyue.app/shop/v1"}],"tags":[{"name":"Products"},{"name":"Account"},{"name":"Orders"}],"security":[{"bearerAuth":[]}],"paths":{"/pricing":{"get":{"operationId":"getPublicPricing","tags":["Products"],"security":[],"summary":"Public price list: every level price for enabled products, plus level thresholds (no auth)","responses":{"200":{"description":"Level thresholds and per-level sell prices","content":{"application/json":{"schema":{"type":"object","required":["levels","products"],"properties":{"levels":{"type":"array","items":{"type":"object","required":["level","threshold"],"properties":{"level":{"type":"integer"},"threshold":{"type":"string","description":"Cumulative top-up USD required for this level"}}}},"products":{"type":"array","items":{"type":"object","required":["id","name","currency","levelPrices"],"properties":{"id":{"type":"string"},"slug":{"type":"string","nullable":true},"name":{"type":"string"},"currency":{"type":"string"},"levelPrices":{"type":"object","additionalProperties":{"type":"string","nullable":true},"description":"Effective USD unit price per level (level1..level5)"}}}}}}}}},"500":{"$ref":"#/components/responses/ServerError"}}}},"/products":{"get":{"operationId":"listProducts","tags":["Products"],"x-required-scopes":["shop:read"],"summary":"List enabled products at the caller level price","responses":{"200":{"description":"Product catalog","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"$ref":"#/components/responses/SupplierUnavailable"}}}},"/products/{id}/availability":{"get":{"operationId":"checkProductAvailability","tags":["Products"],"x-required-scopes":["shop:read"],"summary":"Check quantity and current price","parameters":[{"name":"id","in":"path","required":true,"description":"Supplier product identifier returned by GET /products","schema":{"type":"string","minLength":1,"maxLength":128}},{"name":"qty","in":"query","required":false,"description":"Requested quantity","schema":{"type":"integer","minimum":1,"maximum":1000,"default":1}}],"responses":{"200":{"description":"Availability result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Availability"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"$ref":"#/components/responses/SupplierUnavailable"}}}},"/balance":{"get":{"operationId":"getBalance","tags":["Account"],"x-required-scopes":["shop:read"],"summary":"Get shared API balance and level","responses":{"200":{"description":"Balance and level","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Balance"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/orders":{"post":{"operationId":"createOrder","tags":["Orders"],"x-required-scopes":["shop:order"],"summary":"Purchase redemption codes from balance","description":"Idempotent on externalOrderId: retry any uncertain outcome with the same externalOrderId, productId and qty. May also reject with 403 key_order_limit_exceeded (key single-order cap) or 402 key_daily_limit_exceeded (key daily spend cap).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrderRequest"}}}},"responses":{"200":{"description":"Delivered or idempotently replayed order with codes and redeemUrl","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"$ref":"#/components/responses/SupplierUnavailable"}}},"get":{"operationId":"listOrders","tags":["Orders"],"x-required-scopes":["shop:order"],"summary":"List caller orders","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","required":false,"description":"Opaque nextCursor returned by the previous page","schema":{"type":"string","minLength":1}},{"name":"externalOrderId","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":64}}],"responses":{"200":{"description":"Cursor-paginated orders","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderList"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/orders/{id}":{"get":{"operationId":"getOrder","tags":["Orders"],"x-required-scopes":["shop:order"],"summary":"Get an order; delivered orders include codes","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Order detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"dy_sk_ API key with shop:read; all order endpoints also require shop:order"}},"responses":{"BadRequest":{"description":"Invalid path, query, or request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"API key is missing a required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"PaymentRequired":{"description":"Insufficient available API balance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Product or order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Conflict":{"description":"Idempotency, price, stock, or order-state conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Account request rate exceeded","headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Seconds before retrying"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SupplierUnavailable":{"description":"Product ordering is not configured, the supplier is unavailable, another attempt is in progress, or an order result is pending local commit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ServerError":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"DecimalMoney":{"type":"string","pattern":"^\\d+(\\.\\d{1,4})?$","description":"Non-negative decimal amount encoded as a string","examples":["17.7900"]},"LevelSummary":{"type":"object","required":["level","scoreMicrocents","score","nextLevel"],"properties":{"level":{"type":"integer","minimum":1,"maximum":5},"scoreMicrocents":{"type":"integer","minimum":0},"score":{"$ref":"#/components/schemas/DecimalMoney"},"nextLevel":{"oneOf":[{"type":"object","required":["level","thresholdMicrocents","remainingMicrocents","remaining"],"properties":{"level":{"type":"integer","minimum":2,"maximum":5},"thresholdMicrocents":{"type":"integer","minimum":0},"remainingMicrocents":{"type":"integer","minimum":0},"remaining":{"$ref":"#/components/schemas/DecimalMoney"}},"additionalProperties":false},{"type":"null"}]}},"additionalProperties":false},"Product":{"type":"object","required":["id","slug","name","price","currency","fulfillmentMode","inStock","stockMode","stock","stockCapped","availabilityStatus","deliveryMode"],"properties":{"id":{"type":"string"},"slug":{"type":["string","null"]},"name":{"type":"string"},"price":{"$ref":"#/components/schemas/DecimalMoney"},"currency":{"type":"string","const":"USD"},"fulfillmentMode":{"type":["string","null"]},"inStock":{"type":"boolean"},"stockMode":{"type":["string","null"],"enum":["inventory","on_demand",null]},"stock":{"type":["integer","null"],"minimum":0},"stockCapped":{"type":"boolean"},"availabilityStatus":{"type":"string"},"deliveryMode":{"type":["string","null"]}},"additionalProperties":false},"ProductList":{"type":"object","required":["level","products"],"properties":{"level":{"$ref":"#/components/schemas/LevelSummary"},"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"}}},"additionalProperties":false},"Availability":{"type":"object","required":["productId","qty","available","unitPrice","currency","stockMode","availabilityStatus","deliveryMode","checkedAt"],"properties":{"productId":{"type":"string"},"qty":{"type":"integer","minimum":1,"maximum":1000},"available":{"type":"boolean"},"unitPrice":{"$ref":"#/components/schemas/DecimalMoney"},"currency":{"type":"string","const":"USD"},"stockMode":{"type":["string","null"],"enum":["inventory","on_demand",null]},"availabilityStatus":{"type":"string"},"deliveryMode":{"type":["string","null"]},"checkedAt":{"type":"integer","minimum":0,"description":"Unix timestamp in seconds"}},"additionalProperties":false},"Balance":{"type":"object","required":["balance","reserved","available","currency","level"],"properties":{"balance":{"$ref":"#/components/schemas/DecimalMoney"},"reserved":{"$ref":"#/components/schemas/DecimalMoney"},"available":{"$ref":"#/components/schemas/DecimalMoney"},"currency":{"type":"string","const":"USD"},"level":{"$ref":"#/components/schemas/LevelSummary"}},"additionalProperties":false},"CreateOrderRequest":{"type":"object","required":["externalOrderId","productId","qty"],"properties":{"externalOrderId":{"type":"string","minLength":1,"maxLength":64},"productId":{"type":"string","minLength":1,"maxLength":128},"qty":{"type":"integer","minimum":1,"maximum":1000},"expectedUnitPrice":{"type":"string","pattern":"^\\d+(\\.\\d{1,2})?$"}},"additionalProperties":false},"Order":{"type":"object","required":["orderId","externalOrderId","productId","productName","qty","unitPrice","amount","currency","status","codes","redeemUrl","errorCode","createdAt","deliveredAt","reused"],"properties":{"orderId":{"type":"string"},"externalOrderId":{"type":"string"},"productId":{"type":"string"},"productName":{"type":"string"},"qty":{"type":"integer","minimum":1},"unitPrice":{"$ref":"#/components/schemas/DecimalMoney"},"amount":{"$ref":"#/components/schemas/DecimalMoney"},"currency":{"type":"string","const":"USD"},"status":{"type":"string","enum":["processing","retryable","delivered","failed","refunded"]},"codes":{"type":"array","items":{"type":"string"}},"redeemUrl":{"type":["string","null"],"format":"uri"},"errorCode":{"type":["string","null"]},"createdAt":{"type":"integer","minimum":0,"description":"Unix timestamp in seconds"},"deliveredAt":{"type":["integer","null"],"minimum":0,"description":"Unix timestamp in seconds"},"reused":{"type":"boolean"}},"additionalProperties":false},"OrderList":{"type":"object","required":["orders","hasMore","nextCursor"],"properties":{"orders":{"type":"array","items":{"$ref":"#/components/schemas/Order"}},"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}},"additionalProperties":false},"Error":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string"},"message":{"type":"string"},"details":{}},"additionalProperties":false}}}}