You are viewing a non-production environment — the API surface may differ from production.
Developers
Payments API

Purchases

Purchase history, transaction details, and refunds

/api/v1/purchase/lookup-session/{sessionId}

GET
/api/v1/purchase/lookup-session/{sessionId}

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Path Parameters

sessionId*string

Adyen session ID (psp_request_ref)

Query Parameters

locationId*number

Location ID for permission validation

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/v1/purchase/lookup-session/string?locationId=0"
{  "status": "success",  "data": {    "purchaseIntentId": "7c933f97-ad75-490a-be55-2ca143239cc3",    "locationId": 0  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

/api/v1/purchases

GET
/api/v1/purchases

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Query Parameters

locationId*number

Location ID to filter purchases (required for permissions)

includeChildren?boolean

Include authorized descendants of locationId.

Defaultfalse
locationIds?string

Optional comma-separated subset of the resolved location hierarchy.

Match^[0-9]+(,[0-9]+)*$
Lengthlength <= 11000
startDate?string

Start date for date range filter (ISO 8601)

Formatdate-time
endDate?string

End date for date range filter (ISO 8601)

Formatdate-time
userId?number

Filter by user ID

minAmount?number

Minimum amount in cents

maxAmount?number

Maximum amount in cents

minRefundedAmount?number

Minimum refunded amount in cents

maxRefundedAmount?number

Maximum refunded amount in cents

paymentMethod?string

Filter by payment method

psp?string

Filter by payment provider (comma-separated: adyen, stripe, swish, invoice, prepaid, gift_card)

sourceBrand?string

Filter by payment method brand (comma-separated, case-insensitive)

prepaidType?string

Filter by prepaid type code stored on the payment event (comma-separated)

status?string

Filter by payment status

customerEmail?string

Filter by customer email (partial match)

cardLast4?string

Filter by last 4 digits of the paying card (exact match)

Match^[0-9]{4}$
itemId?number

Filter purchases containing a specific inventory item ID

tableId?string

Filter by table/storefront QR code UUID

tabId?string

Filter by tab UUID

Formatuuid
tabType?string

Filter by tab type (comma-separated: takeaway, over_the_counter, table)

costCenterId?string

Filter by cost center (comma-separated cost center ids). Resolved as COALESCE(tabs.cost_center_id, storefront_qr_codes.cost_center_id) — a tab tag beats the table default — the same rule analytics and the SIE export use.

Match^[0-9]+(,[0-9]+)*$
scopeToUser?boolean

Narrow to the sales credited to the calling staff member. Attribution is per line item — who rang the item in, falling back to the tab's initiator — the same rule the POS sales report uses. There is deliberately no parameter for scoping to another staff member: narrowing is only ever to the caller. Requires a staff (retailer user) token.

Defaultfalse
page?number

Page number for pagination

Range1 <= value
Default1
limit?number

Number of results per page (max 1000, enforced with a 400 error beyond that)

Range1 <= value <= 1000
Default50
cursor?string

Opaque keyset pagination cursor from a previous response's pagination.nextCursor. Recommended over page/offset for locations with a large purchase history, since deep offset pages get progressively more expensive to compute. When provided, page/offset params are ignored and the total count is not computed (pagination.total is omitted).

paginate?string

Pagination mode. 'cursor' opts into keyset pagination: the expensive count query is skipped and pagination.hasMore/nextCursor are returned even on the first page (before any cursor value exists). Defaults to 'offset' (page/total) for backwards compatibility.

Value in

  • "cursor"
  • "offset"

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/v1/purchases?locationId=0"
{  "status": "success",  "data": {    "purchases": [      {        "customFields": [          {            "fieldId": "string",            "key": "string",            "label": "string",            "group": "string",            "type": "string",            "displayValue": "string",            "value": null,            "version": 0,            "status": "string"          }        ],        "metadata": {          "customFields": {}        },        "id": 0,        "locationId": 0,        "userId": 0,        "amount": 0,        "currency": "string",        "paymentMethod": "string",        "paymentProvider": "string",        "status": "string",        "createdAt": "2019-08-24T14:15:22Z",        "updatedAt": "2019-08-24T14:15:22Z",        "tabId": "f4c36190-e358-41c0-b3ad-58e9e89eba63",        "costCenterId": 0,        "costCenterName": "string",        "costCenterCode": "string",        "costCenter": {          "customFields": [            {              "fieldId": "string",              "key": "string",              "label": "string",              "group": "string",              "type": "string",              "displayValue": "string",              "value": null,              "version": 0,              "status": "string"            }          ],          "metadata": {            "customFields": {}          },          "id": 0,          "name": "string",          "code": "string"        },        "servedBy": [          {            "retailerUserId": 0,            "name": "string"          }        ],        "lineItems": [          {            "measurement": {              "unit": "string",              "amountMicros": 0,              "priceQuantityMicros": 0,              "unitPriceCents": 0            },            "id": 0,            "type": "string",            "title": "string",            "quantity": 0,            "quantityCents": 0,            "finalAmountCents": 0,            "totalAmountCents": 0,            "vatRateBasisPoints": 0,            "vatAmountCents": 0,            "totalVatAmountCents": 0,            "appliedTotalDiscountAmountCents": 0,            "articleNo": "string",            "originItemId": 0,            "parentLineItemId": 0,            "kitchenDispatchItemId": "string",            "appliedModifications": [              {}            ],            "channel": "POS",            "isTakeaway": true,            "createdAt": "2019-08-24T14:15:22Z"          }        ]      }    ],    "pagination": {      "page": 1,      "limit": 1,      "total": 0,      "totalPages": 0,      "hasMore": true,      "nextCursor": "string"    }  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

/api/v1/purchases/{id}

GET
/api/v1/purchases/{id}

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Path Parameters

id*string

Purchase ID

Query Parameters

locationId*number

Location ID for permission validation

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/v1/purchases/string?locationId=0"
{  "status": "success",  "data": {    "purchase": {      "customFields": [        {          "fieldId": "string",          "key": "string",          "label": "string",          "group": "string",          "type": "string",          "displayValue": "string",          "value": null,          "version": 0,          "status": "string"        }      ],      "metadata": {        "customFields": {}      },      "id": 0,      "locationId": 0,      "userId": 0,      "amount": 0,      "currency": "string",      "paymentMethod": "string",      "paymentProvider": "string",      "status": "string",      "createdAt": "2019-08-24T14:15:22Z",      "updatedAt": "2019-08-24T14:15:22Z",      "tabId": "f4c36190-e358-41c0-b3ad-58e9e89eba63",      "costCenterId": 0,      "costCenterName": "string",      "costCenterCode": "string",      "costCenter": {        "customFields": [          {            "fieldId": "string",            "key": "string",            "label": "string",            "group": "string",            "type": "string",            "displayValue": "string",            "value": null,            "version": 0,            "status": "string"          }        ],        "metadata": {          "customFields": {}        },        "id": 0,        "name": "string",        "code": "string"      },      "servedBy": [        {          "retailerUserId": 0,          "name": "string"        }      ],      "lineItems": [        {          "measurement": {            "unit": "string",            "amountMicros": 0,            "priceQuantityMicros": 0,            "unitPriceCents": 0          },          "id": 0,          "type": "string",          "title": "string",          "quantity": 0,          "quantityCents": 0,          "finalAmountCents": 0,          "totalAmountCents": 0,          "vatRateBasisPoints": 0,          "vatAmountCents": 0,          "totalVatAmountCents": 0,          "appliedTotalDiscountAmountCents": 0,          "articleNo": "string",          "originItemId": 0,          "parentLineItemId": 0,          "kitchenDispatchItemId": "string",          "appliedModifications": [            {}          ],          "channel": "POS",          "isTakeaway": true,          "createdAt": "2019-08-24T14:15:22Z"        }      ]    }  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

Update purchases custom fields

PATCH
/api/v1/purchases/{id}

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Path Parameters

id*string
Match^[1-9][0-9]*$

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

customFields*array<|>

Optional custom field operations, saved atomically with this record. Omitted values are unchanged; null clears. Use fieldId or a stable key. expectedVersion is optional; supply it to reject conflicting edits.

Itemsitems <= 100

Response Body

application/json

curl -X PATCH "https://example.com/api/v1/purchases/string" \  -H "Content-Type: application/json" \  -d '{    "customFields": [      {}    ]  }'
{  "status": "string",  "data": {    "id": "string",    "locationId": 0,    "customFields": [      {        "fieldId": "string",        "key": "string",        "label": "string",        "group": "string",        "type": "string",        "displayValue": "string",        "value": null,        "version": 0,        "status": "string"      }    ],    "metadata": {      "customFields": {}    }  }}

/api/v1/purchases/{purchaseIntentId}/cash-register/fetch

POST
/api/v1/purchases/{purchaseIntentId}/cash-register/fetch

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Path Parameters

purchaseIntentId*string

Purchase intent UUID

Formatuuid

Query Parameters

locationId*number

Location ID for permission validation

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v1/purchases/497f6eca-6276-4993-bfeb-53cbbbba6f08/cash-register/fetch?locationId=0"
{  "status": "success",  "data": {    "purchaseIntentId": "7c933f97-ad75-490a-be55-2ca143239cc3",    "cashRegister": {      "receiptNumber": 0,      "registerId": "string",      "controlUnit": "string"    }  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

/api/v1/purchases/{purchaseIntentId}/cash-register/register

POST
/api/v1/purchases/{purchaseIntentId}/cash-register/register

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Path Parameters

purchaseIntentId*string

Purchase intent UUID

Formatuuid

Query Parameters

locationId*number

Location ID for permission validation

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v1/purchases/497f6eca-6276-4993-bfeb-53cbbbba6f08/cash-register/register?locationId=0"
{  "status": "success",  "data": {    "purchaseIntentId": "7c933f97-ad75-490a-be55-2ca143239cc3",    "cashRegister": {      "receiptNumber": 0,      "registerId": "string",      "controlUnit": "string"    }  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

/api/v1/purchases/{purchaseIntentId}/connect-customer

POST
/api/v1/purchases/{purchaseIntentId}/connect-customer

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Path Parameters

purchaseIntentId*string

Purchase intent UUID

Formatuuid

Query Parameters

locationId*number

Location ID for permission validation

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

email*string

Customer email address (used to find or create user)

Formatemail
name?string

Customer name (optional, used to update user profile)

phone?string

Customer phone number (optional)

enrollInLoyalty?boolean

Enroll customer in location loyalty program and award retroactive points

customFields?array<|>

Optional custom field operations, saved atomically with this record. Omitted values are unchanged; null clears. Use fieldId or a stable key. expectedVersion is optional; supply it to reject conflicting edits.

Itemsitems <= 100

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v1/purchases/497f6eca-6276-4993-bfeb-53cbbbba6f08/connect-customer?locationId=0" \  -H "Content-Type: application/json" \  -d '{    "email": "user@example.com"  }'
{  "status": "success",  "data": {    "success": true,    "userId": 0,    "isNewUser": true,    "loyaltyEnrolled": true,    "pointsAwarded": 0,    "message": "string"  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

/api/v1/purchases/{purchaseIntentId}/email-receipt

POST
/api/v1/purchases/{purchaseIntentId}/email-receipt

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Path Parameters

purchaseIntentId*string

The purchase intent ID

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

email*string

Email address to send the receipt to

Formatemail

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v1/purchases/497f6eca-6276-4993-bfeb-53cbbbba6f08/email-receipt" \  -H "Content-Type: application/json" \  -d '{    "email": "user@example.com"  }'
{  "status": "success",  "data": {    "purchaseIntentId": "7c933f97-ad75-490a-be55-2ca143239cc3",    "email": "string"  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

/api/v1/purchases/{purchaseIntentId}/order-details

GET
/api/v1/purchases/{purchaseIntentId}/order-details

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Path Parameters

purchaseIntentId*string

Purchase intent UUID

Formatuuid

Query Parameters

locationId*number

Location ID for permission validation

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/v1/purchases/497f6eca-6276-4993-bfeb-53cbbbba6f08/order-details?locationId=0"
{  "status": "success",  "data": {    "orderInfo": {      "orderState": "initial",      "deliveryKind": "takeaway",      "orderNumber": 0,      "tableName": "string",      "paymentFlow": "instant",      "tabId": "f4c36190-e358-41c0-b3ad-58e9e89eba63",      "hasBeenScheduled": true,      "desiredPickupTime": 0,      "phoneNumber": "string"    },    "purchaseInfo": {      "purchasedAtEpochSeconds": 0,      "totalAmountCents": 0,      "serviceFeeCents": 0,      "lineItems": [        {          "measurement": {            "unit": "string",            "amountMicros": 0,            "priceQuantityMicros": 0,            "unitPriceCents": 0          },          "type": "product",          "title": "string",          "amountCents": 0,          "appliedTotalDiscountAmountCents": 0,          "quantity": 0,          "appliedModifications": [            {              "title": "string",              "priceAdjustmentCents": 0            }          ],          "itemId": 0,          "itemType": "string",          "imageUrl": "string"        }      ],      "vatBreakdown": {        "vatPercentage": 0,        "vatAmountCents": 0,        "netAmountCents": 0,        "grossAmountCents": 0      },      "currency": "string"    },    "tabInfo": {      "tabId": "f4c36190-e358-41c0-b3ad-58e9e89eba63",      "remainingAmountCents": 0,      "qrCodeId": "8a619d64-dbe8-4c9d-9490-babe22a53a28"    }  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

/api/v1/purchases/{purchaseIntentId}/receipt

GET
/api/v1/purchases/{purchaseIntentId}/receipt

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Path Parameters

purchaseIntentId*string

Purchase intent UUID

Formatuuid

Query Parameters

locationId*number

Location ID for permission validation

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/v1/purchases/497f6eca-6276-4993-bfeb-53cbbbba6f08/receipt?locationId=0"
{  "status": "success",  "data": {    "purchaseIntentId": "7c933f97-ad75-490a-be55-2ca143239cc3",    "shopLayoutId": "string",    "purchasedAt": "2019-08-24T14:15:22Z",    "currency": "string",    "orderNumber": 0,    "location": {      "name": "string",      "address": "string",      "phone": "string",      "vatId": "string",      "logoUrl": "string",      "storefrontSlug": "string",      "language": "string"    },    "lineItems": [      {        "measurement": {          "unit": "string",          "amountMicros": 0,          "priceQuantityMicros": 0,          "unitPriceCents": 0        },        "type": "product",        "title": "string",        "quantity": 0,        "unitPriceCents": 0,        "totalPriceCents": 0,        "appliedDiscountCents": 0,        "appliedModifications": [          {            "title": "string",            "priceAdjustmentCents": 0          }        ],        "children": [          {            "title": "string",            "quantity": 0,            "unitPriceCents": 0,            "totalPriceCents": 0,            "appliedModifications": [              {                "title": "string",                "priceAdjustmentCents": 0              }            ]          }        ]      }    ],    "subtotalCents": 0,    "totalDiscountCents": 0,    "vatBreakdown": [      {        "rate": 0,        "baseAmountCents": 0,        "vatAmountCents": 0      }    ],    "totalCents": 0,    "serviceFeeCents": 0,    "appliedVouchers": [      {        "code": "string",        "appliedAmountCents": 0      }    ],    "customerEmail": "string",    "paymentMethod": "string",    "paymentBrand": "string",    "paymentLast4": "string",    "tableName": "string",    "deliveryKind": "string",    "cashRegister": {      "receiptNumber": 0,      "registerId": "string",      "controlUnit": "string"    }  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

/api/v1/purchases/{purchaseIntentId}/receipt/print

GET
/api/v1/purchases/{purchaseIntentId}/receipt/print

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Path Parameters

purchaseIntentId*string

Purchase intent UUID

Formatuuid

Query Parameters

locationId*number

Location ID for permission validation

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/v1/purchases/497f6eca-6276-4993-bfeb-53cbbbba6f08/receipt/print?locationId=0"
{  "status": "success",  "data": {    "outputText": [      {        "Text": "string",        "CharacterStyle": "Bold",        "Alignment": "Left",        "EndOfLineFlag": true      }    ],    "qrCode": {      "url": "string"    }  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

/api/v1/purchases/by-intent/{intentId}

GET
/api/v1/purchases/by-intent/{intentId}

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Path Parameters

intentId*string

Purchase intent ID (UUID)

Formatuuid

Query Parameters

locationId*number

Location ID for permission validation

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/v1/purchases/by-intent/497f6eca-6276-4993-bfeb-53cbbbba6f08?locationId=0"
{  "status": "success",  "data": {    "purchase": {      "customFields": [        {          "fieldId": "string",          "key": "string",          "label": "string",          "group": "string",          "type": "string",          "displayValue": "string",          "value": null,          "version": 0,          "status": "string"        }      ],      "metadata": {        "customFields": {}      },      "id": 0,      "locationId": 0,      "userId": 0,      "amount": 0,      "currency": "string",      "paymentMethod": "string",      "paymentProvider": "string",      "status": "string",      "createdAt": "2019-08-24T14:15:22Z",      "updatedAt": "2019-08-24T14:15:22Z",      "tabId": "f4c36190-e358-41c0-b3ad-58e9e89eba63",      "costCenterId": 0,      "costCenterName": "string",      "costCenterCode": "string",      "costCenter": {        "customFields": [          {            "fieldId": "string",            "key": "string",            "label": "string",            "group": "string",            "type": "string",            "displayValue": "string",            "value": null,            "version": 0,            "status": "string"          }        ],        "metadata": {          "customFields": {}        },        "id": 0,        "name": "string",        "code": "string"      },      "servedBy": [        {          "retailerUserId": 0,          "name": "string"        }      ],      "lineItems": [        {          "measurement": {            "unit": "string",            "amountMicros": 0,            "priceQuantityMicros": 0,            "unitPriceCents": 0          },          "id": 0,          "type": "string",          "title": "string",          "quantity": 0,          "quantityCents": 0,          "finalAmountCents": 0,          "totalAmountCents": 0,          "vatRateBasisPoints": 0,          "vatAmountCents": 0,          "totalVatAmountCents": 0,          "appliedTotalDiscountAmountCents": 0,          "articleNo": "string",          "originItemId": 0,          "parentLineItemId": 0,          "kitchenDispatchItemId": "string",          "appliedModifications": [            {}          ],          "channel": "POS",          "isTakeaway": true,          "createdAt": "2019-08-24T14:15:22Z"        }      ]    }  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

List refunds

GET
/api/v1/refunds

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Response Body

curl -X GET "https://example.com/api/v1/refunds"
Empty

Get refund

GET
/api/v1/refunds/{refundId}

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Path Parameters

refundId*string

Response Body

curl -X GET "https://example.com/api/v1/refunds/string"
Empty

/api/v1/refunds/purchase

POST
/api/v1/refunds/purchase

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

refundMode?string

Value in

  • "amount"
  • "products"
idempotencyKey?string
Length8 <= length <= 200
purchaseIntentId*string

UUID of the purchase intent to refund

reason*string

Reason for the refund

Lengthlength <= 500
feeCoveredBy*string

Who covers the transaction fees for this refund

Value in

  • "karma"
  • "seller"
lineItems*array<>

Line items to refund with monetary amounts (amount mode) or quantities in hundredths (products mode)

Items1 <= items

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v1/refunds/purchase" \  -H "Content-Type: application/json" \  -d '{    "purchaseIntentId": "string",    "reason": "string",    "feeCoveredBy": "karma",    "lineItems": [      {        "purchaseLineItemId": 0      }    ]  }'
{  "status": "success",  "data": {    "success": true,    "purchaseRefundId": null,    "message": "string"  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

Gift Cards

Gift card issuance, balance, and redemption

Settlements

Tab settlements and payment groupings