A reseller network turns your store into a wholesaler: other shops, bots and marketplaces buy codes and top-ups from you and sell them on. They connect through an API, send thousands of orders and expect the same answer every time.
This guide covers the parts a reseller API for digital goods needs, using the API in Kavia Commerce as the example. The reseller panel and API are part of the Pro and Max plans.
Keys: shown once, stored as a hash
Each partner gets their own API key. The key is shown once when it is created and stored only as a hash, the same way passwords are. If your database ever leaks, the keys in it cannot be used.
Each key can be limited to an allow-list of IP addresses and has its own rate limit, so one partner's bug cannot slow down everyone else.
Signed requests
A key alone is not enough: anyone who sees a request in a log could replay it. Kavia Commerce requests are signed with HMAC, a standard way to prove a message came from the key holder and was not changed (RFC 2104). Each request also carries a timestamp and a one-time nonce, so an old request cannot be sent again.
Idempotent orders: the rule that saves money
Networks fail. A partner sends an order, the connection drops before the answer arrives, and their system retries. Without protection, that is two orders and two charges.
The fix is idempotency: the partner sends their own order ID with every order. In Kavia Commerce one externalOrderId is one order. A retry with the same ID returns the original order instead of creating a new one. It is the same principle payment APIs use; see Stripe's explanation of idempotent requests.
A simplified order looks like this:
POST /v1/orders with productId, quantity and externalOrderId "A-77812"
Response: status COMPLETED, the total as a decimal string, the currency and the codes.
Money amounts travel as decimal strings, never as floating-point numbers, so 11.20 stays 11.20.
Price groups and bulk orders
Partners do not all pay the same. Price groups let you give a large reseller a different price list from a small one, without separate catalogs. Bulk orders let a partner buy many codes in one request.
Webhooks: tell the partner what happened
Top-ups can take a few seconds, and some fail. Instead of making partners poll, the platform sends webhooks: order.created, order.completed, order.failed and order.refunded. A failed order releases the held amount on the partner's balance.
Sandbox keys
Partners need to test before they spend money. Sandbox keys let them place test orders and receive webhooks without touching real stock.
Try it
The live demos page has an interactive reseller API demo in the browser, and the platform page shows a real request and response with sample values. The live demo store shows the kind of catalog partners order from. To test against the API itself, request a sandbox key. Our security page lists how keys, balances and orders are protected.
Questions
What happens if a partner sends the same order twice?
Nothing extra. Each order carries the partner's externalOrderId, and one externalOrderId is one order. A retry returns the original order instead of creating and charging a second one.
How are reseller API keys protected?
Keys are shown once when created and stored only as hashes. Each key can be limited to an IP allow-list and has its own rate limit, and every request is signed with HMAC, a timestamp and a nonce.
Can different resellers get different prices?
Yes. Price groups let you assign each partner a price list without keeping separate catalogs.
Which plan includes the reseller API?
The reseller panel and API are part of Kavia Pro and Kavia Max.