Op deze paginaREST API

Gifty API.

Markdown

Welcome to the Gifty API documentation. This documentation provides you with all the necessary information to communicate with our API. If you want to use our API you must register your application via the Gifty dashboard.

If you have any questions, don't hesitate to reach out. You can contact us via our contact page.

Introduction

The following section describes generic usage information on the Gifty API.

Authentication

Send the provided token as a header with your requests. You can create an API token on the developer's page in your dashboard.

Authorization: Bearer REPLACE_WITH_YOUR_PRIVATE_TOKEN

Error Handling

Errors are returned in the format below, with a matching HTTP status code.

CodeMeaning
2XXSuccessful request.
4XXThe request is invalid. For example, because the requested resource does not exist. These errors are expected and should be gracefully processed.
5XXOuch. Most likely, something went wrong on our end. We received a notification, but please get in touch with us with additional information about the issue.
Response
JSON
{
  "message": "The transaction tr_kOWB2x0QVvE8GYn6GX7p1oL9 has been captured or released already.",
  "errors": [
    {
      "id": "9fb1f6880a844a72b7fbd9bb5ee10d87",
      "status": "422",
      "type": "giftcard_transaction_error",
      "title": "Giftcard transaction error",
      "detail": "The transaction tr_kOWB2x0QVvE8GYn6GX7p1oL9 has been captured or released already."
    }
  ]
}

Localization

The API's validation error messages are available in both English and Dutch. The default language used is English. If you want Dutch validation errors, send the header below with your request.

Accept-Language: nl

Empty values

A response always contains the same attributes. An attribute without a value is null, an empty list is [] and an empty object is {}. Only attributes you have to request, or have no access to, are left out. The exceptions are location and refund_details on a transaction: they are left out when they have no value.

Rate Limiting

Requests are limited per API key, per account and per IP address.

LimitApplies toDescription
120 requests per minuteAPI keyEvery API key has its own limit.
240 requests per minuteAccountAll API keys of an account share this limit.
2,400 requests per hourIP addressCounts all requests from one IP address, across API keys and accounts.

If you exceed a limit, the API responds with 429 Too Many Requests. The Retry-After header tells you how many seconds to wait. Please get in touch with us if these limits do not meet your requirements.

Idempotency

Add the X-Gifty-Idempotency-Key header with a unique value, for example a UUID version 4, to make sure a request is processed only once. This prevents a gift card from being redeemed twice after a network error.

HeaderDescriptionRegex
X-Gifty-Idempotency-KeyThe idempotency key for the request. Should have a maximum of 128 characters and consist of alphanumeric characters, dashes, and underscores./^[A-Za-z0-9_-]{1,128}$/

You may add this header to all your requests, but it will only be honoured for POST, PUT, and PATCH methods. If a request with the same idempotency key has already been processed in the past 24 hours, we will return the original response from the original request, without performing the operation again.

Pagination

For all responses that can return multiple objects, cursor pagination is available. You can send the cursor_before parameter to navigate through the pages on these requests. Use the limit parameter to set the number of results per page. You can use the ID of objects as the cursor.

The example below lists four locations, two per page. Without a cursor you get the two most recent results.

Now we want to navigate to the following result set to see location 2 and location 1. We pass the last known cursor lc_tOWRgGnbJs0pey3MfHPWjuge to parameter cursor_before.

Cursor pagination example

Currencies

While processing transactions on a gift card, you should provide the currency code of the gift card in the ISO 4217 format. The currencies listed in the table below are supported.

CodeCurrency
EUREuro

Gift Cards

A gift card holds a balance. Issuing a gift card activates it and adds the balance. Redeeming reduces the balance.

The Gift Card object

AttributeTypeDescription
idstringUnique identifier for the card.
codestringThe code of the gift card. Only present if you have access to gift card codes.
balanceintegerThe current balance of the card, in cents. A negative balance is not possible.
currencystringISO 4217 code of the currency. All transactions on this card are required to be made in the same currency.
promotionalbooleanTrue if the card is marked as promotional.
is_redeemablebooleanIndicates if a new redeem transaction can be made on the card. This attribute is false if there is no balance left or if the card is expired.
is_issuablebooleanIndicates if the gift card can be issued. false for a gift card that is issued, expired or blocked.
is_extendablebooleanIndicates if an expired gift card can be re-activated. This attribute is false if the gift card has not expired or if re-activation is not allowed.
expires_atstring or nullISO 8601 time of expiration or null if the gift card won't expire.
created_atstringISO 8601 time of creation.
packagestring or nullThe corresponding package ID.
reporting_labelsarrayThe reporting labels of the gift card. Only present if the gift card was issued by your account.
transactionsAll corresponding transactions made on the card.
imagesURLs to images that visualize the card.

GET Retrieve Gift Card

https://api.gifty.nl/v1/giftcards/:giftcard

The Gift Card object can be retrieved by providing the gift card code.

Request
HTTP
GET /v1/giftcards/AAAABBBBCCCCDDDD HTTP/1.1
Host: api.gifty.nl
Accept: application/json
Response
JSON
{
  "data": {
    "id": "gc_e7V83D5N6An7OgnPJgKlqoyz",
    "balance": 4000,
    "currency": "EUR",
    "promotional": false,
    "is_redeemable": true,
    "is_issuable": false,
    "is_extendable": false,
    "expires_at": "2027-09-15T12:42:42+00:00",
    "created_at": "2022-09-15T12:41:31+00:00",
    "package": null,
    "reporting_labels": ,
    "transactions": ,
    "images": [
        {
            "type": "FRONT_SMALL",
            "url": "https://dashboard.gifty.nl/storage/images/preview/co_AywKZBJOaXn2oWvY47xk5LVp/small.png"
        }
    ]
  }
}
Path Parameters
  • giftcard
  • string
  • required
The code of the gift card. Send a scanned QR code unchanged and a typed code without hyphens or spaces. Do not rely on a fixed length or format.

POST Redeem Gift Card

https://api.gifty.nl/v1/giftcards/:giftcard/redeem

To debit a gift card, a redeem transaction should be made. The 'Transaction' object is returned after a successful transaction.

Request
HTTP
POST /v1/giftcards/AAAABBBBCCCCDDDD/redeem HTTP/1.1
Host: api.gifty.nl
Accept: application/json
Content-Type: application/json

{
    "amount": 1250,
    "currency": "EUR",
    "capture": false
}
Response
JSON
{
  "data": {
    "id": "tr_kOWB2x0QVvE8GYn6GX7p1oL9",
    "amount": -1250,
    "currency": "EUR",
    "status": "pending",
    "type": "redeem",
    "description": "Redeem amount of '€ 12,50'",
    "is_capturable": true,
    "is_cancellable": true,
    "is_refundable": false,
    "captured_at": null,
    "created_at": "2019-01-06T19:10:49+00:00",
    "giftcard": 
  }
}
Path Parameters
  • giftcard
  • string
  • required
The code of the gift card. Send a scanned QR code unchanged and a typed code without hyphens or spaces. Do not rely on a fixed length or format.
Request Body
  • amount
  • integer
  • required
Amount of the transaction. Should be a positive integer in cents. For example, 1000 means a debit transaction of 10,00.

  • currency
  • string
  • required
ISO 4217 code of the currency.

  • capture
  • boolean
  • required
If true, the transaction will be captured immediately and can't be cancelled. When a separate payment needs to be made this should be false so the transaction can be captured or cancelled later.

  • comment
  • string
  • optional
A note for the transaction. Required if your account requires a description for transactions.

POST Issue Gift Card

https://api.gifty.nl/v1/giftcards/:giftcard/issue

To credit a gift card, an issue transaction should be made. Issuing a gift card is only possible once, and issue transactions are always captured immediately. The 'Transaction' object is returned after a successful transaction.

Request
HTTP
POST /v1/giftcards/AAAABBBBCCCCDDDD/issue HTTP/1.1
Host: api.gifty.nl
Accept: application/json
Content-Type: application/json

{
    "amount": 1250,
    "currency": "EUR",
    "promotional": false
}
Response
JSON
{
  "data": {
    "id": "tr_K5Op3zGP4dePxMmyVa9gkXL8",
    "amount": 1250,
    "currency": "EUR",
    "status": "success",
    "type": "issue",
    "description": "Issue amount of '€ 12,50'",
    "is_capturable": false,
    "is_cancellable": false,
    "is_refundable": true,
    "captured_at": "2019-01-08T11:43:44+00:00",
    "created_at": "2019-01-08T11:43:44+00:00",
    "giftcard": 
  }
}
Path Parameters
  • giftcard
  • string
  • required
The code of the gift card. Send a scanned QR code unchanged and a typed code without hyphens or spaces. Do not rely on a fixed length or format.
Request Body
  • amount
  • integer
  • required
Amount of the transaction. Should be a positive integer in cents. For example, 1000 means a credit transaction of 10,00.

  • currency
  • string
  • required
ISO 4217 code of the currency.

  • promotional
  • boolean
  • optional
Marks the card as promotional, so it can be excluded from financial reports. Defaults to false.

  • package_id
  • string
  • optional
The ID of the package to issue. Available packages can be gathered from the packages endpoint.

  • comment
  • string
  • optional
A note for the transaction. Required if your account requires a description for transactions.

POST Extend Gift Card

https://api.gifty.nl/v1/giftcards/:giftcard/extend

To extend the validity of a gift card after it has expired, an extend transaction should be made. The 'Transaction' object is returned after a successful transaction.

Request
HTTP
POST /v1/giftcards/AAAABBBBCCCCDDDD/extend HTTP/1.1
Host: api.gifty.nl
Accept: application/json
Content-Type: application/json

{
    "expires_at": "2023-04-30T16:36:49+00:00"
}
Response
JSON
{
  "data": {
    "id": "tr_kOWB2x0QVvE8GYn6GX7p1oL9",
    "amount": 1250,
    "currency": "EUR",
    "status": "success",
    "type": "reverse_expire",
    "description": "Reverse expire with amount of '€ 12,50'",
    "is_capturable": false,
    "is_cancellable": false,
    "is_refundable": false,
    "captured_at": "2023-02-23T14:16:32+00:00",
    "created_at": "2023-02-23T14:16:32+00:00",
    "giftcard": 
  }
}
Path Parameters
  • giftcard
  • string
  • required
The code of the gift card. Send a scanned QR code unchanged and a typed code without hyphens or spaces. Do not rely on a fixed length or format.
Request Body
  • expires_at
  • string
  • required
ISO 8601 time of expiration. Should be in the future.

Transactions

By issuing a gift card (credit) or redeeming a gift card (debit), a Transaction object represents the change.

The Transaction object

AttributeTypeDescription
idstringUnique identifier for the transaction.
amountintegerThe amount that has been applied on the gift card during this transaction. Negative values (-1000) indicate a debit transaction. Positive values (1000) indicate a credit transaction.
currencystringISO 4217 code of the currency. Should always be the same as the corresponding gift card.
statusstringThe status of the transaction. Can be one of: success, pending or cancelled.
typestringIndicates the reason for the transaction. Can be one of: issue, top_up, redeem, release, refund, block, expire, reverse_issue, reverse_top_up, reverse_redeem, reverse_block or reverse_expire.
descriptionstringProvides more information about the transaction.
is_capturablebooleanIndicates if a capture can be made on the transaction. This attribute is false if the transaction is captured or cancelled already.
is_cancellablebooleanIndicates if the transaction can be released. This attribute is false if the transaction is captured or cancelled already.
is_refundablebooleanIndicates if the transaction can be refunded.
amount_refundedintegerThe amount that has been refunded. Only present if you request it with include=refunds.
refundsarrayThe refunds of the transaction. Only present if you request it with include=refunds.
refund_detailsobjectThe original transaction ID, reason and description of a refund. Left out on every other transaction.
captured_atstring or nullISO 8601 time of capturing. As long as this value is null the transaction can be cancelled.
created_atstringISO 8601 time of creation.
giftcardThe corresponding gift card of the transaction.
locationThe location linked to the transaction. Left out when the transaction has no location.

GET List All Transactions

https://api.gifty.nl/v1/transactions

This call returns all Transaction objects. The most recent transactions are shown first.

Request
HTTP
GET /v1/transactions?limit=10 HTTP/1.1
Host: api.gifty.nl
Accept: application/json
Response
JSON
{
  "data": [
    {
      "id": "tr_W2pJPRYZO0njkQvMrN4zwKqy",
      "amount": 4000,
      "currency": "EUR",
      "status": "success",
      "type": "issue",
      "description": "Issue amount of '€ 40,00'",
      "is_capturable": false,
      "is_cancellable": false,
      "is_refundable": true,
      "captured_at": "2021-11-10T23:32:12+00:00",
      "created_at": "2021-11-10T23:32:12+00:00",
      "giftcard": ,
      "location": 
    },
    {...}
  ]
}
Query Parameters
  • giftcard
  • string
  • optional
Only return transactions for this gift card ID.

  • include
  • string
  • optional
Use "refunds" to add amount_refunded and refunds to each transaction.

  • limit
  • integer
  • optional
The number of results to show. Defaults to 10 and should be between 1 and 100.

  • cursor_before
  • string
  • optional
Pagination cursor ID. See the pagination section for usage instructions.

  • cursor_after
  • string
  • optional
Pagination cursor ID, for the results after this object. Cannot be combined with cursor_before.

GET Retrieve Transaction

https://api.gifty.nl/v1/transactions/:transaction

The Transaction object can be retrieved by providing the transaction identifier.

Request
HTTP
GET /v1/transactions/tr_ABCDEFGHIJK HTTP/1.1
Host: api.gifty.nl
Accept: application/json
Response
JSON
{
  "data": {
    "id": "tr_ABCDEFGHIJK",
    "amount": 4000,
    "currency": "EUR",
    "status": "success",
    "type": "issue",
    "description": "Issue amount of '€ 40,00'",
    "is_capturable": false,
    "is_cancellable": false,
    "is_refundable": true,
    "captured_at": "2018-11-03T12:41:41+00:00",
    "created_at": "2018-11-03T12:41:41+00:00",
    "giftcard": ,
    "location": 
  }
}
Path Parameters
  • transaction
  • string
  • required
The ID of the transaction.
Query Parameters
  • include
  • string
  • optional
Use "refunds" to add amount_refunded and refunds to the transaction.

POST Capture Transaction

https://api.gifty.nl/v1/transactions/:transaction/capture

After the entire payment process has been completed and verified, the gift card transaction should be 'captured'. That makes the transaction final.

Request
HTTP
POST /v1/transactions/tr_ABCDEFGHIJK/capture HTTP/1.1
Host: api.gifty.nl
Accept: application/json
Content-Type: application/json
Response
JSON
{
  "data": {
    "id": "tr_ABCDEFGHIJK",
    "amount": -1250,
    "currency": "EUR",
    "status": "success",
    "type": "redeem",
    "description": "Redeem amount of '€ 12,50'",
    "is_capturable": false,
    "is_cancellable": false,
    "is_refundable": true,
    "captured_at": "2019-01-06T19:41:31+00:00",
    "created_at": "2019-01-06T19:10:49+00:00",
    "giftcard": ,
    "location": 
  }
}
Path Parameters
  • transaction
  • string
  • required
The ID of the transaction.

DELETE Release Transaction

https://api.gifty.nl/v1/transactions/:transaction

If the payment process ends unsuccessfully, for example, because the customer cancelled the payment, the transaction should be 'released'. The transaction is reverted and funds restored. The return is a 'release' transaction.

Request
HTTP
DELETE /v1/transactions/tr_ABCDEFGHIJK HTTP/1.1
Host: api.gifty.nl
Accept: application/json
Content-Type: application/json
Response
JSON
{
  "data": {
    "id": "tr_ABCDEFGHIJK",
    "amount": 1250,
    "currency": "EUR",
    "status": "success",
    "type": "release",
    "description": "Release amount of '€ 12,50' for cancellation of 'tr_ABCDEFGHIJK'",
    "is_capturable": false,
    "is_cancellable": false,
    "is_refundable": false,
    "captured_at": "2019-01-06T19:49:05+00:00",
    "created_at": "2019-01-06T19:49:05+00:00",
    "giftcard": ,
    "location": 
  }
}
Path Parameters
  • transaction
  • string
  • required
The ID of the transaction.

POST Refund Transaction

https://api.gifty.nl/v1/transactions/:transaction/refund

Refund a completed (captured) transaction. This creates a reversal transaction that compensates the original transaction. Supports both full and partial refunds. The 'Transaction' object is returned after a successful refund with the "type" field set to "reverse_redeem", "reverse_issue" or "reverse_top_up" depending on the refunded transaction type.

Request
HTTP
POST /v1/transactions/tr_ABCDEFGHIJK/refund HTTP/1.1
Host: api.gifty.nl
Accept: application/json
Content-Type: application/json

{
  "amount": 1250,
  "currency": "EUR",
  "reason": "CUSTOMER_REQUEST",
  "reason_description": "Customer returned one item from the order"
}
Response
JSON
{
  "data": {
    "id": "tr_ABCDEFGHIJK",
    "amount": 1250,
    "currency": "EUR",
    "status": "success",
    "type": "reverse_redeem",
    "description": "Reversal of redeem transaction tr_ABCDEFGHIJK",
    "is_capturable": false,
    "is_cancellable": false,
    "is_refundable": false,
    "captured_at": "2025-06-15T10:30:45+00:00",
    "created_at": "2025-06-15T10:30:45+00:00",
    "refund_details": {
      "original_transaction": "tr_ABCDEFGHIJK",
      "reason": "CUSTOMER_REQUEST",
      "reason_description": "Customer returned one item from the order"
    },
    "giftcard": ,
    "location": 
  }
}
Path Parameters
  • transaction
  • string
  • required
The ID of the transaction to refund.
Request Body
  • amount
  • integer
  • optional
Amount to refund. Should be a positive integer in cents. For example, 1250 means €12,50. Must not exceed the remaining refundable amount of the original transaction. If omitted, the full transaction amount will be refunded.

  • currency
  • string
  • required
ISO 4217 code of the currency. Required when amount is provided.

  • reason
  • string
  • required
Standardized reason code. Valid values:
  • CUSTOMER_REQUEST
  • OPERATOR_ERROR
  • BOOKING_CANCELLED
  • SYSTEM_ERROR
  • OTHER
  • reason_description
  • string
  • optional
Additional details about the refund reason. Maximum 1000 characters.

Locations

Companies with multiple store locations can specify the employee's location when performing gift card actions. By doing this, preciser administration views are available in the dashboard. Set the location of the user by passing the ID with your API requests as header. We recommend sending it with every request, also for an account with one location.

X-Gifty-Location: REPLACE_WITH_LOCATION_ID

The Location object

AttributeTypeDescription
idstringUnique identifier for the location.
streetstringAddress street.
house_numberstringAddress house number.
additionstring or nullAddress house number addition.
postal_codestringAddress postal code.
citystringAddress city.
country_codestringAddress country code in two-letter format.

GET List All Locations

https://api.gifty.nl/v1/locations

This call returns all Location objects.

Request
HTTP
GET /v1/locations?limit=10 HTTP/1.1
Host: api.gifty.nl
Accept: application/json
Response
JSON
{
  "data": [
    {
      "id": "lc_RVyje31w8pmKwwmqlZW096M7",
      "street": "Floridalaan",
      "house_number": "8 bis",
      "addition": null,
      "postal_code": "3404WV",
      "city": "IJsselstein",
      "country_code": "NL"
    },
    {...}
  ]
}
Query Parameters
  • limit
  • integer
  • optional
The number of results to show. Defaults to 10 and should be between 1 and 100.

  • cursor_before
  • string
  • optional
Pagination cursor ID. See the pagination section for usage instructions.

  • cursor_after
  • string
  • optional
Pagination cursor ID, for the results after this object. Cannot be combined with cursor_before.

Packages

It is possible to sell gift cards with a package value instead of a monetary amount. Each package still represents a monetary value, but it is up to the gift card brand to show this to the customer. Using this API endpoint, you can get the available packages to integrate with your booking platform or webshop.

The Package object

AttributeTypeDescription
idstringUnique identifier for the package.
titlestringTitle of the package.
descriptionstringDescription of the package.
amountintegerThe amount this package represents in cents.
amount_visiblebooleanIndicates if the amount is displayed on the gift card.
currencystringISO 4217 code of the currency.
activebooleanIndicates if the package is available for purchase.

GET List All Packages

https://api.gifty.nl/v1/packages

This call returns all Package objects.

Request
HTTP
GET /v1/packages?limit=10 HTTP/1.1
Host: api.gifty.nl
Accept: application/json
Response
JSON
{
  "data": [
    {
        "id": "gp_rB4kAgGwOzdaQ5dMxN09q62y",
        "title": "Tapasmenu voor 2",
        "description": "Geef een heerlijk verzorgde avond cadeau met ons tapasmenu voor 2.",
        "amount": 4250,
        "amount_visible": true,
        "currency": "EUR",
        "active": true
    },
    {...}
  ]
}
Query Parameters
  • limit
  • integer
  • optional
The number of results to show. Defaults to 10 and should be between 1 and 100.

  • cursor_before
  • string
  • optional
Pagination cursor ID. See the pagination section for usage instructions.

  • cursor_after
  • string
  • optional
Pagination cursor ID, for the results after this object. Cannot be combined with cursor_before.

GET Retrieve Package

https://api.gifty.nl/v1/packages/:package

The Package object can be retrieved by providing the package ID.

Request
HTTP
GET /v1/packages/gp_ABCDABCDABCD HTTP/1.1
Host: api.gifty.nl
Accept: application/json
Response
JSON
{
  "data": {
      "id": "gp_rB4kAgGwOzdaQ5dMxN09q62y",
      "title": "Tapasmenu voor 2",
      "description": "Geef een heerlijk verzorgde avond cadeau met ons tapasmenu voor 2.",
      "amount": 4250,
      "amount_visible": true,
      "currency": "EUR",
      "active": true
  }
}
Path Parameters
  • package
  • string
  • required
The ID of the package.

Reporting labels

Reporting labels group orders and their gift cards, for example by campaign, department or partner. They are used for filtering and reporting in the dashboard and are not shown to recipients.

The API returns the labels of a gift card, so you can recognise the gift cards of a campaign, for example before redeeming them. Applying the conditions of a campaign is up to your integration.

The Reporting Label object

AttributeTypeDescription
idstringUnique identifier of the label within your account. Does not change when the label is renamed.
namestringName of the label. Can change, so match on id.

When two labels are merged, one id remains and the other is no longer returned.

Where labels appear

ObjectAttributeDescription
Gift Cardreporting_labelsThe labels of the order the gift card belongs to. Only present if the gift card was issued by your account.
Transactiongiftcard.reporting_labelsThrough the Gift Card object of the transaction. The same goes for webhook events.
External Orderreporting_labelsThe labels of the order.

Adding labels

Labels are added in the dashboard, or through the API when placing an External Order. A string you send is matched to an existing label by id or name, regardless of case. If there is no match, a new label is created with that name. For a value unique to one order, such as your own order ID, use metadata.external_reference.

  • Send an array of strings: up to 10 labels per order, up to 191 characters per label.
  • Spaces at the start and end are removed; empty labels are ignored.
  • Duplicates are removed regardless of case; the first spelling is kept.
  • A label must contain at least one letter or digit.
  • Commas and the reserved label promotional are not allowed.
  • Do not include personal data.

External Orders

Through the External Orders API you are able to integrate online gift card sales sold outside of the Gifty order module, while still letting Gifty handle the fulfillment and management of the gift cards.

Integration flow

To place an order we suggest a standardised flow as described below.

  1. Fetch Configuration: get available products, customisations, and shipping options
  2. Build Order: customer selects products and provides required details
  3. Preview Order: validate and calculate final pricing
  4. Process Payment: handle payment through your system
  5. Create Order: submit the finalized order to Gifty for fulfillment

Caching

  • We recommend implementing stale-while-revalidate caching on the configuration endpoint with a 1-hour TTL to ensure optimal performance without impacting your storefront's responsiveness.
  • Configuration changes (products, pricing, shipping) may take up to 15 minutes to propagate after updates in the Gifty dashboard.

Reporting labels

Add reporting_labels to the create and preview request as an array of strings, for example ["campaign-spring", "partner-x"]. The response returns them as Reporting Label objects. In the preview response, a label that does not exist yet is shown with the id it will get.

See Reporting labels for how labels are matched and which values are accepted.

Data Models

In the External Orders API you'll use various data models to represent products, customisations, shipping options, and orders. Below are the key models you'll interact with.

Product Types

TypeDescription
gift_cardVariable or fixed price gift cards.
gift_card_packagePre-defined packages with set values.

Fulfillment Modes

ModeDescription
digitalEmail delivery.
physicalPostal delivery.

Order Status

StatusDescription
pendingOrder received, processing not started.
processingOrder is being fulfilled.
completedOrder fulfilled, gift cards activated.
cancelledOrder was cancelled.

Customisation Types

TypeDescriptionAvailable For
personalised_messageAdd custom text to gift card.physical, digital
gift_wrappingAdd decorative wrapping.physical only

GET Configuration

https://api.gifty.nl/v1/external-orders/configuration

Returns the products, customisations and shipping options available for your account.

Request
HTTP
GET /v1/external-orders/configuration HTTP/1.1
Host: api.gifty.nl
Accept: application/json
Response
JSON
{
    "data": {
        "supported_currencies": ["EUR"],
        "supported_locales": ["en","nl"],
        "products": [
            {
                "id": "gc_co_sample_standard",
                "type": "gift_card",
                "title": "Gift card",
                "description": "The Gifty Merch gift card",
                "images": [
                    {"type": "FRONT_SMALL","url": "https://cdn.gifty.nl/preview/sample/small.png"}
                ],
                "pricing": {
                    "model": "variable",
                    "application": "per_item",
                    "currency": "EUR",
                    "range": {
                        "minimum": 500,
                        "maximum": 150000,
                        "suggested_amounts": [1500,2500,5000,7500,10000]
                    }
                },
                "fulfillment_modes": ["physical","digital"],
                "customisation_options": [
                    {
                        "type": "personalised_message",
                        "title": "Personalised message",
                        "description": "Add a personal message to the gift card",
                        "constraints": {"required": false,"max_length": 300},
                        "pricing": {
                            "model": "fixed",
                            "application": "per_order",
                            "currency": "EUR",
                            "price": {"excluding_tax": 79,"including_tax": 96,"tax": 17,"tax_lines": []}
                        },
                        "available_for": ["physical","digital"]
                    },
                    {
                        "type": "gift_wrapping",
                        "title": "Gift wrapping",
                        "description": "Add a festive wrapping to the gift card",
                        "constraints": {
                            "required": false,
                            "options": ["wr_bq3WeLra4wvNXNdA1P8Zx0Yk"]
                        },
                        "pricing": {
                            "model": "variable",
                            "application": "per_item",
                            "currency": "EUR",
                            "variable": true
                        },
                        "available_for": ["physical"]
                    }
                ]
            }
        ],
        "customization_definitions": {
            "gift_wrapping": [
                {
                    "id": "wr_bq3WeLra4wvNXNdA1P8Zx0Yk",
                    "title": "Confetti Blue",
                    "pricing": {
                        "model": "fixed",
                        "application": "per_item",
                        "currency": "EUR",
                        "price": {
                            "excluding_tax": 207,
                            "including_tax": 250,
                            "tax": 43,
                            "tax_lines": [
                                {"name": "VAT 21%", "type": "VAT", "rate": 21, "amount": 43}
                            ]
                        }
                    },
                    "images": [
                        {
                            "type": "FRONT_SMALL",
                            "url": "https://assets.cdn.gifty.nl/wrapping/standaard_confetti_blauw/standaard_confetti_blauw.png"
                        }
                    ]
                }
            ]
        },
        "shipping": {
            "available_countries": ["NL", "BE", "DE", "LU", "FR", "AT", "IE", "SE", "DK", "IT", "ES", "FI"],
            "methods": [
                {
                    "id": "dm_lK8wJE5RLNdo3dAe6bqrjGak",
                    "type": "letter_post",
                    "title": "Letter post",
                    "description": "Sent via letter post.",
                    "available_countries": ["NL", "BE", "DE", "LU", "FR", "AT", "IE", "SE", "DK", "IT", "ES", "FI"],
                    "countries": [
                        {
                            "code": "NL",
                            "pricing": {
                                "model": "fixed",
                                "application": "per_item",
                                "currency": "EUR",
                                "price": {
                                    "excluding_tax": 244,
                                    "including_tax": 295,
                                    "tax": 51,
                                    "tax_lines": [
                                        {"name": "VAT 21%", "type": "VAT", "rate": 21, "amount": 51}
                                    ]
                                }
                            },
                            "schedule_rules": {"cutoff_time": "15:30", "timezone": "Europe/Amsterdam"},
                            "delivery_estimates": {
                                "fulfillment": {"minimum": 0, "maximum": 3, "unit": "business_days"},
                                "delivery": {"minimum": 3, "maximum": 6, "unit": "business_days"}
                            }
                        },
                        {
                            "code": "BE",
                            "pricing": {...},
                            "schedule_rules": {...},
                            "delivery_estimates": {...}
                        }
                    ]
                }
            ]
        },
        "constraints": {
            "order": {
                "minimum_amount": {"currency": "EUR","amount": 500},
                "maximum_amount": {"currency": "EUR","amount": 250000},
                "maximum_line_items": {"quantity": 100}
            }
        },
        "consent": {
            "consumer_terms": {
                "url": "https://gifty.nl/buyer-terms-and-conditions-en.pdf",
                "version": "2024-11-23",
                "required": true
            },
            "privacy_policy": {
                "url": "https://gifty.nl/privacy-statement-en.pdf",
                "version": "2025-03-20",
                "required": true
            }
        }
    }
}
Fulfillment modes

Products can have one or more fulfillment modes. "physical" means the product can be shipped to a physical address. "digital" means the product can be delivered digitally via email.

Customisation options can be limited to specific fulfillment modes. For example, gift wrapping is only available for physical products.

Pricing

Customisation and shipping prices are charged to your account.

Products can have a fixed or variable pricing model. For variable pricing, a minimum and maximum amount is specified along with suggested amounts.

Price "application" can be either "per_item" or "per_order". "per_item" means the price is multiplied by the quantity of items in the order. "per_order" means the price is applied once per order regardless of the number of items.

Shipping

Choose a shipping method available for the destination country. Use the IDs and prices returned by this endpoint.

Schedule rules define the cutoff time for same-day processing and the timezone of the fulfillment center.

Using the preview endpoint you can retrieve more detailed information about shipping methods including estimated delivery dates based on the shipping address and current date.

Remarks

If you apply a gift wrapping, each item in the order should have the same wrapping option. Mixing wrapping options within one order is not supported.

The configuration is cached and updated periodically. Changes to products, customisations or shipping methods can take up to 15 minutes to show.

POST Preview Order

https://api.gifty.nl/v1/external-orders/preview

Calculate pricing and validate order details without creating an order. Call this endpoint multiple times during checkout as needed.

Request
HTTP
POST /v1/external-orders/preview HTTP/1.1
Host: api.gifty.nl
Accept: application/json
Content-Type: application/json

{
  "currency": "EUR",
  "fulfillment": {
    "mode": "physical"
  },
  "line_items": [
    {
      "product_id": "gc_co_sample_standard",
      "configuration": {"amount": 25000},
      "quantity": 1,
      "customisations": [
        {"type": "personalised_message","value": "Happy Birthday! Enjoy your special day!"},
        {"type": "gift_wrapping","value": "wr_bq3WeLra4wvNXNdA1P8Zx0Yk"}
      ]
    }
  ],
  "customer": {
    "name": "John Doe",
    "email": "[email protected]",
    "phone": "+31612345678",
    "locale": "en"
  },
  "shipping": {
    "address": {
      "name": "John Doe",
      "company": "Gifty BV",
      "line1": "Floridalaan 8",
      "postal_code": "3404WV",
      "city": "IJsselstein",
      "country_code": "NL"
    },
    "method_id": "dm_DkOWB2x0QVvEod6GX7p1oL98"
  },
  "reporting_labels": ["Partner X welcome campaign"],
  "metadata": {
    "source": "partner_embedded_commerce",
    "external_reference": "ORD-123456789"
  }
}
Response
JSON
{
  "data": {
    "amounts": {
      "line_items": 25000,
      "customisations": 286,
      "shipping": 632,
      "subtotal": 25918,
      "tax": 193,
      "total": 26111
    },
    "shipping": {
      "method": {
        "id": "dm_DkOWB2x0QVvEod6GX7p1oL98",
        "type": "track-n-trace-priority",
        "title": "Parcel post Track & Trace",
        "carrier": "PostNL",
        "pricing": {
          "model": "fixed",
          "application": "per_order",
          "currency": "EUR",
          "price": {
            "excluding_tax": 632,
            "including_tax": 765,
            "tax": 133,
            "tax_lines": [
              {
                "name": "VAT 21%",
                "type": "VAT",
                "rate": 21,
                "amount": 133
              }
            ]
          }
        }
      },
      "schedule": {
        "cutoff_time": "2025-08-29T15:30:00+02:00",
        "ships_on": "2025-09-01",
        "delivers_between": {
          "earliest": "2025-09-02",
          "latest": "2025-09-03"
        }
      }
    },
    "reporting_labels": ,
    "metadata": {
      "source": "partner_embedded_commerce",
      "external_reference": "ORD-123456789"
    }
  }
}
Request Body
  • currency
  • string
  • required
ISO 4217 code of the currency.

  • fulfillment
  • object
  • required
mode: "physical" or "digital".

  • line_items
  • array
  • required
The products to order, up to 100. Per item:
  • product_id, required: the ID of a product from the configuration.
  • quantity, required: between 1 and 100.
  • configuration.amount: the amount in cents, for a product with variable pricing.
  • customisations: a list of type and value, up to 300 characters per value.
  • customer
  • object
  • required
The customer who places the order:
  • name, required.
  • email, required.
  • phone, optional.
  • locale, optional: one of en, nl, de, fr, es, it.
  • shipping
  • object
  • optional
Required for physical fulfillment: the address and the method_id of a shipping method from the configuration.

  • reporting_labels
  • array
  • optional
Reporting labels to group transactions and reports.

  • metadata
  • object
  • optional
Your reference data: "source" and "external_reference".

POST Create Order

https://api.gifty.nl/v1/external-orders

Create a new order after payment has been processed. Always use an X-Gifty-Idempotency-Key to prevent duplicate orders.

Request
HTTP
POST /v1/external-orders HTTP/1.1
Host: api.gifty.nl
Accept: application/json
Content-Type: application/json
X-Gifty-Idempotency-Key: unique-order-key-123

{
  "currency": "EUR",
  "fulfillment": {
    "mode": "digital"
  },
  "line_items": [
    {
      "product_id": "gc_co_sample_standard",
      "configuration": {"amount": 25000},
      "quantity": 1,
      "customisations": [
        {"type": "personalised_message","value": "Happy Birthday! Enjoy your special day!"}
      ]
    }
  ],
  "customer": {
    "name": "John Doe",
    "email": "[email protected]",
    "phone": "+31612345678",
    "locale": "en"
  },
  "consent": {
    "consumer_terms": {
      "accepted": true,
      "version": "2024-11-23"
    },
    "privacy_policy": {
      "accepted": true,
      "version": "2025-03-20"
    }
  },
  "reporting_labels": ["Partner X welcome campaign"],
  "metadata": {
    "source": "partner_embedded_commerce",
    "external_reference": "ORD-123456789"
  }
}
Response
JSON
{
    "data": {
        "id": "or_rB4kAgGwOzda3MvMxN09q62y",
        "created_at": "2025-08-29T13:48:56+00:00",
        "status": "pending",
        "currency": "EUR",
        "fulfillment": {
            "mode": "digital",
            "status": "pending"
        },
        "customer": {...},
        "line_items": [...],
        "shipping": null,
        "amounts": {...},
        "gift_cards": [
            {
                "id": "gc_q13RLDOQwjdp6EvK5JXxYaBZ",
                "code": "************Q25Y",
                "balance": 25000,
                "currency": "EUR"
            }
        ],
        "reporting_labels": ,
        "metadata": {
            "source": "partner_embedded_commerce",
            "external_reference": "ORD-123456789"
        }
    }
}
Request Body
All fields from preview request, and:

  • consent
  • object
  • required
What the customer agreed to:
  • consumer_terms, required: accepted (must be true) and version.
  • privacy_policy, required: accepted (must be true) and version.
  • marketing_emails, optional: true or false.
  • reporting_labels
  • array
  • optional
Reporting labels to group transactions and reports.

  • metadata
  • object
  • optional
Your reference data. Only "source" and "external_reference" are stored, all other fields are ignored.

GET Retrieve Order

https://api.gifty.nl/v1/external-orders/:order

The Order object can be retrieved by providing the order identifier returned when the order was created. Only orders created through the External Orders API can be retrieved.

Request
HTTP
GET /v1/external-orders/or_rB4kAgGwOzda3MvMxN09q62y HTTP/1.1
Host: api.gifty.nl
Accept: application/json
Response
JSON
{
    "data": {
        "id": "or_rB4kAgGwOzda3MvMxN09q62y",
        "created_at": "2025-08-29T13:48:56+00:00",
        "status": "pending",
        "currency": "EUR",
        "fulfillment": {
            "mode": "digital",
            "status": "pending"
        },
        "customer": {...},
        "line_items": [...],
        "shipping": null,
        "amounts": {...},
        "gift_cards": [
            {
                "id": "gc_q13RLDOQwjdp6EvK5JXxYaBZ",
                "code": "************Q25Y",
                "balance": 25000,
                "currency": "EUR"
            }
        ],
        "reporting_labels": ,
        "metadata": {
            "source": "partner_embedded_commerce",
            "external_reference": "ORD-123456789"
        }
    }
}
Path Parameters
  • order
  • string
  • required
The ID of the order, as returned by the Create Order endpoint.
Live and fixed values

The "status", the "fulfillment.status" and the "balance" of each gift card always reflect the current state of the order.

The "amounts", "line_items" and "shipping" reflect the order as it was placed and do not change afterwards.

The "shipping" attribute is null for orders without physical fulfillment.

Webhooks

This API can be used to automate the creation and configuration of webhooks. For more information about the webhooks integration itself, please refer to its respective .

The Webhook object

AttributeTypeDescription
idstringUnique identifier for the webhook.
namestringName of the webhook, for your own reference.
endpointstringHTTPS endpoint URL which the requests should be sent to.
is_activebooleanIndicates if the webhook is active. If false, no requests will be sent to the endpoint.
notifications_enabledbooleanWhen enabled, we will actively monitor the health of your webhook and will inform you about high error rates and consecutive failures.
eventsarrayThe events the webhook is subscribed to. For a list of available events, please refer to the webhooks integration .
created_atstringISO 8601 time of creation.

GET List All Webhooks

https://api.gifty.nl/v1/webhooks

This call returns all Webhook objects.

Request
HTTP
GET /v1/webhooks?limit=10 HTTP/1.1
Host: api.gifty.nl
Accept: application/json
Response
JSON
{
  "data": [
    {
        "id": "wh_q3WeLra4wvNkKD1mA1P8Zx0Y",
        "name": "General Webhook",
        "endpoint": "https://example.com/webhooks/general",
        "is_active": true,
        "notifications_enabled": true,
        "events": [
          "giftcard.issued",
          "giftcard.redeemed",
          "giftcard.expired",
          "transaction.captured",
          "transaction.released"
        ],
        "created_at": "2025-05-11T14:54:32+00:00"
    },
    {...}
  ]
}
Query Parameters
  • limit
  • integer
  • optional
The number of results to show. Defaults to 10 and should be between 1 and 100.

  • cursor_before
  • string
  • optional
Pagination cursor ID. See the pagination section for usage instructions.

  • cursor_after
  • string
  • optional
Pagination cursor ID, for the results after this object. Cannot be combined with cursor_before.

GET Retrieve Webhook

https://api.gifty.nl/v1/webhooks/:webhook

The Webhook object can be retrieved by providing the webhook identifier.

Request
HTTP
GET /v1/webhooks/wh_ABCDEFGHIJK HTTP/1.1
Host: api.gifty.nl
Accept: application/json
Response
JSON
{
  "data": {
    "id": "wh_ABCDEFGHIJK",
    "name": "Location Synchronization Webhook",
    "endpoint": "https://example.com/locations-sync",
    "is_active": true,
    "notifications_enabled": false,
    "events": [
      "location.created",
      "location.deleted",
      "location.updated"
    ],
    "created_at": "2025-02-23T18:14:45+00:00"
  }
}
Path Parameters
  • webhook
  • string
  • required
The ID of the webhook.

PUT Update Webhook

https://api.gifty.nl/v1/webhooks/:webhook

The Webhook object can be updated by providing the webhook identifier, together with the updated body. The 'secret' parameter is immutable for security reasons and cannot be updated.

Request
HTTP
PUT /v1/webhooks/wh_ABCDEFGHIJK HTTP/1.1
Host: api.gifty.nl
Accept: application/json
Content-Type: application/json

{
    "name": "Transactions Monitoring",
    "status": "active",
    "notifications_enabled": true,
    "endpoint": "https://example.com/transactions/monitor",
    "events": [
      "transaction.captured",
      "transaction.released",
      "transaction.created"
    ]
}
Response
JSON
{
  "data": {
    "id": "wh_ABCDEFGHIJK",
    "name": "Transactions Monitoring",
    "endpoint": "https://example.com/transactions/monitor",
    "is_active": true,
    "notifications_enabled": true,
    "events": [
      "transaction.captured",
      "transaction.released",
      "transaction.created"
    ],
    "created_at": "2025-02-23T18:14:45+00:00"
  }
}
Path Parameters
  • webhook
  • string
  • required
The ID of the webhook.
Request Body
  • name
  • string
  • required
The name of the webhook, for your own reference.

  • endpoint
  • string
  • required
Should be a HTTPS URL, without redirects. This is the URL that will receive the webhook events.

  • events
  • array
  • optional
The events to subscribe to. For a list of available events, please refer to the .

  • status
  • string
  • required
Can be either 'active' or 'inactive'.

  • notifications_enabled
  • boolean
  • required
Whether you want to receive health notifications for this webhook.

POST Create Webhook

https://api.gifty.nl/v1/webhooks

A Webhook object can be created to receive real-time notifications about events in the Gifty API.

Request
HTTP
POST /v1/webhooks HTTP/1.1
Host: api.gifty.nl
Accept: application/json
Content-Type: application/json

{
    "name": "Synchronization Webhook",
    "secret": "85801eac-122a-44f6-9b4c-dbc81ff2f4e0",
    "events": [
        "giftcard.issued",
        "giftcard.redeemed",
        "giftcard.expired",
        "giftcard.extended",
        "giftcard.topped_up"
    ],
    "endpoint": "https://example.com/sync",
    "status": "active",
    "notifications_enabled": true
}
Response
JSON
{
  "data": {
    "id": "wh_kOWB2x0QVvE87xzn6GX7p1oL",
    "name": "Synchronization Webhook",
    "endpoint": "https://example.com/sync",
    "is_active": true,
    "notifications_enabled": true,
    "events": [
        "giftcard.issued",
        "giftcard.redeemed",
        "giftcard.expired",
        "giftcard.extended",
        "giftcard.topped_up"
    ],
    "created_at": "2025-12-30T13:03:52+00:00"
  }
}
Request Body
  • name
  • string
  • required
The name of the webhook, for your own reference.

  • endpoint
  • string
  • required
Should be a HTTPS URL, without redirects. This is the URL that will receive the webhook events.

  • secret
  • string
  • required
A private key used to verify webhook authenticity. At least 16 characters.

  • events
  • array
  • optional
The events to subscribe to. For a list of available events, please refer to the .

  • status
  • string
  • required
Can be either 'active' or 'inactive'.

  • notifications_enabled
  • boolean
  • optional
Whether you want to receive health notifications for this webhook.

DELETE Delete Webhook

https://api.gifty.nl/v1/webhooks/:webhook

A Webhook object can be deleted. This will stop all notifications for the webhook and remove it from the system.

Request
HTTP
DELETE /v1/webhooks/wh_ABCDEFGHIJK HTTP/1.1
Host: api.gifty.nl
Accept: application/json
Path Parameters
  • webhook
  • string
  • required
The ID of the webhook.