Gift Cards

Overview

In SCAYLE Checkout, customers can use gift cards to discount the order total they need to pay. Once a gift card is attached to the customer, its remaining balance is automatically applied to the order, reducing the amount due at confirmation.

For developers, gift card handling is exposed through two endpoints in the headless Checkout API: one to attach a gift card to the customer (which also reserves the balance and applies it to the order) and one to detach an attached gift card from the order's recurring payment options.

Prerequisites

Before integrating gift card flows in your headless checkout, make sure you have:

A working headless checkout integration following the steps in Initialize Checkout.
Gift cards enabled and configured for your shop. For setup, refer to How to enable your customers to pay with gift cards.
A basket and customer (guest or logged-in) already established in the current checkout session.

Step-by-Step Instructions

1. Attach a gift card to the customer

To apply a gift card to the current order, attach it to the customer via the dedicated endpoint:

Endpoint: POST /api/payment/customer/giftcard

You must include the following fields in the request payload:

giftCardCode — the code printed on or issued with the gift card. Required.
giftCardPin — the PIN associated with the gift card. Optional, depending on the gift card provider.
asPaymentMethod — set to true to use the gift card as a payment method on the current order.

When the request is processed, Checkout issues a gift card reservation call (a balance check). If the card has a positive balance, it is attached to the customer and the discount is automatically applied to the order. You do not need to call any additional endpoint to apply the discount — attaching the gift card to the customer is enough.

For developers: On success, the gift card details are included in the state response under orderState.payment.giftCards. Each entry in this list represents one attached gift card, including its recurringPaymentOptionId, which you will need for detachment.

2. Detach a gift card from the order

If a customer wants to remove a gift card from the order, use the recurring payment option deletion endpoint:

Endpoint: DELETE /api/co/v3/state/order/payment/recurring/{id}

The {id} value is the recurringPaymentOptionId returned in the state response under orderOptions.payment.giftCards.X.recurringPaymentOptionId, where X is the index of the gift card you want to remove.

After a successful detachment, the next state response will no longer include the removed gift card under orderState.payment.giftCards, and the discount it provided will no longer be applied to the order total.