Resellers

These endpoints let a merchant read and steer their own wholesale reseller program: list reseller accounts, invite new ones, suspend and reinstate them, and read or update the program settings. They are part of the merchant Developer API and authenticate with a normal shx_ API key. The API resellers themselves use to buy wholesale stock is a different API. See the Reseller API.

Tier authoring, product enrollment, and per-product price overrides are dashboard-only. They are configuration for the price cascade, not automation, and a second write path for them creates a second source of truth. GET /dev/v1/reseller-tiers is read-only for exactly that reason.

Scopes

Scope	Grants
`resellers.read`	`GET /dev/v1/resellers`, `GET /dev/v1/resellers/{id}`, `GET /dev/v1/reseller-program`, `GET /dev/v1/reseller-tiers`
`resellers.write`	`POST /dev/v1/resellers/invite`, `POST /dev/v1/resellers/{id}/suspend`, `POST /dev/v1/resellers/{id}/reinstate`, `PATCH /dev/v1/reseller-program`

A key with only resellers.read gets 403 FORBIDDEN on any of the write routes. Reseller scopes are not implied by customers.*, even though the dashboard puts Resellers under Customers.

Endpoints

GET /dev/v1/resellers

Page-based list, newest first.

Query	Type	Default
`status`	`INVITED`, `APPLIED`, `ACTIVE`, `SUSPENDED`, `REJECTED`	all
`search`	matches the reseller email, max 128 chars	—
`page`	integer ≥ 1	`1`
`per_page`	integer 1–100	`25`

curl "https://api.shoppex.io/dev/v1/resellers?status=ACTIVE&per_page=50" \
  -H "Authorization: Bearer shx_your_key_here"

{
  "data": {
    "items": [
      {
        "id": "019cb402-1111-7000-8000-000000000001",
        "customer_id": "019cb402-2222-7000-8000-000000000002",
        "email": "[email protected]",
        "status": "ACTIVE",
        "tier": {
          "id": "019cb402-3333-7000-8000-000000000003",
          "name": "Gold",
          "discount_percent": 15
        },
        "application_note": null,
        "lifetime_revenue": "1250.00",
        "lifetime_orders": 7,
        "approved_at": "2026-07-01T10:00:00.000Z",
        "suspended_at": null,
        "rejected_at": null,
        "created_at": "2026-06-01T10:00:00.000Z",
        "updated_at": "2026-07-01T10:00:00.000Z"
      }
    ],
    "total": 1,
    "page": 1,
    "per_page": 50
  }
}

GET /dev/v1/resellers/

Returns { "data": { "reseller": { … } } } with the same object. 404 RESELLER_NOT_FOUND when the ID belongs to another shop or does not exist.

POST /dev/v1/resellers/invite

Sends the wholesale invitation email and creates the relationship in INVITED state.

{ "email": "[email protected]", "tier_id": "019cb402-3333-7000-8000-000000000003" }

tier_id is optional. Omit it to use the program’s default tier. If neither is set the call fails with 422 and the message asks you to pick a tier. Requires an enabled program. Inviting an email that is already INVITED, APPLIED, ACTIVE, or SUSPENDED returns 409 CONFLICT. A previously REJECTED email can be re-invited.

POST /dev/v1/resellers//suspend

Blocks wholesale pricing and revokes Reseller API access for that account. Only an ACTIVE reseller can be suspended. Anything else returns 422. The row is never deleted, so the status history stays intact.

POST /dev/v1/resellers//reinstate

Returns a SUSPENDED reseller to ACTIVE. Only a SUSPENDED reseller can be reinstated.

Reinstating sends no webhook. There is no reseller:reinstated event. Shoppex only sends reseller:suspended on the way out.

GET /dev/v1/reseller-program

{
  "data": {
    "program": {
      "id": "019cb402-8888-7000-8000-000000000008",
      "enabled": true,
      "enrollment_mode": "APPLICATION",
      "application_message": "Tell us about your business.",
      "require_application_note": true,
      "default_tier_id": "019cb402-3333-7000-8000-000000000003",
      "created_at": "2026-06-01T10:00:00.000Z",
      "updated_at": "2026-07-01T10:00:00.000Z"
    }
  }
}

The row is created lazily. The first read on a shop that never opened the Resellers page returns a disabled program in MANUAL mode rather than a 404.

PATCH /dev/v1/reseller-program

Partial update. Every field is optional.

{ "enabled": true, "enrollment_mode": "OPEN", "default_tier_id": "019cb402-3333-7000-8000-000000000003" }

Field	Notes
`enabled`	Master switch for the whole program
`enrollment_mode`	`MANUAL` (invite only), `APPLICATION` (customers apply, you approve), `OPEN` (customers self-enroll)
`application_message`	Shown to applicants, max 2000 chars, nullable
`require_application_note`	Forces applicants to write a note
`default_tier_id`	Tier used when an invite does not name a tier, and for open enrollment

enrollment_mode: "OPEN" without a default_tier_id returns 422. Open enrollment turns customers into resellers without review, so the tier they land in has to be decided up front. An unknown default_tier_id returns 404 RESELLER_TIER_NOT_FOUND.

GET /dev/v1/reseller-tiers

Read-only, ordered by sort_order.

{
  "data": {
    "tiers": [
      {
        "id": "019cb402-3333-7000-8000-000000000003",
        "name": "Gold",
        "discount_percent": 15,
        "auto_advance_revenue": "5000.00",
        "auto_advance_orders": 20,
        "auto_advance_requires_both": false,
        "sort_order": 1,
        "member_count": 3,
        "is_default": true,
        "created_at": "2026-06-01T10:00:00.000Z",
        "updated_at": "2026-07-01T10:00:00.000Z"
      }
    ]
  }
}

auto_advance_revenue and auto_advance_orders are the thresholds that promote a reseller into this tier automatically after an order completes. Either being null means it is not part of the condition. auto_advance_requires_both: false means hitting either threshold is enough.

Idempotency

All three write routes accept the standard Idempotency-Key header described in Errors. It is optional here, unlike on the reseller-facing order endpoint where it is mandatory.

Start here

Invoices and payments

Webhooks

Headless commerce

Storefront SDK

Checkout embeds

Integrations

Email marketing

Tutorials

Resellers

Scopes

Endpoints

GET /dev/v1/resellers

GET /dev/v1/resellers/

POST /dev/v1/resellers/invite

POST /dev/v1/resellers//suspend

POST /dev/v1/resellers//reinstate

GET /dev/v1/reseller-program

PATCH /dev/v1/reseller-program

GET /dev/v1/reseller-tiers

Idempotency

​Scopes

​Endpoints

​GET /dev/v1/resellers

​GET /dev/v1/resellers/

​POST /dev/v1/resellers/invite

​POST /dev/v1/resellers//suspend

​POST /dev/v1/resellers//reinstate

​GET /dev/v1/reseller-program

​PATCH /dev/v1/reseller-program

​GET /dev/v1/reseller-tiers

​Idempotency

Scopes

Endpoints

GET /dev/v1/resellers

GET /dev/v1/resellers/

POST /dev/v1/resellers/invite

POST /dev/v1/resellers//suspend

POST /dev/v1/resellers//reinstate

GET /dev/v1/reseller-program

PATCH /dev/v1/reseller-program

GET /dev/v1/reseller-tiers

Idempotency