---
title: Gift Cards
slug: devdocs/gift-cards
docTags: 
createdAt: 2026-10-16T12:03:52.082Z
---

Creating a gift card takes two steps: get the reference data, then create the card.

## Step 1: Get the reference data

You need the keys of the organization, the currency and the VAT category.

**Query**

```graphql
query GetGiftCardReferenceData {
  organization {
    organizations {
      publicKey
      name
    }
    currencies {
      publicKey
      symbol
    }
    vatCategories {
      publicKey
      percentageValue
    }
  }
}
```

**cURL**

```bash
curl --location 'https://sandbox.expressoft.eu/connect/api/interopgql' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{"query": "query GetGiftCardReferenceData { organization { organizations { publicKey name } currencies { publicKey symbol } vatCategories { publicKey percentageValue } } }"}'
```

**Response**

```json
{
  "data": {
    "organization": {
      "organizations": [
        {
          "publicKey": "00000000-0000-0000-0000-000000000601",
          "name": "Example Organization"
        }
      ],
      "currencies": [
        {
          "publicKey": "00000000-0000-0000-0000-000000000211",
          "symbol": "RON"
        }
      ],
      "vatCategories": [
        {
          "publicKey": "00000000-0000-0000-0000-000000000201",
          "percentageValue": 11.0
        },
        {
          "publicKey": "00000000-0000-0000-0000-000000000202",
          "percentageValue": 21.0
        }
      ]
    }
  }
}
```

## Step 2: Create the gift card

**Query**

```graphql
mutation CreateGiftCard($payload: CreateGiftCardInputType!) {
  organization {
    createGiftCard(payload: $payload) {
      result {
        publicKey
        code
        name
        amount
        startOn
        expireOn
        organization { publicKey name }
        currency { publicKey symbol }
        vatCategory { publicKey percentageValue }
      }
      errorCode
      errorMessage
      errorData
    }
  }
}
```

**Variables**

```json
{
  "payload": {
    "organizationKey": "<organization key>",
    "amount": 250,
    "vatCategoryKey": "<VAT category key>",
    "currencyKey": "<currency key>",
    "code": "GC250001",
    "name": "Gift card 250 RON",
    "startOn": "2026-07-30T00:00:00",
    "expireOn": "2026-12-31T23:59:59"
  }
}
```

**cURL**

```bash
curl --location 'https://sandbox.expressoft.eu/connect/api/interopgql' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{"query": "mutation CreateGiftCard($payload: CreateGiftCardInputType!) { organization { createGiftCard(payload: $payload) { result { publicKey code name amount startOn expireOn organization { publicKey name } currency { publicKey symbol } vatCategory { publicKey percentageValue } } errorCode errorMessage errorData } } }", "variables": {"payload": {"organizationKey": "<organization key>", "amount": 250, "vatCategoryKey": "<VAT category key>", "currencyKey": "<currency key>", "code": "GC250001", "name": "Gift card 250 RON", "startOn": "2026-07-30T00:00:00", "expireOn": "2026-12-31T23:59:59"}}}'
```

**Response**

```json
{
  "data": {
    "organization": {
      "createGiftCard": {
        "result": {
          "publicKey": "00000000-0000-0000-0000-000000000221",
          "code": "GC250001",
          "name": "Gift card 250 RON",
          "amount": 250.0,
          "startOn": "2026-07-30T00:00:00",
          "expireOn": "2026-12-31T23:59:59",
          "organization": {
            "publicKey": "00000000-0000-0000-0000-000000000601",
            "name": "Example Organization"
          },
          "currency": {
            "publicKey": "00000000-0000-0000-0000-000000000211",
            "symbol": "RON"
          },
          "vatCategory": {
            "publicKey": "00000000-0000-0000-0000-000000000201",
            "percentageValue": 11.0
          }
        },
        "errorCode": null,
        "errorMessage": null,
        "errorData": null
      }
    }
  }
}
```

| Field             | Type        | Required | Default | Description                                                                    |
| ----------------- | ----------- | -------- | ------- | ------------------------------------------------------------------------------ |
| `organizationKey` | `Guid!`     | yes      |         | Organization that owns the gift card.                                          |
| `amount`          | `Decimal!`  | yes      |         | Gift card face value (TotalAmountWithVAT).                                     |
| `vatCategoryKey`  | `Guid!`     | yes      |         | VAT category applied to the gift card amount.                                  |
| `currencyKey`     | `Guid!`     | yes      |         | Currency of the gift card amount.                                              |
| `code`            | `String`    | no       |         | External code (max 8 alphanumeric). Generated randomly if omitted.             |
| `name`            | `String`    | no       |         | Gift card display name/title, shown in CRM. Falls back to the code if omitted. |
| `startOn`         | `DateTime!` | yes      |         | Validity start date (non-UTC, as stored).                                      |
| `expireOn`        | `DateTime!` | yes      |         | Expiry date (non-UTC, as stored).                                              |

:::BlockQuote
💡 **TIP**
Leave `code` out and Expressoft generates a random one. If you send a code, use at most 8 letters and digits.
:::

:::BlockQuote
ℹ️ **INFO**
`startOn` and `expireOn` are dates and times as stored, without time zone conversion. The card appears in the application, in **Carduri cadou**.
:::

## Use a gift card

A gift card is used when the customer buys something, in an Expressoft POS transaction. This API creates gift cards. It doesn't read, redeem or list them.

:::BlockQuote
ℹ️ **INFO**
The error codes of the gift card mutation include `GiftCardDuplicateCode` (13), `InvalidOrganization` (14), `InvalidVATCategory` (15) and `InvalidCurrency` (16). See **Errors & Troubleshooting**.
:::