Cliento API reference: Point of sale
Base URL: https://api.cliento.com
The Point of sale APIs let an integration list a location's merchants, and read, import and void gift cards. Points of sale, sales, receipts, payments and invoices are coming soon.
A merchant is the company that sells at a location. Most locations have one. A location has several when independent businesses share it, such as a salon with rented chairs.
Sales, receipts, payments and gift cards belong to a merchant, not directly to the location. The money and the bookkeeping are the merchant's.
Merchants
The Merchants API lists a location's merchants. Use it when a call takes or returns a
merchantId, such as the call that imports a gift card.
A merchant is the company that sells at a location: the company whose name is on the receipt. Most locations have one merchant, the organisation's own company. Everything that is sold belongs to a merchant, not directly to the location.
Some locations have several merchants. In a hair salon with rented chairs, each renter is an independent company. Each is a merchant of its own, with its own point of sale and its own card agreement with the bank.
A gift card is sold by one merchant and redeemed at that merchant's point of sale. A location can choose to accept its merchants' gift cards at each other's points of sale.
A merchant belongs to one location and has an id of the form mer_....
GET /v1/locations/{locationId}/merchants lists them. Where a request takes a merchantId, you
can leave it out when the location has one merchant. With several, a call without it is refused
with merchant_required.
List merchants
GET /v1/locations/{locationId}/merchants
Stability: preview
The merchants of a location, oldest first. Most locations have exactly one. Where a request takes a merchantId, it can be left out when the location has one.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
locationId | path | string | Yes |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | OK | MerchantList |
| default | Any failure. See the Errors section. | Error |
Gift cards
The Gift cards API lets an integration read a location's gift cards, import a card that was sold outside Cliento, and void a card that has not been used. It is meant for a system that sells gift cards somewhere else, such as a web shop, so that they can be redeemed at the point of sale.
A gift card has a balance. A merchant sold the card and owes that balance to the card's holder. The holder pays with the card's code at the merchant's point of sale.
A gift card belongs to one merchant and has an id of the form gft_.... It can be linked to a
customer: a person, a company or a vehicle. Reading needs the scope giftcards:read, and
importing and voiding need giftcards:write.
- An imported card can be redeemed at once. Cliento records no sale and makes no receipt for it.
- Give each card your own
externalReference, such as the order number. Sending the same card again then creates nothing. - A card that has not been used can be voided, for example when its order is refunded.
List gift cards
GET /v1/locations/{locationId}/gift-cards
Scope: giftcards:read
Stability: preview
The location's gift cards, newest first, one page at a time. To read them all, repeat the call with after set to the nextCursor of the previous page until a page has none.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
locationId | path | string | Yes | |
limit | query | integer (int32) | No | Page size, 1 to 200. Default 50. |
after | query | string | No | The nextCursor of the previous page. |
customerId | query | string | No | Only this customer's cards. |
externalReference | query | string | No | Only cards with this external reference. |
code | query | string | No | Only the card with this code. |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | OK | GiftCardList |
| default | Any failure. See the Errors section. | Error |
Get a gift card
GET /v1/locations/{locationId}/gift-cards/{giftCardId}
Scope: giftcards:read
Stability: preview
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
locationId | path | string | Yes | |
giftCardId | path | string | Yes |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | OK | GiftCard |
| default | Any failure. See the Errors section. | Error |
Get a gift card by id
GET /v1/gift-cards/{giftCardId}
Scope: giftcards:read
Stability: preview
The same gift card as under its location, found from its id. For a caller that holds an id and not the location it belongs to. The answer carries locationId.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
giftCardId | path | string | Yes |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | OK | GiftCard |
| default | Any failure. See the Errors section. | Error |
Import a gift card
POST /v1/locations/{locationId}/gift-cards/import
Scope: giftcards:write
Stability: preview
Records a gift card that was sold somewhere else, such as a web shop. Cliento records no sale and makes no receipt for it. The card can be redeemed at the merchant's point of sale at once. Answers 201 for a new card and 200 with the existing card when externalReference was used before, so the call is safe to retry.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
locationId | path | string | Yes | |
Idempotency-Key | header | string | No | A value you make up for this one request, such as a UUID. Send the same value when you retry and the first answer is returned; see Retrying safely. Example: 8e03978e-40d5-43e8-bc93-6894a57f9324. |
Request body: GiftCardImport
Responses
| Status | Description | Body |
|---|---|---|
| 200 | A card with this externalReference already existed. It is returned as it is now; nothing in this request was applied. | GiftCard |
| 201 | The card was created. | GiftCard |
| default | Any failure. See the Errors section. | Error |
Void a gift card
POST /v1/locations/{locationId}/gift-cards/{giftCardId}/void
Scope: giftcards:write
Stability: preview
Cancels a card that has not been used, for example when its web shop order is refunded. A card that has been used, even in part, or is already void is refused with gift_card_already_used.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
locationId | path | string | Yes | |
giftCardId | path | string | Yes | |
Idempotency-Key | header | string | No | A value you make up for this one request, such as a UUID. Send the same value when you retry and the first answer is returned; see Retrying safely. Example: 8e03978e-40d5-43e8-bc93-6894a57f9324. |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | OK | GiftCard |
| default | Any failure. See the Errors section. | Error |
Points of sale
Coming soon. Read a merchant's points of sale: the registers its sales are made at.
Sales
Coming soon. Read what a merchant has sold, line by line, with who sold it and to whom.
Receipts
Coming soon. Read the receipt of a sale or a refund.
Payments
Coming soon. Read how each sale was paid, such as by card or gift card.
Invoices
Coming soon. Read the invoices a merchant has sent its customers and whether they are paid.
Schemas
Error
The body of every non-2xx response.
| Field | Type | Required | Description |
|---|---|---|---|
code | string | Yes | Stable, machine-readable error code. Values today: invalid_request, validation_failed, entity_not_found, duplicate, merchant_required, code_already_used, gift_card_already_used, pin_not_recognised, insufficient_stock, not_allowed, request_in_progress, idempotency_key_reused, unauthenticated, forbidden, account_blocked, rate_limited, route_not_found, method_not_allowed, internal_error. |
details | object of any value | No | Extra detail. For validation_failed, fieldErrors maps each rejected field to the reason. |
message | string | Yes | Human-readable explanation. Not stable; do not parse it. |
GiftCard
A gift card. It belongs to one merchant and is redeemed at that merchant's point of sale, or at another merchant's when the location allows it. Amounts are decimal strings in the location's currency.
| Field | Type | Required | Description |
|---|---|---|---|
accountingType | string | No | How VAT is handled. single_purpose: VAT is charged when the card is sold. multi_purpose: VAT is charged when the card is redeemed. Example: single_purpose. |
beneficiary | string | No | Who the card is for, as free text. Example: Anna Andersson. |
code | string | Yes | What the holder shows or types when paying. Example: K7QX9M2D. |
createdAt | string (date-time) | Yes | Example: 2026-11-17T09:14:03Z. |
currency | string | Yes | ISO 4217 currency code. Example: SEK. |
customerId | string | No | The person, company or vehicle the card is linked to, when it is linked to one. The id's prefix says which. Example: per_2QCtWVSaVO7yCRYBj1zsbA. |
description | string | No | Example: Presentkort. |
externalReference | string | No | Your own id for the card, as sent when it was imported. Example: shopify-5512340001-1. |
id | string | Yes | Gift card id. Example: gft_7Qm2xN0cT1kPz4Wb9LrEaD. |
locationId | string | Yes | Example: loc_4fK9xQ2mLr8TzB1vNc7HdW. |
merchantId | string | No | The merchant the card belongs to. Example: mer_2Rk8sVh3Yq6Nf1Tz0JwUcM. |
note | string | No | A note for staff, shown on the card in Cliento. Example: Web shop order 10042. |
remainingValue | string | Yes | What is left to spend. Example: 500.00. |
soldDate | string (date) | No | The day the card was sold, in the location's time zone. Example: 2026-11-17. |
status | string | Yes | active: usable, nothing spent. partially_redeemed: usable, some spent. redeemed: nothing left. expired: past validUntil. void: cancelled. More values may be added. Example: active. |
updatedAt | string (date-time) | Yes | When it last changed, in UTC. Example: 2026-10-12T09:24:31.512Z. |
validUntil | string (date) | No | The last day the card can be used. Example: 2027-11-17. |
value | string | Yes | The card's full value. Example: 500.00. |
vatPercent | string | No | The VAT rate of a single-purpose card. Example: 25. |
GiftCardImport
A gift card that was sold somewhere else, such as a web shop. value is required, and merchantId at a location with several merchants. A field that is left out takes its default, as each field says.
| Field | Type | Required | Description |
|---|---|---|---|
accountingType | string | No | single_purpose or multi_purpose. Defaults to the merchant's setting. Example: single_purpose. |
beneficiary | string | No | Example: Anna Andersson. |
code | string | No | The code the holder uses when paying. Leave out to have one generated. Stored in upper case. Must not already be used at the location. Example: NH-4711. |
customerId | string | No | A person, company or vehicle of this location to link the card to. Example: per_2QCtWVSaVO7yCRYBj1zsbA. |
description | string | No | Defaults to "Presentkort" (Swedish for gift card). Example: Presentkort. |
externalReference | string | No | Your own id for this card, at most 100 characters, such as an order id and line number. Sending the same reference again returns the card created the first time, so a retry never makes a second card. Example: shopify-5512340001-1. |
merchantId | string | No | Which merchant the card belongs to. Needed only when the location has more than one; see GET /v1/locations/{locationId}/merchants. Example: mer_2Rk8sVh3Yq6Nf1Tz0JwUcM. |
note | string | No | A note for staff. Example: Web shop order 10042. |
remainingValue | string | No | What is left on a card that was already partly used. Between 0 and value. Defaults to value. Cannot be changed afterwards. Example: 500.00. |
soldDate | string (date) | No | Defaults to today in the location's time zone. Example: 2026-11-17. |
validUntil | string (date) | No | The last day the card can be used. Defaults to soldDate plus the merchant's standard validity. Example: 2027-11-17. |
value | string | Yes | The card's full value, as a decimal string with at most two decimals. Positive. Example: 500.00. |
vatPercent | string | No | The VAT rate of a single-purpose card, 0 to 100. Defaults to the merchant's setting. Leave out for a multi-purpose card. Example: 25. |
GiftCardList
| Field | Type | Required | Description |
|---|---|---|---|
data | array of GiftCard | Yes | |
nextCursor | string | No | Pass as after to fetch the next page. Absent on the last page. Example: gft_7Qm2xN0cT1kPz4Wb9LrEaD. |
Merchant
The company that sells at a location: the company whose name is on the receipt. A merchant belongs to one location, and a location usually has one. What is sold, such as a gift card, belongs to a merchant.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Merchant id. Example: mer_2Rk8sVh3Yq6Nf1Tz0JwUcM. |
name | string | Yes | The company name. Example: Salong Exempel AB. |
organisationNumber | string | No | The company's registration number, as entered in Cliento. Left out when none is entered. It can be written with or without a hyphen. Example: 556677-8899. |
MerchantList
| Field | Type | Required | Description |
|---|---|---|---|
data | array of Merchant | Yes |