{"openapi":"3.1.0","info":{"title":"BuyCheapKeys Partner API","version":"1.0.0","description":"Import the BuyCheapKeys catalogue, buy with your prepaid balance and receive keys, gift links, accounts or activation links automatically. All amounts are in EUR. Use a `bck_test_` key for the sandbox (fake keys, test balance) and a `bck_live_` key in production.","contact":{"name":"BuyCheapKeys Partners","email":"partners@buycheapkeys.com","url":"https://buycheapkeys.com/en/partners"}},"servers":[{"url":"https://buycheapkeys.com/partner-api/v1","description":"Production and sandbox (the key decides the mode)"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Account"},{"name":"Catalog"},{"name":"Orders"},{"name":"Webhooks"}],"paths":{"/ping":{"get":{"tags":["Account"],"summary":"Check credentials","responses":{"200":{"description":"Authenticated","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"partnerId":{"type":"string"},"mode":{"type":"string","enum":["live","test"]},"scopes":{"type":"array","items":{"type":"string"}},"ip":{"type":"string"}}}}}},"401":{"description":"Invalid or missing key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/balance":{"get":{"tags":["Account"],"summary":"Current prepaid balance","responses":{"200":{"description":"Balance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Balance"}}}}}}},"/products":{"get":{"tags":["Catalog"],"summary":"List / sync products","description":"Ordered by `updatedAt` then id. Sync with the keyset cursor: pass `nextCursor` from the previous response as `cursor` while `hasMore` is true and keep the last one for the next run (never skips or repeats products). Products that left the catalogue come back with `removed: true` when `includeRemoved=true`.","parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque keyset cursor (nextCursor of a previous response). Recommended for sync."},{"name":"updatedSince","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"inStock","in":"query","schema":{"type":"boolean"}},{"name":"platform","in":"query","schema":{"type":"string"},"example":"Steam"},{"name":"region","in":"query","schema":{"type":"string"},"example":"Europe"},{"name":"productType","in":"query","schema":{"type":"string","enum":["game","dlc","software","gift-card","subscription","game-point"]}},{"name":"deliveryType","in":"query","schema":{"type":"string","enum":["key","gift","account","link"]}},{"name":"search","in":"query","schema":{"type":"string","minLength":2}},{"name":"ids","in":"query","description":"Comma-separated product ids (max 100)","schema":{"type":"string"}},{"name":"includeRemoved","in":"query","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Page of products","content":{"application/json":{"schema":{"type":"object","properties":{"page":{"type":["integer","null"]},"limit":{"type":"integer"},"total":{"type":["integer","null"],"description":"null on cursor pages"},"totalPages":{"type":["integer","null"]},"nextCursor":{"type":["string","null"]},"hasMore":{"type":"boolean"},"results":{"type":"array","items":{"$ref":"#/components/schemas/Product"}}}}}}}}}},"/products/{id}":{"get":{"tags":["Catalog"],"summary":"Get one product","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Product","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"404":{"description":"Unknown product","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/meta":{"get":{"tags":["Catalog"],"summary":"Platforms, regions and types with product counts","responses":{"200":{"description":"Facets"}}}},"/orders":{"post":{"tags":["Orders"],"summary":"Place an order (charged to your balance)","description":"The live supplier price is checked for every line. If the unit price is above `maxUnitPrice` the order is rejected with `PRICE_CHANGED` and nothing is charged. On success the total is debited immediately and the order is `processing`; keys arrive within seconds (use `?wait=` or webhooks). Undelivered units are refunded to your balance automatically. Delivered keys, gifts, accounts and links are final and cannot be returned.","parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string","minLength":8,"maxLength":100},"description":"Retry-safe: the same key + body returns the original response."},{"name":"wait","in":"query","schema":{"type":"integer","minimum":0,"maximum":25},"description":"Seconds to wait for completion before answering."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderRequest"}}}},"responses":{"201":{"description":"Order created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"400":{"description":"VALIDATION_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"INSUFFICIENT_BALANCE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"PRICE_CHANGED | OUT_OF_STOCK | PRODUCT_UNAVAILABLE | DUPLICATE_EXTERNAL_ID | IDEMPOTENCY_CONFLICT","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"ORDER_LIMIT_EXCEEDED | DAILY_LIMIT_EXCEEDED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"SERVICE_UNAVAILABLE (not charged)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"tags":["Orders"],"summary":"Search orders","parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"status","in":"query","schema":{"$ref":"#/components/schemas/OrderStatus"}},{"name":"externalId","in":"query","schema":{"type":"string"}},{"name":"createdFrom","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"createdTo","in":"query","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Orders","content":{"application/json":{"schema":{"type":"object","properties":{"page":{"type":"integer"},"total":{"type":"integer"},"results":{"type":"array","items":{"$ref":"#/components/schemas/Order"}}}}}}}}}},"/orders/{id}":{"get":{"tags":["Orders"],"summary":"Get order","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/orders/{id}/keys":{"get":{"tags":["Orders"],"summary":"Download delivered keys","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Keys","content":{"application/json":{"schema":{"type":"object","properties":{"orderId":{"type":"string"},"keys":{"type":"array","items":{"$ref":"#/components/schemas/Key"}}}}}}}}}},"/webhooks/test":{"post":{"tags":["Webhooks"],"summary":"Send a webhook.test event to your endpoint","responses":{"202":{"description":"Queued"}}}}},"webhooks":{"orderEvent":{"post":{"summary":"order.completed | order.partially_completed | order.failed | balance.credited | webhook.test","description":"Headers: `X-BCK-Event`, `X-BCK-Delivery` (unique id, use it to de-duplicate) and `X-BCK-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, t + \".\" + rawBody)>`. Answer 2xx within 8 s; failures are retried for ~26 h.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"200":{"description":"Acknowledged"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"`Authorization: Bearer bck_live_…` (X-Api-Key is also accepted)"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{},"requestId":{"type":"string"}},"required":["code","message","requestId"]}}},"Balance":{"type":"object","properties":{"balance":{"type":"number","example":125.4},"currency":{"type":"string","example":"EUR"},"mode":{"type":"string","enum":["live","test"]}}},"Product":{"type":"object","properties":{"id":{"type":"string","example":"prod-17298"},"name":{"type":"string","example":"Terraria (Steam Gift)"},"platform":{"type":"string","example":"Steam"},"region":{"type":"string","example":"Europe","description":"Global, Europe, RoW, a country name, …"},"productType":{"type":"string","enum":["game","dlc","software","gift-card","subscription","game-point"]},"deliveryType":{"type":"string","enum":["key","gift","account","link"],"description":"key = code to redeem; gift = Steam gift link; account = login credentials; link = activation link"},"price":{"type":"number","description":"Your unit price in EUR (VAT not included)","example":3.71},"currency":{"type":"string","example":"EUR"},"inStock":{"type":"boolean"},"qty":{"type":["integer","null"],"description":"Approximate units available (capped at 99); null = unknown"},"activation":{"type":["object","null"],"properties":{"excludedCountries":{"type":"array","items":{"type":"string"},"description":"ISO 3166-1 alpha-2 codes where the product can NOT be activated"},"allowedCountryCount":{"type":["integer","null"]}}},"description":{"type":["string","null"]},"activationDetails":{"type":["string","null"],"description":"Redemption instructions (English)"},"languages":{"type":"array","items":{"type":"string"}},"genres":{"type":"array","items":{"type":"string"}},"developer":{"type":["string","null"]},"publisher":{"type":["string","null"]},"releaseDate":{"type":["string","null"]},"ageRating":{"type":["string","null"]},"coverImage":{"type":["string","null"],"format":"uri"},"screenshots":{"type":"array","items":{"type":"string","format":"uri"}},"systemRequirements":{},"url":{"type":["string","null"],"format":"uri"},"updatedAt":{"type":"string","format":"date-time"},"removed":{"type":"boolean"}}},"OrderRequest":{"type":"object","required":["externalId","items"],"additionalProperties":false,"properties":{"externalId":{"type":"string","maxLength":100,"pattern":"^[A-Za-z0-9._:-]+$","description":"Your unique order reference. Re-using it returns DUPLICATE_EXTERNAL_ID with the existing order id."},"items":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"object","required":["productId","qty","maxUnitPrice"],"additionalProperties":false,"properties":{"productId":{"type":"string"},"qty":{"type":"integer","minimum":1,"maximum":9},"maxUnitPrice":{"type":"number","description":"Highest unit price (EUR) you accept"}}}}},"example":{"externalId":"shop-10045","items":[{"productId":"prod-17298","qty":1,"maxUnitPrice":4.5}]}},"OrderStatus":{"type":"string","enum":["processing","completed","partially_completed","failed"]},"Order":{"type":"object","properties":{"id":{"type":"string","example":"po_7f3k2m9q4x8z1c5v6b0n"},"externalId":{"type":"string"},"mode":{"type":"string","enum":["live","test"]},"status":{"$ref":"#/components/schemas/OrderStatus"},"currency":{"type":"string"},"total":{"type":"number"},"refunded":{"type":"number"},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"},"failure":{"type":["object","null"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"items":{"type":"array","items":{"type":"object","properties":{"line":{"type":"integer"},"productId":{"type":"string"},"name":{"type":"string"},"deliveryType":{"type":"string"},"qty":{"type":"integer"},"unitPrice":{"type":"number"},"status":{"type":"string","enum":["processing","completed","failed"]},"deliveredQty":{"type":"integer"}}}}}},"Key":{"type":"object","properties":{"id":{"type":"string"},"line":{"type":"integer"},"productId":{"type":"string"},"deliveryType":{"type":"string","enum":["key","gift","account","link"]},"contentType":{"type":"string","description":"text/plain, or image/png|jpeg|gif (value is base64)"},"value":{"type":"string","description":"The key, gift/activation URL or account credentials"},"status":{"type":"string","enum":["delivered"]},"deliveredAt":{"type":"string","format":"date-time"}}},"WebhookEvent":{"type":"object","properties":{"id":{"type":"string"},"event":{"type":"string"},"mode":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"data":{}}}}}}