Vouchers

Server

Download schema

Discount vouchers and promotions

List vouchers

GET

https://common-api.karma.life

/api/v1/vouchers

List all vouchers with optional filters and pagination

Permissions: 🔵 vouchers.read

List vouchers › query Parameters

location_id

number

Filter by location ID

company_id

number

Filter by company ID

voucher_type

string · enum

Filter by voucher type

Enum values:

DISCOUNT_CODE

GIFT_CARD

PROMOTION

LOYALTY_REWARD

CAMPAIGN

REFERRAL

enabled

boolean

Filter by enabled status

is_template

boolean

Filter by template status

code

string

Exact code match

search

string

Search in name or code

include_restrictions

boolean

Include restrictions in response

page

number · min: 1

Default: 1

limit

number · min: 1 · max: 1000

Default: 50

sort

string

Default: created_at

order

string · enum

Enum values:

ASC

DESC

Default: DESC

List vouchers › Responses

List of vouchers

status

string · enum

Enum values:

success

object

GET/api/v1/vouchers

curl --request GET \
  --url https://common-api.karma.life/api/v1/vouchers

Example Responses

{
  "status": "success",
  "data": {
    "vouchers": [
      {
        "id": 0,
        "locationId": 0,
        "companyId": 0,
        "name": "name",
        "code": "code",
        "enabled": true,
        "voucherType": "DISCOUNT_CODE",
        "balanceMode": "NONE",
        "typeSpecification": {
          "type": "percentage",
          "amountInBasisPoints": 0,
          "amountInCents": 0,
          "freeItemIds": [
            0
          ],
          "freeItemQuantity": 0,
          "freeItemId": 0,
          "targetItemIds": [
            0
          ],
          "fixedPriceCents": 0,
          "formula": {
            "type": "buy_x_get_y",
            "rules": {}
          }
        },
        "maxUses": 0,
        "timesUsed": 0,
        "perUserUses": 0,
        "minOrderAmountCents": 0,
        "maxDiscountAmountCents": 0,
        "initialBalanceCents": 0,
        "remainingBalanceCents": 0,
        "canCombine": true,
        "autoApply": true,
        "validFrom": "2024-08-25T15:00:00Z",
        "validUntil": "2024-08-25T15:00:00Z",
        "displayTitle": "displayTitle",
        "displayDescription": "displayDescription",
        "displayImageUrl": "displayImageUrl",
        "createdAt": "2024-08-25T15:00:00Z",
        "updatedAt": "2024-08-25T15:00:00Z",
        "restrictions": [
          {
            "id": 0,
            "discountId": 0,
            "restrictionType": "INCLUDE_ITEM",
            "entityId": 0,
            "quantity": 0,
            "variantIds": [
              0
            ],
            "createdAt": "2024-08-25T15:00:00Z"
          }
        ],
        "userRestrictions": [
          {
            "id": 0,
            "discountId": 0,
            "restrictionType": "EMAIL",
            "value": "value",
            "createdAt": "2024-08-25T15:00:00Z"
          }
        ]
      }
    ],
    "pagination": {
      "page": 0,
      "limit": 0,
      "total": 0,
      "totalPages": 0
    }
  },
  "meta": {
    "requestId": "requestId",
    "timestamp": "2024-08-25T15:00:00Z",
    "executionTimeMs": 0
  }
}

json

application/json

Create voucher

POST

https://common-api.karma.life

/api/v1/vouchers

Create a new voucher with optional restrictions

Permissions: 🟢 vouchers.create

Create voucher › Request Body

name

string · required

Internal voucher name

code

string · required

Voucher code (will be uppercased)

voucherType

string · enum · required

Enum values:

DISCOUNT_CODE

GIFT_CARD

PROMOTION

LOYALTY_REWARD

CAMPAIGN

REFERRAL

object · required

locationId

number

Location ID (required if companyId not set)

companyId

number

Company ID (required if locationId not set)

enabled

boolean

Default: true

balanceMode

string · enum

Enum values:

NONE

DECREMENTAL

Default: NONE

maxUses

number

Total usage limit

perUserUses

number

Per-user usage limit

minOrderAmountCents

number

Minimum order amount in cents

maxDiscountAmountCents

number

Maximum discount cap in cents

initialBalanceCents

number

Initial balance for gift cards

canCombine

boolean

Default: false

autoApply

boolean

Default: false

validFrom

string · date-time

validUntil

string · date-time

displayTitle

string

Guest-facing title

displayDescription

string

Guest-facing description

displayImageUrl

string

Gift card image URL

alwaysVisible

boolean

Show promotion even when requirements not met

Default: false

isTemplate

boolean

Whether this is a template voucher

Default: false

templateVoucherId

number

Parent template voucher ID

object[]

Create voucher › Responses

Voucher created successfully

status

string · enum

Enum values:

success

object

POST/api/v1/vouchers

curl --request POST \
  --url https://common-api.karma.life/api/v1/vouchers \
  --header 'Content-Type: application/json' \
  --data '
{
  "locationId": 0,
  "companyId": 0,
  "name": "name",
  "code": "code",
  "enabled": true,
  "voucherType": "DISCOUNT_CODE",
  "balanceMode": "NONE",
  "typeSpecification": {
    "type": "percentage",
    "amountInBasisPoints": 0,
    "amountInCents": 0,
    "freeItemIds": [
      0
    ],
    "freeItemQuantity": 0,
    "freeItemId": 0,
    "targetItemIds": [
      0
    ],
    "fixedPriceCents": 0,
    "formula": {
      "type": "buy_x_get_y",
      "rules": {}
    }
  },
  "maxUses": 0,
  "perUserUses": 0,
  "minOrderAmountCents": 0,
  "maxDiscountAmountCents": 0,
  "initialBalanceCents": 0,
  "canCombine": false,
  "autoApply": false,
  "validFrom": "2024-08-25T15:00:00Z",
  "validUntil": "2024-08-25T15:00:00Z",
  "displayTitle": "displayTitle",
  "displayDescription": "displayDescription",
  "displayImageUrl": "displayImageUrl",
  "alwaysVisible": false,
  "isTemplate": false,
  "templateVoucherId": 0,
  "restrictions": [
    {
      "restrictionType": "INCLUDE_ITEM",
      "entityId": 0,
      "quantity": 0,
      "variantIds": [
        0
      ]
    }
  ],
  "userRestrictions": [
    {
      "restrictionType": "EMAIL",
      "value": "value"
    }
  ]
}
'

Example Request Body

{
  "locationId": 0,
  "companyId": 0,
  "name": "name",
  "code": "code",
  "enabled": true,
  "voucherType": "DISCOUNT_CODE",
  "balanceMode": "NONE",
  "typeSpecification": {
    "type": "percentage",
    "amountInBasisPoints": 0,
    "amountInCents": 0,
    "freeItemIds": [
      0
    ],
    "freeItemQuantity": 0,
    "freeItemId": 0,
    "targetItemIds": [
      0
    ],
    "fixedPriceCents": 0,
    "formula": {
      "type": "buy_x_get_y",
      "rules": {}
    }
  },
  "maxUses": 0,
  "perUserUses": 0,
  "minOrderAmountCents": 0,
  "maxDiscountAmountCents": 0,
  "initialBalanceCents": 0,
  "canCombine": false,
  "autoApply": false,
  "validFrom": "2024-08-25T15:00:00Z",
  "validUntil": "2024-08-25T15:00:00Z",
  "displayTitle": "displayTitle",
  "displayDescription": "displayDescription",
  "displayImageUrl": "displayImageUrl",
  "alwaysVisible": false,
  "isTemplate": false,
  "templateVoucherId": 0,
  "restrictions": [
    {
      "restrictionType": "INCLUDE_ITEM",
      "entityId": 0,
      "quantity": 0,
      "variantIds": [
        0
      ]
    }
  ],
  "userRestrictions": [
    {
      "restrictionType": "EMAIL",
      "value": "value"
    }
  ]
}

json

Example Responses

{
  "status": "success",
  "data": {
    "id": 0,
    "locationId": 0,
    "companyId": 0,
    "name": "name",
    "code": "code",
    "enabled": true,
    "voucherType": "DISCOUNT_CODE",
    "balanceMode": "NONE",
    "typeSpecification": {
      "type": "percentage",
      "amountInBasisPoints": 0,
      "amountInCents": 0,
      "freeItemIds": [
        0
      ],
      "freeItemQuantity": 0,
      "freeItemId": 0,
      "targetItemIds": [
        0
      ],
      "fixedPriceCents": 0,
      "formula": {
        "type": "buy_x_get_y",
        "rules": {}
      }
    },
    "maxUses": 0,
    "timesUsed": 0,
    "perUserUses": 0,
    "minOrderAmountCents": 0,
    "maxDiscountAmountCents": 0,
    "initialBalanceCents": 0,
    "remainingBalanceCents": 0,
    "canCombine": true,
    "autoApply": true,
    "validFrom": "2024-08-25T15:00:00Z",
    "validUntil": "2024-08-25T15:00:00Z",
    "displayTitle": "displayTitle",
    "displayDescription": "displayDescription",
    "displayImageUrl": "displayImageUrl",
    "createdAt": "2024-08-25T15:00:00Z",
    "updatedAt": "2024-08-25T15:00:00Z",
    "restrictions": [
      {
        "id": 0,
        "discountId": 0,
        "restrictionType": "INCLUDE_ITEM",
        "entityId": 0,
        "quantity": 0,
        "variantIds": [
          0
        ],
        "createdAt": "2024-08-25T15:00:00Z"
      }
    ],
    "userRestrictions": [
      {
        "id": 0,
        "discountId": 0,
        "restrictionType": "EMAIL",
        "value": "value",
        "createdAt": "2024-08-25T15:00:00Z"
      }
    ]
  },
  "meta": {
    "requestId": "requestId",
    "timestamp": "2024-08-25T15:00:00Z",
    "executionTimeMs": 0
  }
}

json

application/json

Get voucher

GET

https://common-api.karma.life

/api/v1/vouchers/{id}

Get single voucher with full details including restrictions and usage statistics

Permissions: 🔵 vouchers.read

Get voucher › path Parameters

id

string · required

Voucher ID

Get voucher › Responses

Voucher details

status

string · enum

Enum values:

success

object

GET/api/v1/vouchers/{id}

curl --request GET \
  --url https://common-api.karma.life/api/v1/vouchers/:id

Example Responses

{
  "status": "success",
  "data": {
    "id": 0,
    "locationId": 0,
    "companyId": 0,
    "name": "name",
    "code": "code",
    "enabled": true,
    "voucherType": "DISCOUNT_CODE",
    "balanceMode": "NONE",
    "typeSpecification": {
      "type": "percentage",
      "amountInBasisPoints": 0,
      "amountInCents": 0,
      "freeItemIds": [
        0
      ],
      "freeItemQuantity": 0,
      "freeItemId": 0,
      "targetItemIds": [
        0
      ],
      "fixedPriceCents": 0,
      "formula": {
        "type": "buy_x_get_y",
        "rules": {}
      }
    },
    "maxUses": 0,
    "timesUsed": 0,
    "perUserUses": 0,
    "minOrderAmountCents": 0,
    "maxDiscountAmountCents": 0,
    "initialBalanceCents": 0,
    "remainingBalanceCents": 0,
    "canCombine": true,
    "autoApply": true,
    "validFrom": "2024-08-25T15:00:00Z",
    "validUntil": "2024-08-25T15:00:00Z",
    "displayTitle": "displayTitle",
    "displayDescription": "displayDescription",
    "displayImageUrl": "displayImageUrl",
    "createdAt": "2024-08-25T15:00:00Z",
    "updatedAt": "2024-08-25T15:00:00Z",
    "restrictions": [
      {
        "id": 0,
        "discountId": 0,
        "restrictionType": "INCLUDE_ITEM",
        "entityId": 0,
        "quantity": 0,
        "variantIds": [
          0
        ],
        "createdAt": "2024-08-25T15:00:00Z"
      }
    ],
    "userRestrictions": [
      {
        "id": 0,
        "discountId": 0,
        "restrictionType": "EMAIL",
        "value": "value",
        "createdAt": "2024-08-25T15:00:00Z"
      }
    ],
    "usageStats": {
      "totalUses": 0,
      "uniqueUsers": 0,
      "totalDiscountedCents": 0,
      "averageDiscountCents": 0
    }
  },
  "meta": {
    "requestId": "requestId",
    "timestamp": "2024-08-25T15:00:00Z",
    "executionTimeMs": 0
  }
}

json

application/json

Update voucher

PUT

https://common-api.karma.life

/api/v1/vouchers/{id}

Update an existing voucher

Permissions: 🟠 vouchers.update

Update voucher › path Parameters

id

string · required

Voucher ID

Update voucher › Request Body

name

string

code

string

enabled

boolean

voucherType

string · enum

Enum values:

DISCOUNT_CODE

GIFT_CARD

PROMOTION

LOYALTY_REWARD

CAMPAIGN

REFERRAL

object

maxUses

number

perUserUses

number

minOrderAmountCents

number

maxDiscountAmountCents

number

canCombine

boolean

autoApply

boolean

displayTitle

string

displayDescription

string

displayImageUrl

string

alwaysVisible

boolean

isTemplate

boolean

templateVoucherId

number

initialBalanceCents

number

remainingBalanceCents

number

balanceMode

string · enum

Enum values:

NONE

DECREMENTAL

validFrom

string

validUntil

string

object[]

Update voucher › Responses

Voucher updated successfully

status

string · enum

Enum values:

success

object

PUT/api/v1/vouchers/{id}

curl --request PUT \
  --url https://common-api.karma.life/api/v1/vouchers/:id \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "name",
  "code": "code",
  "enabled": true,
  "voucherType": "DISCOUNT_CODE",
  "typeSpecification": {
    "type": "percentage",
    "amountInBasisPoints": 0,
    "amountInCents": 0,
    "freeItemIds": [
      0
    ],
    "freeItemQuantity": 0,
    "freeItemId": 0,
    "targetItemIds": [
      0
    ],
    "fixedPriceCents": 0,
    "formula": {
      "type": "buy_x_get_y",
      "rules": {}
    }
  },
  "maxUses": 0,
  "perUserUses": 0,
  "minOrderAmountCents": 0,
  "maxDiscountAmountCents": 0,
  "canCombine": true,
  "autoApply": true,
  "displayTitle": "displayTitle",
  "displayDescription": "displayDescription",
  "displayImageUrl": "displayImageUrl",
  "alwaysVisible": true,
  "isTemplate": true,
  "templateVoucherId": 0,
  "initialBalanceCents": 0,
  "remainingBalanceCents": 0,
  "balanceMode": "NONE",
  "validFrom": "validFrom",
  "validUntil": "validUntil",
  "restrictions": [
    {
      "restrictionType": "INCLUDE_ITEM",
      "entityId": 0,
      "quantity": 0,
      "variantIds": [
        0
      ]
    }
  ],
  "userRestrictions": [
    {
      "restrictionType": "EMAIL",
      "value": "value"
    }
  ]
}
'

Example Request Body

{
  "name": "name",
  "code": "code",
  "enabled": true,
  "voucherType": "DISCOUNT_CODE",
  "typeSpecification": {
    "type": "percentage",
    "amountInBasisPoints": 0,
    "amountInCents": 0,
    "freeItemIds": [
      0
    ],
    "freeItemQuantity": 0,
    "freeItemId": 0,
    "targetItemIds": [
      0
    ],
    "fixedPriceCents": 0,
    "formula": {
      "type": "buy_x_get_y",
      "rules": {}
    }
  },
  "maxUses": 0,
  "perUserUses": 0,
  "minOrderAmountCents": 0,
  "maxDiscountAmountCents": 0,
  "canCombine": true,
  "autoApply": true,
  "displayTitle": "displayTitle",
  "displayDescription": "displayDescription",
  "displayImageUrl": "displayImageUrl",
  "alwaysVisible": true,
  "isTemplate": true,
  "templateVoucherId": 0,
  "initialBalanceCents": 0,
  "remainingBalanceCents": 0,
  "balanceMode": "NONE",
  "validFrom": "validFrom",
  "validUntil": "validUntil",
  "restrictions": [
    {
      "restrictionType": "INCLUDE_ITEM",
      "entityId": 0,
      "quantity": 0,
      "variantIds": [
        0
      ]
    }
  ],
  "userRestrictions": [
    {
      "restrictionType": "EMAIL",
      "value": "value"
    }
  ]
}

json

Example Responses

{
  "status": "success",
  "data": {
    "id": 0,
    "locationId": 0,
    "companyId": 0,
    "name": "name",
    "code": "code",
    "enabled": true,
    "voucherType": "DISCOUNT_CODE",
    "balanceMode": "NONE",
    "typeSpecification": {
      "type": "percentage",
      "amountInBasisPoints": 0,
      "amountInCents": 0,
      "freeItemIds": [
        0
      ],
      "freeItemQuantity": 0,
      "freeItemId": 0,
      "targetItemIds": [
        0
      ],
      "fixedPriceCents": 0,
      "formula": {
        "type": "buy_x_get_y",
        "rules": {}
      }
    },
    "maxUses": 0,
    "timesUsed": 0,
    "perUserUses": 0,
    "minOrderAmountCents": 0,
    "maxDiscountAmountCents": 0,
    "initialBalanceCents": 0,
    "remainingBalanceCents": 0,
    "canCombine": true,
    "autoApply": true,
    "validFrom": "2024-08-25T15:00:00Z",
    "validUntil": "2024-08-25T15:00:00Z",
    "displayTitle": "displayTitle",
    "displayDescription": "displayDescription",
    "displayImageUrl": "displayImageUrl",
    "createdAt": "2024-08-25T15:00:00Z",
    "updatedAt": "2024-08-25T15:00:00Z",
    "restrictions": [
      {
        "id": 0,
        "discountId": 0,
        "restrictionType": "INCLUDE_ITEM",
        "entityId": 0,
        "quantity": 0,
        "variantIds": [
          0
        ],
        "createdAt": "2024-08-25T15:00:00Z"
      }
    ],
    "userRestrictions": [
      {
        "id": 0,
        "discountId": 0,
        "restrictionType": "EMAIL",
        "value": "value",
        "createdAt": "2024-08-25T15:00:00Z"
      }
    ]
  },
  "meta": {
    "requestId": "requestId",
    "timestamp": "2024-08-25T15:00:00Z",
    "executionTimeMs": 0
  }
}

json

application/json

Delete voucher

DELETE

https://common-api.karma.life

/api/v1/vouchers/{id}

Soft delete (disable) a voucher

Permissions: 🔴 vouchers.delete

Delete voucher › path Parameters

id

string · required

Voucher ID

Delete voucher › Responses

Voucher deleted successfully

status

string · enum

Enum values:

success

object

Send voucher email

POST

https://common-api.karma.life

/api/v1/vouchers/{id}/send-email

Send voucher code and QR code via email to a recipient

Permissions: 🟠 vouchers.update

Send voucher email › path Parameters

id

string · required

Voucher ID

Send voucher email › Request Body

email

string · email · required

Recipient email address

personal_message

string

Optional personal message (for gift cards)

Send voucher email › Responses

Email sent successfully

status

string · enum

Enum values:

success

object

Remove applied voucher

DELETE

https://common-api.karma.life

/api/v1/vouchers/applied/{id}

Remove an uncommitted applied voucher from a tab

Remove applied voucher › path Parameters

id

string · required

Applied voucher (tab_voucher) ID

Remove applied voucher › Responses

Voucher removed successfully

status

string · enum

Enum values:

success

object

Apply voucher

POST

https://common-api.karma.life

/api/v1/vouchers/apply

Apply a validated voucher to a tab

Apply voucher › Request Body

codes

string[] · required

Voucher codes to apply

locationId

number · required

Location ID

tabId

string

Tab UUID

kitchenDispatchId

string

Kitchen dispatch UUID

object[]

Items to validate against

userId

number

User ID for tracking

email

string

Email for tracking

phone

string

Phone for tracking

Apply voucher › Responses

Voucher applied successfully

status

string · enum

Enum values:

success

object

POST/api/v1/vouchers/apply

curl --request POST \
  --url https://common-api.karma.life/api/v1/vouchers/apply \
  --header 'Content-Type: application/json' \
  --data '
{
  "codes": [
    "string"
  ],
  "locationId": 0,
  "tabId": "tabId",
  "kitchenDispatchId": "kitchenDispatchId",
  "items": [
    {
      "inventoryItemId": 0,
      "quantity": 0,
      "priceCents": 0,
      "variantIds": [
        0
      ],
      "tagIds": [
        0
      ]
    }
  ],
  "userId": 0,
  "email": "email",
  "phone": "phone"
}
'

Example Request Body

{
  "codes": [
    "string"
  ],
  "locationId": 0,
  "tabId": "tabId",
  "kitchenDispatchId": "kitchenDispatchId",
  "items": [
    {
      "inventoryItemId": 0,
      "quantity": 0,
      "priceCents": 0,
      "variantIds": [
        0
      ],
      "tagIds": [
        0
      ]
    }
  ],
  "userId": 0,
  "email": "email",
  "phone": "phone"
}

json

Example Responses

{
  "status": "success",
  "data": {
    "applied": [
      {
        "code": "code",
        "success": true,
        "reservationId": "reservationId",
        "tabVoucherId": 0,
        "voucherId": 0,
        "discountAmountCents": 0
      }
    ],
    "failed": [
      {
        "code": "code",
        "success": true,
        "error": "error",
        "message": "message"
      }
    ],
    "summary": {
      "totalRequested": 0,
      "successCount": 0,
      "failureCount": 0
    }
  },
  "meta": {
    "requestId": "requestId",
    "timestamp": "2024-08-25T15:00:00Z",
    "executionTimeMs": 0
  }
}

json

application/json

Consume vouchers

POST

https://common-api.karma.life

/api/v1/vouchers/consume

Consume (commit) previously reserved voucher reservations

Consume vouchers › Request Body

reservationIds

string[]

Reservation IDs to consume

tabId

string

Tab UUID

Consume vouchers › Responses

Vouchers consumed successfully

status

string · enum

Enum values:

success

object

Get eligible vouchers

POST

https://common-api.karma.life

/api/v1/vouchers/eligible

Get vouchers eligible for a location/tab. Returns promotions and user-restricted vouchers.

Permissions: 🔵 vouchers.read

Get eligible vouchers › Request Body

locationId

number · required

Location ID (required)

tabId

string

Tab UUID - will fetch user IDs from tab members

userIds

number[]

Direct user IDs to check for user-restricted vouchers

object[]

Cart items. When provided, vouchers are filtered against item/tag/variant/layout restrictions, required items, and minimum order amount — only vouchers that would pass at reservation time are returned.

totalAmountCents

number

Total order amount in cents. Used for min order validation when items array is empty (e.g. tab-level checks).

layoutId

string

Current browsing layout UUID. Used for INCLUDE_LAYOUT/EXCLUDE_LAYOUT restriction filtering at SQL level.

Get eligible vouchers › Responses

List of eligible vouchers

status

string · enum

Enum values:

success

object

POST/api/v1/vouchers/eligible

curl --request POST \
  --url https://common-api.karma.life/api/v1/vouchers/eligible \
  --header 'Content-Type: application/json' \
  --data '
{
  "locationId": 0,
  "tabId": "tabId",
  "userIds": [
    0
  ],
  "items": [
    {
      "item_id": 0,
      "quantity": 0,
      "price_cents": 0,
      "base_price_cents": 0,
      "tags": [
        0
      ],
      "variant_ids": [
        0
      ],
      "layout_id": 0
    }
  ],
  "totalAmountCents": 0,
  "layoutId": "layoutId"
}
'

Example Request Body

{
  "locationId": 0,
  "tabId": "tabId",
  "userIds": [
    0
  ],
  "items": [
    {
      "item_id": 0,
      "quantity": 0,
      "price_cents": 0,
      "base_price_cents": 0,
      "tags": [
        0
      ],
      "variant_ids": [
        0
      ],
      "layout_id": 0
    }
  ],
  "totalAmountCents": 0,
  "layoutId": "layoutId"
}

json

Example Responses

{
  "status": "success",
  "data": {
    "vouchers": [
      {
        "id": 0,
        "code": "code",
        "name": "name",
        "voucherType": "DISCOUNT_CODE",
        "isPromotion": true,
        "isUserVoucher": true,
        "isLoyaltyRestricted": true,
        "alwaysVisible": true,
        "autoApply": true,
        "typeSpecification": {
          "type": "percentage",
          "amountInBasisPoints": 0,
          "amountInCents": 0,
          "freeItemIds": [
            0
          ],
          "freeItemQuantity": 0,
          "freeItemId": 0,
          "targetItemIds": [
            0
          ],
          "fixedPriceCents": 0,
          "formula": {
            "type": "buy_x_get_y",
            "rules": {}
          }
        },
        "displayTitle": "displayTitle",
        "displayDescription": "displayDescription",
        "displayImageUrl": "displayImageUrl",
        "maxDiscountAmountCents": 0,
        "remainingBalanceCents": 0,
        "maxUses": 0,
        "timesUsed": 0,
        "hasUsesLeft": true,
        "restrictions": [
          {
            "type": "INCLUDE_ITEM",
            "entityId": "entityId",
            "quantity": 0
          }
        ]
      }
    ]
  },
  "meta": {
    "requestId": "requestId",
    "timestamp": "2024-08-25T15:00:00Z",
    "executionTimeMs": 0
  }
}

json

application/json

Release vouchers

POST

https://common-api.karma.life

/api/v1/vouchers/release

Release (cancel) previously reserved voucher reservations

Release vouchers › Request Body

reservationIds

string[]

Reservation IDs to release

tabId

string

Tab UUID

Release vouchers › Responses

Vouchers released successfully

status

string · enum

Enum values:

success

object

Get voucher reservations

GET

https://common-api.karma.life

/api/v1/vouchers/reservations

Get active voucher reservations for a tab or kitchen dispatch

Get voucher reservations › query Parameters

tabId

string

Tab UUID

kitchenDispatchId

string

Kitchen dispatch UUID

Get voucher reservations › Responses

List of reservations

status

string · enum

Enum values:

success

object

Search vouchers

GET

https://common-api.karma.life

/api/v1/vouchers/search

Search vouchers by code or name for POS lookup

Search vouchers › query Parameters

q

string · required

Search query (code or name)

location_id

number

Filter by location ID

limit

number · min: 1 · max: 50

Max results to return

Default: 10

Search vouchers › Responses

Matching vouchers

status

string · enum

Enum values:

success

object

GET/api/v1/vouchers/search

curl --request GET \
  --url 'https://common-api.karma.life/api/v1/vouchers/search?q=%3Cstring%3E'

Example Responses

{
  "status": "success",
  "data": {
    "vouchers": [
      {
        "id": 0,
        "locationId": 0,
        "companyId": 0,
        "name": "name",
        "code": "code",
        "enabled": true,
        "voucherType": "DISCOUNT_CODE",
        "balanceMode": "NONE",
        "typeSpecification": {
          "type": "percentage",
          "amountInBasisPoints": 0,
          "amountInCents": 0,
          "freeItemIds": [
            0
          ],
          "freeItemQuantity": 0,
          "freeItemId": 0,
          "targetItemIds": [
            0
          ],
          "fixedPriceCents": 0,
          "formula": {
            "type": "buy_x_get_y",
            "rules": {}
          }
        },
        "maxUses": 0,
        "timesUsed": 0,
        "perUserUses": 0,
        "minOrderAmountCents": 0,
        "maxDiscountAmountCents": 0,
        "initialBalanceCents": 0,
        "remainingBalanceCents": 0,
        "canCombine": true,
        "autoApply": true,
        "validFrom": "2024-08-25T15:00:00Z",
        "validUntil": "2024-08-25T15:00:00Z",
        "displayTitle": "displayTitle",
        "displayDescription": "displayDescription",
        "displayImageUrl": "displayImageUrl",
        "createdAt": "2024-08-25T15:00:00Z",
        "updatedAt": "2024-08-25T15:00:00Z"
      }
    ]
  },
  "meta": {
    "requestId": "requestId",
    "timestamp": "2024-08-25T15:00:00Z",
    "executionTimeMs": 0
  }
}

json

application/json

Validate voucher(s)

POST

https://common-api.karma.life

/api/v1/vouchers/validate

Validate one or more voucher codes against a tab or specific kitchen dispatch items.

Validate voucher(s) › Request Body

codes

string[] · required

Array of voucher codes to validate

locationId

number · required

Location ID

includePromotions

boolean

Include auto-apply promotions for this location

object

Validation context

Validate voucher(s) › Responses

Validation results for all voucher codes

status

string · enum

Enum values:

success

object

POST/api/v1/vouchers/validate

curl --request POST \
  --url https://common-api.karma.life/api/v1/vouchers/validate \
  --header 'Content-Type: application/json' \
  --data '
{
  "codes": [
    "string"
  ],
  "locationId": 0,
  "includePromotions": true,
  "context": {
    "tabId": "tabId",
    "kitchenDispatchItems": [
      "string"
    ],
    "totalAmountCents": 0,
    "items": [
      {
        "inventoryItemId": 0,
        "quantity": 0,
        "priceCents": 0,
        "variantIds": [
          0
        ],
        "tagIds": [
          0
        ]
      }
    ]
  }
}
'

Example Request Body

{
  "codes": [
    "string"
  ],
  "locationId": 0,
  "includePromotions": true,
  "context": {
    "tabId": "tabId",
    "kitchenDispatchItems": [
      "string"
    ],
    "totalAmountCents": 0,
    "items": [
      {
        "inventoryItemId": 0,
        "quantity": 0,
        "priceCents": 0,
        "variantIds": [
          0
        ],
        "tagIds": [
          0
        ]
      }
    ]
  }
}

json

Example Responses

{
  "status": "success",
  "data": {
    "validations": [
      {
        "code": "code",
        "valid": true,
        "error": "error",
        "message": "message",
        "voucher": {
          "id": 0,
          "locationId": 0,
          "companyId": 0,
          "name": "name",
          "code": "code",
          "enabled": true,
          "voucherType": "DISCOUNT_CODE",
          "balanceMode": "NONE",
          "typeSpecification": {
            "type": "percentage",
            "amountInBasisPoints": 0,
            "amountInCents": 0,
            "freeItemIds": [
              0
            ],
            "freeItemQuantity": 0,
            "freeItemId": 0,
            "targetItemIds": [
              0
            ],
            "fixedPriceCents": 0,
            "formula": {
              "type": "buy_x_get_y",
              "rules": {}
            }
          },
          "maxUses": 0,
          "timesUsed": 0,
          "perUserUses": 0,
          "minOrderAmountCents": 0,
          "maxDiscountAmountCents": 0,
          "initialBalanceCents": 0,
          "remainingBalanceCents": 0,
          "canCombine": true,
          "autoApply": true,
          "validFrom": "2024-08-25T15:00:00Z",
          "validUntil": "2024-08-25T15:00:00Z",
          "displayTitle": "displayTitle",
          "displayDescription": "displayDescription",
          "displayImageUrl": "displayImageUrl",
          "createdAt": "2024-08-25T15:00:00Z",
          "updatedAt": "2024-08-25T15:00:00Z"
        },
        "discount": {
          "estimatedDiscountCents": 0,
          "discountType": "discountType"
        },
        "newTotalCents": 0,
        "orderIndex": 0
      }
    ]
  },
  "meta": {
    "requestId": "requestId",
    "timestamp": "2024-08-25T15:00:00Z",
    "executionTimeMs": 0
  }
}

json

application/json

Variant Groups Webhooks