---
title: "Import a gift card"
method: POST
path: "/v1/locations/{locationId}/gift-cards/import"
tags: ["Gift cards"]
---

# Import a gift card

`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

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.

## Path parameters

- `locationId` string, required

## Headers

- `Idempotency-Key` string

## Request body

- 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.
  - `accountingType` string: `single_purpose` or `multi_purpose`. Defaults to the merchant's setting.
  - `beneficiary` string
  - `code` string: 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.
  - `customerId` string: A person, company or vehicle of this location to link the card to.
  - `description` string: Defaults to "Presentkort" (Swedish for gift card).
  - `externalReference` string: 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.
  - `merchantId` string: Which merchant the card belongs to. Needed only when the location has more than one; see `GET /v1/locations/{locationId}/merchants`.
  - `note` string: A note for staff.
  - `remainingValue` string: What is left on a card that was already partly used. Between 0 and `value`. Defaults to `value`. Cannot be changed afterwards.
  - `soldDate` string, date: Defaults to today in the location's time zone.
  - `validUntil` string, date: The last day the card can be used. Defaults to `soldDate` plus the merchant's standard validity.
  - `value` string, required: The card's full value, as a decimal string with at most two decimals. Positive.
  - `vatPercent` string: The VAT rate of a single-purpose card, 0 to 100. Defaults to the merchant's setting. Leave out for a multi-purpose card.

## Response `200`

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

- 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.
  - `accountingType` string: How VAT is handled. `single_purpose`: VAT is charged when the card is sold. `multi_purpose`: VAT is charged when the card is redeemed.
  - `beneficiary` string: Who the card is for, as free text.
  - `code` string, required: What the holder shows or types when paying.
  - `createdAt` string, date-time, required
  - `currency` string, required: ISO 4217 currency code.
  - `customerId` string: The person, company or vehicle the card is linked to, when it is linked to one. The id's prefix says which.
  - `description` string
  - `externalReference` string: Your own id for the card, as sent when it was imported.
  - `id` string, required: Gift card id.
  - `locationId` string, required
  - `merchantId` string: The merchant the card belongs to.
  - `note` string: A note for staff, shown on the card in Cliento.
  - `remainingValue` string, required: What is left to spend.
  - `soldDate` string, date: The day the card was sold, in the location's time zone.
  - `status` string, required: `active`: usable, nothing spent. `partially_redeemed`: usable, some spent. `redeemed`: nothing left. `expired`: past `validUntil`. `void`: cancelled. More values may be added.
  - `updatedAt` string, date-time, required: When it last changed, in UTC.
  - `validUntil` string, date: The last day the card can be used.
  - `value` string, required: The card's full value.
  - `vatPercent` string: The VAT rate of a single-purpose card.

## Other responses

- `201`: The card was created.
- `default`: Any failure. See the Errors section.

---

[API](https://skmtc.dev/cliento/apis/cliento-api.md) · [All operations](https://skmtc.dev/cliento/apis/cliento-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cliento/apis/cliento-api/revisions/29ca811bc061?raw)