Buying from the Supply catalog with the API

Overview

Keysender Supply is a wholesale catalog of game keys, gift cards, and eSIMs you can source without holding stock. The Catalog endpoints let your software browse products with prices and quantities, reserve the items you want, convert the reservation into an order, and collect the delivered codes when the order completes, all against your account's wallet.

Before you start

Make sure you have:

• A bearer token from POST /login (see Getting started with the Keysender API) and the base URL https://panel.keysender.com/api/v1.0.
• Supply access on your account. It is enabled by Keysender; without it every catalog call answers 403 with a message that names the address to write to. Request it through Connect a supplier or a ticket.
• A wallet balance to pay for orders. Confirmed orders are charged to it.

Catalog errors use their own shape: {"status": "...", "error_code": "...", "message": "..."}, and dates are UTC with a Z suffix.

Steps

Browse products

1. Send GET /catalog/products. Filter with sku, name, categories, regions, price_min, price_max, qty_min, type (esim, game, wock), since (a date), updated_at (a UTC timestamp, for polling changes), and sort with sort_by (price, qty, name, updated_at) and sort_order. Page with page and per_page.
2. The response carries total, page, items_per_page, and docs, the product list. Each product has sku, name, type, qty, purchase_price, regular_price, currency, updated_at, and, where known, release_date, developer, publisher, and description.
3. Send GET /catalog/products/EXAMPLE-SKU for one product. Add additional_information=1 to include the extra fields.

Reserve, then order

1. Send POST /catalog/reserve with your own order_id and the lines:

curl -X POST "https://panel.keysender.com/api/v1.0/catalog/reserve" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"order_id": "SHOP-10422", "order_items": [{"sku": "EXAMPLE-SKU", "quantity": 2}]}'

2. Keep the returned reservation_id. A reservation holds the stock but does not charge you.
3. Send POST /catalog/order with {"reservation_id": "..."}. The response is status: "Processing"; the order is fulfilled in the background and your wallet is charged.

Collect the codes

1. Poll GET /catalog/order?order_id=SHOP-10422 every few seconds. While it still says Processing there are no products in the body yet.
2. When complete, products lists each line with sku, quantity, and assigned_codes, each {"code", "type"}. Add additional_information=1 to receive activation details for dynamic products.

Cancel a line

1. Send POST /catalog/order/cancel-item with increment_id (the order) and line_item_id. Success is HTTP 204 with no body; 403, 422, and 502 carry the error shape above.

Top up an eSIM

1. Send POST /catalog/order/top-up with order_id, iccid, and top_up_sku. The response confirms the ICCID and status: "Complete".

Confirm it works

GET /catalog/order returns the codes for every line you reserved, the order appears under Supply in the panel, and the wallet balance has dropped by the purchase price. To sell those codes on, load them into a database with Uploading and managing codes with the API.

Troubleshooting

Symptom	Cause	Action
403 on every catalog call	Supply access is not enabled on the account yet	Request it through Connect a supplier or a ticket
409 on reserve	The quantity is no longer available	Re-read the product's qty and try a smaller line
Processing for a long time	The order is still fulfilling in the background	Keep polling GET /catalog/order; do not create a second order for the same order_id

If it still is not working

Submit a ticket with the order_id, the reservation_id, and the response.