Public API — {{COMPANY_SHORT

Looking for a walkthrough?

This page is the REST + webhook reference. For end-to-end how-tos with screenshots-described-in-text, expected health checks, and troubleshooting, see the matching guides:

Integration API guide · Public read API guide · Outbound webhooks guide · Settings → Connectors walkthrough · Troubleshooting

Writes (Integrations) — `pck_int_*`

Inbound write API for external storefronts, payment processors, and middleware. Push orders, payments, and clients into a single (org, store) using a store-pinned pck_int_* key. Stripe-style idempotency, HMAC body signatures, and a native WooCommerce receiver are all first-class.

WooCommerce paste-and-go (headline path)

The fastest integration we ship. In WordPress admin → WooCommerce → Settings → Advanced → Webhooks, click Add webhook with:

Topic: Order created
Delivery URL: https://api.peptideclients.com/integrations/v1/webhook/woocommerce
Secret: paste your signing_secret_plain from Settings → Connectors
API version: WP REST API Integration v3

Save, repeat for Order updated, place a test order, and watch it land in Settings → Connectors → Request log. Full walkthrough — including secret rotation — lives in the WooCommerce recipe.

Other recipes in the cookbook: 5-minute cURL quickstart, Zapier (Square → PeptideClients), Node Express, Python requests, HMAC signing, error codes.

Integration endpoints

POST

/integrations/v1/orders

Create an order (and optionally record an inline payment). Requires orders:write.

GET

/integrations/v1/orders/by-external/{external_id}

Look up an order by your external_id. No additional scope — any key may read its own orders.

POST

/integrations/v1/orders/{id}/payments

Record an additional payment against an existing order. Requires payments:write.

POST

/integrations/v1/orders/{id}/cancel

Cancel an order (idempotent). Requires orders:cancel.

POST

/integrations/v1/payments/{id}/refund

Mark a payment as refunded. v1 is full refunds only. Requires payments:refund.

POST

/integrations/v1/clients

Upsert a CRM client (match by external_id, then email). Requires clients:write.

POST

/integrations/v1/webhook/woocommerce

Native WooCommerce receiver. Accepts WC's Order shape and X-WC-Webhook-Signature verbatim.

GET

/integrations/v1/health

Liveness probe (no auth required).

GET

/integrations/v1/openapi.json

Machine-readable OpenAPI 3 spec (no auth required).

Auth & safety in one paragraph

Every write needs Authorization: Bearer pck_int_*. Idempotency-Key is optional but recommended — same key + same body returns the cached response for 24 hours; same key + different body returns 409 idempotency_conflict. PC-Signature: t=<unix>,v1=<hex hmac-sha256(t + "." + raw_body, secret)> is required when the key has require_signature=true; we reject timestamp skew > 5 minutes. See the recipes for idempotency semantics and the status truth table.

References

OpenAPI 3.0.3 spec (YAML) — canonical source of truth.
Integration recipes (markdown) — WooCommerce, Zapier, Node, Python, HMAC, error codes.
Live machine-readable spec: /integrations/v1/openapi.json

Reads (Public API) — `pck_live_*`

Operator-managed read API. Same gateway, different key prefix and different scopes — use this to pull data out of your workspace. For pushing data in, see Writes (Integrations) above.

Quickstart

Mint a key in Settings → API keys. Pick read_only unless you also need to fire test webhooks.
Copy the plaintext value once it’s shown — we only store a hash.
Pass it as a bearer token on every request.

curl -H 'Authorization: Bearer pck_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  https://bxbdqmtldkhgwpnwecox.supabase.co/functions/v1/public-api/v1/orders

https://api.peptideclients.com resolves to the same gateway once DNS is wired (operator follow-up).

Pagination

List endpoints use keyset cursors. Send cursor_at + cursor_id from the previous response’s next_cursor; limit is 1–100, default 50.

{
  "rows": [ { "id": "...", "updated_at": "2026-05-19T12:00:00Z", ... } ],
  "next_cursor": { "at": "2026-05-19T12:00:00Z", "id": "..." }
}

Endpoints

GET

/v1/orders

Paginated list of operator orders.

GET

/v1/orders/{id}

One order by UUID.

GET

/v1/vendors

Paginated supplier CRM. vendors.vendors rows have no slug; use UUID.

GET

/v1/vendors/{id}

One vendor by UUID.

GET

/v1/clients

Paginated CRM clients (operator’s customers).

GET

/v1/products

Paginated published shop products belonging to org-linked sellers. Empty for orgs without a marketplace seller.

GET

/v1/products/{id}

One product by UUID.

POST

/v1/webhooks/test/{endpoint_id}

Fire a synthetic webhook.test event. Requires read_write scope.

GET

/v1/openapi.json

Machine-readable OpenAPI 3 spec (no auth required).

GET

/v1/health

Liveness probe (no auth required).

Outbound webhooks

Headers we send

Content-Type:      application/json
User-Agent:        PeptideClients-Webhook/1.0
X-PC-Event-Type:   order.created
X-PC-Event-Id:     ce5f7c0a-...           # null for synthetic test events
X-PC-Delivery-Id:  c0bb1e9f-...
X-PC-Timestamp:    1779249317
X-PC-Signature:    t=1779249317,v1=<hex hmac-sha256(secret, ts + "." + body)>

Verifying signatures (Node)

import crypto from 'node:crypto';

function verify(req, secret) {
  const sig = req.headers['x-pc-signature'] ?? '';
  const ts = req.headers['x-pc-timestamp'] ?? '';
  const expected = crypto.createHmac('sha256', secret).update(`${ts}.${req.rawBody}`).digest('hex');
  return sig.endsWith('v1=' + expected);
}

Retry policy

2xx = success. Anything else (3xx–5xx, timeout, DNS error) is a failure. Failed deliveries retry on a 1m, 5m, 30m, 2h, 8h schedule. After max_attempts (default 5) the delivery is marked dropped and you can manually retry from the UI.

Event catalog

type	description
`order.created`	A new operator-side order is created.
`order.shipped`	An order is marked shipped.
`order.delivered`	A carrier reports delivered.
`client.created`	A client is added to the CRM.
`client.updated`	A client is updated.
`vendor.created`	A supplier is added to vendors.
`vendor.updated`	A supplier is updated.
`vendor.claimed`	A shop vendor profile is claimed.
`payment.recorded`	A payment is recorded against an order.
`shipment.tracking_added`	A tracking number is attached.
`webhook.test`	Synthetic test event from settings.

Limits

Rate limit: 600 requests/minute per API key (best-effort, per-instance).
Page size: 100 items max per list call.
Webhook endpoints: 10 enabled per workspace.
Webhook payload: 6 MB cap (Edge Function limit).

OpenAPI

Two OpenAPI 3.0.3 documents ship with this site:

Reads (Public API) — live at /v1/openapi.json; source YAML at docs/api/openapi.yaml (also mirrored at /api/openapi.yaml).
Writes (Integrations) — live at /integrations/v1/openapi.json; source YAML at docs/api/integration-openapi.yaml (also mirrored at /api/integration-openapi.yaml).

Looking for a walkthrough?

Writes (Integrations) — pck_int_*

WooCommerce paste-and-go (headline path)

Integration endpoints

Auth & safety in one paragraph

References

Reads (Public API) — pck_live_*

Quickstart

Pagination

Endpoints

Outbound webhooks

Headers we send

Verifying signatures (Node)

Retry policy

Event catalog

Limits

OpenAPI

Writes (Integrations) — `pck_int_*`

Reads (Public API) — `pck_live_*`