Gift Cards

7 min

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

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

cURL

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

{
  "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

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"
  }
}

cURL

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

{
  "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	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).

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

ℹ️ 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.

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