Reseller API codes and plans

Issue batches of redeemable codes, revoke them, redeem a code into a key and manage your tariff plans through the reseller API.

Code batches

A batch is created with POST /code-batches (scope codes; an Idempotency-Key header is required): label, count up to 200, amount_usd up to 5000 per code. Optional: key_expires_days or key_expires_hours (how long the key lives after the code is activated, default 90 days) and codes_valid_until (until when a code can be activated, ISO 8601; later the unactivated codes are revoked automatically and the reserve returns).

curl -s -X POST https://app.oneprovider.dev/partner/v1/code-batches \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Idempotency-Key: batch-oct-001" \
-H "Content-Type: application/json" \
-d '{"label":"October promo","count":50,"amount_usd":"5.00","key_expires_hours":24,"codes_valid_until":"2026-12-31T23:59:59Z"}'

A batch only reserves its cost (count x amount_usd) on the reseller balance: it must fit into Free, but nothing is debited. When a code is activated it becomes a key whose limit stays reserved, and money is debited as it is spent. Revoking unactivated codes releases the reserve. Batch object: id, label, count, amount_usd, used, revoked, key_expires_hours, key_expires_days, codes_valid_until, created_at.

# list batches, read one, list its codes
curl -s https://app.oneprovider.dev/partner/v1/code-batches -H "Authorization: Bearer $OP_PARTNER_TOKEN"
curl -s https://app.oneprovider.dev/partner/v1/code-batches/<batch id> -H "Authorization: Bearer $OP_PARTNER_TOKEN"
curl -s "https://app.oneprovider.dev/partner/v1/code-batches/<batch id>/codes?status=active&limit=100" \
-H "Authorization: Bearer $OP_PARTNER_TOKEN"
# revoke what is still unredeemed
curl -s -X POST https://app.oneprovider.dev/partner/v1/code-batches/<batch id>/revoke -H "Authorization: Bearer $OP_PARTNER_TOKEN"

Code object: code, status (active, used, revoked: active/used/revoked), amount_usd, batch_id, redeemed_at, key_id. Status of one code: GET /codes/{code}.

Redeem a code through the API

If you turn a code into a key yourself, call POST /codes/{code}/redeem (an Idempotency-Key header is required). The customer can be passed as customer_id or customer_external_id.

curl -s -X POST https://app.oneprovider.dev/partner/v1/codes/<code>/redeem \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Idempotency-Key: redeem-<code>" \
-H "Content-Type: application/json" \
-d '{"customer_external_id":"user-77"}'

The 201 answer contains the key and its secret (once). An already redeemed code gives 409 code_used, a revoked one 409 code_revoked.

Plans

A plan is your price to clients: how many USD the key gets, how much the client pays you and in which currency, for how long. Plans feed POST /orders (the plan_id parameter). The maximum is 20 plans (409 plan_limit). Reading plans needs the read scope, changing them needs plans.

curl -s -X POST https://app.oneprovider.dev/partner/v1/plans \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"Start 10 USD","balance_usd":"10.00","price":"890.00","currency":"RUB","expires_days":30,"sort":1,"active":true}'
curl -s -X PATCH https://app.oneprovider.dev/partner/v1/plans/<plan id> -H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Content-Type: application/json" -d '{"active":false}'
curl -s -X DELETE https://app.oneprovider.dev/partner/v1/plans/<plan id> -H "Authorization: Bearer $OP_PARTNER_TOKEN"

GET /pricing returns the limits to stay within: minimum and maximum key amount, maximum lifetime, maximum code amount, batch size, and the number of plans and tokens.