Resellers

Automate your wholesale reseller program from the Developer API.

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 surface — 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 would be 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": "[e-mail]",
        "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": "[e-mail]", "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 emits no webhook. There is no reseller:reinstated event — only 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, so 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 for invites without an explicit 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.

---

Next Steps

Merchant guide

Set the program up in the dashboard.

Reseller API

What your resellers can automate.