> 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. With auto-restore enabled (the default), when the order is reopened for editing the amount it used is restored, and when the editing is completed the amount required by the edited order is debited again. When the order is cancelled, whatever it still holds on the gift card is restored, so the same amount is never restored twice — even if it's cancelled while being edited.

If the [organization](/core-api-reference/organization.md)'s `gift_cards_auto_restore` setting is disabled, the balance is restored neither on editing nor on cancellation. When an edit is completed, only the difference from the amount already debited is charged, or credited back if the edited order uses less of the gift card.

All of this happens 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" %}
Since, with auto-restore enabled, 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.