Dealers

Rep and dealer portals on your own site

Your site signs the visitor in, works out which rep or dealer account they are, and calls the API from its server with one secret key, passing ?rep= or ?customerId=. The API applies that as a filter and nothing else, so a wrong code returns an empty list, never another account’s data. The key never reaches the browser.

The same parameters work on customer sales, contact interest and products/top. List endpoints that take ?format=csv return a CSV download.

GET /cx/v1/dealers

The directory with lifetime totals, ranked by revenue. The dealer id is your customer account number. Scope dealers:read.

Param	Default	Notes
`limit`	50	1 to 200
`rep`		Only this rep’s accounts (assigned rep or sold-by)
`format`		`csv` for a download

{
  "count": 50,
  "rep": null,
  "items": [
    {
      "id": "D-1042",
      "name": "Main Street Interiors",
      "city": "Charlotte",
      "region": "NC",
      "assignedRep": "R07",
      "stage": "customer",
      "lapsed": false,
      "lapseRisk": "watch",
      "customerId": "…",
      "accountStatus": "active",
      "revenue": 412870.00,
      "orders": 214,
      "units": 1130,
      "firstOrder": "2023-02-11T00:00:00",
      "lastOrder": "2026-08-19T00:00:00"
    }
  ]
}

GET /cx/v1/dealers/performance/{range}

Ranked by revenue in the window, with the comparison period and a full-period pace. Scope dealer-performance:read.

Param	Default	Notes
`comparison`	`previous_period`	`previous_period` (the prior equal-length window) or `previous_year`
`limit`	50	1 to 200
`rep`		Only this rep’s accounts
`format`		`csv` for a download

curl "https://api.plunk.io/cx/v1/dealers/performance/this_quarter?rep=R07&comparison=previous_year" \
  -H "Authorization: Bearer sk_live_••••"

{
  "range": "this_quarter",
  "comparison": "previous_period",
  "rep": null,
  "count": 50,
  "items": [
    {
      "id": "D-1042",
      "name": "Main Street Interiors",
      "city": "Charlotte",
      "region": "NC",
      "assignedRep": "R07",
      "revenue": 88450.00,
      "units": 96,
      "orders": 41,
      "aov": 2157.32,
      "revenuePrev": 78690.00,
      "deltaPct": 12.4,
      "pace": 121400.00,
      "lastOrder": "2026-10-02T00:00:00",
      "lapseRisk": "healthy"
    }
  ]
}

pace is revenue projected to the end of the window.

GET /cx/v1/dealers/lapse-risk

Accounts that have gone quiet compared with their own ordering rhythm: the win-back call list. Scope dealer-performance:read.

Param	Default	Notes
`band`		`healthy`, `watch`, `at_risk` or `lapsing`. Anything else is `400 bad_band`
`rep`		Only this rep’s accounts
`minOrders`	3	Accounts with fewer orders aren’t scored
`limit`	100
`format`		`csv` for a download

{
  "rep": "R07",
  "band": "at_risk",
  "minOrders": 3,
  "totalAccounts": 182,
  "medianCadenceDays": 41.0,
  "bands": { "healthy": 120, "watch": 31, "at_risk": 19, "lapsing": 12 },
  "revenueAtRisk": 214300.00,
  "count": 19,
  "items": [
    {
      "customerId": "D-1042",
      "name": "Main Street Interiors",
      "region": "NC",
      "assignedRep": "R07",
      "customerType": "wholesale",
      "orders": 14,
      "firstOrder": "2023-02-11",
      "lastOrder": "2026-07-30",
      "trailing12Revenue": 48210.00,
      "cadenceDays": 32.5,
      "daysSinceLast": 76,
      "ratio": 2.34,
      "band": "at_risk",
      "expectedNextOrder": "2026-08-31"
    }
  ]
}

404 not_applicable when no account has enough orders to score.

GET /cx/v1/dealers/{id}

One dealer: totals, account profile with bill-to and ship-to, the assigned rep, contacts, and top products. Contacts carry personal data, so this stays on secret keys. Unknown ids return 404 dealer_not_found.

{
  "dealer": {
    "id": "D-1042",
    "name": "Main Street Interiors",
    "revenue": 412870.00,
    "orders": 214,
    "units": 1130,
    "aov": 1929.30,
    "firstOrder": "…",
    "lastOrder": "…"
  },
  "profile": {
    "accountNumber": "D-1042",
    "name": "Main Street Interiors",
    "parentAccountNumber": null,
    "accountStatus": "active",
    "email": "…",
    "phone": "…",
    "billTo": { "street": "…", "street2": null, "city": "Charlotte", "region": "NC", "postalCode": "28202", "country": "US" },
    "shipTo": { "street": "…", "street2": null, "city": "Charlotte", "region": "NC", "postalCode": "28202", "country": "US" },
    "customerId": "…",
    "stage": "customer",
    "lapsed": false,
    "lapseRisk": "watch",
    "lapseLastOrderDate": "…",
    "lapseCadenceDays": 32.5
  },
  "assignedRep": { "repCode": "R07", "name": "…", "email": "…", "phone": "…", "status": "active" },
  "contacts": [
    { "firstName": "…", "lastName": "…", "email": "…", "phone": "…", "role": "buyer", "isPrimary": true, "personId": 18442 }
  ],
  "topProducts": [
    { "id": "…", "title": "…", "revenue": 61200.00, "units": 84 }
  ]
}

Was this helpful?

Still stuck? Contact support and include the job or page you were on.