# Gifty API.

> Source: https://docs.gifty.nl/nl/api
> Language: nl

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](https://gifty.nl/contact).

<a id="introduction"></a>

## Introduction

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

<a id="authentication"></a>

### 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`

<a id="error-handling"></a>

### Error Handling

If there are validation issues or other unexpected events, an error will be thrown in the format shown below. Along with the request, a corresponding HTTP header is sent.

| Code | Meaning |
| --- | --- |
| 2XX | Successful request. |
| 4XX | The request is invalid. For example, because the requested resource does not exist. These errors are expected and should be gracefully processed. |
| 5XX | Ouch. 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."
    }
  ]
}
```

<a id="localization"></a>

### 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`

<a id="rate-limiting"></a>

### Rate Limiting

The API is limited to 120 requests per minute. If you exceed this limit, access to the API will be temporarily disabled. Please get in touch with us if you think this limit does not meet your requirements.

<a id="idempotency"></a>

### Idempotency

[Idempotency](https://en.wikipedia.org/wiki/Idempotence), in the context of APIs, means that if you (accidentally) send the same request multiple times, the result will be the same as if you sent it only once. This prevents issues like duplicate transactions or unintended changes to resources, like accidentally redeeming the same gift card more than once due to a networking error.

You can instruct the API to treat a request as idempotent by adding the `X-Gifty-Idempotency-Key` header to your request, along with a unique key as the value. We recommend using [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) version 4 as the value, but you can use any format that fits your needs, as long as it matches the criteria explained below.

| Header | Description | Regex |
| --- | --- | --- |
| X-Gifty-Idempotency-Key | The 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.

<a id="pagination"></a>

### 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.

If you need to become more familiar with cursor pagination, it might confuse you first. Cursor pagination is more efficient and predictable than *offset* pagination. Let's take a look at the example below. We paginate through the list of four locations, show two results per page and do not pass a cursor. So we see 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](https://docs.gifty.nl/images/content/cursor-pagination-1637676663Oq0r3.svg)

<a id="currencies"></a>

### 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.

| Code | Currency |
| --- | --- |
| EUR | Euro |

<a id="gift-cards"></a>

## Gift Cards

In most use cases, gift cards are the most important objects using the Gifty API. Gift cards represent a monetary value. You activate the card and add a balance by *issuing* a gift card (credit). Later, *redeeming* a gift card reduces the balance (debit).

<a id="the-gift-card-object"></a>

### The Gift Card object

| Attribute | Type | Description |
| --- | --- | --- |
| id | `string` | Unique identifier for the card. |
| balance | `integer` | The current balance of the card, in cents. A negative balance is not possible. |
| currency | `string` | ISO 4217 code of the currency. All transactions on this card are required to be made in the same currency. |
| promotional | `boolean` | True if the card is marked as *promotional*. |
| is_redeemable | `boolean` | Indicates 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_issuable | `boolean` | Indicates if a new issue transaction can be made on the card. This attribute is `false` if there are transactions made on this card already. |
| is_extendable | `boolean` | Indicates 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_at | `string` or `null` | ISO 8601 time of expiration or null if the gift card won't expire. |
| created_at | `string` | ISO 8601 time of creation. |
| package | `string` or `null` | The corresponding package ID. |
| transactions |  | All corresponding transactions made on the card. |
| images |  | URLs to images that visualize the card. |

<a id="get-retrieve-gift-card"></a>

### 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",
    "transactions": [ ...TransactionObject ],
    "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 card, 16 characters long. Do not send hyphens (-), spaces or other special characters in the request.

<a id="post-redeem-gift-card"></a>

### 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,
    "captured_at": null,
    "created_at": "2019-01-06T19:10:49+00:00",
    "giftcard": ...GiftCardObject
  }
}
```

Path Parameters

- giftcard
- string
- required

 The code of the card, 16 characters long. Do not send hyphens (-) in the request.

Request Body

- amount
- int
- 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.

<a id="post-issue-gift-card"></a>

### 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,
    "captured_at": "2019-01-08T11:43:44+00:00",
    "created_at": "2019-01-08T11:43:44+00:00",
    "giftcard": ...GiftCardObject
  }
}
```

Path Parameters

- giftcard
- string
- required

 The code of the card, 16 characters long. Do not send hyphens (-) in the request.

Request Body

- amount
- int
- 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](https://docs.gifty.nl/nl/api#packages).

<a id="post-extend-gift-card"></a>

### 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": true,
    "captured_at": "2023-02-23T14:16:32+00:00",
    "created_at": "2023-02-23T14:16:32+00:00",
    "giftcard": ...GiftCardObject
  }
}
```

Path Parameters

- giftcard
- string
- required

 The code of the card, 16 characters long. Do not send hyphens (-) in the request.

Request Body

- expires_at
- string
- required

 ISO 8601 time of expiration. Should be in the future.

<a id="transactions"></a>

## Transactions

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

<a id="the-transaction-object"></a>

### The Transaction object

| Attribute | Type | Description |
| --- | --- | --- |
| id | `string` | Unique identifier for the transaction. |
| amount | `integer` | The 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. |
| currency | `string` | ISO 4217 code of the currency. Should always be the same as the corresponding gift card. |
| status | `string` | The status of the transaction. Can be one of: *success*, *pending* or *cancelled*. |
| type | `string` | Indicates the reason for the transaction. Can be one of: *issue*, *top_up*, *redeem*, *release*, *refund*, *block*, *expire*, *reverse_issue*, *reverse_top_up*, *reverse_redeem* or *reverse_expire*. |
| description | `string` | Provides more information about the transaction. |
| is_capturable | `boolean` | Indicates if a capture can be made on the transaction. This attribute is *false* if the transaction is captured or cancelled already. |
| captured_at | `string` or `null` | ISO 8601 time of capturing. As long as this value is null the transaction can be cancelled. |
| refund_details | `object` | Available for transactions with type 'refund'. Contains the original transaction ID, refund reason and description of the transaction. |
| created_at | `string` | ISO 8601 time of creation. |
| giftcard |  | The corresponding gift card of the transaction. |
| location |  | The location linked to the transaction. |

<a id="get-list-all-transactions"></a>

### 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,
      "captured_at": "2021-11-10T23:32:12+00:00",
      "created_at": "2021-11-10T23:32:12+00:00",
      "giftcard": ...GiftCardObject,
      "location": ...LocationObject
    },
    {...}
  ]
}
```

Query Parameters

- giftcard
- string
- optional

 Only return transactions for this gift card ID.   

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

<a id="get-retrieve-transaction"></a>

### 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,
    "captured_at": "2018-11-03T12:41:41+00:00",
    "created_at": "2018-11-03T12:41:41+00:00",
    "giftcard": ...GiftCardObject,
    "location": ...LocationObject
  }
}
```

Path Parameters

- transaction
- string
- required

 The ID of the transaction.

<a id="post-capture-transaction"></a>

### 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,
    "captured_at": "2019-01-06T19:41:31+00:00",
    "created_at": "2019-01-06T19:10:49+00:00",
    "giftcard": ...GiftCardObject,
    "location": ...LocationObject
  }
}
```

Path Parameters

- transaction
- string
- required

 The ID of the transaction.

<a id="delete-release-transaction"></a>

### 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,
    "captured_at": "2019-01-06T19:49:05+00:00",
    "created_at": "2019-01-06T19:49:05+00:00",
    "giftcard": ...GiftCardObject,
    "location": ...LocationObject
  }
}
```

Path Parameters

- transaction
- string
- required

 The ID of the transaction.

<a id="post-refund-transaction"></a>

### 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,
    "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": ...GiftCardObject,
    "location": ...LocationObject
  }
}
```

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.

<a id="locations"></a>

## 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.

`X-Gifty-Location: REPLACE_WITH_LOCATION_ID`

<a id="the-location-object"></a>

### The Location object

| Attribute | Type | Description |
| --- | --- | --- |
| id | `string` | Unique identifier for the transaction. |
| street | `string` | Address street. |
| house_number | `string` | Address house number. |
| addition | `string` or `null` | Address house number addition. |
| postal_code | `string` | Address postal code. |
| city | `string` | Address city. |
| country_code | `string` | Address country code in two-letter format. |

<a id="get-list-all-locations"></a>

### 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.

<a id="packages"></a>

## 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.

<a id="the-package-object"></a>

### The Package object

| Attribute | Type | Description |
| --- | --- | --- |
| id | `string` | Unique identifier for the package. |
| title | `string` | Title of the package. |
| description | `string` | Description of the package. |
| amount | `integer` | The amount this package represents in cents. |
| amount_visible | `boolean` | Indicates if the amount is displayed on the gift card. |
| currency | `string` | ISO 4217 code of the currency. |
| active | `boolean` | Indicates if the package is available for purchase. |

<a id="get-list-all-packages"></a>

### 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.

<a id="get-retrieve-package"></a>

### 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.

<a id="external-orders"></a>

## 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.

<a id="integration-flow"></a>

### Integration flow

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

1. **Fetch Configuration:** get available products, customizations, 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

<a id="caching"></a>

### 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.

<a id="data-models"></a>

### Data Models

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

#### Product Types

| Type | Description |
| --- | --- |
| gift_card | Variable or fixed price gift cards. |
| gift_card_package | Pre-defined packages with set values. |

#### Fulfillment Modes

| Mode | Description |
| --- | --- |
| digital | Email delivery. |
| physical | Postal delivery. |

#### Order Status

| Status | Description |
| --- | --- |
| pending | Order received, processing not started. |
| processing | Order is being fulfilled. |
| completed | Order fulfilled, gift cards activated. |
| cancelled | Order was cancelled. |

#### Customization Types

| Type | Description | Available For |
| --- | --- | --- |
| personalised_message | Add custom text to gift card. | physical, digital |
| gift_wrapping | Add decorative wrapping. | physical only |

<a id="get-configuration"></a>

### GET Configuration

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

Returns the complete configuration required to place and order including products, customizations and shipping options.

**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_2gxa9kQJYbm5gn584K1G7VOy"]
                        },
                        "pricing": {
                            "model": "variable",
                            "application": "per_item",
                            "currency": "EUR",
                            "variable": true
                        },
                        "available_for": ["physical"]
                    }
                ]
            }
        ],
        "customization_definitions": {
            "gift_wrapping": [
                {
                    "id": "wr_2gxa9kQJYbm5gn584K1G7VOy",
                    "title": "Confetti",
                    "pricing": {
                        "model": "fixed",
                        "application": "per_item",
                        "currency": "EUR",
                        "price": {...}
                    },
                    "images": [
                        {"type": "FRONT_SMALL","url": "https://cdn.gifty.nl/preview/wr_sample/small.png"}
                    ]
                }
            ]
        },
        "shipping": {
            "available_countries": ["NL", "BE"],
            "methods": [
                {
                    "id": "dm_lK8wJE5RLNdo3dAe6bqrjGak",
                    "type": "letter_post",
                    "title": "Letter post",
                    "description": "Sent via letter post.",
                    "available_countries": ["NL","BE"],
                    "countries": [
                        {
                            "code": "NL",
                            "pricing": {
                                "model": "fixed",
                                "application": "per_item",
                                "currency": "EUR",
                                "price": {...}
                            },
                            "schedule_rules": {"cutoff_time": "15:30","timezone": "Europe/Amsterdam"},
                            "delivery_estimates": {...}
                        },
                        {
                            "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 the merchant.

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

Shipping methods can be limited to specific countries. Each country has its own pricing, schedule rules and delivery estimates.

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, customizations or shipping methods may take a few minutes to be reflected in the configuration.

<a id="post-preview-order"></a>

### 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_2gxa9kQJYbm5gn584K1G7VOy"}
      ]
    }
  ],
  "customer": {
    "name": "John Doe",
    "email": "john.doe@gifty.nl",
    "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_2gxa9kQJYbm5gn584K1G7VOy"
  }
}
```

**Response**

```json
{
  "data": {
    "amounts": {
      "line_items": 29565,
      "customisations": 572,
      "shipping": 558,
      "subtotal": 30695,
      "tax": 237,
      "total": 30932
    },
    "shipping": {
      "method": {
        "id": "dm_2gxa9kQJYbm5gn584K1G7VOy",
        "type": "track-n-trace",
        "title": "Track & Trace",
        "carrier": "PostNL",
        "pricing": {...}
      },
      "schedule": {
        "cutoff_time": "2025-08-29T17:30:00+02:00",
        "ships_on": "2025-09-01",
        "delivers_between": {
          "earliest": "2025-09-02",
          "latest": "2025-09-03"
        }
      }
    }
  }
}
```

Request Body

- currency
- string
- required

 ISO 4217 code of the currency.   

- fulfillment
- object
- required

 Fulfillment mode configuration   

- line_items
- array
- required

 Products to order   

- customer
- object
- required

 Customer information   

- shipping
- object
- optional

 Shipping details

<a id="post-create-order"></a>

### 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": "john.doe@gifty.nl",
    "phone": "+31612345678",
    "locale": "en"
  },
  "consent": {
    "consumer_terms": {
      "accepted": true,
      "version": "2024-11-23"
    },
    "privacy_policy": {
      "accepted": true,
      "version": "2025-03-20"
    }
  },
  "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": [...],
        "amounts": {...},
        "gift_cards": [
            {
                "id": "gc_q13RLDOQwjdp6EvK5JXxYaBZ",
                "code": "************Q25Y",
                "balance": 25000,
                "currency": "EUR"
            }
        ],
        "metadata": {
            "source": "partner_embedded_commerce",
            "external_reference": "ORD-123456789"
        }
    }
}
```

Request Body

All fields from preview request, and:   

- consent
- object
- required

 Customer consent confirmations   

- metadata
- object
- optional

 Your reference data

<a id="get-retrieve-order"></a>

### 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": [...],
        "amounts": {...},
        "gift_cards": [
            {
                "id": "gc_q13RLDOQwjdp6EvK5JXxYaBZ",
                "code": "************Q25Y",
                "balance": 25000,
                "currency": "EUR"
            }
        ],
        "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" object is only present for orders with physical fulfillment. Unlike the preview response, it does not contain "available_methods" or a "cutoff_time", because those describe shipping options at the moment of ordering and are not meaningful for an order retrieved later.

<a id="webhooks"></a>

## 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 [documentation](https://docs.gifty.nl/nl/webhooks).

<a id="the-webhook-object"></a>

### The Webhook object

| Attribute | Type | Description |
| --- | --- | --- |
| id | `string` | Unique identifier for the webhook. |
| name | `string` | Name of the webhook, used for internal reference. |
| endpoint | `string` | HTTPS endpoint URL which the requests should be sent to. |
| is_active | `boolean` | Indicates if the webhook is active. If false, no requests will be sent to the endpoint. |
| notifications_enabled | `boolean` | When enabled, we will actively monitor the health of your webhook and will inform you about high error rates and consecutive failures. |
| events | `object` | An object containing the events you will receive updates about. For a list of available events, please refer to the webhooks integration [documentation](https://docs.gifty.nl/nl/webhooks). |
| created_at | `string` | ISO 8601 time of creation. |

<a id="get-list-all-webhooks"></a>

### 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.issue",
          "giftcard.redeem",
          "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.

<a id="get-retrieve-webhook"></a>

### 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.

<a id="put-update-webhook"></a>

### 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
- object
- required

 An object containing the events you want to subscribe to. For a list of available events, please refer to the [documentation](https://docs.gifty.nl/nl/webhooks).   

- status
- string
- required

 Can be either 'active' or 'inactive'.   

- notifications_enabled
- boolean
- required

 Whether you want to receive health notifications for this webhook.

<a id="post-create-webhook"></a>

### 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. Should match the requirements as described in the [documentation](https://docs.gifty.nl/nl/webhooks).   

- events
- object
- required

 An object containing the events you want to subscribe to. For a list of available events, please refer to the [documentation](https://docs.gifty.nl/nl/webhooks).   

- status
- string
- required

 Can be either 'active' or 'inactive'.   

- notifications_enabled
- boolean
- optional

 Whether you want to receive health notifications for this webhook.

<a id="delete-retrieve-webhook"></a>

### DELETE Retrieve 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.