Reseller API

The Reseller API lets an approved reseller browse a merchant’s wholesale catalog, check their balance, and buy stock programmatically. These are the same operations the Reseller tab of the customer portal exposes, but as a machine interface. It is a separate API from the merchant Developer API. Different base path, different credential family, different key prefix. A merchant automating their own reseller program uses /dev/v1/resellers instead.

	Reseller API	Developer API
Base path	`/reseller/v1`	`/dev/v1`
Key prefix	`shxr_`	`shx_`
Who holds the key	the reseller	the merchant
Where keys are created	customer portal, Reseller tab	dashboard, API keys

Wholesale orders are paid from your reseller balance, not with a card. Top up your balance in the portal before ordering. This API has no payment step.

Authentication

Send your key as a bearer token on every request:

curl https://api.shoppex.io/reseller/v1/me \
  -H "Authorization: Bearer shxr_your_key_here"

Keys are created in the customer portal of the merchant’s store, under the Reseller tab. The full key is shown once at creation. Shoppex only stores its hash, so a lost key cannot be recovered, only replaced. Revoking a key is permanent.

Open https://<shop-domain>/customer-portal on the merchant’s storefront, sign in with your customer account, and select the Reseller tab. You can create API keys and top up your balance there — see the reseller panel guide. If needed, use https://portal.shoppex.io as the central portal fallback.

The key determines both the shop and the reseller identity. Passing a shop or reseller identifier in the request is not possible and any such parameter is ignored.

401 — invalid, unknown, or revoked key

Returned for a missing or malformed Authorization header, an unrecognised key, and a revoked key. The message is always Invalid API key. Shoppex does not distinguish the cases, so a revoked key cannot be used to probe which keys ever existed.

403 — program disabled or account not active

The reseller program of this shop is not active. when the merchant turned the program off. This reseller account is suspended. when the merchant suspended you. Any other non-active status returns This reseller account cannot use the API.

429 — rate limited

See Rate limits. Retry after the window in retry-after.

Errors

Every failure uses one envelope:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "doc_url": "https://docs.shoppex.io/reseller-api/errors",
    "details": [
      { "field": "per_page", "message": "per_page must be 100 or less" }
    ]
  }
}

details appears only on VALIDATION_ERROR. error.balance appears only on INSUFFICIENT_BALANCE.

Code	Status	When
`UNAUTHORIZED`	401	Missing, unknown, or revoked key
`FORBIDDEN`	403	Program disabled, or reseller not `ACTIVE`
`IDEMPOTENCY_KEY_REQUIRED`	400	`Idempotency-Key` missing or longer than 128 characters on order create
`INSUFFICIENT_BALANCE`	402	Wholesale total is more than available balance
`NOT_FOUND`	404	Generic not found
`ORDER_NOT_FOUND`	404	Unknown order, or an order belonging to another reseller
`PRODUCT_NOT_FOUND`	404	Product not enrolled in the program, or unknown
`CONFLICT`	409	Idempotency-key reuse with a different payload, or a request still in flight
`VALIDATION_ERROR`	422	Body or query failed validation
`RATE_LIMITED`	429	More requests sent than the rate limit allows
`INTERNAL_ERROR`	500	Unexpected server error

Every response carries an x-request-id header, whether it succeeds or fails. Quote it when reporting a problem to the merchant.

An order belonging to a different reseller returns ORDER_NOT_FOUND, not 403. Ownership is checked before existence, so the API never reveals that an order exists but is not yours.

Idempotency

POST /reseller/v1/orders requires an Idempotency-Key header. It is the only endpoint that requires one, and the only one that reads it.

curl -X POST https://api.shoppex.io/reseller/v1/orders \
  -H "Authorization: Bearer shxr_your_key_here" \
  -H "Idempotency-Key: restock-2026-07-24-001" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"product_id":"019cb402-5555-7000-8000-000000000005","quantity":5}]}'

Rules:

Same key, same payload → the stored response is replayed. No second order, no second charge. The response carries idempotency-status: cached, and data.order.reused is true.
Same key, different payload → 409 CONFLICT.
Same key while the first call is still running → 409 CONFLICT with idempotency-status: processing. Retry shortly.
A key that placed an order never expires. The cached response lives 24 hours. After that the order itself still answers the key: the same basket returns the original order with reused: true, a different basket returns 409 RESELLER_ORDER_IDEMPOTENCY_CONFLICT. Use a new key for every new order.
Maximum key length is 128 characters. X-Idempotency-Key is accepted as a synonym.

4xx responses are cached. A 402 INSUFFICIENT_BALANCE replayed under the same key returns the same 402, even after you have topped up. Use a new Idempotency-Key after a top-up. Otherwise the retry keeps failing for 24 hours.

Only 5xx and 429 responses are never cached, so a transient outage cannot permanently poison a key. Beyond the cache, the order itself carries an idempotency hash in the database. A duplicate cannot be charged twice even if the cache is unavailable. That backstop answers the same way the cache does: the original order for the same basket, or 409 CONFLICT for a different one. The idempotency-status response header tells you which path ran: created, cached, processing, or bypassed.

Rate limits

A token bucket per key: 30 requests burst, refilling 10 tokens every 2 seconds. It applies uniformly to every endpoint, reads included.

Header	Meaning
`x-ratelimit-limit`	Bucket capacity
`x-ratelimit-remaining`	Tokens left
`x-ratelimit-reset`	Seconds until the next refill
`retry-after`	Seconds to wait, sent only when the request is rejected

Rejected requests return 429 with code RATE_LIMITED. An invalid key never consumes a token.

GET /reseller/v1/me

Your identity, tier, and progress toward the next tier.

curl https://api.shoppex.io/reseller/v1/me \
  -H "Authorization: Bearer shxr_your_key_here"

{
  "data": {
    "shop": {
      "id": "019cb402-0000-7000-8000-000000000000",
      "name": "Demo Store",
      "slug": "demo",
      "currency": "EUR"
    },
    "reseller": {
      "id": "019cb402-1111-7000-8000-000000000001",
      "status": "ACTIVE",
      "email": "[email protected]"
    },
    "tier": {
      "id": "019cb402-3333-7000-8000-000000000003",
      "name": "Gold",
      "discount_percent": 15
    },
    "progress": {
      "lifetime_revenue": "120.00",
      "lifetime_orders": 4,
      "next_tier": {
        "id": "019cb402-4444-7000-8000-000000000004",
        "name": "Platinum",
        "discount_percent": 25,
        "requirements": { "revenue": "500.00", "orders": 20, "requires_both": false },
        "remaining": { "revenue": "380.00", "orders": 16 }
      }
    }
  }
}

next_tier is null when no higher tier has an auto-advance threshold configured. Inside requirements, revenue and orders are independently nullable. The merchant can configure only one of them. requires_both: false means either threshold alone advances you.

GET /reseller/v1/balance

{
  "data": {
    "currency": "EUR",
    "balance": "200.00",
    "hold_balance": "10.00",
    "available": "190.00",
    "is_active": true
  }
}

available is balance - hold_balance and is the figure an order is checked against. A reseller who has never topped up reads all zeros.

GET /reseller/v1/products

Each product includes description exactly as stored by the merchant, including HTML when present. An unset description is null; an empty description remains "". The wholesale catalog: only products the merchant enrolled in the program, priced for your tier.

Query	Type	Default
`search`	string, max 128 chars	—
`page`	integer ≥ 1	`1`
`per_page`	integer 1–100	`25`

{
  "data": [
    {
      "product_id": "019cb402-5555-7000-8000-000000000005",
      "uniqid": "prod_1",
      "title": "Pro License",
      "description": "A license for the Pro edition.",
      "type": "SERIALS",
      "stock": 12,
      "orderable": true,
      "currency": "EUR",
      "base_price": "100.00",
      "wholesale_price": "85.00",
      "discount_percent": 15,
      "applied_override": "tier",
      "volume_discount_enabled": true,
      "custom_fields": [
        {
          "name": "Discord Server Invite",
          "type": "text",
          "required": true,
          "placeholder": "https://discord.gg/...",
          "default_value": "",
          "regex": null,
          "min_length": null,
          "format": "discord_invite"
        }
      ],
      "variants": [
        {
          "variant_id": "019cb402-6666-7000-8000-000000000006",
          "title": "1 month",
          "stock": 5,
          "orderable": true,
          "base_price": "50.00",
          "wholesale_price": "42.50",
          "discount_percent": 15,
          "applied_override": "tier"
        }
      ]
    }
  ],
  "pagination": { "page": 1, "per_page": 25, "total": 1 },
  "currency": "EUR"
}

applied_override tells you which rung of the price cascade set your price. It is variant (a per-variant override), product (a per-product override), or tier (your tier’s flat discount). stock: -1 means unlimited. Check orderable, not stock, before you order a row. stock is the merchant’s local stock. A row with "orderable": false is the only one POST /reseller/v1/orders refuses as out of stock. On a product that has variants, the top-level orderable is a gate for the whole product. It is true when the product itself is orderable or at least one of its variants is. So filtering a listing on the top-level flag never hides something you can buy. But once a product is in, still check each variant’s own orderable to pick the option to order. custom_fields lists the questions the merchant asks for this product, for example a Discord server invite the delivery needs. Every order line for the product answers them in items[].custom_fields (see below). All variants of a product share the same fields. The list is empty when the product has none.

Field	Meaning
`name`	The key of the answer in `items[].custom_fields`, and the label to show.
`type`	`text`, `textarea`, `number`, `checkbox` or `select`. Answer a checkbox with `"true"`.
`required`	The order is refused without a non-empty answer.
`min_length`, `regex`	The answer must have at least this many characters and match the pattern.
`format`	`number`, `discord_invite` or `url`. Shoppex checks the answer for this format when the field has no `regex`.
`options`	Only on a `select`. The answer must be one of these labels, exactly as listed.

POST /reseller/v1/orders

Buys stock at wholesale price and pays from your balance in one step. Requires Idempotency-Key.

{
  "items": [
    {
      "product_id": "019cb402-5555-7000-8000-000000000005",
      "variant_id": null,
      "quantity": 5,
      "custom_fields": { "Discord Server Invite": "https://discord.gg/abc" }
    }
  ]
}

1–100 items per order, each quantity an integer between 1 and 100000.
variant_id is optional. Omit or send null for products without variants.
custom_fields answers the product’s custom_fields from GET /reseller/v1/products, keyed by name. One set of answers covers the whole line, whatever the quantity. Omit it for a product without fields. Keys the product does not define are ignored. A missing required answer or an invalid one returns 422 with RESELLER_ORDER_CUSTOM_FIELDS_INVALID, and nothing is charged.

Returns 201:

{
  "data": {
    "order": {
      "uniqid": "019cb402-7777-7000-8000-000000000007",
      "url": "https://checkout.shoppex.io/invoice/019cb402-7777-7000-8000-000000000007",
      "status": "COMPLETED",
      "currency": "EUR",
      "total": "425.00",
      "created_at": "2026-07-24T09:00:00.000Z",
      "reused": false,
      "tier": {
        "id": "019cb402-3333-7000-8000-000000000003",
        "name": "Gold",
        "discount_percent": 15
      },
      "items": [
        {
          "product_id": "019cb402-5555-7000-8000-000000000005",
          "variant_id": null,
          "quantity": 5,
          "base_price": "100.00",
          "unit_price": "85.00",
          "discount_percent": 15,
          "line_total": "425.00",
          "volume_discount_applied": "0.00"
        }
      ]
    },
    "deliverables": [
      {
        "product_id": "019cb402-5555-7000-8000-000000000005",
        "product_title": "Pro License",
        "variant_id": null,
        "variant_title": null,
        "quantity": 5,
        "delivered": true,
        "delivered_at": "2026-07-24T09:00:01.000Z",
        "serials": ["CODE-1", "CODE-2", "CODE-3", "CODE-4", "CODE-5"]
      }
    ],
    "partially_delivered": false,
    "refunded_amount": null
  }
}

Read the deliverables, not just the status. If the merchant ran short of stock, the order still completes for what can be delivered. The undeliverable lines come back with delivered: false and an empty serials array. partially_delivered becomes true, and refunded_amount carries the amount credited back to your balance. partially_delivered also becomes true when a line delivered fewer codes than it ordered. Compare serials against quantity per line rather than assuming an all-or-nothing line. refunded_amount is the total credited back to your balance for this order, whatever caused the refund. When your balance is too low, the call returns 402 and tells you the gap:

{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Your reseller balance is not sufficient for this order.",
    "doc_url": "https://docs.shoppex.io/reseller-api/errors",
    "balance": { "required": "425.00", "available": "190.00", "currency": "EUR" }
  }
}

Top up in the portal, then retry with a new Idempotency-Key. The 402 is cached under the old one.

GET /reseller/v1/orders

Query	Type	Default
`page`	integer ≥ 1	`1`
`per_page`	integer 1–100	`25`

{
  "data": [
    {
      "uniqid": "019cb402-7777-7000-8000-000000000007",
      "status": "COMPLETED",
      "currency": "EUR",
      "total": "425.00",
      "item_count": 1,
      "created_at": "2026-07-24T09:00:00.000Z"
    }
  ],
  "pagination": { "page": 1, "per_page": 25, "total": 1 }
}

GET /reseller/v1/orders/

One order with its delivered codes. This is the endpoint to poll or re-read when you need the serials again. They are the same codes a normal buyer sees.

{
  "data": {
    "uniqid": "019cb402-7777-7000-8000-000000000007",
    "status": "COMPLETED",
    "currency": "EUR",
    "total": "425.00",
    "item_count": 1,
    "created_at": "2026-07-24T09:00:00.000Z",
    "tier_name": "Gold",
    "tier_discount_percent": 15,
    "partially_delivered": false,
    "refunded_amount": null,
    "lines": [
      {
        "product_id": "019cb402-5555-7000-8000-000000000005",
        "product_title": "Pro License",
        "variant_id": null,
        "variant_title": null,
        "quantity": 5,
        "unit_price": "85.00",
        "total": "425.00",
        "delivered": true,
        "delivered_at": "2026-07-24T09:00:01.000Z",
        "serials": ["CODE-1", "CODE-2", "CODE-3", "CODE-4", "CODE-5"]
      }
    ]
  }
}

serials is always an array. It is empty when nothing has been delivered for that line, and never null. delivered is delivered_at !== null.

Dynamic delivery URL

A personal delivery URL lets you sell a supplier’s serial keys in your own shop without holding stock. Your shop’s Dynamic Delivery calls the URL when a buyer pays; the call places a wholesale order at your tier price, paid from your reseller balance, and answers with the keys your buyer receives. The supplier switches the channel on (Partners → Resellers → Settings → Dynamic delivery, or delivery_url_enabled on the Developer API reseller program). You create the URL in the customer portal, Reseller tab, Dynamic delivery. The portal catalog lists the URL of every product, with today’s wholesale price as max_unit_price, so a later price rise refuses the sale before your balance is charged. The catalog stays readable while the supplier has portal purchasing off. Only serial products can be delivered this way.


Endpoint	`POST /reseller/v1/dynamic/{token}?product_id=<uuid>[&variant_id=<uuid>][&max_unit_price=<decimal>]`
Authentication	the token in the path plus the `X-Shoppex-Signature-V2` signature, no API key
Signing secret	the Signing secret shown with your URL, one per reseller account
Idempotency key	`X-Shoppex-Delivery-Id`, covered by the signature
Rate limit	after 60 refused calls (unknown token or bad signature) in a minute, an address gets `429 RATE_LIMITED` for the rest of that minute

Connect a Shoppex shop

In your own Shoppex dashboard, open Products → ⋯ → Import from Supplier and paste the Connect key from the portal. The supplier’s serial products arrive unlisted, priced at the supplier’s list price, with the delivery URLs and signing secret filled in. Each URL carries today’s wholesale price as max_unit_price, so a later supplier price rise refuses the sale before your balance is charged; edit the URL to accept the new price. Check the prices, then publish. Running the import again only adds products that are new. To set up a product by hand instead: set its type to Dynamic, paste the catalog row’s delivery URL into Dynamic Delivery URL and the signing secret into Signing secret. A variant gets its own URL with &variant_id=. A supplier’s serial products that resellers can buy hold keys of at most 500 characters. The supplier cannot add or save a longer key on such a product. A Shoppex checkout sells at most 348 units of a product per order through a delivery URL, imported or set by hand, whatever maximum quantity the product has. All keys of a line come back in one answer, and 348 keys of 500 characters still fit the 1 MiB answer limit.

Call it from your own system

Any caller that follows the Dynamic Delivery request contract works:

BODY='{"quantity":1}'
DELIVERY_ID="order-1042-line-1"
TS=$(date +%s)
SIG=$(printf '%s' "$DELIVERY_ID.$TS.$BODY" | openssl dgst -sha256 -hmac "$SIGNING_SECRET" -hex | sed 's/^.* //')

curl -X POST "https://api.shoppex.io/reseller/v1/dynamic/$TOKEN?product_id=019cb402-5555-7000-8000-000000000005&max_unit_price=45.00" \
  -H "Content-Type: application/json" \
  -H "X-Shoppex-Delivery-Id: $DELIVERY_ID" \
  -H "X-Shoppex-Signature-V2: v1,t=$TS,h=$SIG" \
  -d "$BODY"

Sign the exact body bytes you send: HMAC-SHA256(secret, "<delivery id>.<timestamp>.<body>"), hex. The timestamp must be within 5 minutes of the server clock.
The body needs quantity, a whole number of at least 1 (Dynamic Delivery sends the line’s quantity). String values in custom_fields answer the supplier product’s fields of the same name; other keys are dropped.
max_unit_price is a ceiling per unit in the supplier’s currency. A higher price is refused before anything is charged.

{
  "data": {
    "delivery_type": "DYNAMIC",
    "serials": ["KEY-1"],
    "count": 1,
    "order": { "uniqid": "019cb402-…", "currency": "USD", "total": "44.25" }
  }
}

Retries and failures

Same delivery id → the same keys, charged once. Two calls at the same time place one order.
Low balance → 402 INSUFFICIENT_BALANCE with the balance block, nothing charged. Top up and call again with the same delivery id; in a Shoppex shop that is Retry Delivery on the invoice line.
Out of stock or above max_unit_price → 409, nothing charged.
A key sold elsewhere between price check and delivery → the order is refunded to your reseller balance and the call answers 409. A retry with the same delivery id after the supplier restocks orders again.
Revoked or replaced URL, wrong signature or old timestamp → 401, nothing charged.

Replacing the URL and secret in the portal stops the old ones at once. Update every product that used them, or run the import again after deleting the old products.

Conventions

Money is always a decimal string ("425.00"), never a float. Percentages are numbers.
Timestamps in data are ISO 8601 strings.
Lists return data plus pagination (page, per_page, total). Pagination is page-based, not cursor-based.
Field names are snake_case throughout.

Start here

Agents & CLI

Products

Invoices and payments

Webhooks

Headless commerce

Storefront SDK

Checkout embeds

Elements

Integrations

Customers

Resellers

Email marketing

Tutorials

Authentication

401 — invalid, unknown, or revoked key

403 — program disabled or account not active

429 — rate limited

Errors

Idempotency

Rate limits

GET /reseller/v1/me

GET /reseller/v1/balance

GET /reseller/v1/products

POST /reseller/v1/orders

GET /reseller/v1/orders

GET /reseller/v1/orders/

Dynamic delivery URL

Connect a Shoppex shop

Call it from your own system

Retries and failures

Conventions

​Authentication

​401 — invalid, unknown, or revoked key

​403 — program disabled or account not active

​429 — rate limited

​Errors

​Idempotency

​Rate limits

​GET /reseller/v1/me

​GET /reseller/v1/balance

​GET /reseller/v1/products

​POST /reseller/v1/orders

​GET /reseller/v1/orders

​GET /reseller/v1/orders/

​Dynamic delivery URL

​Connect a Shoppex shop

​Call it from your own system

​Retries and failures

​Conventions

Authentication

401 — invalid, unknown, or revoked key

403 — program disabled or account not active

429 — rate limited

Errors

Idempotency

Rate limits

GET /reseller/v1/me

GET /reseller/v1/balance

GET /reseller/v1/products

POST /reseller/v1/orders

GET /reseller/v1/orders

GET /reseller/v1/orders/

Dynamic delivery URL

Connect a Shoppex shop

Call it from your own system

Retries and failures

Conventions