From 873820b208fb1e3a8759390f660a2078fbb0385c Mon Sep 17 00:00:00 2001 From: Deepa Kumari Date: Wed, 15 Jul 2026 14:26:56 +0530 Subject: [PATCH 1/7] 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) From 63168ae70c220c184335f1a20b2d51cdd5fcd518 Mon Sep 17 00:00:00 2001 From: DeepaAdobe Date: Wed, 29 Jul 2026 17:48:20 +0530 Subject: [PATCH 2/7] AC-16808: Document the new Free Gift cart price rule action type --- src/pages/graphql/schema/cart/mutations/select-free-gift.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/src/pages/graphql/schema/cart/mutations/select-free-gift.md b/src/pages/graphql/schema/cart/mutations/select-free-gift.md index f723146d5..19e2e626f 100644 --- a/src/pages/graphql/schema/cart/mutations/select-free-gift.md +++ b/src/pages/graphql/schema/cart/mutations/select-free-gift.md @@ -5,6 +5,9 @@ description: The selectFreeGiftForCart mutation defines the product that a shopp # selectFreeGiftForCart mutation + +This mutation is part of the Storefront Compatibility Package and is only available on [Adobe Commerce as a Cloud Service](https://experienceleague.adobe.com/en/docs/commerce/cloud-service/overview). + 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: From 194f5d93072d2714716e14d95b90e2a1dad32642 Mon Sep 17 00:00:00 2001 From: DeepaAdobe Date: Tue, 4 Aug 2026 13:00:44 +0530 Subject: [PATCH 3/7] AC-16808: Document the new Free Gift cart price rule action type --- .../graphql/schema/cart/mutations/select-free-gift.md | 8 -------- 1 file changed, 8 deletions(-) diff --git a/src/pages/graphql/schema/cart/mutations/select-free-gift.md b/src/pages/graphql/schema/cart/mutations/select-free-gift.md index 19e2e626f..d0590b147 100644 --- a/src/pages/graphql/schema/cart/mutations/select-free-gift.md +++ b/src/pages/graphql/schema/cart/mutations/select-free-gift.md @@ -21,14 +21,6 @@ After the shopper selects a gift, the mutation adds the product to the cart as a `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 From 50149b3f40d4655866aa05b57a2716d051da73fd Mon Sep 17 00:00:00 2001 From: DeepaAdobe Date: Thu, 3 Sep 2026 13:10:52 +0530 Subject: [PATCH 4/7] AC-16808::Document the new Free Gift cart price rule action type --- .../schema/cart/mutations/select-free-gift.md | 80 ++++++++++++++----- 1 file changed, 60 insertions(+), 20 deletions(-) diff --git a/src/pages/graphql/schema/cart/mutations/select-free-gift.md b/src/pages/graphql/schema/cart/mutations/select-free-gift.md index d0590b147..a56c22612 100644 --- a/src/pages/graphql/schema/cart/mutations/select-free-gift.md +++ b/src/pages/graphql/schema/cart/mutations/select-free-gift.md @@ -21,6 +21,14 @@ After the shopper selects a gift, the mutation adds the product to the cart as a `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 @@ -214,27 +222,59 @@ mutation { } } ``` +**Response:** -## 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. | +```json +{ + "data": { + "selectFreeGiftForCart": { + "cart": { + "has_available_free_gifts": false, + "itemsV2": { + "items": [ + { + "uid": "Mg==", + "quantity": 1, + "is_free_gift": false, + "product": { + "sku": "WSH12", + "name": "Gwen Drawstring Bike Short" + }, + "prices": { + "price": { + "value": 32, + "currency": "USD" + } + } + }, + { + "uid": "Mjc=", + "quantity": 1, + "is_free_gift": true, + "product": { + "sku": "WSH12", + "name": "Gwen Drawstring Bike Short" + }, + "prices": { + "price": { + "value": 0, + "currency": "USD" + } + } + } + ], + "total_count": 2, + "page_info": { + "page_size": 20, + "current_page": 1, + "total_pages": 1 + } + } + } + } + } +} +``` ## Errors From cdde8ba27e2cf5c4ffb744ca021d8632de4c5ca7 Mon Sep 17 00:00:00 2001 From: Kevin Harper Date: Thu, 3 Sep 2026 11:26:56 -0500 Subject: [PATCH 5/7] add fragment --- src/pages/graphql/schema/cart/mutations/select-free-gift.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/pages/graphql/schema/cart/mutations/select-free-gift.md b/src/pages/graphql/schema/cart/mutations/select-free-gift.md index d0590b147..f0e516cf4 100644 --- a/src/pages/graphql/schema/cart/mutations/select-free-gift.md +++ b/src/pages/graphql/schema/cart/mutations/select-free-gift.md @@ -5,8 +5,7 @@ description: The selectFreeGiftForCart mutation defines the product that a shopp # selectFreeGiftForCart mutation - -This mutation is part of the Storefront Compatibility Package and is only available on [Adobe Commerce as a Cloud Service](https://experienceleague.adobe.com/en/docs/commerce/cloud-service/overview). + 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. @@ -23,6 +22,8 @@ After the shopper selects a gift, the mutation adds the product to the cart as a ## Example usage +The following examples show how to determine which Free Gift rules require a selection and how to select a gift SKU for a rule. + ### 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. From de7c932b95afc157fee876e11ab71662fe3689f1 Mon Sep 17 00:00:00 2001 From: Kevin Harper Date: Thu, 3 Sep 2026 11:30:38 -0500 Subject: [PATCH 6/7] linting --- src/pages/graphql/schema/cart/mutations/select-free-gift.md | 1 + 1 file changed, 1 insertion(+) diff --git a/src/pages/graphql/schema/cart/mutations/select-free-gift.md b/src/pages/graphql/schema/cart/mutations/select-free-gift.md index ecd30a933..d2758d30d 100644 --- a/src/pages/graphql/schema/cart/mutations/select-free-gift.md +++ b/src/pages/graphql/schema/cart/mutations/select-free-gift.md @@ -223,6 +223,7 @@ mutation { } } ``` + **Response:** ```json From 6478e50282f2c10a7bdc4c1f77648bcb0a86d1a8 Mon Sep 17 00:00:00 2001 From: Kevin Harper Date: Thu, 3 Sep 2026 13:28:19 -0500 Subject: [PATCH 7/7] Comment out reference section --- src/pages/graphql/schema/cart/mutations/select-free-gift.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/pages/graphql/schema/cart/mutations/select-free-gift.md b/src/pages/graphql/schema/cart/mutations/select-free-gift.md index d2758d30d..3805e90cf 100644 --- a/src/pages/graphql/schema/cart/mutations/select-free-gift.md +++ b/src/pages/graphql/schema/cart/mutations/select-free-gift.md @@ -20,13 +20,13 @@ After the shopper selects a gift, the mutation adds the product to the cart as a `mutation: {selectFreeGiftForCart(input: SelectFreeGiftForCartInput!): SelectFreeGiftForCartOutput}` -## Reference +\