# 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 |  |