Gift cards

Import a gift card

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.

post/v1/locations/{locationId}/gift-cards/import

Request

  • Base URL: https://api.cliento.com
  • URL: https://api.cliento.com/v1/locations/{locationId}/gift-cards/import
  • Auth: HTTP bearer

Path parameters

locationIdstring required

Headers

Idempotency-Keystring

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.

Request body

accountingTypestring

single_purpose or multi_purpose. Defaults to the merchant's setting.

beneficiarystring
codestring

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.

customerIdstring

A person, company or vehicle of this location to link the card to.

descriptionstring

Defaults to "Presentkort" (Swedish for gift card).

externalReferencestring

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.

merchantIdstring

Which merchant the card belongs to. Needed only when the location has more than one; see GET /v1/locations/{locationId}/merchants.

notestring

A note for staff.

remainingValuestring

What is left on a card that was already partly used. Between 0 and value. Defaults to value. Cannot be changed afterwards.

soldDatestring date

Defaults to today in the location's time zone.

validUntilstring date

The last day the card can be used. Defaults to soldDate plus the merchant's standard validity.

valuestring required

The card's full value, as a decimal string with at most two decimals. Positive.

vatPercentstring

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 request

{
  "accountingType": "single_purpose",
  "beneficiary": "Anna Andersson",
  "code": "NH-4711",
  "customerId": "per_2QCtWVSaVO7yCRYBj1zsbA",
  "description": "Presentkort",
  "externalReference": "shopify-5512340001-1",
  "merchantId": "mer_2Rk8sVh3Yq6Nf1Tz0JwUcM",
  "note": "Web shop order 10042",
  "remainingValue": "500.00",
  "soldDate": "2026-11-17",
  "validUntil": "2027-11-17",
  "value": "500.00",
  "vatPercent": "25"
}

Response

A card with this externalReference already existed. It is returned as it is now; nothing in this request was applied.

accountingTypestring

How VAT is handled. single_purpose: VAT is charged when the card is sold. multi_purpose: VAT is charged when the card is redeemed.

beneficiarystring

Who the card is for, as free text.

codestring required

What the holder shows or types when paying.

createdAtstring date-time required
currencystring required

ISO 4217 currency code.

customerIdstring

The person, company or vehicle the card is linked to, when it is linked to one. The id's prefix says which.

descriptionstring
externalReferencestring

Your own id for the card, as sent when it was imported.

idstring required

Gift card id.

locationIdstring required
merchantIdstring

The merchant the card belongs to.

notestring

A note for staff, shown on the card in Cliento.

remainingValuestring required

What is left to spend.

soldDatestring date

The day the card was sold, in the location's time zone.

statusstring required

active: usable, nothing spent. partially_redeemed: usable, some spent. redeemed: nothing left. expired: past validUntil. void: cancelled. More values may be added.

updatedAtstring date-time required

When it last changed, in UTC.

validUntilstring date

The last day the card can be used.

valuestring required

The card's full value.

vatPercentstring

The VAT rate of a single-purpose card.

Example response

{
  "accountingType": "single_purpose",
  "beneficiary": "Anna Andersson",
  "code": "K7QX9M2D",
  "createdAt": "2026-11-17T09:14:03Z",
  "currency": "SEK",
  "customerId": "per_2QCtWVSaVO7yCRYBj1zsbA",
  "description": "Presentkort",
  "externalReference": "shopify-5512340001-1",
  "id": "gft_7Qm2xN0cT1kPz4Wb9LrEaD",
  "locationId": "loc_4fK9xQ2mLr8TzB1vNc7HdW",
  "merchantId": "mer_2Rk8sVh3Yq6Nf1Tz0JwUcM",
  "note": "Web shop order 10042",
  "remainingValue": "500.00",
  "soldDate": "2026-11-17",
  "status": "active",
  "updatedAt": "2026-10-12T09:24:31.512Z",
  "validUntil": "2027-11-17",
  "value": "500.00",
  "vatPercent": "25"
}

Changes

No recorded changes to this operation across all 1 revision of this API.