{ "openapi": "3.1.0", "info": { "title": "stmpr API", "version": "1.0", "description": "The stmpr API lets your POS or other systems enroll customers, add and remove stamps, redeem rewards, and read loyalty statistics.\n\n## Authentication\n\nCreate an API key on the dashboard **API & Webhooks** page and send it as a Bearer token:\n\n```\nAuthorization: Bearer stmpr_...\n```\n\nThe full key is shown once at creation; only a hash is stored. API keys belong to the workspace, not to one loyalty card. **Business** plans can use read endpoints. **Pro** plans can also use write endpoints when the key was created with write access.\n\n## Identifiers\n\nLoyalty cards use a short Wallet ID (for example `A7K9Q2`). Customers use a secure, non-guessable Customer ID in API paths and QR, Aztec, or PDF417 pass barcodes. The separate four-digit Customer code is intended for manual staff lookup and Code128 passes; do not use it as an API identifier. Find and copy these values in the dashboard. Internal database ids are never exposed.\n\n## Idempotency\n\nStamp and redemption mutations require an `Idempotency-Key` header containing a client-generated value of at most 120 characters, such as a UUID. A key must be unique across all mutation requests made with the same API key. Retrying the same mutation with the same key returns the stored response instead of applying the change twice.\n\n## Rate limits\n\nRequests are limited to 120 per minute per API key. Exceeding the limit returns `429 Too Many Requests`.\n\n## Webhooks\n\nPro workspaces can register webhook endpoints on the dashboard **API & Webhooks** page. stmpr sends a `POST` request with a JSON body for the subscribed events:\n\n`customer.created`, `stamp.added`, `stamp.removed`, `reward.ready`, `reward.redeemed`, `pass.updated`\n\nEvery delivery uses this envelope:\n\n```json\n{\n \"id\": \"10482\",\n \"event\": \"stamp.added\",\n \"created_at\": \"2026-07-17T10:15:30+00:00\",\n \"data\": {\n \"customer\": {\n \"id\": \"01JZ8Y7X6W5V4U3T2S1R0Q9P8N\",\n \"display_code\": \"4829\",\n \"stamps_count\": 4,\n \"stamps_required\": 10,\n \"ready_to_redeem\": false\n },\n \"quantity\": 1\n }\n}\n```\n\n`data.customer` contains the affected customer card. Mutation events may add event-specific fields such as `quantity`, `note`, or pass update metadata. Use the `event` value to select the matching payload handler and tolerate new fields for forward compatibility.\n\nEach request carries the headers `X-Stmpr-Event`, `X-Stmpr-Delivery`, and `X-Stmpr-Signature: t={unix_timestamp},v1={signature}`, where the signature is `HMAC-SHA256(secret, \"{t}.{raw_body}\")` using the endpoint's signing secret. Verify it like this:\n\n```php\n[$t, $v1] = explode(',', $header);\n$t = substr($t, 2);\n$v1 = substr($v1, 3);\n$expected = hash_hmac('sha256', $t.'.'.$rawBody, $secret);\n$valid = hash_equals($expected, $v1);\n```\n\nFailed deliveries are retried up to 5 times with increasing backoff (10s, 60s, 300s, 900s). Your endpoint should respond with a 2xx status within 10 seconds and must be idempotent, because the same event can be delivered more than once." }, "servers": [ { "url": "https:\/\/stmpr.io\/api\/v1" } ], "tags": [ { "name": "Loyalty cards" }, { "name": "Customers" }, { "name": "Webhook deliveries" } ], "security": [ { "http": [] } ], "paths": { "\/wallets": { "get": { "operationId": "v1.wallets.index", "description": "Returns every loyalty card the API key can access. A key limited to one\nloyalty card returns only that card.", "summary": "Cards", "tags": [ "Loyalty cards" ], "responses": { "200": { "description": "Cards completed successfully.", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "message": "Loyalty cards retrieved successfully.", "data": [ { "id": "A7K9Q2", "name": "Coffee rewards", "status": "published", "stamps_required": 10, "reward": "One free coffee", "public_url": "https:\/\/stmpr.io\/card\/A7K9Q2", "created_at": "2026-07-17T10:15:30+00:00" } ] } ], "properties": { "message": { "type": "string", "description": "Human-readable confirmation that the request completed successfully.", "examples": [ "Loyalty cards retrieved successfully." ] }, "data": { "type": "array", "description": "Response payload for the completed request.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Wallet ID used in API paths.", "examples": [ "A7K9Q2" ] }, "name": { "type": "string", "description": "Display name of the loyalty card.", "examples": [ "Coffee rewards" ] }, "status": { "type": "string", "description": "Current lifecycle status of the loyalty card.", "examples": [ "published" ] }, "stamps_required": { "type": "integer", "description": "Number of stamps required before the reward can be redeemed.", "examples": [ 10 ] }, "reward": { "type": [ "string", "null" ], "description": "Customer-facing description of the reward.", "examples": [ "One free coffee" ] }, "public_url": { "type": "string", "format": "uri", "description": "Public enrollment page for this loyalty card.", "examples": [ "https:\/\/stmpr.io\/card\/A7K9Q2" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time the loyalty card was created, in ISO 8601 format.", "examples": [ "2026-07-17T10:15:30+00:00" ] } }, "required": [ "id", "name", "status", "stamps_required", "reward", "public_url", "created_at" ] } } }, "required": [ "message", "data" ] } } } }, "401": { "description": "The API key is missing, invalid, or revoked.", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "invalid_request_error", "code": "invalid_api_key", "message": "The API key is invalid or has been revoked." } } ], "properties": { "error": { "type": "object", "description": "Structured details explaining why the API request failed.", "properties": { "type": { "type": "string", "description": "Broad category of API error." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "type": "object", "description": "Additional structured error details, when available." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "The workspace plan does not include API access.", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "invalid_request_error", "code": "permission_denied", "message": "The API key does not permit this request." } } ], "properties": { "error": { "type": "object", "description": "Structured details explaining why the API request failed.", "properties": { "type": { "type": "string", "description": "Broad category of API error." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "type": "object", "description": "Additional structured error details, when available." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "The API key exceeded its request limit.", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "invalid_request_error", "code": "rate_limit_exceeded", "message": "Too many requests. Please try again later." } } ], "properties": { "error": { "type": "object", "description": "Structured details explaining why the API request failed.", "properties": { "type": { "type": "string", "description": "Broad category of API error." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "type": "object", "description": "Additional structured error details, when available." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "\/wallets\/{walletId}\/stats": { "get": { "operationId": "v1.wallets.stats", "description": "Returns aggregate counters for one loyalty card: total customers,\ncustomers with a full card, lifetime stamps added, and rewards redeemed.", "summary": "Statistics", "tags": [ "Loyalty cards" ], "parameters": [ { "name": "walletId", "in": "path", "required": true, "description": "Wallet ID shown on the loyalty card overview and API setup page.", "schema": { "type": "string" }, "example": "A7K9Q2" } ], "responses": { "200": { "description": "Statistics completed successfully.", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "message": "Loyalty card statistics retrieved successfully.", "data": { "wallet_id": "A7K9Q2", "customers_total": 842, "customers_ready_to_redeem": 36, "stamps_added_total": 5192, "rewards_redeemed_total": 417 } } ], "properties": { "message": { "type": "string", "description": "Human-readable confirmation that the request completed successfully.", "examples": [ "Loyalty card statistics retrieved successfully." ] }, "data": { "type": "object", "description": "Response payload for the requested resource or operation.", "properties": { "wallet_id": { "type": "string", "description": "Public identifier of the loyalty card.", "examples": [ "A7K9Q2" ] }, "customers_total": { "type": "integer", "description": "Total number of customers enrolled in the loyalty card.", "examples": [ 842 ] }, "customers_ready_to_redeem": { "type": "integer", "description": "Number of active customers currently eligible to redeem.", "examples": [ 36 ] }, "stamps_added_total": { "type": "integer", "description": "Sum of all positive stamp changes recorded for this loyalty card.", "examples": [ 5192 ] }, "rewards_redeemed_total": { "type": "integer", "description": "Total number of rewards redeemed on this loyalty card.", "examples": [ 417 ], "minimum": 0 } }, "required": [ "wallet_id", "customers_total", "customers_ready_to_redeem", "stamps_added_total", "rewards_redeemed_total" ] } }, "required": [ "message", "data" ] } } } }, "401": { "description": "The API key is missing, invalid, or revoked.", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "invalid_request_error", "code": "invalid_api_key", "message": "The API key is invalid or has been revoked." } } ], "properties": { "error": { "type": "object", "description": "Structured details explaining why the API request failed.", "properties": { "type": { "type": "string", "description": "Broad category of API error." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "type": "object", "description": "Additional structured error details, when available." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "The workspace plan does not include API access.", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "invalid_request_error", "code": "permission_denied", "message": "The API key does not permit this request." } } ], "properties": { "error": { "type": "object", "description": "Structured details explaining why the API request failed.", "properties": { "type": { "type": "string", "description": "Broad category of API error." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "type": "object", "description": "Additional structured error details, when available." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "The loyalty card does not exist or is outside the API key scope.", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The requested resource was not found." } } ], "properties": { "error": { "type": "object", "description": "Structured details explaining why the API request failed.", "properties": { "type": { "type": "string", "description": "Broad category of API error." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "type": "object", "description": "Additional structured error details, when available." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "The API key exceeded its request limit.", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "invalid_request_error", "code": "rate_limit_exceeded", "message": "Too many requests. Please try again later." } } ], "properties": { "error": { "type": "object", "description": "Structured details explaining why the API request failed.", "properties": { "type": { "type": "string", "description": "Broad category of API error." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "type": "object", "description": "Additional structured error details, when available." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "\/wallets\/{walletId}\/locations": { "get": { "operationId": "v1.wallets.locations.index", "description": "Returns workspace locations that may be supplied as `location_id` when\nadding or removing stamps and redeeming rewards.", "summary": "Locations", "tags": [ "Loyalty cards" ], "parameters": [ { "name": "walletId", "in": "path", "required": true, "description": "Wallet ID shown on the loyalty card overview and API setup page.", "schema": { "type": "string" }, "example": "A7K9Q2" } ], "responses": { "200": { "description": "Locations completed successfully.", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "message": "Locations retrieved successfully.", "data": [ { "id": 12, "name": "Downtown store", "address": "1051 Budapest, Sas utca 1." } ] } ], "properties": { "message": { "type": "string", "description": "Human-readable confirmation that the request completed successfully.", "examples": [ "Locations retrieved successfully." ] }, "data": { "type": "array", "description": "Response payload for the requested resource or operation.", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Value returned in the `id` field.", "examples": [ 42 ] }, "name": { "type": [ "string", "null" ], "description": "Human-readable display name.", "examples": [ "Downtown store" ] }, "address": { "type": "string", "description": "Formatted postal address of the workspace location.", "examples": [ "1051 Budapest, Sas utca 1." ] } }, "required": [ "id", "name", "address" ] } } }, "required": [ "message", "data" ] } } } } } } }, "\/wallets\/{walletId}\/customers": { "get": { "operationId": "v1.customers.index", "description": "Returns customers in ascending creation order. Use the returned cursor to\ncontinue through large loyalty cards without loading the full collection.", "summary": "Customers", "tags": [ "Customers" ], "parameters": [ { "name": "walletId", "in": "path", "required": true, "description": "Wallet ID shown on the loyalty card overview and API setup page.", "schema": { "type": "string" }, "example": "A7K9Q2" }, { "name": "search", "in": "query", "description": "Optional text matched against the Customer ID, customer code, and collected customer fields.", "schema": { "type": [ "string", "null" ] }, "example": "anna@example.com" }, { "name": "cursor", "in": "query", "description": "Customer id returned as `meta.next_cursor` by the previous page.", "schema": { "type": [ "integer", "null" ] }, "example": 1240 }, { "name": "limit", "in": "query", "description": "Maximum number of customers to return. Defaults to 25 and cannot exceed 100.", "schema": { "type": [ "integer", "null" ], "default": 25 }, "example": 50 } ], "responses": { "200": { "description": "Customers completed successfully.", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "message": "Customers retrieved successfully.", "data": [ { "id": "01JZ8Y7X6W5V4U3T2S1R0Q9P8N", "display_code": "4829", "wallet_id": "A7K9Q2", "stamps_count": 4, "stamps_required": 10, "ready_to_redeem": false, "redemptions_count": 2, "revoked": false, "fields": { "first_name": "Anna", "email": "anna@example.com" }, "marketing_consent": true, "created_at": "2026-07-17T08:30:00Z", "first_stamp_at": "2026-07-17T08:45:00Z", "last_stamp_at": "2026-07-17T09:15:00Z", "last_redemption_at": "2026-07-10T11:20:00Z", "last_activity_at": "2026-07-17T09:15:00Z", "updated_at": "2026-07-17T09:15:00Z" } ], "meta": { "next_cursor": 1240, "has_more": true } } ], "properties": { "message": { "type": "string", "description": "Human-readable confirmation that the request completed successfully.", "examples": [ "Customers retrieved successfully." ] }, "data": { "type": "array", "description": "Response payload for the completed request.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable, non-guessable Customer ID used in API paths and encoded in QR, Aztec, and PDF417 pass barcodes.", "examples": [ "01JZ8Y7X6W5V4U3T2S1R0Q9P8N" ] }, "display_code": { "type": "string", "description": "Four-digit Customer code staff can enter manually. Code128 passes encode this value.", "examples": [ "4829" ] }, "wallet_id": { "type": "string", "description": "Wallet ID of the loyalty card this customer belongs to.", "examples": [ "A7K9Q2" ] }, "stamps_count": { "type": "integer", "description": "Customer's current number of stamps.", "examples": [ 4 ] }, "stamps_required": { "type": "integer", "description": "Number of stamps required before the reward can be redeemed.", "examples": [ 10 ] }, "ready_to_redeem": { "type": "boolean", "description": "Whether the customer currently has enough stamps to redeem the reward.", "examples": [ false ] }, "redemptions_count": { "type": "integer", "description": "Total number of rewards this customer has redeemed on this card.", "examples": [ 2 ] }, "revoked": { "type": "boolean", "description": "Whether this customer card has been revoked and can no longer be used.", "examples": [ false ] }, "fields": { "type": "array", "description": "Customer data keyed by the loyalty card's configured field identifiers.", "examples": [ { "first_name": "Anna", "email": "anna@example.com" } ], "items": {} }, "marketing_consent": { "type": "boolean", "description": "Whether the customer consented to marketing communication.", "examples": [ true ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time the customer enrolled, in ISO 8601 format.", "examples": [ "2026-07-17T08:30:00Z" ] }, "first_stamp_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time the customer's first stamp was added, or `null` before the first stamp." }, "last_stamp_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time the customer's most recent stamp was added, or `null` if none exists." }, "last_redemption_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time the customer's most recent reward was redeemed, or `null` if none exists." }, "last_activity_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time of the customer's most recent card activity, in ISO 8601 format." }, "updated_at": { "type": [ "string", "null" ], "description": "Time this customer record was most recently updated, in ISO 8601 format. @format date-time", "examples": [ "2026-07-17T09:15:00Z" ] } }, "required": [ "id", "display_code", "wallet_id", "stamps_count", "stamps_required", "ready_to_redeem", "redemptions_count", "revoked", "fields", "marketing_consent", "created_at", "first_stamp_at", "last_stamp_at", "last_redemption_at", "last_activity_at", "updated_at" ] } }, "meta": { "type": "object", "description": "Pagination or synchronization metadata for this response.", "properties": { "next_cursor": { "type": [ "integer", "null" ], "description": "Cursor to send with the next request, or `null` when the page is empty.", "examples": [ 1240 ] }, "has_more": { "type": "boolean", "description": "Whether another page of records is available.", "examples": [ true ] } }, "required": [ "next_cursor", "has_more" ] } }, "required": [ "message", "data", "meta" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } }, "post": { "operationId": "v1.customers.store", "description": "Creates a new customer on a published loyalty card and returns the card\ntoken used for all other customer endpoints. When the loyalty card\ncollects customer data, the optional `fields` object is keyed by the\nconfigured customer field id. Requires a write key on a Gold plan.", "summary": "Enroll customer", "tags": [ "Customers" ], "parameters": [ { "name": "walletId", "in": "path", "required": true, "description": "Wallet ID shown on the loyalty card overview and API setup page.", "schema": { "type": "string" }, "example": "A7K9Q2" } ], "requestBody": { "content": { "application\/json": { "schema": { "type": "object", "properties": { "fields": { "type": [ "object", "null" ], "description": "Customer data keyed by the configured field identifier. Accepted values depend on the loyalty card field configuration.", "examples": [ { "first_name": "Anna", "email": "anna@example.com" } ], "additionalProperties": { "anyOf": [ { "type": "boolean" }, { "type": "number" }, { "type": "integer" }, { "type": "string" }, { "type": "null" } ] } }, "marketing_consent": { "type": [ "boolean", "null" ], "description": "Whether the customer consented to marketing communication.", "default": false, "examples": [ true ] } } } } } }, "responses": { "201": { "description": "Enroll customer created successfully.", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "message": "Customer enrolled successfully.", "data": { "id": "01JZ8Y7X6W5V4U3T2S1R0Q9P8N", "display_code": "4829", "wallet_id": "A7K9Q2", "stamps_count": 4, "stamps_required": 10, "ready_to_redeem": false, "redemptions_count": 2, "revoked": false, "fields": { "first_name": "Anna", "email": "anna@example.com" }, "marketing_consent": true, "created_at": "2026-07-17T08:30:00Z", "first_stamp_at": "2026-07-17T08:45:00Z", "last_stamp_at": "2026-07-17T09:15:00Z", "last_redemption_at": "2026-07-10T11:20:00Z", "last_activity_at": "2026-07-17T09:15:00Z", "updated_at": "2026-07-17T09:15:00Z" } } ], "properties": { "message": { "type": "string", "description": "Human-readable confirmation that the request completed successfully.", "examples": [ "Customer enrolled successfully." ] }, "data": { "type": "object", "description": "Response payload for the completed request.", "properties": { "id": { "type": "string", "description": "Stable, non-guessable Customer ID used in API paths and encoded in QR, Aztec, and PDF417 pass barcodes.", "examples": [ "01JZ8Y7X6W5V4U3T2S1R0Q9P8N" ] }, "display_code": { "type": "string", "description": "Four-digit Customer code staff can enter manually. Code128 passes encode this value.", "examples": [ "4829" ] }, "wallet_id": { "type": "string", "description": "Wallet ID of the loyalty card this customer belongs to.", "examples": [ "A7K9Q2" ] }, "stamps_count": { "type": "integer", "description": "Customer's current number of stamps.", "examples": [ 4 ] }, "stamps_required": { "type": "integer", "description": "Number of stamps required before the reward can be redeemed.", "examples": [ 10 ] }, "ready_to_redeem": { "type": "boolean", "description": "Whether the customer currently has enough stamps to redeem the reward.", "examples": [ false ] }, "redemptions_count": { "type": "integer", "description": "Total number of rewards this customer has redeemed on this card.", "examples": [ 2 ] }, "revoked": { "type": "boolean", "description": "Whether this customer card has been revoked and can no longer be used.", "examples": [ false ] }, "fields": { "type": "array", "description": "Customer data keyed by the loyalty card's configured field identifiers.", "examples": [ { "first_name": "Anna", "email": "anna@example.com" } ], "items": {} }, "marketing_consent": { "type": "boolean", "description": "Whether the customer consented to marketing communication.", "examples": [ true ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time the customer enrolled, in ISO 8601 format.", "examples": [ "2026-07-17T08:30:00Z" ] }, "first_stamp_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time the customer's first stamp was added, or `null` before the first stamp." }, "last_stamp_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time the customer's most recent stamp was added, or `null` if none exists." }, "last_redemption_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time the customer's most recent reward was redeemed, or `null` if none exists." }, "last_activity_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time of the customer's most recent card activity, in ISO 8601 format." }, "updated_at": { "type": [ "string", "null" ], "description": "Time this customer record was most recently updated, in ISO 8601 format. @format date-time", "examples": [ "2026-07-17T09:15:00Z" ] } }, "required": [ "id", "display_code", "wallet_id", "stamps_count", "stamps_required", "ready_to_redeem", "redemptions_count", "revoked", "fields", "marketing_consent", "created_at", "first_stamp_at", "last_stamp_at", "last_redemption_at", "last_activity_at", "updated_at" ] } }, "required": [ "message", "data" ] } } } }, "422": { "description": "The request body is invalid or the loyalty card cannot enroll customers.", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "The request data is invalid." } } ], "properties": { "error": { "type": "object", "description": "Structured details explaining why the API request failed.", "properties": { "type": { "type": "string", "description": "Broad category of API error." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "type": "object", "description": "Additional structured error details, when available." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "The API key is missing, invalid, or revoked.", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "invalid_request_error", "code": "invalid_api_key", "message": "The API key is invalid or has been revoked." } } ], "properties": { "error": { "type": "object", "description": "Structured details explaining why the API request failed.", "properties": { "type": { "type": "string", "description": "Broad category of API error." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "type": "object", "description": "Additional structured error details, when available." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "The plan or API key does not allow write access.", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "invalid_request_error", "code": "permission_denied", "message": "The API key does not permit this request." } } ], "properties": { "error": { "type": "object", "description": "Structured details explaining why the API request failed.", "properties": { "type": { "type": "string", "description": "Broad category of API error." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "type": "object", "description": "Additional structured error details, when available." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "The loyalty card does not exist or is outside the API key scope.", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The requested resource was not found." } } ], "properties": { "error": { "type": "object", "description": "Structured details explaining why the API request failed.", "properties": { "type": { "type": "string", "description": "Broad category of API error." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "type": "object", "description": "Additional structured error details, when available." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "The API key exceeded its request limit.", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "invalid_request_error", "code": "rate_limit_exceeded", "message": "Too many requests. Please try again later." } } ], "properties": { "error": { "type": "object", "description": "Structured details explaining why the API request failed.", "properties": { "type": { "type": "string", "description": "Broad category of API error." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "type": "object", "description": "Additional structured error details, when available." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "\/wallets\/{walletId}\/customers\/sync": { "get": { "operationId": "v1.customers.sync", "description": "Returns a stable window of customers updated after the supplied timestamp.\nPersist `sync_started_at` after consuming all pages and use it as the next\nsynchronization timestamp.", "summary": "Sync customers", "tags": [ "Customers" ], "parameters": [ { "name": "walletId", "in": "path", "required": true, "description": "Wallet ID shown on the loyalty card overview and API setup page.", "schema": { "type": "string" }, "example": "A7K9Q2" }, { "name": "updated_after", "in": "query", "required": true, "description": "Exclusive ISO 8601 timestamp of the last completed synchronization.", "schema": { "type": "string" }, "example": "2026-07-17T08:30:00Z" }, { "name": "cursor", "in": "query", "description": "Customer id returned as `meta.next_cursor` by the previous synchronization page.", "schema": { "type": [ "integer", "null" ] }, "example": 1240 }, { "name": "limit", "in": "query", "description": "Maximum number of changed customers to return. Defaults to 100 and cannot exceed 250.", "schema": { "type": [ "integer", "null" ], "default": 100 }, "example": 100 } ], "responses": { "200": { "description": "Sync customers completed successfully.", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "message": "Customer synchronization completed successfully.", "data": [ { "id": "01JZ8Y7X6W5V4U3T2S1R0Q9P8N", "display_code": "4829", "wallet_id": "A7K9Q2", "stamps_count": 4, "stamps_required": 10, "ready_to_redeem": false, "redemptions_count": 2, "revoked": false, "fields": { "first_name": "Anna", "email": "anna@example.com" }, "marketing_consent": true, "created_at": "2026-07-17T08:30:00Z", "first_stamp_at": "2026-07-17T08:45:00Z", "last_stamp_at": "2026-07-17T09:15:00Z", "last_redemption_at": "2026-07-10T11:20:00Z", "last_activity_at": "2026-07-17T09:15:00Z", "updated_at": "2026-07-17T09:15:00Z" } ], "meta": { "next_cursor": 1240, "sync_started_at": "2026-07-17T09:20:00Z", "has_more": true } } ], "properties": { "message": { "type": "string", "description": "Human-readable confirmation that the request completed successfully.", "examples": [ "Customer synchronization completed successfully." ] }, "data": { "type": "array", "description": "Response payload for the completed request.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable, non-guessable Customer ID used in API paths and encoded in QR, Aztec, and PDF417 pass barcodes.", "examples": [ "01JZ8Y7X6W5V4U3T2S1R0Q9P8N" ] }, "display_code": { "type": "string", "description": "Four-digit Customer code staff can enter manually. Code128 passes encode this value.", "examples": [ "4829" ] }, "wallet_id": { "type": "string", "description": "Wallet ID of the loyalty card this customer belongs to.", "examples": [ "A7K9Q2" ] }, "stamps_count": { "type": "integer", "description": "Customer's current number of stamps.", "examples": [ 4 ] }, "stamps_required": { "type": "integer", "description": "Number of stamps required before the reward can be redeemed.", "examples": [ 10 ] }, "ready_to_redeem": { "type": "boolean", "description": "Whether the customer currently has enough stamps to redeem the reward.", "examples": [ false ] }, "redemptions_count": { "type": "integer", "description": "Total number of rewards this customer has redeemed on this card.", "examples": [ 2 ] }, "revoked": { "type": "boolean", "description": "Whether this customer card has been revoked and can no longer be used.", "examples": [ false ] }, "fields": { "type": "array", "description": "Customer data keyed by the loyalty card's configured field identifiers.", "examples": [ { "first_name": "Anna", "email": "anna@example.com" } ], "items": {} }, "marketing_consent": { "type": "boolean", "description": "Whether the customer consented to marketing communication.", "examples": [ true ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time the customer enrolled, in ISO 8601 format.", "examples": [ "2026-07-17T08:30:00Z" ] }, "first_stamp_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time the customer's first stamp was added, or `null` before the first stamp." }, "last_stamp_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time the customer's most recent stamp was added, or `null` if none exists." }, "last_redemption_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time the customer's most recent reward was redeemed, or `null` if none exists." }, "last_activity_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time of the customer's most recent card activity, in ISO 8601 format." }, "updated_at": { "type": [ "string", "null" ], "description": "Time this customer record was most recently updated, in ISO 8601 format. @format date-time", "examples": [ "2026-07-17T09:15:00Z" ] } }, "required": [ "id", "display_code", "wallet_id", "stamps_count", "stamps_required", "ready_to_redeem", "redemptions_count", "revoked", "fields", "marketing_consent", "created_at", "first_stamp_at", "last_stamp_at", "last_redemption_at", "last_activity_at", "updated_at" ] } }, "meta": { "type": "object", "description": "Pagination or synchronization metadata for this response.", "properties": { "next_cursor": { "type": [ "integer", "null" ], "description": "Cursor to send with the next request, or `null` when the page is empty.", "examples": [ 1240 ] }, "sync_started_at": { "type": "string", "description": "Server timestamp bounding this synchronization window.", "examples": [ "2026-07-17T09:20:00Z" ] }, "has_more": { "type": "boolean", "description": "Whether another page of records is available.", "examples": [ true ] } }, "required": [ "next_cursor", "sync_started_at", "has_more" ] } }, "required": [ "message", "data", "meta" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/wallets\/{walletId}\/customers\/{customerId}\/activity": { "get": { "operationId": "v1.customers.activity", "description": "Returns the latest stamp and redemption events as one reverse-chronological\ntimeline suitable for a staff application or customer history view.", "summary": "Activity", "tags": [ "Customers" ], "parameters": [ { "name": "walletId", "in": "path", "required": true, "description": "Wallet ID shown on the loyalty card overview and API setup page.", "schema": { "type": "string" }, "example": "A7K9Q2" }, { "name": "customerId", "in": "path", "required": true, "description": "Secure Customer ID shown in the dashboard and encoded in QR, Aztec, or PDF417 pass barcodes.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Activity completed successfully.", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "message": "Customer activity retrieved successfully.", "data": [ { "id": 42, "type": "stamp", "change": 1, "stamps_after": 4, "source": "api", "location_id": 12, "occurred_at": "2026-07-17T09:15:00Z" } ] } ], "properties": { "message": { "type": "string", "description": "Human-readable confirmation that the request completed successfully.", "examples": [ "Customer activity retrieved successfully." ] }, "data": { "type": "array", "description": "Response payload for the requested resource or operation.", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique activity record id. @example 42" }, "type": { "type": "string", "description": "Activity kind. @example \"stamp\"", "const": "stamp" }, "change": { "type": "integer", "description": "Number of stamps added or removed. @example 1" }, "stamps_after": { "type": "integer", "description": "Stamp balance immediately after the activity. @example 7" }, "source": { "type": "string", "description": "System source that created the stamp activity. @example \"api\"" }, "location_id": { "type": [ "integer", "null" ], "description": "Attributed workspace location id, or null. @example 12" }, "occurred_at": { "type": [ "string", "null" ], "description": "Time the activity occurred in ISO 8601 format. @example \"2026-07-17T09:15:00Z\"" } }, "required": [ "id", "type", "change", "stamps_after", "source", "location_id", "occurred_at" ] }, { "type": "string" } ] } } }, "required": [ "message", "data" ] } } } } } } }, "\/wallets\/{walletId}\/customers\/{customerId}": { "get": { "operationId": "v1.customers.show", "description": "Returns the customer's current stamp balance, reward state, and activity\ntimestamps. The token is the value encoded in the pass QR code.", "summary": "Customer", "tags": [ "Customers" ], "parameters": [ { "name": "walletId", "in": "path", "required": true, "description": "Wallet ID shown on the loyalty card overview and API setup page.", "schema": { "type": "string" }, "example": "A7K9Q2" }, { "name": "customerId", "in": "path", "required": true, "description": "Secure Customer ID shown in the dashboard and encoded in QR, Aztec, or PDF417 pass barcodes.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Customer completed successfully.", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "message": "Customer retrieved successfully.", "data": { "id": "01JZ8Y7X6W5V4U3T2S1R0Q9P8N", "display_code": "4829", "wallet_id": "A7K9Q2", "stamps_count": 4, "stamps_required": 10, "ready_to_redeem": false, "redemptions_count": 2, "revoked": false, "fields": { "first_name": "Anna", "email": "anna@example.com" }, "marketing_consent": true, "created_at": "2026-07-17T08:30:00Z", "first_stamp_at": "2026-07-17T08:45:00Z", "last_stamp_at": "2026-07-17T09:15:00Z", "last_redemption_at": "2026-07-10T11:20:00Z", "last_activity_at": "2026-07-17T09:15:00Z", "updated_at": "2026-07-17T09:15:00Z" } } ], "properties": { "message": { "type": "string", "description": "Human-readable confirmation that the request completed successfully.", "examples": [ "Customer retrieved successfully." ] }, "data": { "type": "object", "description": "Response payload for the completed request.", "properties": { "id": { "type": "string", "description": "Stable, non-guessable Customer ID used in API paths and encoded in QR, Aztec, and PDF417 pass barcodes.", "examples": [ "01JZ8Y7X6W5V4U3T2S1R0Q9P8N" ] }, "display_code": { "type": "string", "description": "Four-digit Customer code staff can enter manually. Code128 passes encode this value.", "examples": [ "4829" ] }, "wallet_id": { "type": "string", "description": "Wallet ID of the loyalty card this customer belongs to.", "examples": [ "A7K9Q2" ] }, "stamps_count": { "type": "integer", "description": "Customer's current number of stamps.", "examples": [ 4 ] }, "stamps_required": { "type": "integer", "description": "Number of stamps required before the reward can be redeemed.", "examples": [ 10 ] }, "ready_to_redeem": { "type": "boolean", "description": "Whether the customer currently has enough stamps to redeem the reward.", "examples": [ false ] }, "redemptions_count": { "type": "integer", "description": "Total number of rewards this customer has redeemed on this card.", "examples": [ 2 ] }, "revoked": { "type": "boolean", "description": "Whether this customer card has been revoked and can no longer be used.", "examples": [ false ] }, "fields": { "type": "array", "description": "Customer data keyed by the loyalty card's configured field identifiers.", "examples": [ { "first_name": "Anna", "email": "anna@example.com" } ], "items": {} }, "marketing_consent": { "type": "boolean", "description": "Whether the customer consented to marketing communication.", "examples": [ true ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time the customer enrolled, in ISO 8601 format.", "examples": [ "2026-07-17T08:30:00Z" ] }, "first_stamp_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time the customer's first stamp was added, or `null` before the first stamp." }, "last_stamp_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time the customer's most recent stamp was added, or `null` if none exists." }, "last_redemption_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time the customer's most recent reward was redeemed, or `null` if none exists." }, "last_activity_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time of the customer's most recent card activity, in ISO 8601 format." }, "updated_at": { "type": [ "string", "null" ], "description": "Time this customer record was most recently updated, in ISO 8601 format. @format date-time", "examples": [ "2026-07-17T09:15:00Z" ] } }, "required": [ "id", "display_code", "wallet_id", "stamps_count", "stamps_required", "ready_to_redeem", "redemptions_count", "revoked", "fields", "marketing_consent", "created_at", "first_stamp_at", "last_stamp_at", "last_redemption_at", "last_activity_at", "updated_at" ] } }, "required": [ "message", "data" ] } } } }, "401": { "description": "The API key is missing, invalid, or revoked.", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "invalid_request_error", "code": "invalid_api_key", "message": "The API key is invalid or has been revoked." } } ], "properties": { "error": { "type": "object", "description": "Structured details explaining why the API request failed.", "properties": { "type": { "type": "string", "description": "Broad category of API error." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "type": "object", "description": "Additional structured error details, when available." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "The workspace plan does not include API access.", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "invalid_request_error", "code": "permission_denied", "message": "The API key does not permit this request." } } ], "properties": { "error": { "type": "object", "description": "Structured details explaining why the API request failed.", "properties": { "type": { "type": "string", "description": "Broad category of API error." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "type": "object", "description": "Additional structured error details, when available." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "The loyalty card or customer does not exist, or is outside the API key scope.", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The requested resource was not found." } } ], "properties": { "error": { "type": "object", "description": "Structured details explaining why the API request failed.", "properties": { "type": { "type": "string", "description": "Broad category of API error." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "type": "object", "description": "Additional structured error details, when available." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "The API key exceeded its request limit.", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "invalid_request_error", "code": "rate_limit_exceeded", "message": "Too many requests. Please try again later." } } ], "properties": { "error": { "type": "object", "description": "Structured details explaining why the API request failed.", "properties": { "type": { "type": "string", "description": "Broad category of API error." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "type": "object", "description": "Additional structured error details, when available." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } } } }, "patch": { "operationId": "v1.customers.update", "description": "Replaces the customer's collected field values and marketing consent.", "summary": "Update customer", "tags": [ "Customers" ], "parameters": [ { "name": "walletId", "in": "path", "required": true, "description": "Wallet ID shown on the loyalty card overview and API setup page.", "schema": { "type": "string" }, "example": "A7K9Q2" }, { "name": "customerId", "in": "path", "required": true, "description": "Secure Customer ID shown in the dashboard and encoded in QR, Aztec, or PDF417 pass barcodes.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique value for this API key. Reusing it returns the stored response without updating twice.", "schema": { "type": "string", "maxLength": 120 } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "fields": { "type": "object", "description": "Complete customer data keyed by configured field identifier.", "examples": [ { "first_name": "Anna", "email": "anna@example.com" } ], "additionalProperties": { "anyOf": [ { "type": "boolean" }, { "type": "number" }, { "type": "integer" }, { "type": "string" }, { "type": "null" } ] } }, "marketing_consent": { "type": "boolean", "description": "Whether the customer currently consents to marketing communication.", "examples": [ true ] } }, "required": [ "fields", "marketing_consent" ] } } } }, "responses": { "200": { "description": "Update customer completed successfully.", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "message": "Customer updated successfully.", "data": { "id": "01JZ8Y7X6W5V4U3T2S1R0Q9P8N", "display_code": "4829", "wallet_id": "A7K9Q2", "stamps_count": 4, "stamps_required": 10, "ready_to_redeem": false, "redemptions_count": 2, "revoked": false, "fields": { "first_name": "Anna", "email": "anna@example.com" }, "marketing_consent": true, "created_at": "2026-07-17T08:30:00Z", "first_stamp_at": "2026-07-17T08:45:00Z", "last_stamp_at": "2026-07-17T09:15:00Z", "last_redemption_at": "2026-07-10T11:20:00Z", "last_activity_at": "2026-07-17T09:15:00Z", "updated_at": "2026-07-17T09:15:00Z" } } ], "properties": { "message": { "type": "string", "description": "Human-readable confirmation that the request completed successfully.", "examples": [ "Customer updated successfully." ] }, "data": { "type": "object", "description": "Response payload for the completed request.", "properties": { "id": { "type": "string", "description": "Stable, non-guessable Customer ID used in API paths and encoded in QR, Aztec, and PDF417 pass barcodes.", "examples": [ "01JZ8Y7X6W5V4U3T2S1R0Q9P8N" ] }, "display_code": { "type": "string", "description": "Four-digit Customer code staff can enter manually. Code128 passes encode this value.", "examples": [ "4829" ] }, "wallet_id": { "type": "string", "description": "Wallet ID of the loyalty card this customer belongs to.", "examples": [ "A7K9Q2" ] }, "stamps_count": { "type": "integer", "description": "Customer's current number of stamps.", "examples": [ 4 ] }, "stamps_required": { "type": "integer", "description": "Number of stamps required before the reward can be redeemed.", "examples": [ 10 ] }, "ready_to_redeem": { "type": "boolean", "description": "Whether the customer currently has enough stamps to redeem the reward.", "examples": [ false ] }, "redemptions_count": { "type": "integer", "description": "Total number of rewards this customer has redeemed on this card.", "examples": [ 2 ] }, "revoked": { "type": "boolean", "description": "Whether this customer card has been revoked and can no longer be used.", "examples": [ false ] }, "fields": { "type": "array", "description": "Customer data keyed by the loyalty card's configured field identifiers.", "examples": [ { "first_name": "Anna", "email": "anna@example.com" } ], "items": {} }, "marketing_consent": { "type": "boolean", "description": "Whether the customer consented to marketing communication.", "examples": [ true ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time the customer enrolled, in ISO 8601 format.", "examples": [ "2026-07-17T08:30:00Z" ] }, "first_stamp_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time the customer's first stamp was added, or `null` before the first stamp." }, "last_stamp_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time the customer's most recent stamp was added, or `null` if none exists." }, "last_redemption_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time the customer's most recent reward was redeemed, or `null` if none exists." }, "last_activity_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time of the customer's most recent card activity, in ISO 8601 format." }, "updated_at": { "type": [ "string", "null" ], "description": "Time this customer record was most recently updated, in ISO 8601 format. @format date-time", "examples": [ "2026-07-17T09:15:00Z" ] } }, "required": [ "id", "display_code", "wallet_id", "stamps_count", "stamps_required", "ready_to_redeem", "redemptions_count", "revoked", "fields", "marketing_consent", "created_at", "first_stamp_at", "last_stamp_at", "last_redemption_at", "last_activity_at", "updated_at" ] } }, "required": [ "data", "message" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/wallets\/{walletId}\/customers\/{customerId}\/revoke": { "post": { "operationId": "v1.customers.revoke", "description": "Disables the card so it can no longer collect stamps or redeem rewards.", "summary": "Revoke customer", "tags": [ "Customers" ], "parameters": [ { "name": "walletId", "in": "path", "required": true, "description": "Wallet ID shown on the loyalty card overview and API setup page.", "schema": { "type": "string" }, "example": "A7K9Q2" }, { "name": "customerId", "in": "path", "required": true, "description": "Secure Customer ID shown in the dashboard and encoded in QR, Aztec, or PDF417 pass barcodes.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique value for this API key. Reusing it returns the stored response without revoking twice.", "schema": { "type": "string", "maxLength": 120 } } ], "responses": { "200": { "description": "Revoke customer completed successfully.", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "message": "Customer revoked successfully.", "data": { "id": "01JZ8Y7X6W5V4U3T2S1R0Q9P8N", "display_code": "4829", "wallet_id": "A7K9Q2", "stamps_count": 4, "stamps_required": 10, "ready_to_redeem": false, "redemptions_count": 2, "revoked": true, "fields": { "first_name": "Anna", "email": "anna@example.com" }, "marketing_consent": true, "created_at": "2026-07-17T08:30:00Z", "first_stamp_at": "2026-07-17T08:45:00Z", "last_stamp_at": "2026-07-17T09:15:00Z", "last_redemption_at": "2026-07-10T11:20:00Z", "last_activity_at": "2026-07-17T09:15:00Z", "updated_at": "2026-07-17T09:15:00Z" } } ], "properties": { "message": { "type": "string", "description": "Human-readable confirmation that the request completed successfully.", "examples": [ "Customer revoked successfully." ] }, "data": { "type": "object", "description": "Response payload for the completed request.", "properties": { "id": { "type": "string", "description": "Stable, non-guessable Customer ID used in API paths and encoded in QR, Aztec, and PDF417 pass barcodes.", "examples": [ "01JZ8Y7X6W5V4U3T2S1R0Q9P8N" ] }, "display_code": { "type": "string", "description": "Four-digit Customer code staff can enter manually. Code128 passes encode this value.", "examples": [ "4829" ] }, "wallet_id": { "type": "string", "description": "Wallet ID of the loyalty card this customer belongs to.", "examples": [ "A7K9Q2" ] }, "stamps_count": { "type": "integer", "description": "Customer's current number of stamps.", "examples": [ 4 ] }, "stamps_required": { "type": "integer", "description": "Number of stamps required before the reward can be redeemed.", "examples": [ 10 ] }, "ready_to_redeem": { "type": "boolean", "description": "Whether the customer currently has enough stamps to redeem the reward.", "examples": [ false ] }, "redemptions_count": { "type": "integer", "description": "Total number of rewards this customer has redeemed on this card.", "examples": [ 2 ] }, "revoked": { "type": "boolean", "description": "Whether this customer card has been revoked and can no longer be used.", "examples": [ false ] }, "fields": { "type": "array", "description": "Customer data keyed by the loyalty card's configured field identifiers.", "examples": [ { "first_name": "Anna", "email": "anna@example.com" } ], "items": {} }, "marketing_consent": { "type": "boolean", "description": "Whether the customer consented to marketing communication.", "examples": [ true ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time the customer enrolled, in ISO 8601 format.", "examples": [ "2026-07-17T08:30:00Z" ] }, "first_stamp_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time the customer's first stamp was added, or `null` before the first stamp." }, "last_stamp_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time the customer's most recent stamp was added, or `null` if none exists." }, "last_redemption_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time the customer's most recent reward was redeemed, or `null` if none exists." }, "last_activity_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time of the customer's most recent card activity, in ISO 8601 format." }, "updated_at": { "type": [ "string", "null" ], "description": "Time this customer record was most recently updated, in ISO 8601 format. @format date-time", "examples": [ "2026-07-17T09:15:00Z" ] } }, "required": [ "id", "display_code", "wallet_id", "stamps_count", "stamps_required", "ready_to_redeem", "redemptions_count", "revoked", "fields", "marketing_consent", "created_at", "first_stamp_at", "last_stamp_at", "last_redemption_at", "last_activity_at", "updated_at" ] } }, "required": [ "data", "message" ] } } } } } } }, "\/wallets\/{walletId}\/customers\/{customerId}\/restore": { "post": { "operationId": "v1.customers.restore", "description": "Reactivates a previously revoked card while preserving its stamp balance.", "summary": "Restore customer", "tags": [ "Customers" ], "parameters": [ { "name": "walletId", "in": "path", "required": true, "description": "Wallet ID shown on the loyalty card overview and API setup page.", "schema": { "type": "string" }, "example": "A7K9Q2" }, { "name": "customerId", "in": "path", "required": true, "description": "Secure Customer ID shown in the dashboard and encoded in QR, Aztec, or PDF417 pass barcodes.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique value for this API key. Reusing it returns the stored response without restoring twice.", "schema": { "type": "string", "maxLength": 120 } } ], "responses": { "200": { "description": "Restore customer completed successfully.", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "message": "Customer restored successfully.", "data": { "id": "01JZ8Y7X6W5V4U3T2S1R0Q9P8N", "display_code": "4829", "wallet_id": "A7K9Q2", "stamps_count": 4, "stamps_required": 10, "ready_to_redeem": false, "redemptions_count": 2, "revoked": false, "fields": { "first_name": "Anna", "email": "anna@example.com" }, "marketing_consent": true, "created_at": "2026-07-17T08:30:00Z", "first_stamp_at": "2026-07-17T08:45:00Z", "last_stamp_at": "2026-07-17T09:15:00Z", "last_redemption_at": "2026-07-10T11:20:00Z", "last_activity_at": "2026-07-17T09:15:00Z", "updated_at": "2026-07-17T09:15:00Z" } } ], "properties": { "message": { "type": "string", "description": "Human-readable confirmation that the request completed successfully.", "examples": [ "Customer restored successfully." ] }, "data": { "type": "object", "description": "Response payload for the completed request.", "properties": { "id": { "type": "string", "description": "Stable, non-guessable Customer ID used in API paths and encoded in QR, Aztec, and PDF417 pass barcodes.", "examples": [ "01JZ8Y7X6W5V4U3T2S1R0Q9P8N" ] }, "display_code": { "type": "string", "description": "Four-digit Customer code staff can enter manually. Code128 passes encode this value.", "examples": [ "4829" ] }, "wallet_id": { "type": "string", "description": "Wallet ID of the loyalty card this customer belongs to.", "examples": [ "A7K9Q2" ] }, "stamps_count": { "type": "integer", "description": "Customer's current number of stamps.", "examples": [ 4 ] }, "stamps_required": { "type": "integer", "description": "Number of stamps required before the reward can be redeemed.", "examples": [ 10 ] }, "ready_to_redeem": { "type": "boolean", "description": "Whether the customer currently has enough stamps to redeem the reward.", "examples": [ false ] }, "redemptions_count": { "type": "integer", "description": "Total number of rewards this customer has redeemed on this card.", "examples": [ 2 ] }, "revoked": { "type": "boolean", "description": "Whether this customer card has been revoked and can no longer be used.", "examples": [ false ] }, "fields": { "type": "array", "description": "Customer data keyed by the loyalty card's configured field identifiers.", "examples": [ { "first_name": "Anna", "email": "anna@example.com" } ], "items": {} }, "marketing_consent": { "type": "boolean", "description": "Whether the customer consented to marketing communication.", "examples": [ true ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time the customer enrolled, in ISO 8601 format.", "examples": [ "2026-07-17T08:30:00Z" ] }, "first_stamp_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time the customer's first stamp was added, or `null` before the first stamp." }, "last_stamp_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time the customer's most recent stamp was added, or `null` if none exists." }, "last_redemption_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time the customer's most recent reward was redeemed, or `null` if none exists." }, "last_activity_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time of the customer's most recent card activity, in ISO 8601 format." }, "updated_at": { "type": [ "string", "null" ], "description": "Time this customer record was most recently updated, in ISO 8601 format. @format date-time", "examples": [ "2026-07-17T09:15:00Z" ] } }, "required": [ "id", "display_code", "wallet_id", "stamps_count", "stamps_required", "ready_to_redeem", "redemptions_count", "revoked", "fields", "marketing_consent", "created_at", "first_stamp_at", "last_stamp_at", "last_redemption_at", "last_activity_at", "updated_at" ] } }, "required": [ "data", "message" ] } } } } } } }, "\/wallets\/{walletId}\/customers\/{customerId}\/stamps": { "post": { "operationId": "v1.customers.stamps.store", "description": "Adds one or more stamps to the customer's card, clamped to the card's\nremaining capacity. Triggers a Wallet pass update and, when the card\nbecomes full, the reward-ready state. Requires a write key on a Gold plan.", "summary": "Add stamps", "tags": [ "Customers" ], "parameters": [ { "name": "walletId", "in": "path", "required": true, "description": "Wallet ID shown on the loyalty card overview and API setup page.", "schema": { "type": "string" }, "example": "A7K9Q2" }, { "name": "customerId", "in": "path", "required": true, "description": "Secure Customer ID shown in the dashboard and encoded in QR, Aztec, or PDF417 pass barcodes.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique value for this API key, up to 120 characters. Reusing it returns the stored response instead of stamping again.", "schema": { "type": "string", "maxLength": 120 }, "example": "9f2b6c1e-3a90-4a5e-9d1a-2f8f2f6a7b1c" } ], "requestBody": { "content": { "application\/json": { "schema": { "type": "object", "properties": { "quantity": { "type": [ "integer", "null" ], "description": "Number of stamps to add. The applied value is clamped to the remaining card capacity.", "default": 1, "examples": [ 2 ] }, "location_id": { "type": [ "integer", "null" ], "description": "Optional workspace location id used to attribute the transaction.", "examples": [ 12 ] } } } } } }, "responses": { "200": { "description": "Add stamps completed successfully.", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "message": "Stamps added successfully.", "data": { "id": "01JZ8Y7X6W5V4U3T2S1R0Q9P8N", "display_code": "4829", "wallet_id": "A7K9Q2", "stamps_count": 5, "stamps_required": 10, "ready_to_redeem": false, "redemptions_count": 2, "revoked": false, "fields": { "first_name": "Anna", "email": "anna@example.com" }, "marketing_consent": true, "created_at": "2026-07-17T08:30:00Z", "first_stamp_at": "2026-07-17T08:45:00Z", "last_stamp_at": "2026-07-17T09:15:00Z", "last_redemption_at": "2026-07-10T11:20:00Z", "last_activity_at": "2026-07-17T09:15:00Z", "updated_at": "2026-07-17T09:15:00Z" } } ], "properties": { "message": { "type": "string", "description": "Human-readable confirmation that the request completed successfully.", "examples": [ "Stamps added successfully." ] }, "data": { "type": "object", "description": "Response payload for the completed request.", "properties": { "id": { "type": "string", "description": "Stable, non-guessable Customer ID used in API paths and encoded in QR, Aztec, and PDF417 pass barcodes.", "examples": [ "01JZ8Y7X6W5V4U3T2S1R0Q9P8N" ] }, "display_code": { "type": "string", "description": "Four-digit Customer code staff can enter manually. Code128 passes encode this value.", "examples": [ "4829" ] }, "wallet_id": { "type": "string", "description": "Wallet ID of the loyalty card this customer belongs to.", "examples": [ "A7K9Q2" ] }, "stamps_count": { "type": "integer", "description": "Customer's current number of stamps.", "examples": [ 4 ] }, "stamps_required": { "type": "integer", "description": "Number of stamps required before the reward can be redeemed.", "examples": [ 10 ] }, "ready_to_redeem": { "type": "boolean", "description": "Whether the customer currently has enough stamps to redeem the reward.", "examples": [ false ] }, "redemptions_count": { "type": "integer", "description": "Total number of rewards this customer has redeemed on this card.", "examples": [ 2 ] }, "revoked": { "type": "boolean", "description": "Whether this customer card has been revoked and can no longer be used.", "examples": [ false ] }, "fields": { "type": "array", "description": "Customer data keyed by the loyalty card's configured field identifiers.", "examples": [ { "first_name": "Anna", "email": "anna@example.com" } ], "items": {} }, "marketing_consent": { "type": "boolean", "description": "Whether the customer consented to marketing communication.", "examples": [ true ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time the customer enrolled, in ISO 8601 format.", "examples": [ "2026-07-17T08:30:00Z" ] }, "first_stamp_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time the customer's first stamp was added, or `null` before the first stamp." }, "last_stamp_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time the customer's most recent stamp was added, or `null` if none exists." }, "last_redemption_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time the customer's most recent reward was redeemed, or `null` if none exists." }, "last_activity_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time of the customer's most recent card activity, in ISO 8601 format." }, "updated_at": { "type": [ "string", "null" ], "description": "Time this customer record was most recently updated, in ISO 8601 format. @format date-time", "examples": [ "2026-07-17T09:15:00Z" ] } }, "required": [ "id", "display_code", "wallet_id", "stamps_count", "stamps_required", "ready_to_redeem", "redemptions_count", "revoked", "fields", "marketing_consent", "created_at", "first_stamp_at", "last_stamp_at", "last_redemption_at", "last_activity_at", "updated_at" ] } }, "required": [ "data", "message" ] } } } }, "422": { "description": "The request is invalid or the loyalty card is not published.", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "The request data is invalid." } } ], "properties": { "error": { "type": "object", "description": "Structured details explaining why the API request failed.", "properties": { "type": { "type": "string", "description": "Broad category of API error." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "type": "object", "description": "Additional structured error details, when available." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "400": { "description": "The Idempotency-Key header is missing or longer than 120 characters.", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "invalid_request_error", "code": "invalid_request", "message": "The request could not be processed." } } ], "properties": { "error": { "type": "object", "description": "Structured details explaining why the API request failed.", "properties": { "type": { "type": "string", "description": "Broad category of API error." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "type": "object", "description": "Additional structured error details, when available." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "The API key is missing, invalid, or revoked.", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "invalid_request_error", "code": "invalid_api_key", "message": "The API key is invalid or has been revoked." } } ], "properties": { "error": { "type": "object", "description": "Structured details explaining why the API request failed.", "properties": { "type": { "type": "string", "description": "Broad category of API error." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "type": "object", "description": "Additional structured error details, when available." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "The plan or API key does not allow write access.", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "invalid_request_error", "code": "permission_denied", "message": "The API key does not permit this request." } } ], "properties": { "error": { "type": "object", "description": "Structured details explaining why the API request failed.", "properties": { "type": { "type": "string", "description": "Broad category of API error." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "type": "object", "description": "Additional structured error details, when available." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "The loyalty card or customer does not exist, or is outside the API key scope.", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The requested resource was not found." } } ], "properties": { "error": { "type": "object", "description": "Structured details explaining why the API request failed.", "properties": { "type": { "type": "string", "description": "Broad category of API error." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "type": "object", "description": "Additional structured error details, when available." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "Another request with the same idempotency key is still being processed.", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "invalid_request_error", "code": "conflict", "message": "The request conflicts with the current resource state." } } ], "properties": { "error": { "type": "object", "description": "Structured details explaining why the API request failed.", "properties": { "type": { "type": "string", "description": "Broad category of API error." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "type": "object", "description": "Additional structured error details, when available." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "The API key exceeded its request limit.", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "invalid_request_error", "code": "rate_limit_exceeded", "message": "Too many requests. Please try again later." } } ], "properties": { "error": { "type": "object", "description": "Structured details explaining why the API request failed.", "properties": { "type": { "type": "string", "description": "Broad category of API error." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "type": "object", "description": "Additional structured error details, when available." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } } } }, "delete": { "operationId": "v1.customers.stamps.destroy", "description": "Removes one stamp from the customer's card, for example after a correction\nor a refund. Requires a write key on a Gold plan.", "summary": "Remove stamp", "tags": [ "Customers" ], "parameters": [ { "name": "location_id", "in": "query", "schema": { "type": [ "integer", "null" ] } }, { "name": "walletId", "in": "path", "required": true, "description": "Wallet ID shown on the loyalty card overview and API setup page.", "schema": { "type": "string" }, "example": "A7K9Q2" }, { "name": "customerId", "in": "path", "required": true, "description": "Secure Customer ID shown in the dashboard and encoded in QR, Aztec, or PDF417 pass barcodes.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique value for this API key, up to 120 characters. Reusing it returns the stored response instead of removing another stamp.", "schema": { "type": "string", "maxLength": 120 }, "example": "a665cb1f-52f4-4f37-91f8-476c767cc2a0" }, { "name": "location_id", "in": "body", "description": "Optional workspace location id used to attribute the correction.", "schema": { "type": [ "integer", "null" ] }, "example": 12 } ], "responses": { "200": { "description": "Remove stamp completed successfully.", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "message": "Stamp removed successfully.", "data": { "id": "01JZ8Y7X6W5V4U3T2S1R0Q9P8N", "display_code": "4829", "wallet_id": "A7K9Q2", "stamps_count": 3, "stamps_required": 10, "ready_to_redeem": false, "redemptions_count": 2, "revoked": false, "fields": { "first_name": "Anna", "email": "anna@example.com" }, "marketing_consent": true, "created_at": "2026-07-17T08:30:00Z", "first_stamp_at": "2026-07-17T08:45:00Z", "last_stamp_at": "2026-07-17T09:15:00Z", "last_redemption_at": "2026-07-10T11:20:00Z", "last_activity_at": "2026-07-17T09:15:00Z", "updated_at": "2026-07-17T09:15:00Z" } } ], "properties": { "message": { "type": "string", "description": "Human-readable confirmation that the request completed successfully.", "examples": [ "Stamp removed successfully." ] }, "data": { "type": "object", "description": "Response payload for the completed request.", "properties": { "id": { "type": "string", "description": "Stable, non-guessable Customer ID used in API paths and encoded in QR, Aztec, and PDF417 pass barcodes.", "examples": [ "01JZ8Y7X6W5V4U3T2S1R0Q9P8N" ] }, "display_code": { "type": "string", "description": "Four-digit Customer code staff can enter manually. Code128 passes encode this value.", "examples": [ "4829" ] }, "wallet_id": { "type": "string", "description": "Wallet ID of the loyalty card this customer belongs to.", "examples": [ "A7K9Q2" ] }, "stamps_count": { "type": "integer", "description": "Customer's current number of stamps.", "examples": [ 4 ] }, "stamps_required": { "type": "integer", "description": "Number of stamps required before the reward can be redeemed.", "examples": [ 10 ] }, "ready_to_redeem": { "type": "boolean", "description": "Whether the customer currently has enough stamps to redeem the reward.", "examples": [ false ] }, "redemptions_count": { "type": "integer", "description": "Total number of rewards this customer has redeemed on this card.", "examples": [ 2 ] }, "revoked": { "type": "boolean", "description": "Whether this customer card has been revoked and can no longer be used.", "examples": [ false ] }, "fields": { "type": "array", "description": "Customer data keyed by the loyalty card's configured field identifiers.", "examples": [ { "first_name": "Anna", "email": "anna@example.com" } ], "items": {} }, "marketing_consent": { "type": "boolean", "description": "Whether the customer consented to marketing communication.", "examples": [ true ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time the customer enrolled, in ISO 8601 format.", "examples": [ "2026-07-17T08:30:00Z" ] }, "first_stamp_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time the customer's first stamp was added, or `null` before the first stamp." }, "last_stamp_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time the customer's most recent stamp was added, or `null` if none exists." }, "last_redemption_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time the customer's most recent reward was redeemed, or `null` if none exists." }, "last_activity_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time of the customer's most recent card activity, in ISO 8601 format." }, "updated_at": { "type": [ "string", "null" ], "description": "Time this customer record was most recently updated, in ISO 8601 format. @format date-time", "examples": [ "2026-07-17T09:15:00Z" ] } }, "required": [ "id", "display_code", "wallet_id", "stamps_count", "stamps_required", "ready_to_redeem", "redemptions_count", "revoked", "fields", "marketing_consent", "created_at", "first_stamp_at", "last_stamp_at", "last_redemption_at", "last_activity_at", "updated_at" ] } }, "required": [ "data", "message" ] } } } }, "422": { "description": "The loyalty card is not published or the stamp cannot be removed.", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "The request data is invalid." } } ], "properties": { "error": { "type": "object", "description": "Structured details explaining why the API request failed.", "properties": { "type": { "type": "string", "description": "Broad category of API error." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "type": "object", "description": "Additional structured error details, when available." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "400": { "description": "The Idempotency-Key header is missing or longer than 120 characters.", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "invalid_request_error", "code": "invalid_request", "message": "The request could not be processed." } } ], "properties": { "error": { "type": "object", "description": "Structured details explaining why the API request failed.", "properties": { "type": { "type": "string", "description": "Broad category of API error." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "type": "object", "description": "Additional structured error details, when available." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "The API key is missing, invalid, or revoked.", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "invalid_request_error", "code": "invalid_api_key", "message": "The API key is invalid or has been revoked." } } ], "properties": { "error": { "type": "object", "description": "Structured details explaining why the API request failed.", "properties": { "type": { "type": "string", "description": "Broad category of API error." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "type": "object", "description": "Additional structured error details, when available." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "The plan or API key does not allow write access.", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "invalid_request_error", "code": "permission_denied", "message": "The API key does not permit this request." } } ], "properties": { "error": { "type": "object", "description": "Structured details explaining why the API request failed.", "properties": { "type": { "type": "string", "description": "Broad category of API error." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "type": "object", "description": "Additional structured error details, when available." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "The loyalty card or customer does not exist, or is outside the API key scope.", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The requested resource was not found." } } ], "properties": { "error": { "type": "object", "description": "Structured details explaining why the API request failed.", "properties": { "type": { "type": "string", "description": "Broad category of API error." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "type": "object", "description": "Additional structured error details, when available." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "Another request with the same idempotency key is still being processed.", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "invalid_request_error", "code": "conflict", "message": "The request conflicts with the current resource state." } } ], "properties": { "error": { "type": "object", "description": "Structured details explaining why the API request failed.", "properties": { "type": { "type": "string", "description": "Broad category of API error." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "type": "object", "description": "Additional structured error details, when available." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "The API key exceeded its request limit.", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "invalid_request_error", "code": "rate_limit_exceeded", "message": "Too many requests. Please try again later." } } ], "properties": { "error": { "type": "object", "description": "Structured details explaining why the API request failed.", "properties": { "type": { "type": "string", "description": "Broad category of API error." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "type": "object", "description": "Additional structured error details, when available." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "\/wallets\/{walletId}\/customers\/{customerId}\/redeem": { "post": { "operationId": "v1.customers.redeem", "description": "Redeems the customer's reward once the card is full. Depending on the\nloyalty card settings the stamp counter resets for the next round or the\ncard completes. Requires a write key on a Gold plan.", "summary": "Redeem reward", "tags": [ "Customers" ], "parameters": [ { "name": "walletId", "in": "path", "required": true, "description": "Wallet ID shown on the loyalty card overview and API setup page.", "schema": { "type": "string" }, "example": "A7K9Q2" }, { "name": "customerId", "in": "path", "required": true, "description": "Secure Customer ID shown in the dashboard and encoded in QR, Aztec, or PDF417 pass barcodes.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique value for this API key, up to 120 characters. Reusing it returns the stored response instead of redeeming again.", "schema": { "type": "string", "maxLength": 120 }, "example": "7422cf59-0f55-494c-b06f-39ff35fd728a" } ], "requestBody": { "content": { "application\/json": { "schema": { "type": "object", "properties": { "note": { "type": [ "string", "null" ], "description": "Optional internal note stored with the redemption.", "examples": [ "Redeemed at the main counter" ] }, "location_id": { "type": [ "integer", "null" ], "description": "Optional workspace location id used to attribute the redemption.", "examples": [ 12 ] } } } } } }, "responses": { "200": { "description": "Redeem reward completed successfully.", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "message": "Reward redeemed successfully.", "data": { "id": "01JZ8Y7X6W5V4U3T2S1R0Q9P8N", "display_code": "4829", "wallet_id": "A7K9Q2", "stamps_count": 0, "stamps_required": 10, "ready_to_redeem": false, "redemptions_count": 3, "revoked": false, "fields": { "first_name": "Anna", "email": "anna@example.com" }, "marketing_consent": true, "created_at": "2026-07-17T08:30:00Z", "first_stamp_at": "2026-07-17T08:45:00Z", "last_stamp_at": "2026-07-17T09:15:00Z", "last_redemption_at": "2026-07-10T11:20:00Z", "last_activity_at": "2026-07-17T09:15:00Z", "updated_at": "2026-07-17T09:15:00Z" } } ], "properties": { "message": { "type": "string", "description": "Human-readable confirmation that the request completed successfully.", "examples": [ "Reward redeemed successfully." ] }, "data": { "type": "object", "description": "Response payload for the completed request.", "properties": { "id": { "type": "string", "description": "Stable, non-guessable Customer ID used in API paths and encoded in QR, Aztec, and PDF417 pass barcodes.", "examples": [ "01JZ8Y7X6W5V4U3T2S1R0Q9P8N" ] }, "display_code": { "type": "string", "description": "Four-digit Customer code staff can enter manually. Code128 passes encode this value.", "examples": [ "4829" ] }, "wallet_id": { "type": "string", "description": "Wallet ID of the loyalty card this customer belongs to.", "examples": [ "A7K9Q2" ] }, "stamps_count": { "type": "integer", "description": "Customer's current number of stamps.", "examples": [ 4 ] }, "stamps_required": { "type": "integer", "description": "Number of stamps required before the reward can be redeemed.", "examples": [ 10 ] }, "ready_to_redeem": { "type": "boolean", "description": "Whether the customer currently has enough stamps to redeem the reward.", "examples": [ false ] }, "redemptions_count": { "type": "integer", "description": "Total number of rewards this customer has redeemed on this card.", "examples": [ 2 ] }, "revoked": { "type": "boolean", "description": "Whether this customer card has been revoked and can no longer be used.", "examples": [ false ] }, "fields": { "type": "array", "description": "Customer data keyed by the loyalty card's configured field identifiers.", "examples": [ { "first_name": "Anna", "email": "anna@example.com" } ], "items": {} }, "marketing_consent": { "type": "boolean", "description": "Whether the customer consented to marketing communication.", "examples": [ true ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time the customer enrolled, in ISO 8601 format.", "examples": [ "2026-07-17T08:30:00Z" ] }, "first_stamp_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time the customer's first stamp was added, or `null` before the first stamp." }, "last_stamp_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time the customer's most recent stamp was added, or `null` if none exists." }, "last_redemption_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time the customer's most recent reward was redeemed, or `null` if none exists." }, "last_activity_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time of the customer's most recent card activity, in ISO 8601 format." }, "updated_at": { "type": [ "string", "null" ], "description": "Time this customer record was most recently updated, in ISO 8601 format. @format date-time", "examples": [ "2026-07-17T09:15:00Z" ] } }, "required": [ "id", "display_code", "wallet_id", "stamps_count", "stamps_required", "ready_to_redeem", "redemptions_count", "revoked", "fields", "marketing_consent", "created_at", "first_stamp_at", "last_stamp_at", "last_redemption_at", "last_activity_at", "updated_at" ] } }, "required": [ "data", "message" ] } } } }, "422": { "description": "The request is invalid, the card is not published, or the reward is not ready.", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "The request data is invalid." } } ], "properties": { "error": { "type": "object", "description": "Structured details explaining why the API request failed.", "properties": { "type": { "type": "string", "description": "Broad category of API error." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "type": "object", "description": "Additional structured error details, when available." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "400": { "description": "The Idempotency-Key header is missing or longer than 120 characters.", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "invalid_request_error", "code": "invalid_request", "message": "The request could not be processed." } } ], "properties": { "error": { "type": "object", "description": "Structured details explaining why the API request failed.", "properties": { "type": { "type": "string", "description": "Broad category of API error." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "type": "object", "description": "Additional structured error details, when available." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "The API key is missing, invalid, or revoked.", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "invalid_request_error", "code": "invalid_api_key", "message": "The API key is invalid or has been revoked." } } ], "properties": { "error": { "type": "object", "description": "Structured details explaining why the API request failed.", "properties": { "type": { "type": "string", "description": "Broad category of API error." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "type": "object", "description": "Additional structured error details, when available." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "The plan or API key does not allow write access.", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "invalid_request_error", "code": "permission_denied", "message": "The API key does not permit this request." } } ], "properties": { "error": { "type": "object", "description": "Structured details explaining why the API request failed.", "properties": { "type": { "type": "string", "description": "Broad category of API error." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "type": "object", "description": "Additional structured error details, when available." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "The loyalty card or customer does not exist, or is outside the API key scope.", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The requested resource was not found." } } ], "properties": { "error": { "type": "object", "description": "Structured details explaining why the API request failed.", "properties": { "type": { "type": "string", "description": "Broad category of API error." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "type": "object", "description": "Additional structured error details, when available." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "Another request with the same idempotency key is still being processed.", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "invalid_request_error", "code": "conflict", "message": "The request conflicts with the current resource state." } } ], "properties": { "error": { "type": "object", "description": "Structured details explaining why the API request failed.", "properties": { "type": { "type": "string", "description": "Broad category of API error." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "type": "object", "description": "Additional structured error details, when available." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "The API key exceeded its request limit.", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "invalid_request_error", "code": "rate_limit_exceeded", "message": "Too many requests. Please try again later." } } ], "properties": { "error": { "type": "object", "description": "Structured details explaining why the API request failed.", "properties": { "type": { "type": "string", "description": "Broad category of API error." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "type": "object", "description": "Additional structured error details, when available." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "\/webhook-deliveries": { "get": { "operationId": "v1.webhook-deliveries.index", "description": "Returns recent delivery attempts without exposing webhook secrets or full\npayloads. Results are ordered newest first.", "summary": "Deliveries", "tags": [ "Webhook deliveries" ], "parameters": [ { "name": "cursor", "in": "query", "description": "Delivery id returned as `meta.next_cursor` by the previous page.", "schema": { "type": [ "integer", "null" ] }, "example": 980 }, { "name": "limit", "in": "query", "description": "Maximum number of deliveries to return. Defaults to 25 and cannot exceed 100.", "schema": { "type": [ "integer", "null" ], "default": 25 }, "example": 50 }, { "name": "status", "in": "query", "description": "Only return pending, successful, or failed deliveries.", "schema": { "type": [ "string", "null" ] }, "example": "failed" } ], "responses": { "200": { "description": "Deliveries completed successfully.", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "message": "Webhook deliveries retrieved successfully.", "data": [ { "id": 981, "webhook_id": 8, "event": "stamp.added", "status": "success", "attempts": 1, "response_status": 200, "error": null, "created_at": "2026-07-17T09:15:00Z", "delivered_at": "2026-07-17T09:15:02Z" } ], "meta": { "next_cursor": 980, "has_more": true } } ], "properties": { "message": { "type": "string", "description": "Human-readable confirmation that the request completed successfully.", "examples": [ "Webhook deliveries retrieved successfully." ] }, "data": { "type": "array", "description": "Response payload for the requested resource or operation.", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Value returned in the `id` field.", "examples": [ 42 ] }, "webhook_id": { "type": "integer", "description": "Identifier of the configured webhook endpoint.", "examples": [ 8 ] }, "event": { "type": "string", "description": "Webhook event name.", "examples": [ "customer.stamp_added" ] }, "status": { "type": "string", "description": "Current processing status.", "examples": [ "success" ] }, "attempts": { "type": "integer", "description": "Number of delivery attempts made.", "examples": [ 1 ] }, "response_status": { "type": [ "integer", "null" ], "description": "HTTP status returned by the webhook endpoint, or `null`.", "examples": [ 200 ] }, "error": { "type": [ "string", "null" ], "description": "Structured API error details." }, "created_at": { "type": [ "string", "null" ], "description": "Value returned in the `created_at` field.", "examples": [ "2026-07-17T08:30:00Z" ] }, "delivered_at": { "type": [ "string", "null" ], "description": "Time the webhook was delivered successfully, or `null`.", "examples": [ "2026-07-17T09:15:02Z" ] } }, "required": [ "id", "webhook_id", "event", "status", "attempts", "response_status", "error", "created_at", "delivered_at" ] } }, "meta": { "type": "object", "description": "Pagination or synchronization metadata for this response.", "properties": { "next_cursor": { "type": [ "integer", "null" ], "description": "Cursor to send with the next request, or `null` when the page is empty.", "examples": [ 1240 ] }, "has_more": { "type": "boolean", "description": "Whether another page of records is available.", "examples": [ true ] } }, "required": [ "next_cursor", "has_more" ] } }, "required": [ "message", "data", "meta" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/webhook-deliveries\/{delivery}\/retry": { "post": { "operationId": "v1.webhook-deliveries.retry", "description": "Queues a failed delivery again and resets its previous response details.\nPending or successful deliveries cannot be retried.", "summary": "Retry delivery", "tags": [ "Webhook deliveries" ], "parameters": [ { "name": "delivery", "in": "path", "required": true, "description": "Numeric id of a failed webhook delivery owned by the workspace.", "schema": { "type": "integer" }, "example": 981 } ], "responses": { "202": { "description": "Retry delivery accepted for processing.", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "message": "Webhook delivery queued for retry.", "data": { "id": 981, "webhook_id": 8, "event": "stamp.added", "status": "pending", "attempts": 0, "response_status": null, "error": null, "created_at": "2026-07-17T09:15:00Z", "delivered_at": null } } ], "properties": { "message": { "type": "string", "description": "Human-readable confirmation that the request completed successfully.", "examples": [ "Webhook delivery queued for retry." ] }, "data": { "type": "object", "description": "Response payload for the requested resource or operation.", "properties": { "id": { "type": "integer", "description": "Value returned in the `id` field.", "examples": [ 42 ] }, "webhook_id": { "type": "integer", "description": "Identifier of the configured webhook endpoint.", "examples": [ 8 ] }, "event": { "type": "string", "description": "Webhook event name.", "examples": [ "customer.stamp_added" ] }, "status": { "type": "string", "description": "Current processing status.", "examples": [ "success" ] }, "attempts": { "type": "integer", "description": "Number of delivery attempts made.", "examples": [ 1 ] }, "response_status": { "type": [ "integer", "null" ], "description": "HTTP status returned by the webhook endpoint, or `null`.", "examples": [ 200 ] }, "error": { "type": [ "string", "null" ], "description": "Structured API error details." }, "created_at": { "type": [ "string", "null" ], "description": "Value returned in the `created_at` field.", "examples": [ "2026-07-17T08:30:00Z" ] }, "delivered_at": { "type": [ "string", "null" ], "description": "Time the webhook was delivered successfully, or `null`.", "examples": [ "2026-07-17T09:15:02Z" ] } }, "required": [ "id", "webhook_id", "event", "status", "attempts", "response_status", "error", "created_at", "delivered_at" ] } }, "required": [ "message", "data" ] } } } }, "422": { "description": "An error", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "The request data is invalid." } } ], "properties": { "error": { "type": "object", "description": "Structured details explaining why the API request failed.", "properties": { "type": { "type": "string", "description": "Broad category of API error." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "type": "object", "description": "Additional structured error details, when available." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" } } } } }, "components": { "securitySchemes": { "http": { "type": "http", "scheme": "bearer" } }, "schemas": { "CustomerResource": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable, non-guessable Customer ID used in API paths and encoded in QR, Aztec, and PDF417 pass barcodes.", "examples": [ "01JZ8Y7X6W5V4U3T2S1R0Q9P8N" ] }, "display_code": { "type": "string", "description": "Four-digit Customer code staff can enter manually. Code128 passes encode this value.", "examples": [ "4829" ] }, "wallet_id": { "type": "string", "description": "Wallet ID of the loyalty card this customer belongs to.", "examples": [ "A7K9Q2" ] }, "stamps_count": { "type": "integer", "description": "Customer's current number of stamps.", "examples": [ 4 ] }, "stamps_required": { "type": "integer", "description": "Number of stamps required before the reward can be redeemed.", "examples": [ 10 ] }, "ready_to_redeem": { "type": "boolean", "description": "Whether the customer currently has enough stamps to redeem the reward.", "examples": [ false ] }, "redemptions_count": { "type": "integer", "description": "Total number of rewards this customer has redeemed on this card.", "examples": [ 2 ] }, "revoked": { "type": "boolean", "description": "Whether this customer card has been revoked and can no longer be used.", "examples": [ false ] }, "fields": { "type": "array", "description": "Customer data keyed by the loyalty card's configured field identifiers.", "examples": [ { "first_name": "Anna", "email": "anna@example.com" } ], "items": {} }, "marketing_consent": { "type": "boolean", "description": "Whether the customer consented to marketing communication.", "examples": [ true ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time the customer enrolled, in ISO 8601 format.", "examples": [ "2026-07-17T08:30:00Z" ] }, "first_stamp_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time the customer's first stamp was added, or `null` before the first stamp." }, "last_stamp_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time the customer's most recent stamp was added, or `null` if none exists." }, "last_redemption_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time the customer's most recent reward was redeemed, or `null` if none exists." }, "last_activity_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time of the customer's most recent card activity, in ISO 8601 format." }, "updated_at": { "type": [ "string", "null" ], "description": "Time this customer record was most recently updated, in ISO 8601 format. @format date-time", "examples": [ "2026-07-17T09:15:00Z" ] } }, "required": [ "id", "display_code", "wallet_id", "stamps_count", "stamps_required", "ready_to_redeem", "redemptions_count", "revoked", "fields", "marketing_consent", "created_at", "first_stamp_at", "last_stamp_at", "last_redemption_at", "last_activity_at", "updated_at" ], "title": "CustomerResource" }, "WalletResource": { "type": "object", "properties": { "id": { "type": "string", "description": "Wallet ID used in API paths.", "examples": [ "A7K9Q2" ] }, "name": { "type": "string", "description": "Display name of the loyalty card.", "examples": [ "Coffee rewards" ] }, "status": { "type": "string", "description": "Current lifecycle status of the loyalty card.", "examples": [ "published" ] }, "stamps_required": { "type": "integer", "description": "Number of stamps required before the reward can be redeemed.", "examples": [ 10 ] }, "reward": { "type": [ "string", "null" ], "description": "Customer-facing description of the reward.", "examples": [ "One free coffee" ] }, "public_url": { "type": "string", "format": "uri", "description": "Public enrollment page for this loyalty card.", "examples": [ "https:\/\/stmpr.io\/card\/A7K9Q2" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time the loyalty card was created, in ISO 8601 format.", "examples": [ "2026-07-17T10:15:30+00:00" ] } }, "required": [ "id", "name", "status", "stamps_required", "reward", "public_url", "created_at" ], "title": "WalletResource" } }, "responses": { "ValidationException": { "description": "Validation error", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "The request data is invalid." } } ], "properties": { "error": { "type": "object", "description": "Structured details explaining why the API request failed.", "properties": { "type": { "type": "string", "description": "Broad category of API error." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "type": "object", "description": "Additional structured error details, when available." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "ModelNotFoundException": { "description": "Not found", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "The requested resource was not found." } } ], "properties": { "error": { "type": "object", "description": "Structured details explaining why the API request failed.", "properties": { "type": { "type": "string", "description": "Broad category of API error." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "details": { "type": "object", "description": "Additional structured error details, when available." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } } } } }