> 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/2026-05/payment_setting_gift_cards.md).
# Payment setting gift cards
The payment setting gift card object and the allowed CRUD operations on the related resource endpoint
Gift card payment settings are a plain payment instrument subtype of [payment settings](/core-api-reference/2026-05/payment_settings.md). Unlike gateway-based subtypes, they require no external integration — redemption is resolved entirely within Commerce Layer by matching the provided code against a valid [gift card](/core-api-reference/2026-05/gift_cards.md) scoped to the order's market or currency, and deducting the payment amount from its balance.
{% hint style="info" %}
Since each payment session covers a single gift card, customers can combine multiple gift cards on the same order by creating one session per card.
{% endhint %}
## Capabilities
Gift card payment settings support the following Commerce Layer features:
| Feature | Supported |
|---|
| Payment sessions | true |
| Payment wallets | false |
| Payment links | false |
| 3DS / SCA | false |
## Gift card validation
When a payment session is created with a gift card payment setting, the customer provides a `gift_card_code`. The code is validated against active, unexpired, non-empty gift cards scoped to the order's market or currency. The session amount is capped at the gift card's available balance.
{% hint style="info" %}
The accepted gift card code length is controlled by the [organization](/core-api-reference/2026-05/organization.md)'s `gift_cards_min_code_length` and `gift_cards_max_code_length` settings.
{% endhint %}
## Paying a subscription
A gift card can also fund an [order subscription](/core-api-reference/2026-05/order_subscriptions.md#payment-sessions): the subscription stores this payment setting together with the gift card code, and each run opens a new gift card session on its target order. Since a gift card cannot be vaulted, the code itself is what gets carried from one run to the next.
{% hint style="warning" %}
Unlike a stored card, a gift card can simply run out. Its balance is checked against the target order before every run, and a card that falls short — or can no longer be resolved — fails that run and leaves the subscription `pending`. More on this [here](/core-api-reference/2026-05/order_subscriptions.md#gift-card-coverage).
{% endhint %}
## Invalidation at authorization
The gift card's validity and balance are re-checked when the session's [payment authorization](/core-api-reference/2026-05/payment_authorizations.md) is processed, not only at session creation — time can pass between the two, and the gift card's state may have changed in the meantime (e.g. it was deleted, or its balance was spent elsewhere).
If the gift card can no longer be resolved, or its balance is now lower than the session's amount, the authorization attempt fails outright — without ever reaching `succeeded` — and the payment session moves directly to `invalidated`. No balance is deducted from the gift card.
{% hint style="info" %}
#### Neither a reversal nor an overage
This is a separate path to `invalidated` from the [gateway-reversal](/core-api-reference/2026-05/payment_authorizations.md#invalidation) one. There, a transaction succeeds first and is corrected afterward. Here, it never succeeds at all.
This also differs from a session [whose balance exceeded](/core-api-reference/2026-05/payment_sessions.md#exceeding-the-order-balance). There, the authorization genuinely succeeded and needs reconciling via a void, a refund, or a partial capture. Here, the authorization never succeeds in the first place, so there's nothing to reconcile — simply create a new payment session to retry, e.g. with a different gift card code.
{% endhint %}
{% hint style="warning" %}
A [payment refund](/core-api-reference/2026-05/payment_refunds.md) against a capture whose gift card can no longer be resolved (e.g. it was deleted since the capture was made) still succeeds as a transaction — Commerce Layer doesn't require the gift card to exist to record the refund. Restoring the refunded amount to the gift card's balance is silently skipped in that case, since there's no gift card left to credit.
{% endhint %}
---
# 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/2026-05/payment_setting_gift_cards.md?ask=&goal=
```
`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.