Pixoo APIv1 private beta

Generate, track and recycle discount codes from your own stack.

The engine behind 200+ Shopify brands, now behind a clean REST API. Mint unique codes one at a time or 100,000 at once, hear back the second one is redeemed, and never babysit a CSV again.

REST + JSON
Scoped API keys
Idempotent writes
Signed webhooks

Start in 3 steps Browse the reference

one POST, one fresh unique code

curl -X POST https://api.pixoo.app/api/v1/discounts/1234567890/codes \
  -H "Authorization: Bearer pixoo_live_…" \
  -H "Content-Type: application/json" \
  -d '{"prefix": "WELCOME-"}'

{
  "codes": ["WELCOME-7F3K9Q2M8T1Z"],
  "discount": { "id": "1234567890", "title": "Welcome codes" }
}

Real request, real response shape. Copy it once your key exists.

What you can build

Four flows merchants keep asking for

Before any endpoint reference: this is what plugging Pixoo into your stack actually unlocks.

Send a unique welcome code to every new customer

A customer signs up, your backend makes one call, and a fresh unique code lands in their welcome email. No pre-generated pools, no spreadsheet handoffs: one request per customer, the code comes back in the response.

See it in the quick start

Launch a 10,000-code campaign in one call

Influencer drop, print inserts, a partner newsletter: one POST queues the whole batch, and Pixoo pings you the moment every code is ready. Up to 100,000 codes per discount, unique and collision-free.

Read the campaign guide

Know the second a code is redeemed

The code.redeemed webhook delivers the code, the order and the savings: signed, retried, and free of customer PII. Credit the referrer, close the loyalty loop, update your CRM in real time.

Wire up webhooks

Never hit the 100k code cap

Every discount tops out at 100,000 codes, unless you recycle. Collect redeemed codes from webhooks, purge them on a schedule, and the capacity frees up instantly. High-volume stores run this loop forever.

Set up the recycling loop

How it works

The life of a code, end to end

Six moments, two of them where Pixoo calls you. The whole API exists to run this loop.

1
Create the discount
One POST creates a bulk discount, with the same server-side validation as the Pixoo CSV import.
POST/discounts
2
Generate codes at scale
Queue up to 100,000 unique codes in a single call. It returns immediately with a batch to track.
POST/discounts/{id}/code-batches
Pixoo tells you when they’re ready
webhook: Pixoo calls you
No polling loops: the code_batch.completed webhook fires the moment the batch lands.
code_batch.completed
Distribute from your stack
your stack
Emails, packing slips, partner portals, loyalty rewards: the codes are yours to route anywhere.
Know the second a code is used
webhook: Pixoo calls you
code.redeemed delivers the code, order and savings: signed, retried, no customer PII.
code.redeemed
3
Purge & recycle
Delete redeemed codes in batches of 250. Capacity is freed instantly.
POST/discounts/{id}/code-deletions
…and back to step 2
Purged capacity is freed the moment the deletion is accepted, so you can keep generating. That closed loop is how a busy store never hits the 100,000-code cap.

Quick start

Your first code in three steps

From zero to a fresh, unique discount code in about five minutes, no SDK required.

Create your API key
In the Pixoo admin, open Integrations → Pixoo API and create a key. Give it a label (“Production backend”) and pick its scopes: discounts:read to look things up, discounts:write to create and delete.
The pixoo_live_… secret is shown once. Store it in your secret manager. It never appears in the admin again.

Say hello

GET /whoami is the “is my key wired correctly?” call: it echoes your shop, scopes and rate limits.

curl https://api.pixoo.app/api/v1/whoami \
  -H "Authorization: Bearer pixoo_live_YOUR_KEY"

200: response.json

{
  "shop": "acme.myshopify.com",
  "key": {
    "label": "Production backend",
    "lastFour": "8T1Z",
    "scopes": ["discounts:read", "discounts:write"],
    "createdAt": "2026-07-10T09:00:00Z",
    "lastUsedAt": "2026-07-10T10:00:00Z"
  },
  "rateLimit": {
    "sustained": { "limit": 120, "windowSeconds": 60 },
    "burst": { "limit": 20, "windowSeconds": 1 }
  }
}

Mint your first code

Point the call at any Pixoo bulk discount (create one in the admin, or via POST /discounts) and a fresh unique code comes straight back in the response.

curl -X POST https://api.pixoo.app/api/v1/discounts/1234567890/codes \
  -H "Authorization: Bearer pixoo_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prefix": "WELCOME-"}'

200: response.json

{
  "codes": ["WELCOME-7F3K9Q2M8T1Z"],
  "discount": { "id": "1234567890", "title": "Welcome codes" }
}

All examples use the production base URL https://api.pixoo.app/api/v1. The /v1 contract only changes with a new major version.

Essentials

Four things every integration should know

Auth, errors, quotas and idempotency: the same conventions on all 14 endpoints, so you learn them once.

Authentication

Every request carries your key as a bearer token: Authorization: Bearer pixoo_live_…. Keys are created in the Pixoo admin (Integrations → Pixoo API) and carry scopes: discounts:read for lookups, discounts:write for anything that creates or deletes.

Missing or invalid key → 401 unauthorized
Valid key, missing scope → 403 forbidden_scope
Shop not on an API plan → 403 forbidden_plan

Rate limits

Per key: 120 requests/minute sustained with a burst of 20/second. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset and the IETF RateLimit headers.

On 429 rate_limited, honor the Retry-After header (seconds) before retrying. 5xx responses are transient. Retry with backoff.

429: rate limited

HTTP/1.1 429 Too Many Requests
Retry-After: 1
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 0
RateLimit-Policy: 120;w=60, 20;w=1

{"message": "Rate limit exceeded. Retry after 1s.", "code": "rate_limited"}

Idempotency

Every POST that creates discounts or codes accepts an Idempotency-Key header (1–255 chars, unique per shop). Replaying a key returns the stored original response, never a second side effect. Perfect for retry-on-timeout logic.

Concurrent duplicate (first request in flight) → 409 conflict
A failed request releases the key, so the same key can retry
Keys are retained at least 24 hours
Keys are endpoint-agnostic: use one key per logical operation, never reuse a key across different calls

Errors

Every non-2xx body has the same two fields: message (human-readable, safe to surface) and code (stable, machine-matchable). Wrong HTTP method → 405 invalid_request.

422: response.json

{
  "message": "Discount 1234567890 is expired and cannot receive new codes.",
  "code": "invalid_config"
}

All error codes

Code	HTTP	Meaning
unauthorized	401	Missing, unknown or revoked key
forbidden_scope	403	Key lacks the required scope
forbidden_plan	403	Shop's plan does not include the API
not_found	404	Discount / batch / resource not found (or not a Pixoo discount)
invalid_request	422	Malformed body or params (details in message)
invalid_config	422	Valid request, unusable target (e.g. discount expired)
cap_reached	409	Discount is at the 100,000-code cap
conflict	409	Same Idempotency-Key in flight, or a batch/deletion already running on this discount
rate_limited	429	Per-key quota exceeded. Honor Retry-After
internal_error	500	Unexpected server error. Transient, retry with backoff

Guides

Three recipes you can ship today

Complete, working walkthroughs for the flows from the use cases above: copy, paste, adapt.

Guide 01

Launch a 10,000-code campaign in one call

Anything above 10 codes goes through code batches: one POST queues the generation, Pixoo processes it FIFO per shop, and you collect the codes when it completes.

Queue the batch

The call returns 202 immediately with a codeBatch to track. The Idempotency-Key makes retries safe: replays return the original batch instead of queuing a second one.

curl -X POST https://api.pixoo.app/api/v1/discounts/1234567890/code-batches \
  -H "Authorization: Bearer pixoo_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: summer-launch-2026" \
  -d '{"quantity": 10000, "prefix": "SUMMER-"}'

202: response.json (grab codeBatch.id for step 2)

{
  "codeBatch": {
    "id": "cb_9b1deb4d…",
    "status": "queued",
    "totalCodes": 10000,
    "codesProcessed": 0,
    "percentComplete": 0,
    "queuePosition": 0,
    "discountId": "1234567890",
    "createdAt": "2026-07-10T09:00:00Z",
    "completedAt": null,
    "error": null
  }
}

Wait for it: webhook or poll

Subscribe to code_batch.completed (see the webhook guide) and Pixoo pings you the moment the batch lands. Or poll the batch: once completed, add ?include=codes to fetch every code in one go.

curl "https://api.pixoo.app/api/v1/code-batches/cb_9b1deb4d…?include=codes" \
  -H "Authorization: Bearer pixoo_live_YOUR_KEY"

200: response.json

{
  "codeBatch": {
    "id": "cb_9b1deb4d…",
    "status": "completed",
    "totalCodes": 10000,
    "codesProcessed": 10000,
    "percentComplete": 100,
    "queuePosition": null,
    "discountId": "1234567890",
    "createdAt": "2026-07-10T09:00:00Z",
    "completedAt": "2026-07-10T09:04:12Z",
    "error": null,
    "codes": ["SUMMER-7F3K9Q2M8T1Z", "SUMMER-2B8XW4KQ90MJ", "…"]
  }
}

Distribute

The codes are yours: pipe them to your ESP, print partner, loyalty platform or affiliate portal. Each code is unique on the discount, and the discount enforces all the usual Pixoo rules (markets, currencies, caps) at checkout.

Guide 02

Receive & verify webhooks

Three events can reach your server: code.redeemed, code_batch.completed and gift.redeemed. Every delivery is signed. Always verify before trusting the payload.

The response contains the signingSecret (whsec_…) once. Store it. It signs every delivery and is never shown again. Up to 10 active webhooks per shop.

curl -X POST https://api.pixoo.app/api/v1/webhooks \
  -H "Authorization: Bearer pixoo_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event": "code.redeemed", "targetUrl": "https://example.com/hooks/pixoo"}'

201: response.json

{
  "webhook": {
    "id": "…",
    "event": "code.redeemed",
    "targetUrl": "https://example.com/hooks/pixoo",
    "status": "active",
    "lastDeliveryAt": null,
    "createdAt": "2026-07-10T13:00:00Z"
  },
  "signingSecret": "whsec_…"
}

Verify the signature

Each delivery carries Pixoo-Signature: sha256=<hex HMAC-SHA256(raw body, secret)>. A complete Express server, ready to run:

server.js: complete webhook consumer

import express from 'express'
import crypto from 'node:crypto'

const app = express()

// The signing secret returned once by POST /webhooks.
const SIGNING_SECRET = process.env.PIXOO_WEBHOOK_SECRET // "whsec_…"

const seenEventIds = new Set() // use your database in production

// Keep the raw body: the signature covers the exact bytes Pixoo sent.
app.post(
  '/hooks/pixoo',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    // Pixoo-Signature: sha256=<hex HMAC-SHA256(raw body, signing secret)>
    const signature = req.get('Pixoo-Signature') ?? ''
    const expected =
      'sha256=' +
      crypto.createHmac('sha256', SIGNING_SECRET).update(req.body).digest('hex')

    const valid =
      signature.length === expected.length &&
      crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
    if (!valid) return res.status(401).send('invalid signature')

    // Deliveries are at-least-once: dedupe on Pixoo-Event-Id.
    const eventId = req.get('Pixoo-Event-Id')
    if (seenEventIds.has(eventId)) return res.sendStatus(200)
    seenEventIds.add(eventId)

    const { event, data } = JSON.parse(req.body)
    if (event === 'code.redeemed') {
      // data: { orderId, discountTitle, code, savingsAmount, currency }
      markCodeAsRedeemed(data.code) // your storage (feeds the purge cron)
    }

    res.sendStatus(200) // answer 2xx within 10 seconds
  },
)

app.listen(3000)

Know the delivery rules

These are the payloads your endpoint receives: no customer PII, by design (no names, no emails). The body id is the same value as the Pixoo-Event-Id header. Note that code_batch.completed does not carry the codes themselves. Fetch them with GET /code-batches/{batchId}?include=codes.

delivery headers

POST https://your-server.example/hooks/pixoo
Content-Type: application/json
Pixoo-Event: code.redeemed
Pixoo-Event-Id: evt_01H…   ← dedup on this
Pixoo-Signature: sha256=3f1a…

{
  "id": "evt_01H…",
  "event": "code.redeemed",
  "createdAt": "2026-07-10T14:02:11Z",
  "data": {
    "orderId": "…",
    "discountTitle": "Holiday bulk",
    "code": "VIP-7F3K9Q2M8T1Z",
    "savingsAmount": 9.5,
    "currency": "EUR"
  }
}

Deliveries are at-least-once: dedupe on the Pixoo-Event-Id header.
Answer 2xx within 10 seconds; do slow work asynchronously.
Failures retry with backoff: 1 min, 5 min, 30 min, 2 h, 8 h. Retries survive restarts.
After 20 consecutive terminally-failed deliveries the subscription is auto-disabled. Recreate it to resume.
Missed something during an outage? GET /events replays the last 7 days.

Guide 03

Recycle redeemed codes on a schedule

Single-use codes pile up. A discount caps at 100,000 codes, so purge the redeemed ones nightly and the loop runs forever. Capacity is freed the moment a deletion is accepted.

Collect redeemed codes

Your webhook consumer from Guide 02 already marks codes as redeemed when code.redeemed fires. That list is the input for the cron below.

Purge them nightly

Deletions take up to 250 explicit codes per call and run one at a time per discount. The script waits for each to complete. Unknown codes are silently ignored, and cleanup works even on expired discounts.

// Nightly cron: purge redeemed codes so the discount
// never reaches the 100,000-code cap.
import crypto from 'node:crypto'

const BASE = 'https://api.pixoo.app/api/v1'
const HEADERS = { Authorization: `Bearer ${process.env.PIXOO_API_KEY}` }
const DISCOUNT_ID = '1234567890'

// 1. Codes your webhook consumer marked as redeemed
const redeemed = await getRedeemedCodesFromDb() // your storage

// 2. Delete in chunks of 250 (the per-call maximum).
//    One deletion runs at a time per discount, so wait between chunks.
for (let i = 0; i < redeemed.length; i += 250) {
  const chunk = redeemed.slice(i, i + 250)
  const res = await fetch(`${BASE}/discounts/${DISCOUNT_ID}/code-deletions`, {
    method: 'POST',
    headers: {
      ...HEADERS,
      'Content-Type': 'application/json',
      // Same key when a chunk is retried: that is what prevents over-release
      'Idempotency-Key': `purge-${DISCOUNT_ID}-${chunk[0]}`,
    },
    body: JSON.stringify({ codes: chunk }),
  })
  let { codeDeletion } = await res.json() // 202: accepted
  console.log(`purging ${codeDeletion.matchedCount}/${chunk.length} codes`)

  while (codeDeletion.status === 'processing') {
    await new Promise((resolve) => setTimeout(resolve, 2000))
    const poll = await fetch(`${BASE}/code-deletions/${codeDeletion.id}`, {
      headers: HEADERS,
    })
    ;({ codeDeletion } = await poll.json())
  }
}

202: response.json

{
  "codeDeletion": {
    "id": "cd_01H…",
    "status": "processing",
    "requestedCount": 250,
    "matchedCount": 248,
    "discountId": "1234567890",
    "createdAt": "2026-07-10T09:00:00Z",
    "completedAt": null,
    "error": null
  }
}

API reference

All 14 endpoints

Scannable first, detailed on demand: expand any card for parameters, response shapes and error codes.

Keys

Check that a key is wired correctly before anything else.

scope: any valid key

Works with any valid key, no specific scope. It is the “is my key wired correctly?” call.

Response200

response.json

{
  "shop": "acme.myshopify.com",
  "key": {
    "label": "Production backend",
    "lastFour": "8T1Z",
    "scopes": ["discounts:read", "discounts:write"],
    "createdAt": "2026-07-10T09:00:00Z",
    "lastUsedAt": "2026-07-10T10:00:00Z"
  },
  "rateLimit": {
    "sustained": { "limit": 120, "windowSeconds": 60 },
    "burst": { "limit": 20, "windowSeconds": 1 }
  }
}

Errors

unauthorizedrate_limited

Discounts

List, inspect and create Pixoo discounts of any of the four types.

scope: discounts:read

discountClasses is always an array (a discount may carry several classes): never assume a single class. A page may contain fewer than limit items while nextCursor is set: iterate until nextCursor is null.

Parameters

statusquery: active | scheduled | expired
titlequery: Exact title match (the Flow-style lookup)
isBulkquery: true | false
cursorquery: From the previous page
limitquery: 1–50, default 20

Response200

response.json

{
  "discounts": [
    {
      "id": "1234567890",
      "title": "Holiday bulk",
      "status": "active",
      "discountClasses": ["PRODUCT"],
      "isBulk": true,
      "codesCount": 48210,
      "createdAt": "2026-06-01T09:00:00Z"
    }
  ],
  "nextCursor": "eyJ…"
}

Errors

rate_limited

scope: discounts:writesupports Idempotency-Key

Creates any of the four discount types (product, order, shipping, buy-x-get-y), validated by the same server-side chain as the CSV import. The body uses the exact field names of the import field reference (Pixoo admin → Discounts → Import → Field reference), with native JSON types. Unknown fields are rejected by name. method: "Bulk" additionally requires bulkConfig: the discount is created with its first code and the remaining codes ride the async queue; the response then includes a codeBatch to poll.

Parameters

typebody: product-discount | order-discount | shipping-discount | buy-x-get-y-discount (required)
methodbody: Code | Automatic | Bulk (required)
titlebody: Required
codebody: Required when method is "Code"
bulkConfigbody: Required when method is "Bulk": { numberOfCodes, codeLength?, prefix?, suffix?, characterSet?, specificCodes?, isSpecificCodes? }
…type-specific fieldsbody: Import field reference is the single source of truth for names, enums and defaults

Request body

POST /discounts

{
  "type": "product-discount",
  "method": "Bulk",
  "title": "Welcome codes",
  "discountValuesType": "PERCENTAGE",
  "discountPercentageValue": 15,
  "appliesToEligibility": "COLLECTIONS",
  "appliesToSelectedItems": [{ "id": "gid://shopify/Collection/123456789" }],
  "bulkConfig": { "numberOfCodes": 1000, "prefix": "WELCOME-" }
}

Response201

response.json

{
  "discount": {
    "id": "1234567890",
    "title": "Welcome codes",
    "status": "active",
    "discountClasses": ["PRODUCT"],
    "isBulk": true,
    "codesCount": 1,
    "createdAt": "2026-07-10T09:00:00Z"
  },
  "codeBatch": {
    "id": "cb_9b1deb4d…",
    "status": "queued",
    "totalCodes": 999,
    "codesProcessed": 0,
    "percentComplete": 0,
    "queuePosition": 0,
    "discountId": "1234567890",
    "createdAt": "2026-07-10T09:00:00Z",
    "completedAt": null,
    "error": null
  }
}

Errors

invalid_requestconflictrate_limited

scope: discounts:read

Same representation as a list item. Discounts are addressed by their numeric Shopify id (the one visible in the admin URL), serialized as a string.

Parameters

idpath: Numeric Shopify discount id, as a string

Response200

response.json

{
  "id": "1234567890",
  "title": "Holiday bulk",
  "status": "active",
  "discountClasses": ["PRODUCT"],
  "isBulk": true,
  "codesCount": 48210,
  "createdAt": "2026-06-01T09:00:00Z"
}

Errors

not_foundrate_limited

Codes

Mint codes one at a time, in 100k batches, and clean them up.

scope: discounts:read

Returns invalid_config for automatic discounts, which have no codes.

Parameters

idpath: Discount id
searchquery: Matches code values
cursorquery: From the previous page
limitquery: 1–100, default 20

Response200

response.json

{
  "codes": [{ "code": "VIP-7F3K9Q2M8T1Z", "usageCount": 1 }],
  "nextCursor": null
}

Errors

not_foundinvalid_configrate_limited

scope: discounts:writesupports Idempotency-Key

Works on Pixoo bulk discounts. The sweet spot for “one fresh code per customer” flows: no polling, the codes are in the response body. Above 10 codes, use code-batches.

Parameters

idpath: Discount id (must be a Pixoo bulk discount)
quantitybody: Integer 1–10, default 1
prefixbody: String ≤32 chars, default "", prepended to each code

Request body

POST /discounts/{id}/codes

{ "quantity": 1, "prefix": "XMAS-" }

Response200

response.json

{
  "codes": ["XMAS-7F3K9Q2M8T1Z"],
  "discount": { "id": "1234567890", "title": "Holiday bulk" }
}

Errors

not_foundinvalid_configcap_reachedconflictinvalid_requestrate_limited

scope: discounts:writesupports Idempotency-Key

Returns 202 immediately with a codeBatch to track. Get notified with the code_batch.completed webhook, or poll GET /code-batches/{id}. quantity is capped by the remaining discount capacity.

Parameters

idpath: Discount id
quantitybody: Integer 1–100,000 (required)
prefixbody: String ≤32 chars, optional

Request body

POST /discounts/{id}/code-batches

{ "quantity": 50000, "prefix": "SUMMER-" }

Response202

response.json

{
  "codeBatch": {
    "id": "cb_9b1deb4d…",
    "status": "queued",
    "totalCodes": 50000,
    "codesProcessed": 0,
    "percentComplete": 0,
    "queuePosition": 0,
    "discountId": "1234567890",
    "createdAt": "2026-07-09T10:00:00Z",
    "completedAt": null,
    "error": null
  }
}

Errors

not_foundconflictinvalid_requestrate_limited

scope: discounts:read

status ∈ queued | processing | completed | failed. Adds percentComplete, queuePosition (while queued), completedAt, and error ({message, code}, failed only). With ?include=codes on a completed batch, the response adds the full codes array (large, up to 100k strings).

Parameters

idpath: Batch id from the 202 response
includequery: "codes" adds the full codes array on completed batches

Response200 (with ?include=codes)

response.json

{
  "codeBatch": {
    "id": "cb_9b1deb4d…",
    "status": "completed",
    "totalCodes": 50000,
    "codesProcessed": 50000,
    "percentComplete": 100,
    "queuePosition": null,
    "discountId": "1234567890",
    "createdAt": "2026-07-09T10:00:00Z",
    "completedAt": "2026-07-09T10:18:27Z",
    "error": null,
    "codes": ["SUMMER-7F3K9Q2M8T1Z", "…"]
  }
}

Errors

not_foundrate_limited

scope: discounts:writesupports Idempotency-Key

Collect redeemed codes from code.redeemed webhooks, purge them here, and the discount never reaches the 100,000-code ceiling. Codes are matched case-insensitively; codes that don’t exist on the discount are silently ignored (matchedCount tells you how many will be deleted). Works on expired discounts: cleanup is always legal. One deletion at a time per discount: a POST while one is processing returns 409 conflict. Use Idempotency-Key on retries, because replaying without it can over-release capacity accounting.

Parameters

idpath: Discount id
codesbody: Array of 1–250 explicit code strings (required)

Request body

POST /discounts/{id}/code-deletions

{ "codes": ["VIP-7F3K9Q2M8T1Z", "VIP-2B8XW4KQ90MJ"] }

Response202

response.json

{
  "codeDeletion": {
    "id": "…",
    "status": "processing",
    "requestedCount": 250,
    "matchedCount": 248,
    "discountId": "1234567890",
    "createdAt": "…",
    "completedAt": null,
    "error": null
  }
}

Errors

not_foundinvalid_requestconflictrate_limited

scope: discounts:read

status ∈ processing | completed | failed (failed is reserved; current failures surface as request errors). Capacity accounting is freed as soon as the deletion is accepted.

Parameters

idpath: Deletion id from the 202 response

Response200

response.json

{
  "codeDeletion": {
    "id": "…",
    "status": "completed",
    "requestedCount": 250,
    "matchedCount": 248,
    "discountId": "1234567890",
    "createdAt": "2026-07-10T02:00:00Z",
    "completedAt": "2026-07-10T02:00:41Z",
    "error": null
  }
}

Errors

not_foundrate_limited

Webhooks & events

Let Pixoo call you, with a signed, retried, at-least-once delivery.

scope: discounts:write

event ∈ code.redeemed | code_batch.completed | gift.redeemed. targetUrl must be an https URL on a publicly reachable host. Up to 10 active webhooks per shop. The signingSecret is shown once, store it now; it signs every delivery. Re-subscribing the same event and URL is idempotent: it returns the existing subscription with a 200 and a null signingSecret, so an automation can safely re-subscribe.

Parameters

eventbody: code.redeemed | code_batch.completed | gift.redeemed (required)
targetUrlbody: Public https:// URL to deliver to. Localhost, private and loopback addresses are rejected (required)

Request body

POST /webhooks

{ "event": "code.redeemed", "targetUrl": "https://example.com/hooks/pixoo" }

Response201 / 200

response.json

{
  "webhook": {
    "id": "…",
    "event": "code.redeemed",
    "targetUrl": "https://example.com/hooks/pixoo",
    "status": "active",
    "lastDeliveryAt": null,
    "createdAt": "2026-07-10T13:00:00Z"
  },
  "signingSecret": "whsec_…"
}

Errors

invalid_requestrate_limited

scope: discounts:read

The list never exposes signing secrets.

Response200

response.json

{
  "webhooks": [
    {
      "id": "…",
      "event": "code.redeemed",
      "targetUrl": "https://example.com/hooks/pixoo",
      "status": "active",
      "lastDeliveryAt": "2026-07-10T14:02:11Z",
      "createdAt": "2026-07-10T13:00:00Z"
    }
  ]
}

Errors

rate_limited

scope: discounts:write

Auto-disabled subscriptions (after 20 consecutive terminally-failed deliveries) must be recreated to resume.

Parameters

idpath: Webhook id

Response200

response.json

{ "deleted": true }

Errors

not_foundrate_limited

scope: discounts:read

Newest first, 7-day window. Items have the exact delivery shape (id, event, createdAt, data). Payloads carry no customer PII.

Parameters

typequery: Event name filter
cursorquery: From the previous page
limitquery: 1–100, default 20

Response200

response.json

{
  "events": [
    {
      "id": "evt_…",
      "event": "code.redeemed",
      "createdAt": "2026-07-10T14:02:11Z",
      "data": {
        "orderId": "…",
        "discountTitle": "Holiday bulk",
        "code": "VIP-7F3K9Q2M8T1Z",
        "savingsAmount": 9.5,
        "currency": "EUR"
      }
    }
  ],
  "nextCursor": null
}

Errors

invalid_requestrate_limited

Analytics

The numbers behind the in-app dashboard: every redemption, plus per-currency aggregates.

scope: discounts:read

Amounts are in their own currency, never converted: do not sum across currencies. createdAt is the order payment time. discountTitle is null when the discount was deleted. History is bounded by the analytics retention (13 months).

Parameters

cursorquery: From the previous page
limitquery: 1-100, default 20
discountIdquery: Filter to one discount (numeric id)
sincequery: ISO 8601 date or datetime

Response200

response.json

{
  "redemptions": [
    {
      "id": "5d1f…",
      "order": "#1042",
      "discountId": "1234567890",
      "discountTitle": "Holiday bulk",
      "discountType": "product-discount",
      "method": "CODE",
      "code": "VIP-7F3K9Q2M8T1Z",
      "currency": "EUR",
      "amountSaved": 9.5,
      "shippingSaved": 0,
      "orderTotal": 99.9,
      "country": "DE",
      "isFreeGift": false,
      "createdAt": "2026-07-10T14:02:11Z"
    }
  ],
  "nextCursor": null
}

Errors

invalid_requestrate_limited

scope: discounts:read

rangeDays is one of 7, 30, 90 or 365 (default 30). revenue is the total of orders that carried at least one Pixoo discount, per currency. orders.total counts every paid order in the window.

Parameters

rangeDaysquery: 7, 30, 90 or 365 (default 30)

Response200

response.json

{
  "rangeDays": 30,
  "from": "2026-06-10T09:00:00Z",
  "currencies": [
    {
      "currency": "EUR",
      "uses": 410,
      "savingsGiven": 1647.0,
      "shippingSaved": 96.5,
      "revenue": 14200.0,
      "discountedOrders": 377
    }
  ],
  "orders": { "total": 2049, "withPixooDiscount": 377 },
  "freeGifts": { "count": 148 }
}

Errors

invalid_requestrate_limited

Versioning

Built to not break you

The version lives in the URL: /v1.
Additive changes (new optional fields, new endpoints, new event types) may happen at any time without notice: consumers must ignore unknown fields.
Breaking changes only ship as /v2, with at least 12 months of continued /v1 support.
During the private beta, field names may still shift. The contract freezes the day the first external key is issued.

Generate, track and recycle discount codes from your own stack.

Four flows merchants keep asking for

Send a unique welcome code to every new customer

Launch a 10,000-code campaign in one call

Know the second a code is redeemed

Never hit the 100k code cap

The life of a code, end to end

Create the discount

Generate codes at scale

Pixoo tells you when they’re ready

Distribute from your stack

Know the second a code is used

Purge & recycle

…and back to step 2

Your first code in three steps

Create your API key

Say hello

Mint your first code

Four things every integration should know

Authentication

Rate limits

Idempotency

Errors

All error codes

Three recipes you can ship today

Launch a 10,000-code campaign in one call

1Queue the batch

2Wait for it: webhook or poll

3Distribute

Receive & verify webhooks

1Subscribe

2Verify the signature

3Know the delivery rules

Recycle redeemed codes on a schedule

1Collect redeemed codes

2Purge them nightly

All 14 endpoints

Keys

Response200

Errors

Discounts

Parameters

Response200

Errors

Parameters

Request body

Response201

Errors

Parameters

Response200

Errors

Codes

Parameters

Response200

Errors

Parameters

Request body

Response200

Errors

Parameters

Request body

Response202

Errors

Parameters

Response200 (with ?include=codes)

Errors

Parameters

Request body

Response202

Errors

Parameters

Response200

Errors

Webhooks & events

Parameters

Request body

Response201 / 200

Errors

Response200

Errors

Queue the batch

Wait for it: webhook or poll

Distribute

Subscribe

Verify the signature

Know the delivery rules

Collect redeemed codes

Purge them nightly