Reseller API

The Reseller Developer API lets a merchant or approved OAuth app manage reseller workflows without using the dashboard. Use it when you are building:

an internal reseller operations tool
a partner onboarding flow
a reseller analytics dashboard
a headless portal for stock requests and payout operations

Resellers are scoped to a merchant shop. Always treat reseller_relationship_id as a tenant boundary, not just a record ID.

Scopes

Use the smallest scope set your integration needs.

Workflow	Scopes
Read program settings	`reseller_programs.read`
Update program settings	`reseller_programs.write`
Invite or update resellers	`resellers.write`
List resellers	`resellers.read`
Read reseller sales and analytics	`reseller_sales.read`
Read payout state	`reseller_payouts.read`
Approve, reject, complete, or cancel payouts	`reseller_payouts.write`
Read stock transfers and inventory	`reseller_stock.read`
Request stock, allocate stock, or deliver inventory	`reseller_stock.write`

SDK Example

import { ShoppexClient } from '@shoppexio/sdk';

const client = new ShoppexClient({
  apiKey: process.env.SHOPPEX_API_KEY!,
});

await client.resellerProgram.update({
  is_enabled: true,
  default_mode: 'BOTH',
  default_commission_percent: 25,
  default_wholesale_discount_percent: 35,
});

const invite = await client.resellers.invite({
  email: '[email protected]',
  mode: 'BOTH',
  custom_commission_percent: 30,
  product_access: [{
    product_id: '11111111-1111-4111-8111-111111111111',
    commission_percent_override: 30,
    max_quantity: 100,
  }],
});

console.log(invite.data.invitation.id);

// Once the invitation is accepted, use the reseller relationship id from
// resellers.list() or the dashboard detail view. Invitation ids are not valid
// for relationship-scoped calls.
const relationshipId = 'rel_123';

await client.resellers.createEmbedCampaign(relationshipId, {
  name: 'Discord Launch',
  product_ids: ['11111111-1111-4111-8111-111111111111'],
});

Enable Program

curl -X PATCH https://api.shoppex.io/dev/v1/reseller-program \
  -H "Authorization: Bearer shx_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: reseller-program-setup-1" \
  -d '{
    "is_enabled": true,
    "default_mode": "BOTH",
    "default_commission_percent": 25,
    "default_wholesale_discount_percent": 35,
    "min_payout_threshold": 50
  }'

Invite Reseller

curl -X POST https://api.shoppex.io/dev/v1/resellers/invite \
  -H "Authorization: Bearer shx_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: reseller-invite-partner-example" \
  -d '{
    "email": "[email protected]",
    "mode": "BOTH",
    "custom_commission_percent": 30,
    "purchase_limit_daily": 50,
    "product_access": [
      {
        "product_id": "11111111-1111-4111-8111-111111111111",
        "commission_percent_override": 30,
        "max_quantity": 100
      }
    ]
  }'

After the reseller accepts the invitation, Shoppex creates the reseller relationship and links it to reseller attribution.

Reseller Analytics

Use shop-wide analytics for overview screens:

curl https://api.shoppex.io/dev/v1/resellers/analytics \
  -H "Authorization: Bearer shx_your_api_key"

Use relationship-specific analytics for detail screens:

curl https://api.shoppex.io/dev/v1/resellers/rel_123/analytics \
  -H "Authorization: Bearer shx_your_api_key"

Embed Campaigns

Create reseller-owned embed campaigns from your partner tooling:

curl -X POST https://api.shoppex.io/dev/v1/resellers/rel_123/embed-campaigns \
  -H "Authorization: Bearer shx_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: embed-campaign-rel-123-discord" \
  -d '{
    "name": "Discord Launch",
    "product_ids": ["11111111-1111-4111-8111-111111111111"]
  }'

Pause or revoke a campaign without deleting its reporting history:

curl -X PATCH https://api.shoppex.io/dev/v1/resellers/rel_123/embed-campaigns/campaign_123 \
  -H "Authorization: Bearer shx_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: embed-campaign-campaign-123-pause" \
  -d '{
    "status": "PAUSED"
  }'

Stock Purchase Flow

Stock Mode uses normal Shoppex invoice and payment infrastructure. The stock transfer is allocated only after payment.

curl -X POST https://api.shoppex.io/dev/v1/resellers/rel_123/stock-purchases \
  -H "Authorization: Bearer shx_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: stock-request-rel-123-prod-123-25" \
  -d '{
    "product_id": "11111111-1111-4111-8111-111111111111",
    "quantity": 25
  }'

Then create the invoice:

curl -X POST https://api.shoppex.io/dev/v1/resellers/rel_123/stock-transfers/transfer_123/invoice \
  -H "Authorization: Bearer shx_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: stock-invoice-transfer-123" \
  -d '{}'

Merchant-side tools can mark a stock transfer paid and allocate inventory when payment confirmation is handled outside the normal checkout path:

curl -X POST https://api.shoppex.io/dev/v1/resellers/rel_123/stock-transfers/transfer_123/allocate \
  -H "Authorization: Bearer shx_your_api_key" \
  -H "Idempotency-Key: stock-allocate-transfer-123"

Allocation is idempotent, but integrations should still send stable Idempotency-Key values for stock mutations.

Inventory Delivery

Deliver one allocated stock item to an end customer:

curl -X POST https://api.shoppex.io/dev/v1/resellers/rel_123/inventory/item_123/deliver \
  -H "Authorization: Bearer shx_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: stock-deliver-item-123" \
  -d '{
    "email": "[email protected]"
  }'

Reseller Fulfillment API

Reseller API keys are different from merchant Developer API keys. A merchant key starts with shx_ and can manage a shop. A reseller key starts with shr_ and can only operate one reseller relationship. Use this flow when a reseller sells through their own store and wants Shoppex to deliver merchant stock without showing Shoppex to their buyer.

The reseller creates an API key in the Reseller Portal API tab.
The reseller tops up prepaid balance.
The external store calls the Reseller Fulfillment API after payment.
Shoppex debits wholesale cost from the reseller balance and delivers merchant serial stock.

curl -X POST https://api.shoppex.io/reseller/v1/fulfillments \
  -H "Authorization: Bearer shr_reseller_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1001-line-1" \
  -d '{
    "external_order_id": "order-1001",
    "customer_email": "[email protected]",
    "product_id": "11111111-1111-4111-8111-111111111111",
    "quantity": 1
  }'

For tools that only support a dynamic URL, use the URL template from the Reseller Portal. The path is /reseller/v1/fulfillments/dynamic and the required query params are api_key, external_order_id, customer_email, product_id, and quantity.

Send a stable external_order_id or Idempotency-Key. Retries return the same fulfillment instead of debiting balance twice.

Check reseller prepaid balance:

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

Common errors:

402 Insufficient reseller prepaid balance
409 Fulfillment stock is unavailable
401 Invalid or inactive reseller API key

Webhooks

Subscribe to reseller events to keep partner portals in sync. Important events:

reseller:invited
reseller:accepted
reseller:sale
reseller:embed_campaign_created
reseller:payout_requested
reseller:stock_purchase_requested
reseller:api_fulfillment_delivered
reseller:stock_purchase_paid
reseller:stock_allocated
reseller:stock_item_delivered

See Webhook Events for payload examples.

Endpoint Reference

The full generated endpoint reference is available in the Resellers group in the API Reference sidebar.

Start Here

Concepts

Webhooks

Headless Commerce

Use Cases

Embed SDK

Scopes

SDK Example

Enable Program

Invite Reseller

Reseller Analytics

Embed Campaigns

Stock Purchase Flow

Inventory Delivery

Reseller Fulfillment API

Webhooks

Endpoint Reference

​Scopes

​SDK Example

​Enable Program

​Invite Reseller

​Reseller Analytics

​Embed Campaigns

​Stock Purchase Flow

​Inventory Delivery

​Reseller Fulfillment API

​Webhooks

​Endpoint Reference

Scopes

SDK Example

Enable Program

Invite Reseller

Reseller Analytics

Embed Campaigns

Stock Purchase Flow

Inventory Delivery

Reseller Fulfillment API

Webhooks

Endpoint Reference