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

Gift Cards

Gift card issuance, balance, and redemption

List gift cards

GET
/api/v1/gift-cards

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Query Parameters

location_id?number

Filter by location ID

include_children?boolean

Include authorized descendants of location_id.

Defaultfalse
location_ids?string

Optional comma-separated subset of the resolved location hierarchy.

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

Filter by status

Value in

  • "active"
  • "redeemed"
  • "expired"
  • "frozen"
  • "cancelled"
code?string

Exact code match (case-insensitive)

loyalty_member_id?number

Filter by loyalty member ID

page?number
Range1 <= value
Default1
limit?number
Range1 <= value <= 1000
Default50
sort?string
Default"created_at"

Value in

  • "created_at"
  • "valid_end_date"
  • "balance_cents"
  • "status"
  • "code"
order?string
Default"DESC"

Value in

  • "ASC"
  • "DESC"

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/v1/gift-cards"
{  "status": "success",  "data": {    "giftCards": [      {        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",        "locationId": 0,        "companyId": 0,        "code": "string",        "status": "active",        "balanceCents": 0,        "initialBalanceCents": 0,        "currency": "string",        "voucherClassification": "enfunktion",        "validStartDate": "2019-08-24T14:15:22Z",        "validEndDate": "2019-08-24T14:15:22Z",        "designId": "033e957b-7b88-4dd7-902f-29ec7b58670b",        "loyaltyMemberId": 0,        "recipientName": "string",        "recipientEmail": "string",        "recipientPhone": "string",        "senderName": "string",        "senderEmail": "string",        "purchaserUserId": 0,        "recipientAddress": {          "property1": "string",          "property2": "string"        },        "emailLanguage": "string",        "personalMessage": "string",        "sourcePurchaseLineItemId": 0,        "createdAt": "2019-08-24T14:15:22Z",        "updatedAt": "2019-08-24T14:15:22Z",        "isInherited": true,        "issuingLocationName": "string"      }    ],    "pagination": {      "page": 0,      "limit": 0,      "total": 0,      "totalPages": 0    }  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

Create gift card

POST
/api/v1/gift-cards

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.

locationId*integer

Location ID

Range1 <= value
companyId?integer

Legacy field; ignored. The issuing location determines card ownership.

Range1 <= value
code?string

Gift card code (cryptographically generated if not provided)

Length1 <= length <= 50
initialBalanceCents*integer

Initial balance in cents

Range1 <= value <= 2147483647
currency?string

Currency code

Default"SEK"
voucherClassification?string

Swedish VAT classification (defaults to location setting)

Value in

  • "enfunktion"
  • "flerfunktion"
validStartDate?string

Start of validity (YYYY-MM-DD; defaults to now)

Formatdate
validEndDate?string

End of validity (YYYY-MM-DD; computed from location defaults if not set)

Formatdate
designId?string

Gift card design template ID

Formatuuid
loyaltyMemberId?number

Loyalty member ID

recipientName?string
recipientEmail?string
Formatemail
recipientPhone?string
Length5 <= length <= 32
senderName?string
senderEmail?string
Formatemail
personalMessage?string
sourcePurchaseLineItemId?number

purchase_line_items.id for idempotency when generating gift cards from purchases

sendEmail?boolean

Send the e-card email to recipientEmail (backoffice flows). POS purchase flow sends automatically via sourcePurchaseLineItemId.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v1/gift-cards" \  -H "Content-Type: application/json" \  -d '{    "locationId": 1,    "initialBalanceCents": 1  }'
{  "status": "success",  "data": {    "giftCard": {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "locationId": 0,      "companyId": 0,      "code": "string",      "status": "active",      "balanceCents": 0,      "initialBalanceCents": 0,      "currency": "string",      "voucherClassification": "enfunktion",      "validStartDate": "2019-08-24T14:15:22Z",      "validEndDate": "2019-08-24T14:15:22Z",      "designId": "033e957b-7b88-4dd7-902f-29ec7b58670b",      "loyaltyMemberId": 0,      "recipientName": "string",      "recipientEmail": "string",      "recipientPhone": "string",      "senderName": "string",      "senderEmail": "string",      "purchaserUserId": 0,      "recipientAddress": {        "property1": "string",        "property2": "string"      },      "emailLanguage": "string",      "personalMessage": "string",      "sourcePurchaseLineItemId": 0,      "createdAt": "2019-08-24T14:15:22Z",      "updatedAt": "2019-08-24T14:15:22Z",      "isInherited": true,      "issuingLocationName": "string"    },    "transaction": {      "id": 0,      "giftCardId": "9c83b4f5-280c-4968-8797-b9fdb3bd911c",      "type": "create",      "amountCents": 0,      "balanceAfterCents": 0,      "referenceType": "string",      "referenceId": "string",      "notes": "string",      "actorType": "string",      "actorId": "string",      "createdAt": "2019-08-24T14:15:22Z"    }  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

Get gift card

GET
/api/v1/gift-cards/{id}

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Path Parameters

id*string

Gift card UUID

Formatuuid

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/v1/gift-cards/497f6eca-6276-4993-bfeb-53cbbbba6f08"
{  "status": "success",  "data": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "locationId": 0,    "companyId": 0,    "code": "string",    "status": "active",    "balanceCents": 0,    "initialBalanceCents": 0,    "currency": "string",    "voucherClassification": "enfunktion",    "validStartDate": "2019-08-24T14:15:22Z",    "validEndDate": "2019-08-24T14:15:22Z",    "designId": "033e957b-7b88-4dd7-902f-29ec7b58670b",    "loyaltyMemberId": 0,    "recipientName": "string",    "recipientEmail": "string",    "recipientPhone": "string",    "senderName": "string",    "senderEmail": "string",    "purchaserUserId": 0,    "recipientAddress": {      "property1": "string",      "property2": "string"    },    "emailLanguage": "string",    "personalMessage": "string",    "sourcePurchaseLineItemId": 0,    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z",    "isInherited": true,    "issuingLocationName": "string",    "transactions": [      {        "id": 0,        "giftCardId": "9c83b4f5-280c-4968-8797-b9fdb3bd911c",        "type": "create",        "amountCents": 0,        "balanceAfterCents": 0,        "referenceType": "string",        "referenceId": "string",        "notes": "string",        "actorType": "string",        "actorId": "string",        "createdAt": "2019-08-24T14:15:22Z"      }    ]  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

Update gift card

PATCH
/api/v1/gift-cards/{id}

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Path Parameters

id*string

Gift card UUID

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

code?string
Match^[A-Za-z0-9-]+$
Length3 <= length <= 50
reason?string
Length3 <= length <= 500
designId?|
Formatuuid
loyaltyMemberId?number|null
recipientName?string|null
recipientEmail?|
Formatemail
recipientPhone?|
Length5 <= length <= 32
recipientAddress?|null
senderName?string|null
senderEmail?|
Formatemail
personalMessage?string|null
emailLanguage?string

Value in

  • "en"
  • "sv"
validEndDate?string
Formatdate

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/api/v1/gift-cards/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Content-Type: application/json" \  -d '{}'
{  "status": "success",  "data": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "locationId": 0,    "companyId": 0,    "code": "string",    "status": "active",    "balanceCents": 0,    "initialBalanceCents": 0,    "currency": "string",    "voucherClassification": "enfunktion",    "validStartDate": "2019-08-24T14:15:22Z",    "validEndDate": "2019-08-24T14:15:22Z",    "designId": "033e957b-7b88-4dd7-902f-29ec7b58670b",    "loyaltyMemberId": 0,    "recipientName": "string",    "recipientEmail": "string",    "recipientPhone": "string",    "senderName": "string",    "senderEmail": "string",    "purchaserUserId": 0,    "recipientAddress": {      "property1": "string",      "property2": "string"    },    "emailLanguage": "string",    "personalMessage": "string",    "sourcePurchaseLineItemId": 0,    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z",    "isInherited": true,    "issuingLocationName": "string"  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

Invalidate gift card

DELETE
/api/v1/gift-cards/{id}

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Path Parameters

id*string
Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

reason*string

Required audit reason

Length3 <= length <= 500

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X DELETE "https://example.com/api/v1/gift-cards/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Content-Type: application/json" \  -d '{    "reason": "string"  }'
{  "status": "success",  "data": {    "giftCard": {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "locationId": 0,      "companyId": 0,      "code": "string",      "status": "active",      "balanceCents": 0,      "initialBalanceCents": 0,      "currency": "string",      "voucherClassification": "enfunktion",      "validStartDate": "2019-08-24T14:15:22Z",      "validEndDate": "2019-08-24T14:15:22Z",      "designId": "033e957b-7b88-4dd7-902f-29ec7b58670b",      "loyaltyMemberId": 0,      "recipientName": "string",      "recipientEmail": "string",      "recipientPhone": "string",      "senderName": "string",      "senderEmail": "string",      "purchaserUserId": 0,      "recipientAddress": {        "property1": "string",        "property2": "string"      },      "emailLanguage": "string",      "personalMessage": "string",      "sourcePurchaseLineItemId": 0,      "createdAt": "2019-08-24T14:15:22Z",      "updatedAt": "2019-08-24T14:15:22Z",      "isInherited": true,      "issuingLocationName": "string"    },    "transaction": {      "id": 0,      "giftCardId": "9c83b4f5-280c-4968-8797-b9fdb3bd911c",      "type": "create",      "amountCents": 0,      "balanceAfterCents": 0,      "referenceType": "string",      "referenceId": "string",      "notes": "string",      "actorType": "string",      "actorId": "string",      "createdAt": "2019-08-24T14:15:22Z"    }  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

Add gift card balance

POST
/api/v1/gift-cards/{id}/add-balance

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Path Parameters

id*string

Gift card UUID

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

amountCents*integer

Amount to add in cents

Range1 <= value <= 2147483647
referenceId?string

Unique client reference for this adjustment

reason*string

Required audit reason

Length3 <= length <= 500
expectedBalanceCents?integer

Reject the operation if the balance no longer matches this value

Range0 <= value <= 2147483647

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v1/gift-cards/497f6eca-6276-4993-bfeb-53cbbbba6f08/add-balance" \  -H "Content-Type: application/json" \  -d '{    "amountCents": 1,    "reason": "string"  }'
{  "status": "success",  "data": {    "giftCard": {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "locationId": 0,      "companyId": 0,      "code": "string",      "status": "active",      "balanceCents": 0,      "initialBalanceCents": 0,      "currency": "string",      "voucherClassification": "enfunktion",      "validStartDate": "2019-08-24T14:15:22Z",      "validEndDate": "2019-08-24T14:15:22Z",      "designId": "033e957b-7b88-4dd7-902f-29ec7b58670b",      "loyaltyMemberId": 0,      "recipientName": "string",      "recipientEmail": "string",      "recipientPhone": "string",      "senderName": "string",      "senderEmail": "string",      "purchaserUserId": 0,      "recipientAddress": {        "property1": "string",        "property2": "string"      },      "emailLanguage": "string",      "personalMessage": "string",      "sourcePurchaseLineItemId": 0,      "createdAt": "2019-08-24T14:15:22Z",      "updatedAt": "2019-08-24T14:15:22Z",      "isInherited": true,      "issuingLocationName": "string"    },    "transaction": {      "id": 0,      "giftCardId": "9c83b4f5-280c-4968-8797-b9fdb3bd911c",      "type": "create",      "amountCents": 0,      "balanceAfterCents": 0,      "referenceType": "string",      "referenceId": "string",      "notes": "string",      "actorType": "string",      "actorId": "string",      "createdAt": "2019-08-24T14:15:22Z"    }  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

Get gift card audit history

GET
/api/v1/gift-cards/{id}/audit

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Path Parameters

id*string
Formatuuid

Query Parameters

page?integer
Range1 <= value
Default1
limit?integer
Range1 <= value <= 100
Default50

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/v1/gift-cards/497f6eca-6276-4993-bfeb-53cbbbba6f08/audit"
{  "status": "string",  "data": {    "events": [      {        "id": "string",        "giftCardId": "string",        "action": "string",        "changes": {},        "actorType": "string",        "actorId": "string",        "actor": {          "name": "string",          "email": "string",          "imageUrl": "string"        },        "requestId": "string",        "reason": "string",        "createdAt": "2019-08-24T14:15:22Z"      }    ],    "pagination": {      "page": 0,      "limit": 0,      "total": 0    }  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

Deduct gift card balance

POST
/api/v1/gift-cards/{id}/deduct

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Path Parameters

id*string

Gift card UUID

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

amountCents*integer

Amount to deduct in cents

Range1 <= value <= 2147483647
referenceId?string

Unique client reference for this adjustment

reason*string

Required audit reason

Length3 <= length <= 500
expectedBalanceCents?integer

Reject the operation if the balance no longer matches this value

Range0 <= value <= 2147483647

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v1/gift-cards/497f6eca-6276-4993-bfeb-53cbbbba6f08/deduct" \  -H "Content-Type: application/json" \  -d '{    "amountCents": 1,    "reason": "string"  }'
{  "status": "success",  "data": {    "giftCard": {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "locationId": 0,      "companyId": 0,      "code": "string",      "status": "active",      "balanceCents": 0,      "initialBalanceCents": 0,      "currency": "string",      "voucherClassification": "enfunktion",      "validStartDate": "2019-08-24T14:15:22Z",      "validEndDate": "2019-08-24T14:15:22Z",      "designId": "033e957b-7b88-4dd7-902f-29ec7b58670b",      "loyaltyMemberId": 0,      "recipientName": "string",      "recipientEmail": "string",      "recipientPhone": "string",      "senderName": "string",      "senderEmail": "string",      "purchaserUserId": 0,      "recipientAddress": {        "property1": "string",        "property2": "string"      },      "emailLanguage": "string",      "personalMessage": "string",      "sourcePurchaseLineItemId": 0,      "createdAt": "2019-08-24T14:15:22Z",      "updatedAt": "2019-08-24T14:15:22Z",      "isInherited": true,      "issuingLocationName": "string"    },    "transaction": {      "id": 0,      "giftCardId": "9c83b4f5-280c-4968-8797-b9fdb3bd911c",      "type": "create",      "amountCents": 0,      "balanceAfterCents": 0,      "referenceType": "string",      "referenceId": "string",      "notes": "string",      "actorType": "string",      "actorId": "string",      "createdAt": "2019-08-24T14:15:22Z"    }  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

Freeze gift card

POST
/api/v1/gift-cards/{id}/freeze

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Path Parameters

id*string
Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

reason*string

Required audit reason

Length3 <= length <= 500

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v1/gift-cards/497f6eca-6276-4993-bfeb-53cbbbba6f08/freeze" \  -H "Content-Type: application/json" \  -d '{    "reason": "string"  }'
{  "status": "success",  "data": {    "giftCard": {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "locationId": 0,      "companyId": 0,      "code": "string",      "status": "active",      "balanceCents": 0,      "initialBalanceCents": 0,      "currency": "string",      "voucherClassification": "enfunktion",      "validStartDate": "2019-08-24T14:15:22Z",      "validEndDate": "2019-08-24T14:15:22Z",      "designId": "033e957b-7b88-4dd7-902f-29ec7b58670b",      "loyaltyMemberId": 0,      "recipientName": "string",      "recipientEmail": "string",      "recipientPhone": "string",      "senderName": "string",      "senderEmail": "string",      "purchaserUserId": 0,      "recipientAddress": {        "property1": "string",        "property2": "string"      },      "emailLanguage": "string",      "personalMessage": "string",      "sourcePurchaseLineItemId": 0,      "createdAt": "2019-08-24T14:15:22Z",      "updatedAt": "2019-08-24T14:15:22Z",      "isInherited": true,      "issuingLocationName": "string"    },    "transaction": {      "id": 0,      "giftCardId": "9c83b4f5-280c-4968-8797-b9fdb3bd911c",      "type": "create",      "amountCents": 0,      "balanceAfterCents": 0,      "referenceType": "string",      "referenceId": "string",      "notes": "string",      "actorType": "string",      "actorId": "string",      "createdAt": "2019-08-24T14:15:22Z"    }  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}
POST
/api/v1/gift-cards/{id}/link-loyalty

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Path Parameters

id*string

Gift card UUID

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

userId*number

User ID of the loyalty member

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v1/gift-cards/497f6eca-6276-4993-bfeb-53cbbbba6f08/link-loyalty" \  -H "Content-Type: application/json" \  -d '{    "userId": 0  }'
{  "status": "success",  "data": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "locationId": 0,    "companyId": 0,    "code": "string",    "status": "active",    "balanceCents": 0,    "initialBalanceCents": 0,    "currency": "string",    "voucherClassification": "enfunktion",    "validStartDate": "2019-08-24T14:15:22Z",    "validEndDate": "2019-08-24T14:15:22Z",    "designId": "033e957b-7b88-4dd7-902f-29ec7b58670b",    "loyaltyMemberId": 0,    "recipientName": "string",    "recipientEmail": "string",    "recipientPhone": "string",    "senderName": "string",    "senderEmail": "string",    "purchaserUserId": 0,    "recipientAddress": {      "property1": "string",      "property2": "string"    },    "emailLanguage": "string",    "personalMessage": "string",    "sourcePurchaseLineItemId": 0,    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z",    "isInherited": true,    "issuingLocationName": "string"  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}
DELETE
/api/v1/gift-cards/{id}/link-loyalty

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Path Parameters

id*string

Gift card UUID

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

userId*number

User ID of the loyalty member to unlink

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X DELETE "https://example.com/api/v1/gift-cards/497f6eca-6276-4993-bfeb-53cbbbba6f08/link-loyalty" \  -H "Content-Type: application/json" \  -d '{    "userId": 0  }'
{  "status": "success",  "data": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "locationId": 0,    "companyId": 0,    "code": "string",    "status": "active",    "balanceCents": 0,    "initialBalanceCents": 0,    "currency": "string",    "voucherClassification": "enfunktion",    "validStartDate": "2019-08-24T14:15:22Z",    "validEndDate": "2019-08-24T14:15:22Z",    "designId": "033e957b-7b88-4dd7-902f-29ec7b58670b",    "loyaltyMemberId": 0,    "recipientName": "string",    "recipientEmail": "string",    "recipientPhone": "string",    "senderName": "string",    "senderEmail": "string",    "purchaserUserId": 0,    "recipientAddress": {      "property1": "string",      "property2": "string"    },    "emailLanguage": "string",    "personalMessage": "string",    "sourcePurchaseLineItemId": 0,    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z",    "isInherited": true,    "issuingLocationName": "string"  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

Resend a gift card email

POST
/api/v1/gift-cards/{id}/resend-email

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Path Parameters

id*string
Formatuuid

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v1/gift-cards/497f6eca-6276-4993-bfeb-53cbbbba6f08/resend-email"
{  "status": "string",  "data": {    "queued": true  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

Get gift card transactions

GET
/api/v1/gift-cards/{id}/transactions

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Path Parameters

id*string

Gift card UUID

Formatuuid

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/v1/gift-cards/497f6eca-6276-4993-bfeb-53cbbbba6f08/transactions"
{  "status": "success",  "data": {    "transactions": [      {        "id": 0,        "giftCardId": "9c83b4f5-280c-4968-8797-b9fdb3bd911c",        "type": "create",        "amountCents": 0,        "balanceAfterCents": 0,        "referenceType": "string",        "referenceId": "string",        "notes": "string",        "actorType": "string",        "actorId": "string",        "createdAt": "2019-08-24T14:15:22Z"      }    ]  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

Unfreeze gift card

POST
/api/v1/gift-cards/{id}/unfreeze

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Path Parameters

id*string
Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

reason*string

Required audit reason

Length3 <= length <= 500

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v1/gift-cards/497f6eca-6276-4993-bfeb-53cbbbba6f08/unfreeze" \  -H "Content-Type: application/json" \  -d '{    "reason": "string"  }'
{  "status": "success",  "data": {    "giftCard": {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "locationId": 0,      "companyId": 0,      "code": "string",      "status": "active",      "balanceCents": 0,      "initialBalanceCents": 0,      "currency": "string",      "voucherClassification": "enfunktion",      "validStartDate": "2019-08-24T14:15:22Z",      "validEndDate": "2019-08-24T14:15:22Z",      "designId": "033e957b-7b88-4dd7-902f-29ec7b58670b",      "loyaltyMemberId": 0,      "recipientName": "string",      "recipientEmail": "string",      "recipientPhone": "string",      "senderName": "string",      "senderEmail": "string",      "purchaserUserId": 0,      "recipientAddress": {        "property1": "string",        "property2": "string"      },      "emailLanguage": "string",      "personalMessage": "string",      "sourcePurchaseLineItemId": 0,      "createdAt": "2019-08-24T14:15:22Z",      "updatedAt": "2019-08-24T14:15:22Z",      "isInherited": true,      "issuingLocationName": "string"    },    "transaction": {      "id": 0,      "giftCardId": "9c83b4f5-280c-4968-8797-b9fdb3bd911c",      "type": "create",      "amountCents": 0,      "balanceAfterCents": 0,      "referenceType": "string",      "referenceId": "string",      "notes": "string",      "actorType": "string",      "actorId": "string",      "createdAt": "2019-08-24T14:15:22Z"    }  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

Get gift card by code

GET
/api/v1/gift-cards/by-code

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Query Parameters

code*string

Gift card code (case-insensitive)

issuerLocationId?integer
Range1 <= value

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/v1/gift-cards/by-code?code=string"
{  "status": "success",  "data": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "locationId": 0,    "companyId": 0,    "code": "string",    "status": "active",    "balanceCents": 0,    "initialBalanceCents": 0,    "currency": "string",    "voucherClassification": "enfunktion",    "validStartDate": "2019-08-24T14:15:22Z",    "validEndDate": "2019-08-24T14:15:22Z",    "designId": "033e957b-7b88-4dd7-902f-29ec7b58670b",    "loyaltyMemberId": 0,    "recipientName": "string",    "recipientEmail": "string",    "recipientPhone": "string",    "senderName": "string",    "senderEmail": "string",    "purchaserUserId": 0,    "recipientAddress": {      "property1": "string",      "property2": "string"    },    "emailLanguage": "string",    "personalMessage": "string",    "sourcePurchaseLineItemId": 0,    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z",    "isInherited": true,    "issuingLocationName": "string"  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

Look up gift card by code

POST
/api/v1/gift-cards/lookup

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.

code*string

Gift card code

Length1 <= length <= 50
issuerLocationId?integer
Range1 <= value

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v1/gift-cards/lookup" \  -H "Content-Type: application/json" \  -d '{    "code": "string"  }'
{  "status": "success",  "data": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "locationId": 0,    "companyId": 0,    "code": "string",    "status": "active",    "balanceCents": 0,    "initialBalanceCents": 0,    "currency": "string",    "voucherClassification": "enfunktion",    "validStartDate": "2019-08-24T14:15:22Z",    "validEndDate": "2019-08-24T14:15:22Z",    "designId": "033e957b-7b88-4dd7-902f-29ec7b58670b",    "loyaltyMemberId": 0,    "recipientName": "string",    "recipientEmail": "string",    "recipientPhone": "string",    "senderName": "string",    "senderEmail": "string",    "purchaserUserId": 0,    "recipientAddress": {      "property1": "string",      "property2": "string"    },    "emailLanguage": "string",    "personalMessage": "string",    "sourcePurchaseLineItemId": 0,    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z",    "isInherited": true,    "issuingLocationName": "string",    "transactions": [      {        "id": 0,        "giftCardId": "9c83b4f5-280c-4968-8797-b9fdb3bd911c",        "type": "create",        "amountCents": 0,        "balanceAfterCents": 0,        "referenceType": "string",        "referenceId": "string",        "notes": "string",        "actorType": "string",        "actorId": "string",        "createdAt": "2019-08-24T14:15:22Z"      }    ]  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

/api/v1/gift-cards/redeemable-issuers

POST
/api/v1/gift-cards/redeemable-issuers

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.

code*string
Length1 <= length <= 50
locationId*integer
Range1 <= value

Response Body

curl -X POST "https://example.com/api/v1/gift-cards/redeemable-issuers" \  -H "Content-Type: application/json" \  -d '{    "code": "string",    "locationId": 1  }'
Empty

Get gift card settings

GET
/api/v1/gift-cards/settings

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Query Parameters

locationId?number

Overrides the X-Location-Id header

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/v1/gift-cards/settings"
{  "status": "success",  "data": {    "locationId": 0,    "voucherClassification": "enfunktion",    "giftCardDefaultValidityDays": 0,    "giftCardLiabilityAccount": "string",    "giftCardDeliveryFeeAccount": "string",    "giftCardPhysicalFeeAccount": "string"  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

Update gift card settings

PUT
/api/v1/gift-cards/settings

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.

locationId?number

Overrides the X-Location-Id header

voucherClassification?string

Value in

  • "enfunktion"
  • "flerfunktion"
giftCardDefaultValidityDays?integer
Range1 <= value <= 7300
giftCardDeliveryFeeAccount?string
Match^[1-9][0-9]{3}$
giftCardPhysicalFeeAccount?string
Match^[1-9][0-9]{3}$

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PUT "https://example.com/api/v1/gift-cards/settings" \  -H "Content-Type: application/json" \  -d '{}'
{  "status": "success",  "data": {    "locationId": 0,    "voucherClassification": "enfunktion",    "giftCardDefaultValidityDays": 0,    "giftCardLiabilityAccount": "string",    "giftCardDeliveryFeeAccount": "string",    "giftCardPhysicalFeeAccount": "string"  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

Get gift card portfolio statistics

GET
/api/v1/gift-cards/stats

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Query Parameters

location_id?number

Location ID; defaults to X-Location-Id

include_children?boolean

Include authorized descendants of location_id.

Defaultfalse
location_ids?string

Optional comma-separated subset of the resolved location hierarchy.

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

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/v1/gift-cards/stats"
{  "status": "success",  "data": {    "totalLiabilityCents": 0,    "totalCards": 0,    "activeCards": 0,    "fullyRedeemedCards": 0,    "expiredCards": 0,    "totalIssuedCents": 0,    "totalRedeemedCents": 0,    "totalRefilledCents": 0,    "totalExpiredCents": 0,    "avgBalanceCents": 0,    "avgInitialValueCents": 0,    "redemptionRate": 0,    "expiredRate": 0,    "expiring": {      "days30": {        "count": 0,        "valueCents": 0      },      "days90": {        "count": 0,        "valueCents": 0      },      "days365": {        "count": 0,        "valueCents": 0      }    },    "last30Days": {      "cardsCreated": 0,      "cardsRedeemed": 0,      "issuedCents": 0,      "redeemedCents": 0    },    "monthlyFlow": [      {        "month": "string",        "issuedCents": 0,        "redeemedCents": 0,        "expiredCents": 0      }    ]  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

Validate gift card for payment

POST
/api/v1/gift-cards/validate

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.

code*string

Gift card code

locationId*number

Location ID for context

issuerLocationId?integer
Range1 <= value

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v1/gift-cards/validate" \  -H "Content-Type: application/json" \  -d '{    "code": "string",    "locationId": 0  }'
{  "status": "success",  "data": {    "valid": true,    "reason": "string",    "giftCard": {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "locationId": 0,      "companyId": 0,      "code": "string",      "status": "active",      "balanceCents": 0,      "initialBalanceCents": 0,      "currency": "string",      "voucherClassification": "enfunktion",      "validStartDate": "2019-08-24T14:15:22Z",      "validEndDate": "2019-08-24T14:15:22Z",      "designId": "033e957b-7b88-4dd7-902f-29ec7b58670b",      "loyaltyMemberId": 0,      "recipientName": "string",      "recipientEmail": "string",      "recipientPhone": "string",      "senderName": "string",      "senderEmail": "string",      "purchaserUserId": 0,      "recipientAddress": {        "property1": "string",        "property2": "string"      },      "emailLanguage": "string",      "personalMessage": "string",      "sourcePurchaseLineItemId": 0,      "createdAt": "2019-08-24T14:15:22Z",      "updatedAt": "2019-08-24T14:15:22Z",      "isInherited": true,      "issuingLocationName": "string"    }  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

Prepaid Types

Prepaid payment categories for externally-paid tabs (e.g. third-party channels)

Purchases

Purchase history, transaction details, and refunds