diff --git a/src/pages/config.md b/src/pages/config.md index 9ee938678..98160cec7 100644 --- a/src/pages/config.md +++ b/src/pages/config.md @@ -229,6 +229,7 @@ - [removeItemFromCart](/graphql/schema/cart/mutations/remove-item.md) - [removeRewardPointsFromCart](/graphql/schema/cart/mutations/remove-reward-points.md) - [removeStoreCreditFromCart](/graphql/schema/cart/mutations/remove-store-credit.md) + - [selectFreeGiftForCart](/graphql/schema/cart/mutations/select-free-gift.md) - [setBillingAddressOnCart](/graphql/schema/cart/mutations/set-billing-address.md) - [setGiftOptionsOnCart](/graphql/schema/cart/mutations/set-gift-options.md) - [setGuestEmailOnCart](/graphql/schema/cart/mutations/set-guest-email.md) diff --git a/src/pages/graphql/schema/cart/mutations/index.md b/src/pages/graphql/schema/cart/mutations/index.md index 6188c0ad0..b6666d698 100644 --- a/src/pages/graphql/schema/cart/mutations/index.md +++ b/src/pages/graphql/schema/cart/mutations/index.md @@ -23,6 +23,7 @@ The cart mutations allow you to perform the following operations: * [`clearCart`](clear-cart.md) * [`addVirtualProductsToCart`](add-virtual-products.md) * [`removeItemFromCart`](remove-item.md) + * [`selectFreeGiftForCart`](select-free-gift.md) * [`setGiftOptionsOnCart`](set-gift-options.md) * [`updateCartItems`](update-items.md) diff --git a/src/pages/graphql/schema/cart/mutations/select-free-gift.md b/src/pages/graphql/schema/cart/mutations/select-free-gift.md new file mode 100644 index 000000000..3805e90cf --- /dev/null +++ b/src/pages/graphql/schema/cart/mutations/select-free-gift.md @@ -0,0 +1,295 @@ +--- +title: selectFreeGiftForCart mutation +description: The selectFreeGiftForCart mutation defines the product that a shopper has selected as a free gift. +--- + +# selectFreeGiftForCart mutation + + + +The `selectFreeGiftForCart` mutation defines the product that a shopper has selected as a free gift. This mutation is applicable only when a Free Gift cart price rule has been applied to the cart and the rule requires the shopper to choose a gift SKU before placing the order. + +Some Free Gift rules add a gift to the cart automatically. Other rules offer multiple SKUs, or a product with configurable or bundle options, and require the shopper to make a selection. Use the following [`Cart`](../queries/cart.md) fields to determine whether a selection is needed and which products are eligible: + +* `has_available_free_gifts` is `true` when at least one applied Free Gift rule is still waiting for the shopper to select a SKU. +* `available_free_gifts` lists each rule that requires a selection, along with its `rule_id`, `gift_qty`, `available_skus`, and the corresponding `products`. + +After the shopper selects a gift, the mutation adds the product to the cart as a free-gift line item. Line items added by a Free Gift rule return `true` for the `is_free_gift` field on the [`CartItemInterface`](../interfaces/index.md). After the order is placed, the corresponding order item returns the rule label in the `free_gift_label` field on the `OrderItemInterface`. + +## Syntax + +`mutation: {selectFreeGiftForCart(input: SelectFreeGiftForCartInput!): SelectFreeGiftForCartOutput}` + +\