ApplyGiftCardToCartMutation

Description

Applies a gift card to the cart. This mutation allows you to add a gift card to a cart, which may reduce the total price based on the gift card's value.

Endpoint

mutation applyGiftCardToCart($cartId: String!, $giftCardCode: String!) {
  applyGiftCardToCart(cartId: $cartId, giftCardCode: $giftCardCode) {
    # Return fields
  }
}

Arguments

Argument	Type	Required	Description
cartId	String	Yes	The unique identifier of the cart to which the gift card will be applied. This ID is obtained from createGuestCart or createCustomerCart mutations.
giftCardCode	String	Yes	The gift card code to apply to the cart.

Return Values

The mutation returns a CartType object with the following structure:

Field	Type	Description
billing_address	Object	The billing address associated with the cart.
shipping_address	Object	The shipping address associated with the cart.
items	[CartItem]	Array of items in the cart.
selected_shipping_method	Object	The selected shipping method for the cart.
selected_payment_method	Object	The selected payment method for the cart.
totals	Object	Cart totals information, including any discounts applied by the gift card.

For detailed information about the structure of these fields, refer to the CartQuery documentation.

Usage Example

mutation {
  applyGiftCardToCart(
    cartId: "abc123",
    giftCardCode: "GC12345678"
  ) {
    items {
      id
      quantity
      name
      row_total {
        value
        currency
      }
    }
    totals {
      grand_total {
        value
        currency
      }
      gift_card_amount {
        value
        currency
      }
    }
  }
}

Example Response

{
  "data": {
    "applyGiftCardToCart": {
      "items": [
        {
          "id": "123",
          "quantity": 2,
          "name": "Sample Product",
          "row_total": {
            "value": 39.98,
            "currency": "USD"
          }
        }
      ],
      "totals": {
        "grand_total": {
          "value": 29.98,
          "currency": "USD"
        },
        "gift_card_amount": {
          "value": 10.00,
          "currency": "USD"
        }
      }
    }
  }
}

Notes

• If the gift card code is invalid or cannot be applied to the cart, an error will be thrown with a descriptive message.
• Multiple gift cards can be applied to a cart, up to the store's configured limit.
• The gift card amount will be deducted from the cart total. If the gift card value exceeds the cart total, the remaining balance may be available for future use, depending on the store's configuration.
• To remove a gift card from the cart, use the removeGiftCardFromCart mutation.
• Gift cards may have expiration dates or other restrictions set by the store administrator.