Skip to main content
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.
WorkflowScopes
Read program settingsreseller_programs.read
Update program settingsreseller_programs.write
Invite or update resellersresellers.write
List resellersresellers.read
Read reseller sales and analyticsreseller_sales.read
Read payout statereseller_payouts.read
Approve, reject, complete, or cancel payoutsreseller_payouts.write
Read stock transfers and inventoryreseller_stock.read
Request stock, allocate stock, or deliver inventoryreseller_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]"
  }'

​
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: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.