From 873820b208fb1e3a8759390f660a2078fbb0385c Mon Sep 17 00:00:00 2001 From: Deepa Kumari Date: Wed, 15 Jul 2026 14:26:56 +0530 Subject: [PATCH] AC-16808: Document the new Free Gift cart price rule action type --- src/pages/config.md | 1 + .../graphql/schema/cart/mutations/index.md | 1 + .../schema/cart/mutations/select-free-gift.md | 258 ++++++++++++++++++ 3 files changed, 260 insertions(+) create mode 100644 src/pages/graphql/schema/cart/mutations/select-free-gift.md diff --git a/src/pages/config.md b/src/pages/config.md index 5056d7b7f..aa284f645 100644 --- a/src/pages/config.md +++ b/src/pages/config.md @@ -224,6 +224,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..f723146d5 --- /dev/null +++ b/src/pages/graphql/schema/cart/mutations/select-free-gift.md @@ -0,0 +1,258 @@ +--- +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}` + +## Reference + +The `selectFreeGiftForCart` reference provides detailed information about the types and fields defined in this mutation. + +* [Adobe Commerce as a Cloud Service](/reference/graphql/saas/mutations.md#selectfreegiftforcart) + +* [On-Premises/Cloud](/reference/graphql/latest/mutations.md#selectfreegiftforcart) + +## Example usage + +### Determine which free gifts require a selection + +The following query returns the Free Gift rules that are applied to the cart but still need the shopper to choose a gift SKU. + +**Request:** + +```graphql +{ + cart(cart_id: "8k0Q4MpH2IGahWrTRtqM61YV2MtLPApz") { + has_available_free_gifts + available_free_gifts { + rule_id + rule_label + gift_qty + available_skus + products { + sku + name + } + } + } +} +``` + +**Response:** + +```json +{ + "data": { + "cart": { + "has_available_free_gifts": true, + "available_free_gifts": [ + { + "rule_id": 5, + "rule_label": "Free gift with orders over $50", + "gift_qty": 1, + "available_skus": [ + "24-MB01", + "24-MB04" + ], + "products": [ + { + "sku": "24-MB01", + "name": "Joust Duffle Bag" + }, + { + "sku": "24-MB04", + "name": "Strive Shoulder Pack" + } + ] + } + ] + } + } +} +``` + +### Select a free gift + +The following example selects the `24-MB01` gift product for rule `5` and adds it to the cart. The response confirms that the item was added as a free gift. + +**Request:** + +```graphql +mutation { + selectFreeGiftForCart( + input: { + cart_id: "8k0Q4MpH2IGahWrTRtqM61YV2MtLPApz" + rule_id: 5 + sku: "24-MB01" + quantity: 1 + } + ) { + cart { + has_available_free_gifts + itemsV2 { + items { + uid + quantity + is_free_gift + product { + sku + name + } + prices { + price { + value + currency + } + } + } + total_count + page_info { + page_size + current_page + total_pages + } + } + } + } +} +``` + +**Response:** + +```json +{ + "data": { + "selectFreeGiftForCart": { + "cart": { + "has_available_free_gifts": false, + "itemsV2": { + "items": [ + { + "uid": "Mg==", + "quantity": 1, + "is_free_gift": false, + "product": { + "sku": "24-WB05", + "name": "Savvy Shoulder Tote" + }, + "prices": { + "price": { + "value": 32, + "currency": "USD" + } + } + }, + { + "uid": "Mjc=", + "quantity": 1, + "is_free_gift": true, + "product": { + "sku": "24-MB01", + "name": "Joust Duffle Bag" + }, + "prices": { + "price": { + "value": 0, + "currency": "USD" + } + } + } + ], + "total_count": 2, + "page_info": { + "page_size": 20, + "current_page": 1, + "total_pages": 1 + } + } + } + } + } +} +``` + +### Select a gift with product options + +If the gift SKU is a configurable or bundle product, provide the `selected_options` (and, when applicable, `entered_options`) values, in the same way you would when calling the [`addProductsToCart` mutation](add-products.md). + +```graphql +mutation { + selectFreeGiftForCart( + input: { + cart_id: "8k0Q4MpH2IGahWrTRtqM61YV2MtLPApz" + rule_id: 5 + sku: "WSH12" + quantity: 1 + selected_options: [ + "Y29uZmlndXJhYmxlLzkzLzUz" + "Y29uZmlndXJhYmxlLzE2MS8xNzQ=" + ] + } + ) { + cart { + itemsV2 { + items { + uid + is_free_gift + product { + sku + name + } + } + total_count + } + } + } +} +``` + +## Input attributes + +The `SelectFreeGiftForCartInput` object must contain the following attributes. + +| Attribute | Data Type | Description | +| --- | --- | --- | +| `cart_id` | String! | The masked ID of the shopper's cart. | +| `rule_id` | Int! | The identifier of the Free Gift rule the selection is for. Must be a rule that is currently applied to the cart and pending selection. | +| `sku` | String! | The SKU of the gift product to add. Must be one of the rule's configured SKUs. | +| `quantity` | Int | Overrides the rule's configured gift quantity. Must be a positive integer no greater than the rule's `gift_qty`. Defaults to the rule's `gift_qty`. | +| `entered_options` | [[EnteredOptionInput!]](../../products/interfaces/index.md) | An array of custom option values entered by the shopper, such as text inputs. | +| `selected_options` | [ID!] | An array of UIDs that identify selected option values, such as configurable variants or bundle selections. | + +## Output attributes + +The `SelectFreeGiftForCartOutput` object contains the `Cart` object. + +| Attribute | Data Type | Description | +| --- | --- | --- | +| `cart` | [Cart!](../queries/cart.md) | The cart after adding the selected free-gift product. | + +## Errors + +| Error | Description | +| --- | --- | +| `Could not find a cart with ID "XXX"` | The specified `cart_id` value does not exist in the `quote_id_mask` table. | +| `Required parameter "cart_id" is missing` | The mutation does not contain a `cart_id` argument. | +| `The rule ID "XXX" is not currently pending a free gift selection for this cart.` | The specified `rule_id` is not applied to the cart, or it does not require a gift selection. | +| `The SKU "XXX" is not a valid free gift for rule ID "YYY".` | The specified `sku` is not one of the SKUs configured on the rule. | +| `The requested quantity exceeds the free gift quantity allowed by the rule.` | The specified `quantity` is greater than the rule's `gift_qty`. | + +## Related topics + +* [cart query](../queries/cart.md) +* [addProductsToCart mutation](add-products.md) +* [CartItemInterface attributes and implementations](../interfaces/index.md)