FOR DEVELOPERS

Partner API

Wire your own website up to WCell: browse the live catalogue, place orders, and check delivery status — all billed against your existing WCell account balance. Ask WCell to generate you an API key to get started.

Authentication

Every order-related request needs an X-Partner-Key header carrying your API key. Catalogue browsing is public and needs no key.

X-Partner-Key: wcpk_your_key_here

Keep this key server-side. Anyone holding it can spend your account's WCell balance. If it leaks, ask WCell to revoke it and issue a new one — there's no self-service rotation yet.

Browse the catalogue

GET/api/catalog

Returns every active product with its price, stock, category, and product group — the same feed the storefront itself uses. No authentication required. Cached for about a minute.

# curl
curl https://wcell.app/api/catalog

{
  "success": true,
  "products": [
    {
      "id": "f2fcb04b-...-39dee131f80b",
      "title": "Itunes 500$ US GiftCard",
      "price": 477.23,
      "available": 3,
      "category": "Apps & Entertainment",
      "categorySlug": "apps-entertainment",
      "productGroup": "Apple Gift Cards",
      "image": "https://..."
      // ...more fields
    }
  ]
}

Filter to what you actually sell by categorySlug or productGroup client-side, or ask WCell for a scoped feed if you only carry a handful of items.

Place an order

POST/api/purchase

Places an order against your account's WCell balance. Requires X-Partner-Key.

Field	Type	Notes
`productId`	string	The `id` from the catalogue feed.
`quantity`	integer	Defaults to 1.
`expectedUnitPrice`	number	Optional. If the live price has moved since you fetched the catalogue, the order is rejected instead of silently charging a different amount.
`requestId`	string	Required. A unique 16-128 character ID you generate per attempt — retry the exact same request with the same `requestId` and you'll get the same order back instead of a duplicate charge.

# curl
curl -X POST https://wcell.app/api/purchase \
  -H "X-Partner-Key: wcpk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"productId":"f2fcb04b-...","quantity":1,"requestId":"order-2026-08-25-0001"}'

A completed order returns immediately with codes:

{
  "orderId": "9c1e2f4a-...",
  "status": "completed",
  "codes": [{ "productTitle": "...", "code": "XXXX-XXXX-XXXX" }]
}

Some suppliers take a moment to confirm — those come back as pending or review_required instead of completed. Poll the status endpoint below until it resolves; never re-submit the same order to "retry" it.

Check order status

GET/api/purchase?orderId=...

Requires X-Partner-Key. Only returns orders that belong to your own account.

# curl
curl https://wcell.app/api/purchase?orderId=9c1e2f4a-... \
  -H "X-Partner-Key: wcpk_your_key_here"

{
  "orderId": "9c1e2f4a-...",
  "status": "completed",
  "total": 477.23,
  "codes": [ ... ],
  "createdAt": "2026-08-25T12:00:00.000Z",
  "completedAt": "2026-08-25T12:00:04.000Z"
}

Order statuses

completed Delivered — codes are in the response.
pending Still processing. Poll again shortly.
failed Rejected before anything was delivered. Your balance was refunded automatically.
review_required Outcome is ambiguous. Your balance stays reserved until WCell staff resolve it manually — don't resubmit.

Errors

Non-2xx responses return { "error": "human-readable message" }. A few worth handling explicitly:

401 Missing, invalid, or revoked API key.
400 Bad request — check the message (invalid product, price changed, quantity too high).
409 A previous attempt with this requestId already failed; don't retry it under a new ID without checking why first.
429 Too many requests — back off and retry after the Retry-After header.

Getting a key

API keys are issued by WCell directly, one per integration. Contact WCell with the account email you'd like the key tied to, and what you're building.