Customer API quickstart

Create API key ›Keys and scopes

Quick answer

Create a key in Billing & Usage, call GET https://api.plunk.io/cx/v1/capabilities with it as a bearer token, then call any endpoint the capabilities document lists for your key.

Before you start

• A Plunk Commerce plan (or Studio Storefront). See which plans include the API.
• A workspace owner or admin to create the key. See API keys.
• Decide where the key will run. Browser code gets a publishable key (pk_live_…), locked to your site’s origins. Server code gets a secret key (sk_live_…). See authentication and keys.

Caution

Test keys (pk_test_, sk_test_) read and write your real account. There is no sandbox. Don’t post sales or order status you don’t want in your reports.

Steps

1. Read your capabilities document

Every integration starts here. It lists the resource families and endpoints your key can reach.

cURL

Terminal

curl https://api.plunk.io/cx/v1/capabilities \
  -H "Authorization: Bearer sk_test_••••"

JavaScript

capabilities.js

// Server-side (Node 18+). Never put a secret key in browser code.
const res = await fetch('https://api.plunk.io/cx/v1/capabilities', {
  headers: { Authorization: `Bearer ${process.env.PLUNK_SECRET_KEY}` },
});
const caps = await res.json();
console.log(caps.tenantType, caps.families.map((f) => f.name));

Python

capabilities.py

import os, requests

res = requests.get(
    "https://api.plunk.io/cx/v1/capabilities",
    headers={"Authorization": f"Bearer {os.environ['PLUNK_SECRET_KEY']}"},
)
caps = res.json()
print(caps["tenantType"], [f["name"] for f in caps["families"]])

Response (shortened)

{
  "tenant": "youraccount",
  "tenantType": "retailer",
  "mode": "test",
  "aggregationFloor": 5,
  "labels": { "location": "Showroom" },
  "families": [
    {
      "name": "products",
      "key": "publishable",
      "scopes": ["products:read", "recommendations:read"],
      "label": null,
      "endpoints": ["GET /cx/v1/products/top/{range}", "GET /cx/v1/products/{id}", "…"]
    }
  ]
}

2. Pull this month’s bestsellers

cURL

Terminal

curl "https://api.plunk.io/cx/v1/products/top/this_month?limit=3" \
  -H "Authorization: Bearer sk_test_••••"

JavaScript

top-products.js

const res = await fetch(
  'https://api.plunk.io/cx/v1/products/top/this_month?limit=3',
  { headers: { Authorization: `Bearer ${process.env.PLUNK_SECRET_KEY}` } },
);
const { items } = await res.json();
for (const p of items) console.log(p.rank, p.id, p.title, p.units);

Python

top_products.py

res = requests.get(
    "https://api.plunk.io/cx/v1/products/top/this_month",
    params={"limit": 3},
    headers={"Authorization": f"Bearer {os.environ['PLUNK_SECRET_KEY']}"},
)
for p in res.json()["items"]:
    print(p["rank"], p["id"], p["title"], p["units"])

A secret key also gets revenue and aov on each row. A publishable key gets rank, units and orders only, and rows under 5 orders are left out.

3. Send an event from your storefront

Publishable keys can write events. Register your site’s origins on the key first, or the call is refused with 401.

cURL

Terminal

curl -X POST https://api.plunk.io/cx/v1/ingest/event \
  -H "Authorization: Bearer pk_test_••••" \
  -H "Content-Type: application/json" \
  -d '{ "type": "product_view", "visitorRef": "v_84af", "productId": "SF-1042" }'

JavaScript

Browser

await fetch('https://api.plunk.io/cx/v1/ingest/event', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer pk_test_••••', // publishable keys are safe in the browser
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ type: 'product_view', visitorRef: 'v_84af', productId: 'SF-1042' }),
});

Python

event.py

requests.post(
    "https://api.plunk.io/cx/v1/ingest/event",
    headers={"Authorization": "Bearer pk_test_••••"},
    json={"type": "product_view", "visitorRef": "v_84af", "productId": "SF-1042"},
)

202 Accepted

{ "accepted": true, "eventId": "9d1c…", "type": "product_view" }

4. Record a sale from your server

Sales need a secret key. Posting the same orderId again replaces that order’s lines, so webhook retries are safe.

cURL

Terminal

curl -X POST https://api.plunk.io/cx/v1/ingest/sale \
  -H "Authorization: Bearer sk_test_••••" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "cs_a1B2c3",
    "customerRef": "cus_R8xT2m",
    "email": "buyer@example.com",
    "lines": [ { "productId": "SF-1042", "description": "Harbor Sofa", "quantity": 2, "price": 2398.00 } ]
  }'

JavaScript

sale.js

await fetch('https://api.plunk.io/cx/v1/ingest/sale', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.PLUNK_SECRET_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    orderId: 'cs_a1B2c3',
    customerRef: 'cus_R8xT2m',
    email: 'buyer@example.com',
    lines: [{ productId: 'SF-1042', description: 'Harbor Sofa', quantity: 2, price: 2398.0 }],
  }),
});

Python

sale.py

requests.post(
    "https://api.plunk.io/cx/v1/ingest/sale",
    headers={"Authorization": f"Bearer {os.environ['PLUNK_SECRET_KEY']}"},
    json={
        "orderId": "cs_a1B2c3",
        "customerRef": "cus_R8xT2m",
        "email": "buyer@example.com",
        "lines": [{"productId": "SF-1042", "description": "Harbor Sofa", "quantity": 2, "price": 2398.00}],
    },
)

If something looks off

• 401 means the key is missing or wrong, a publishable key came from an origin that isn’t registered on it, or a secret key came from a browser. See API returns 401 or 403.
• 403 secret_key_required means you sent a sale, order status or reorder request with a publishable key. Move the call to your server.
• 403 scope_not_permitted means the key’s class or scopes don’t cover that family, or the family isn’t enabled for your account yet. Check your capabilities document.

Related

• Authentication and keys
• Errors and rate limits
• Ingest