> For the complete documentation index, see [llms.txt](https://docs.commercelayer.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.commercelayer.io/core-api-reference/gift_cards.md).

# Gift cards

The gift card object and the allowed CRUD operations on the related resource endpoint

A gift card is a special type of payment instrument that can be either purchased or used to pay for an order — in total or in part — depending on its outstanding balance. All gift cards must be activated before being used. Rechargeable gift cards can be reloaded at any time. Single-use gift cards become redeemed after the first usage, regardless of how much of the balance is used.

{% hint style="info" %}
You can set an expiration date for a gift card. Expired gift cards cannot be used anymore, but they remain active so that you can use them again once the expiration date is updated.
{% endhint %}

You can associate a gift card to a market if you want to restrict its availability to that specific market. Check the `balance_log` attribute to browse the history of a gift card's balance changes and the `usage_log` attribute for more information about how, when, and by which order the gift card has been used.

### Balance usage and restore

A gift card's balance is debited when the order that uses it is placed, and automatically restored when that order is cancelled — regardless of whether the associated payment was only authorized or already captured, since the gift card and the payment gateway are tracked independently.

{% hint style="warning" %}
Because the restore always happens on order cancellation, if you also restore or recharge a gift card manually (e.g. as part of a custom return flow) before cancelling the related order, the balance will be credited twice: once by your own logic and once automatically by the platform.
{% endhint %}

{% hint style="info" %}
You can cap how much a restore can credit back by setting the `balance_max_cents` attribute on the gift card. When present, any restore — automatic or otherwise — is capped at that value rather than added without limit, which can help contain the impact of an unexpected double restore.
{% endhint %}

### Discount calculation and distribution

Unless you set the `distribute_discount` attribute to `false` (default is `true`) at the single gift card level, the total discount due to gift cards used to pay for an order is calculated and distributed on all the [taxable items](/core-api-reference/orders.md#taxable-items) of the order, based on the ratio between the line item amount and the sum of the amounts of all the line items to which the promotion is applied.

{% hint style="warning" %}
If you set the `distribute_discount` attribute to `false` and the price list associated with the market where you're placing the order does not include taxes (i.e. the [price list](/core-api-reference/price_lists.md) `tax_included` attribute is set to `false`), the discount will be applied to the whole order amount plus taxes. This means that if the gift card balance is greater enough, it will saturate both the order amount and taxes amount. In any other case, only the order amount (taxes excluded) will be considered when applying the gift card discount.
{% endhint %}

<details>

<summary>Data model</summary>

Check the related [ER diagram](/data-model/promo-and-loyalty/promotions-and-gift-cards.md) and explore the flowchart that illustrates how the gift card resource relates to the other API entities.

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.commercelayer.io/core-api-reference/gift_cards.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.