Mutation

applyGiftCardToCart

Applies a gift card to a cart.

The code is passed on exactly as given; the gift card provider decides which gift card it means and answers with the canonical spelling, which is what AppliedGiftCard.code resolves to. On success the gift card shows up in Cart.appliedGiftCards and Cart.amountDue drops by the part of the cart it covers.

Several gift cards can be applied to the same cart. They cover it in the order they were applied, each taking the smaller of its balance and what is left to pay, so the one applied last carries the remainder. A gift card is never applied for nothing: if there is nothing left to pay, applying it fails instead.

Nothing is charged here. The gift card sits on the cart as an allocation against the full price and Cart.grandTotal stays as it was.

Every rejection names its reason in extensions.code:

• UnknownCart — no cart with that ID exists.
• GiftCardsNotAccepted — the cart does not take gift cards. See Cart.acceptsGiftCards.
• GiftCardTooManyAttempts — too many codes have been refused from this source lately, so no further code is looked at for now. extensions.data carries retryAfter, a Unix timestamp not to try again before. It is padded, so it is no countdown of what has been spent.
• GiftCardAlreadyApplied — the cart already carries this gift card, however the code was spelled.
• CartAlreadyCovered — the applied gift cards already cover the cart completely.
• UnknownGiftCard — the provider does not know the code.
• GiftCardHasNoBalance — the gift card has nothing left to spend.
• GiftCardCurrencyMismatch — the gift card's currency is not the cart's. extensions.data carries giftCardCurrency and cartCurrency as ISO 4217 codes.
• GiftCardRequiresPin — the gift card is PIN-protected, which is not supported.
• GiftCardNotRedeemableOnline — this kind of gift card is only redeemable in person.
• GiftCardTypeNotAcceptedOnline — gift cards of this kind are not accepted online.
• GiftCardNotRedeemable — the provider refuses the gift card for a reason of its own. extensions.data carries status, the provider's own wording, which nothing can be branched on.
• GiftCardRequiresFullRedemption — the gift card can only be redeemed in full but is worth more than the cart still owes. extensions.data carries balance, amountDue and the currency both are in, with the amounts in minor units.
• GiftCardProviderUnavailable — the provider could not be reached. The cart is untouched, so this can simply be retried.
• GiftCardTimeout — the provider did not answer in time. The work carries on, so the gift card may still land on the cart; read the cart again rather than retrying blindly.
• UnexpectedGiftCardError — the gift card was refused for a reason that has no code of its own. Nothing can be said about the cart afterwards; read it again to find out.

The source those refusals are counted against is the client address the request arrives from. A consumer that dispatches this mutation for many buyers from a server of its own is therefore one source: its buyers share a single budget, and once it is spent the next buyer is refused with GiftCardTooManyAttempts for codes someone else got wrong. Dispatching from each buyer's own client keeps their attempts apart. If that does not fit how your integration works, talk to us about how your buyers can be identified instead.

To take a gift card off the cart again, use removeGiftCardFromCart.