From 873820b208fb1e3a8759390f660a2078fbb0385c Mon Sep 17 00:00:00 2001 From: Deepa Kumari Date: Wed, 15 Jul 2026 14:26:56 +0530 Subject: [PATCH 01/23] 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 02/23] 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 03/23] 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 0f65810bdd0e83922165eda5d15d24ce1b0f08eb Mon Sep 17 00:00:00 2001 From: Sangmi Lee Date: Mon, 10 Aug 2026 14:01:56 +0200 Subject: [PATCH 04/23] ACCS-1448: document search filter on customer.orders Adds a "Search a customer's order history" example showing the new search filter (matches order number, product name, or SKU) added to CustomerOrdersFilterInput via the Storefront Compatibility Package. --- .../schema/customer/queries/customer.md | 54 +++++++++++++++++++ 1 file changed, 54 insertions(+) diff --git a/src/pages/graphql/schema/customer/queries/customer.md b/src/pages/graphql/schema/customer/queries/customer.md index 3289acbd8..91e418ef8 100644 --- a/src/pages/graphql/schema/customer/queries/customer.md +++ b/src/pages/graphql/schema/customer/queries/customer.md @@ -592,6 +592,60 @@ These topics contain examples with fragments and provide even more details: } ``` +### Search a customer's order history + +The following example uses the `search` filter to return orders matching a term against the order number or an item's product name or SKU. `search` is combined with other filters, such as `status`, using AND logic. The matched item is included in the response to show why the order matched the search term. + +**Request:** + +```graphql +{ + customer { + orders(filter: {search: "shirt", status: {eq: "complete"}}) { + total_count + items { + id + number + order_date + status + items { + product_name + product_sku + } + } + } + } +} +``` + +**Response:** + +```json +{ + "data": { + "customer": { + "orders": { + "total_count": 1, + "items": [ + { + "id": "MQ==", + "number": "000000001", + "order_date": "2020-11-14 22:25:48", + "status": "Complete", + "items": [ + { + "product_name": "Aria Flannel Shirt", + "product_sku": "MS12-M-Blue" + } + ] + } + ] + } + } + } +} +``` + ### Retrieve the store credit history The following example returns the store credit history for the logged-in user. From e37a88346d11e0e436c8eda51c047a68838e8d0d Mon Sep 17 00:00:00 2001 From: Kevin Harper Date: Tue, 11 Aug 2026 11:01:46 -0500 Subject: [PATCH 05/23] Document customer order history search functionality Added documentation for searching a customer's order history using filters. --- src/pages/graphql/schema/customer/queries/customer.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/pages/graphql/schema/customer/queries/customer.md b/src/pages/graphql/schema/customer/queries/customer.md index 91e418ef8..77c469b46 100644 --- a/src/pages/graphql/schema/customer/queries/customer.md +++ b/src/pages/graphql/schema/customer/queries/customer.md @@ -594,6 +594,8 @@ These topics contain examples with fragments and provide even more details: ### Search a customer's order history + + The following example uses the `search` filter to return orders matching a term against the order number or an item's product name or SKU. `search` is combined with other filters, such as `status`, using AND logic. The matched item is included in the response to show why the order matched the search term. **Request:** From fb5aaab6ac4a05da9d14572dd492afc44ee5cfbe Mon Sep 17 00:00:00 2001 From: Jared Hoover Date: Wed, 26 Aug 2026 17:48:35 -0500 Subject: [PATCH 06/23] configuration copy --- src/pages/config.md | 1 + src/pages/rest/saas-integrations/index.md | 1 + .../saas-integrations/system-config/index.md | 276 ++++++++++++++++++ 3 files changed, 278 insertions(+) create mode 100644 src/pages/rest/saas-integrations/system-config/index.md diff --git a/src/pages/config.md b/src/pages/config.md index 9ee938678..df590ecfd 100644 --- a/src/pages/config.md +++ b/src/pages/config.md @@ -161,6 +161,7 @@ - [Login as Customer](/rest/saas-integrations/login-as-customer/index.md) - [Order management](/rest/saas-integrations/order-management/index.md) - [S3 uploads](/rest/saas-integrations/s3-uploads/index.md) + - [System configuration](/rest/saas-integrations/system-config/index.md) - [Introduction](/graphql/index.md) - [Usage](/graphql/usage/index.md) - [Authorization](/graphql/usage/authorization-tokens.md) diff --git a/src/pages/rest/saas-integrations/index.md b/src/pages/rest/saas-integrations/index.md index 00293f6fb..5e6151745 100644 --- a/src/pages/rest/saas-integrations/index.md +++ b/src/pages/rest/saas-integrations/index.md @@ -14,3 +14,4 @@ Review the following topics to learn more about REST APIs available only on Adob - [Login as Customer](login-as-customer/index.md) - [Order management](order-management/index.md) - [S3 uploads](s3-uploads/index.md) +- [System configuration](system-config/index.md) diff --git a/src/pages/rest/saas-integrations/system-config/index.md b/src/pages/rest/saas-integrations/system-config/index.md new file mode 100644 index 000000000..ec3d31d2e --- /dev/null +++ b/src/pages/rest/saas-integrations/system-config/index.md @@ -0,0 +1,276 @@ +--- +title: System Configuration REST Endpoints +description: Learn how to use the GET and PUT V1/system/config REST endpoints to sync store, shipping, tax, payment, and B2B settings between sandbox and production. +keywords: + - REST + - Integration +--- + + + +# System configuration API + +The system configuration REST endpoints provide programmatic access to Adobe Commerce as a Cloud Service system configuration values, including store information, shipping and tax settings, payment method settings, and B2B and company settings. Use this endpoint to read configuration from one environment and apply it to another. + +These endpoints are designed for: + +* Developers and administrators who want to sync configuration across Adobe Commerce as a Cloud Service environments as part of a deployment or CI pipeline +* Administrators who copy verified settings from a sandbox environment to production +* Automated workflows that back up or restore configuration values + +## Sync configuration from sandbox to production + +This API endpoint allows you to easily copy configuration values from one environment to another. This section provides a generalized overview of how you could copy values that you were testing in your sandbox environment to production. For details about these endpoints, see: + +- [Retrieve configuration values](#retrieve-configuration-values) +- [Update configuration values](#update-configuration-values) + +1. Call `GET /V1/system/config` on the sandbox environment to retrieve the configuration items you want to sync. Filter by `path` to limit the response to the sections you plan to move. For example, you could [retrieve a single value](#example-retrieve-a-single-configuration-path). + +1. Review the returned `items` array and remove any values that you do not want to update on production. Environment-specific values, such as base URLs, API credentials, and payment gateway keys, typically need different values in production. + +1. Call `PUT /V1/system/config` on the production environment, passing the reviewed items in the request body. + +1. Check the response `errors` array for any rejected items. + + + +Review every item before syncing from sandbox to production. Copying environment-specific values, such as base URLs or payment credentials, can break the production store. + +## Authentication + +All endpoints require a [bearer token](../../authentication/index.md) for authentication. The API only exposes paths that are visible in the Commerce Admin UI and allowed by your [user role](https://experienceleague.adobe.com/en/docs/commerce/cloud-service/user-management#role-resources). + +## REST API reference + +| Method | URL | Description | +|--------|-----|-------------| +| GET | `/V1/system/config` | Retrieve configuration values that match a search criteria | +| PUT | `/V1/system/config` | Update one or more configuration values | + +### Retrieve configuration values + +Returns configuration items that match the given search criteria. Only paths visible in the Commerce Admin UI and allowed by your user role are returned. + +| Item | Value | +|---|---| +| **Method** | `GET` | +| **URL** | `/V1/system/config` | + +#### Query parameters + +| Parameter | Type | Description | +|---|---|---| +| `searchCriteria[filterGroups][0][filters][0][field]` | string | Field to filter on. Use `path` to filter by configuration path. | +| `searchCriteria[filterGroups][0][filters][0][value]` | string | Value to match. For a `path` filter, pass a single path, or a comma-separated list of paths when `conditionType` is `in`. | +| `searchCriteria[filterGroups][0][filters][0][conditionType]` | string | Condition type, such as `eq` for a single path or `in` for a comma-separated list of paths. | +| `searchCriteria[pageSize]` | integer | Number of items per page. If omitted or `0`, the API returns up to 500 paths without pagination. Ignored when a `path` filter is present. | +| `searchCriteria[currentPage]` | integer | Page number to return. Ignored when a `path` filter is present. | +| `scope` | string | Scope to read from: `default`, `website`, or `store`. | +| `scopeCode` | string | Website code or store view code. Omit for the default scope. | + + + +A `path` filter returns exactly the paths you request, so `pageSize` and `currentPage` are ignored. Without a `path` filter, the endpoint falls back to the legacy behavior of returning up to 500 paths. + +#### Example: retrieve a single configuration path + +```text +GET /V1/system/config + ?searchCriteria[filterGroups][0][filters][0][field]=path + &searchCriteria[filterGroups][0][filters][0][value]=sales/totals_sort/tax + &searchCriteria[filterGroups][0][filters][0][conditionType]=eq + &scope=default +``` + +**Response (200):** + +```json +{ + "items": [ + { + "path": "sales/totals_sort/tax", + "value": "40", + "scope": "default" + } + ], + "search_criteria": { + "filter_groups": [ + { + "filters": [ + { + "field": "path", + "value": "sales/totals_sort/tax", + "condition_type": "eq" + } + ] + } + ], + "page_size": 1, + "current_page": 1 + }, + "total_count": 1 +} +``` + +#### Example: retrieve multiple configuration paths + +Use `conditionType=in` with a comma-separated list of paths to retrieve several values in one request: + +```text +GET /V1/system/config + ?searchCriteria[filterGroups][0][filters][0][field]=path + &searchCriteria[filterGroups][0][filters][0][value]=general/locale/code,currency/options/base,payment/checkmo/active + &searchCriteria[filterGroups][0][filters][0][conditionType]=in + &scope=default +``` + +**Response (200):** + +```json +{ + "items": [ + { + "path": "general/locale/code", + "value": "en_US", + "scope": "default" + }, + { + "path": "currency/options/base", + "value": "USD", + "scope": "default" + }, + { + "path": "payment/checkmo/active", + "value": "1", + "scope": "default" + } + ], + "search_criteria": { + "filter_groups": [ + { + "filters": [ + { + "field": "path", + "value": "general/locale/code,currency/options/base,payment/checkmo/active", + "condition_type": "in" + } + ] + } + ], + "page_size": 3, + "current_page": 1 + }, + "total_count": 3 +} +``` + +A path that exists in `system.xml` but has no stored value returns `null`. For example, a fresh environment with no store information configured yet returns `{"path": "general/store_information/name", "value": null, "scope": "default"}`. + +### Update configuration values + +Saves one or more configuration items similar to manually changing the value in the Commerce Admin. If an item fails to save, it does not prevent other items in the same request from being saved. + +| Item | Value | +|---|---| +| **Method** | `PUT` | +| **URL** | `/V1/system/config` | + +#### Request body + +| Field | Type | Required | Description | +|---|---|---|---| +| `items` | array | Yes | Configuration items to save | +| `items[].path` | string | Yes | Configuration path, for example `general/locale/code` | +| `items[].value` | string | Yes | Value to save. Multi-value fields use a delimited string. | +| `items[].scope` | string | Yes | Scope to write to: `default`, `website`, or `store` | +| `items[].scope_code` | string | No | Website code or store view code. Omit for the default scope. | + +**Request body:** + +```json +{ + "items": [ + { + "path": "carriers/flatrate/price", + "value": "6.00", + "scope": "website", + "scope_code": "base" + } + ] +} +``` + +**Response (200):** + +```json +{ + "items": [ + { + "path": "carriers/flatrate/price", + "value": "6.00", + "scope": "website", + "scope_code": "base" + } + ], + "errors": [] +} +``` + +#### Example: a request with a rejected item + +Submitting a path that does not exist, is not visible for the given scope, or is not available due to user permissions, does not fail the whole request. The valid items in the same request are still saved: + +```json +{ + "items": [ + { + "path": "carriers/flatrate/price", + "value": "6.00", + "scope": "website", + "scope_code": "base" + }, + { + "path": "fictional/path", + "value": "x", + "scope": "default" + } + ] +} +``` + +**Response (200):** + +```json +{ + "items": [ + { + "path": "carriers/flatrate/price", + "value": "6.00", + "scope": "website", + "scope_code": "base" + } + ], + "errors": [ + { + "path": "fictional/path", + "scope": "default", + "message": "Configuration path \"fictional/path\" was not found, is not visible for this scope, or is not allowed." + } + ] +} +``` + +The `errors` message does not include the value you submitted, so review the `path` and `scope` of each rejected item and confirm it is visible to the requesting user at that scope before retrying. + +## Error handling + +The API returns standard HTTP status codes: + +| Status code | Condition | +|---|---| +| `200` | Request succeeded. For `PUT`, individual items can still appear in the response `errors` array. | +| `401` | Missing or invalid bearer token. | +| `500` | Internal server error. | + +Rejected items in a `PUT` request are not reported as HTTP errors. Check the response body's `errors` array for the path, scope, and reason for each rejected item. From d3d8eff826b5a7860b4f3b4c7f0fb973248bc632 Mon Sep 17 00:00:00 2001 From: Jared Hoover <98363870+jhadobe@users.noreply.github.com> Date: Fri, 28 Aug 2026 15:15:35 -0500 Subject: [PATCH 07/23] Apply batched suggestions from code review Co-authored-by: Kevin Harper Co-authored-by: Jared Hoover <98363870+jhadobe@users.noreply.github.com> --- src/pages/rest/saas-integrations/system-config/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/pages/rest/saas-integrations/system-config/index.md b/src/pages/rest/saas-integrations/system-config/index.md index ec3d31d2e..8eb88631e 100644 --- a/src/pages/rest/saas-integrations/system-config/index.md +++ b/src/pages/rest/saas-integrations/system-config/index.md @@ -20,7 +20,7 @@ These endpoints are designed for: ## Sync configuration from sandbox to production -This API endpoint allows you to easily copy configuration values from one environment to another. This section provides a generalized overview of how you could copy values that you were testing in your sandbox environment to production. For details about these endpoints, see: +This section provides a generalized overview of how you could copy values that you were testing in your sandbox environment to production. For details about these endpoints, see: - [Retrieve configuration values](#retrieve-configuration-values) - [Update configuration values](#update-configuration-values) @@ -71,7 +71,7 @@ Returns configuration items that match the given search criteria. Only paths vis -A `path` filter returns exactly the paths you request, so `pageSize` and `currentPage` are ignored. Without a `path` filter, the endpoint falls back to the legacy behavior of returning up to 500 paths. +A `path` filter returns exactly the paths you request, so `pageSize` and `currentPage` are ignored. Without a `path` filter, the endpoint returns all available configuration paths. #### Example: retrieve a single configuration path From aaac63b7ef52dd3812716437d2567d6432e40a43 Mon Sep 17 00:00:00 2001 From: Jared Hoover Date: Wed, 2 Sep 2026 13:55:39 -0500 Subject: [PATCH 08/23] draft --- .../graphql/schema/cart/queries/index.md | 2 + .../cart/queries/source-availability.md | 96 +++++++++++++++++++ 2 files changed, 98 insertions(+) create mode 100644 src/pages/graphql/schema/cart/queries/source-availability.md diff --git a/src/pages/graphql/schema/cart/queries/index.md b/src/pages/graphql/schema/cart/queries/index.md index 48520c281..97355ec29 100644 --- a/src/pages/graphql/schema/cart/queries/index.md +++ b/src/pages/graphql/schema/cart/queries/index.md @@ -8,3 +8,5 @@ description: The cart query returns the content of the shopper's cart. Adobe Com The [`cart`](cart.md) query returns the content of the shopper's cart. Adobe Commerce returns the [`Cart`](/reference/graphql/latest/types-c-e.md#cart) object. This object is also returned by numerous mutations, including those that add products to the cart and prepare a cart for checkout. When Inventory Management is installed and configured, you can use the [`pickupLocations`](pickup-locations.md) query to help a shopper determine whether their order can be picked up at a physical location. This query is most useful when the shopper has selected one or more items for purchase. + +Use the [`sourceAvailability`](source-availability.md) query to check per-source inventory availability for one or more SKUs before nominating a source on a cart item. diff --git a/src/pages/graphql/schema/cart/queries/source-availability.md b/src/pages/graphql/schema/cart/queries/source-availability.md new file mode 100644 index 000000000..9bc0e61ba --- /dev/null +++ b/src/pages/graphql/schema/cart/queries/source-availability.md @@ -0,0 +1,96 @@ +--- +title: sourceAvailability query +description: Use the sourceAvailability query to check per-source inventory availability for one or more SKUs, scoped to the current sales channel's assigned stock sources. +--- + + + +# sourceAvailability query + +Use the `sourceAvailability` query to check per-source inventory availability for one or more SKUs. The query reports availability only for the inventory sources assigned and enabled for the current sales channel's stock, and computes availability the same way the order-placement guard does, so a storefront read never disagrees with what checkout allows. + +A merchant admin must enable this query before it returns data. Go to **Stores** > Configuration > **Catalog** > **Inventory** > **Per-Source Availability (Storefront)** and set **Enable sourceAvailability GraphQL Query** to **Yes**. The query is disabled by default because it discloses which sources stock a SKU, and returns an error while disabled. + +Requesting a `source_codes` value that is not assigned to the current sales channel does not return an error. The unrecognized code is silently dropped from the response so its existence is never disclosed. + + + +The exact `available_qty` value is returned only when it is at or below the merchant's storefront display threshold (`cataloginventory/options/stock_threshold_qty`). Above the threshold, `available_qty` is `null` and `is_in_stock` is the only reliable signal. The threshold defaults to `0`, so by default every positive quantity is masked and `is_in_stock` is the authoritative field to check. + +## Syntax + +```graphql +sourceAvailability (skus: [String!]! source_codes: [String!] only_in_stock: Boolean): [SkuSourceAvailability!]! +``` + +| Argument | Description | +| --- | --- | +| `skus` | The product SKUs to report availability for. Required. Accepts up to 100 entries. | +| `source_codes` | Restricts the report to these inventory sources. Accepts up to 100 entries. When omitted, the query reports every source assigned to the current sales channel's stock. | +| `only_in_stock` | When `true`, omits sources where the SKU is not salable. Defaults to `false`. | + +## Reference + +The [`sourceAvailability`](/reference/graphql/saas/index.md#sourceavailability) reference provides detailed information about the types and fields defined in this query. + +## Example usage + +The following query checks availability for a single SKU at two named sources. + +**Request:** + +```graphql +{ + sourceAvailability( + skus: ["24-MB01"] + source_codes: ["default", "east-warehouse"] + only_in_stock: false + ) { + sku + sources { + source_code + sku + available_qty + is_in_stock + } + } +} +``` + +**Response:** + +```json +{ + "data": { + "sourceAvailability": [ + { + "sku": "24-MB01", + "sources": [ + { + "source_code": "default", + "sku": "24-MB01", + "available_qty": null, + "is_in_stock": true + }, + { + "source_code": "east-warehouse", + "sku": "24-MB01", + "available_qty": 0, + "is_in_stock": false + } + ] + } + ] + } +} +``` + +## Errors + +| Error | Description | +| --- | --- | +| `Required parameter "skus" is missing or empty.` | The `skus` argument was omitted or is an empty list. | +| `Parameter "skus" may contain at most 100 entries.` | The `skus` argument contains more than 100 entries. | +| `Parameter "source_codes" must be a list of source codes.` | The `source_codes` argument was provided as a non-list value. | +| `Parameter "source_codes" may contain at most 100 entries.` | The `source_codes` argument contains more than 100 entries. | +| `The per-source availability query is not enabled for this store.` | A merchant admin has not enabled the query for the current store. | From 28a34f6292231659125c4338546fa07f60a2dc5e Mon Sep 17 00:00:00 2001 From: Jared Hoover Date: Wed, 2 Sep 2026 16:01:05 -0500 Subject: [PATCH 09/23] COMDOX-1796 GraphQL for Per source availability --- src/pages/graphql/schema/cart/queries/index.md | 2 -- src/pages/graphql/schema/products/queries/index.md | 1 + .../queries/source-availability.md | 12 ++++-------- 3 files changed, 5 insertions(+), 10 deletions(-) rename src/pages/graphql/schema/{cart => products}/queries/source-availability.md (69%) diff --git a/src/pages/graphql/schema/cart/queries/index.md b/src/pages/graphql/schema/cart/queries/index.md index 97355ec29..48520c281 100644 --- a/src/pages/graphql/schema/cart/queries/index.md +++ b/src/pages/graphql/schema/cart/queries/index.md @@ -8,5 +8,3 @@ description: The cart query returns the content of the shopper's cart. Adobe Com The [`cart`](cart.md) query returns the content of the shopper's cart. Adobe Commerce returns the [`Cart`](/reference/graphql/latest/types-c-e.md#cart) object. This object is also returned by numerous mutations, including those that add products to the cart and prepare a cart for checkout. When Inventory Management is installed and configured, you can use the [`pickupLocations`](pickup-locations.md) query to help a shopper determine whether their order can be picked up at a physical location. This query is most useful when the shopper has selected one or more items for purchase. - -Use the [`sourceAvailability`](source-availability.md) query to check per-source inventory availability for one or more SKUs before nominating a source on a cart item. diff --git a/src/pages/graphql/schema/products/queries/index.md b/src/pages/graphql/schema/products/queries/index.md index 5d642fe72..e03a1bb45 100644 --- a/src/pages/graphql/schema/products/queries/index.md +++ b/src/pages/graphql/schema/products/queries/index.md @@ -16,6 +16,7 @@ This section describes the following queries: * [`productReviewRatingsMetadata`](product-review-ratings-metadata.md) * [`products`](products.md) * [`route`](route.md) +* [`sourceAvailability`](source-availability.md) * [`urlResolver`](url-resolver.md) diff --git a/src/pages/graphql/schema/cart/queries/source-availability.md b/src/pages/graphql/schema/products/queries/source-availability.md similarity index 69% rename from src/pages/graphql/schema/cart/queries/source-availability.md rename to src/pages/graphql/schema/products/queries/source-availability.md index 9bc0e61ba..33c8cece9 100644 --- a/src/pages/graphql/schema/cart/queries/source-availability.md +++ b/src/pages/graphql/schema/products/queries/source-availability.md @@ -7,15 +7,11 @@ description: Use the sourceAvailability query to check per-source inventory avai # sourceAvailability query -Use the `sourceAvailability` query to check per-source inventory availability for one or more SKUs. The query reports availability only for the inventory sources assigned and enabled for the current sales channel's stock, and computes availability the same way the order-placement guard does, so a storefront read never disagrees with what checkout allows. +Use the `sourceAvailability` query to check per-source inventory availability for one or more SKUs. The query reports availability only for the inventory sources assigned and enabled for the current sales channel's stock, so a storefront read never disagrees with what checkout allows. -A merchant admin must enable this query before it returns data. Go to **Stores** > Configuration > **Catalog** > **Inventory** > **Per-Source Availability (Storefront)** and set **Enable sourceAvailability GraphQL Query** to **Yes**. The query is disabled by default because it discloses which sources stock a SKU, and returns an error while disabled. +An admin must enable this query before it returns data. Go to **Stores** > Configuration > **Catalog** > **Inventory** > **Per-Source Availability (Storefront)** and set **Enable `sourceAvailability` GraphQL Query** to **Yes**. The query is disabled by default because it discloses which sources stock a SKU, and returns an error while disabled. -Requesting a `source_codes` value that is not assigned to the current sales channel does not return an error. The unrecognized code is silently dropped from the response so its existence is never disclosed. - - - -The exact `available_qty` value is returned only when it is at or below the merchant's storefront display threshold (`cataloginventory/options/stock_threshold_qty`). Above the threshold, `available_qty` is `null` and `is_in_stock` is the only reliable signal. The threshold defaults to `0`, so by default every positive quantity is masked and `is_in_stock` is the authoritative field to check. +The exact `available_qty` value is returned only when it is at or below the store's **Only X left Threshold** setting. Above the threshold, `available_qty` is `null` and `is_in_stock` is the only reliable signal. This threshold defaults to `0`, so by default every positive quantity is masked and `is_in_stock` is the authoritative field to check. To change it, go to **Stores** > Configuration > **Catalog** > **Inventory** > **Stock Options** and set **Only X left Threshold**. ## Syntax @@ -93,4 +89,4 @@ The following query checks availability for a single SKU at two named sources. | `Parameter "skus" may contain at most 100 entries.` | The `skus` argument contains more than 100 entries. | | `Parameter "source_codes" must be a list of source codes.` | The `source_codes` argument was provided as a non-list value. | | `Parameter "source_codes" may contain at most 100 entries.` | The `source_codes` argument contains more than 100 entries. | -| `The per-source availability query is not enabled for this store.` | A merchant admin has not enabled the query for the current store. | +| `The per-source availability query is not enabled for this store.` | An admin has not enabled the query for the current store. | From 4115a0d52cb7ee01f6a14bbd399d65aa6d36444c Mon Sep 17 00:00:00 2001 From: Jared Hoover Date: Wed, 2 Sep 2026 17:13:28 -0500 Subject: [PATCH 10/23] SCP Example --- .../schema/store/queries/store-config.md | 34 +++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/src/pages/graphql/schema/store/queries/store-config.md b/src/pages/graphql/schema/store/queries/store-config.md index d8ac90123..9b46699c2 100644 --- a/src/pages/graphql/schema/store/queries/store-config.md +++ b/src/pages/graphql/schema/store/queries/store-config.md @@ -223,6 +223,40 @@ The following query returns information about the store's customer configuration } ``` +### Query a store's persistent cart and account sharing configuration + +The following query returns the store's persistent shopping cart settings (**Stores** > Settings > **Configuration** > **Customers** > **Persistent Shopping Cart**) and the account sharing scope (**Stores** > Settings > **Configuration** > **Customers** > **Customer Configuration** > **Account Sharing Options** > **Share Customer Accounts**). + +The `share_customer_accounts_scope` field returns `0` when customer accounts are shared globally across all stores and `1` when accounts are scoped per website. + +**Request:** + +```graphql +{ + storeConfig { + persistent_enabled + persistent_shopping_cart + persistent_options_wishlist + share_customer_accounts_scope + } +} +``` + +**Response:** + +```json +{ + "data": { + "storeConfig": { + "persistent_enabled": true, + "persistent_shopping_cart": true, + "persistent_options_wishlist": false, + "share_customer_accounts_scope": 0 + } + } +} +``` + ### Query a store's access token expiration configuration The following query returns the value of the **Stores** > Settings > **Configuration** > **Services** > **OAuth** > **Access Token Expiration** > **Customer Token Lifetime (hours)** field. From 72776a0ae992bf37647525ba999a8fc075a78a82 Mon Sep 17 00:00:00 2001 From: Jared Hoover Date: Wed, 2 Sep 2026 17:45:02 -0500 Subject: [PATCH 11/23] update custom email --- .../saas-integrations/custom-email/index.md | 83 ++++++++++++++++++- 1 file changed, 82 insertions(+), 1 deletion(-) diff --git a/src/pages/rest/saas-integrations/custom-email/index.md b/src/pages/rest/saas-integrations/custom-email/index.md index cfee71b18..4b1082dc4 100644 --- a/src/pages/rest/saas-integrations/custom-email/index.md +++ b/src/pages/rest/saas-integrations/custom-email/index.md @@ -99,13 +99,15 @@ The API returns HTTP 200 on successful send. The `reply_to_email` field is only ## Manage custom email templates -Use the following endpoints to list, retrieve, and create custom email templates from the REST API. +Use the following endpoints to list, retrieve, create, update, and delete custom email templates from the REST API. | Method | Endpoint | Description | | --- | --- | --- | | `GET` | `/V1/custom-email/templates` | List custom email templates, returning each template's ID, code, subject, and type. | | `GET` | `/V1/custom-email/templates/{id}` | Retrieve a single template, including its body and styles. | | `POST` | `/V1/custom-email/templates` | Create a custom email template and return its server-assigned ID. | +| `PUT` | `/V1/custom-email/templates/{id}` | Update an existing custom email template. | +| `DELETE` | `/V1/custom-email/templates/{id}` | Delete a custom email template. | @@ -260,6 +262,85 @@ The response returns the created template in the same shape as [Retrieve a custo Example: `"message": "A custom email template with code \"my_code\" already exists."` +### Update a custom email template + +Use the following endpoint to update an existing custom email template by its ID. + +#### Endpoint + +- **URL** - `PUT /rest/V1/custom-email/templates/{id}` + +The `{id}` in the URL identifies the template to update. A `template_id` supplied in the request body is ignored. + +#### Request body + +Use a `template` object to contain the fields to update. This is a **partial update**, which means that only the fields present in the request body are changed. Fields that are not included keep their previous value. + +- **template_code** (string, optional) – Must remain unique across templates. Maximum 150 characters. The template being updated is excluded from the uniqueness check, so keeping the existing code is allowed. +- **template_subject** (string, optional) – Maximum 200 characters. Supports the same directive syntax as create, described in [Supported template scenarios](#supported-template-scenarios). +- **template_text** (string, optional) – Raw template body. Directives are stored as-is and are not rendered at update time. +- **template_type** (string, optional) – `html` or `text`. Switching to `text` forces `template_styles` to an empty string. +- **template_styles** (string, optional) – CSS for the template. Ignored when the `template_type` is `text`. + + + +Included fields cannot contain empty values. Sending an empty `template_code`, `template_subject`, or `template_text` returns an **HTTP 400** error. To leave a field unchanged, do not include it. + +#### Example request + +```json +{ + "template": { + "template_subject": "You *still* left something behind", + "template_text": "

Hi {{var customer.name}}, your cart really misses you.

" + } +} +``` + +#### Success response (HTTP 200) + +The response returns the updated template in the same shape as [Retrieve a custom email template](#retrieve-a-custom-email-template). + +#### Error responses + +- **HTTP 400 – Validation error** + + Returned for an over-length value, an invalid `template_type`, or a required field that was supplied as an empty value. + +- **HTTP 404 – Template not found** + + Returned when no custom template matches the given `id`. + +- **HTTP 409 – Duplicate template code** + + Returned when the new `template_code` collides with another existing template. + + Example: `"message": "A custom email template with code \"my_code\" already exists."` + +### Delete a custom email template + +Use the following endpoint to delete a custom email template by its ID. + +#### Endpoint + +- **URL** - `DELETE /rest/V1/custom-email/templates/{id}` + +#### Success response (HTTP 200) + +The API returns `true` in the response body on successful deletion. + +#### Error responses + +- **HTTP 404 – Template not found** + + Returned when no custom template matches the given `id`. + +- **HTTP 409 – Template in use** + + Returned when the template is currently referenced by store configuration, for example assigned as the template for a Sales Email under **Stores** > _Configuration_ > **Sales** > **Sales Emails**. Clear or reassign the configuration, then try the delete call again. + + Example: `"message": "The custom email template with id \"5\" is currently in use and cannot be deleted."` + ## Supported template scenarios The following template features are supported in both the **email body** and the **template subject**: From 50149b3f40d4655866aa05b57a2716d051da73fd Mon Sep 17 00:00:00 2001 From: DeepaAdobe Date: Thu, 3 Sep 2026 13:10:52 +0530 Subject: [PATCH 12/23] 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 13/23] 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 14/23] 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 3791fe6baefc4b6d4672f4d3fe61c79ce2163556 Mon Sep 17 00:00:00 2001 From: Jared Hoover Date: Thu, 3 Sep 2026 12:39:42 -0500 Subject: [PATCH 15/23] add saas tag --- src/pages/graphql/schema/store/queries/store-config.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/pages/graphql/schema/store/queries/store-config.md b/src/pages/graphql/schema/store/queries/store-config.md index 9b46699c2..d46618446 100644 --- a/src/pages/graphql/schema/store/queries/store-config.md +++ b/src/pages/graphql/schema/store/queries/store-config.md @@ -225,6 +225,8 @@ The following query returns information about the store's customer configuration ### Query a store's persistent cart and account sharing configuration + + The following query returns the store's persistent shopping cart settings (**Stores** > Settings > **Configuration** > **Customers** > **Persistent Shopping Cart**) and the account sharing scope (**Stores** > Settings > **Configuration** > **Customers** > **Customer Configuration** > **Account Sharing Options** > **Share Customer Accounts**). The `share_customer_accounts_scope` field returns `0` when customer accounts are shared globally across all stores and `1` when accounts are scoped per website. From b75d78c051e9ac3efe92a0415e0b2effa2af88f2 Mon Sep 17 00:00:00 2001 From: Jared Hoover Date: Thu, 3 Sep 2026 12:52:46 -0500 Subject: [PATCH 16/23] review - template object unified --- .../saas-integrations/custom-email/index.md | 55 +++++++++---------- 1 file changed, 26 insertions(+), 29 deletions(-) diff --git a/src/pages/rest/saas-integrations/custom-email/index.md b/src/pages/rest/saas-integrations/custom-email/index.md index 4b1082dc4..cc086a71c 100644 --- a/src/pages/rest/saas-integrations/custom-email/index.md +++ b/src/pages/rest/saas-integrations/custom-email/index.md @@ -14,7 +14,7 @@ Previously, you could only send emails when events were triggered, such as durin -Currently, only newly created, custom templates can be sent. Predefined and system templates are not supported. +Currently, only customer-created custom templates can be sent. Predefined and system templates are not supported. The `V1/custom-email/send` endpoint allows **third-party systems**, such as integrations and external services, to send emails on demand by specifying: @@ -113,6 +113,21 @@ Use the following endpoints to list, retrieve, create, update, and delete custom Use the `template_id` returned by these endpoints with `POST /V1/custom-email/send` instead of looking up the ID manually. +### Template object + +The `template` object represents a custom email template. Create and update requests wrap these fields in a `template` object, while list and retrieve responses return the same fields at the top level of the response. + +| Field | Type | Description | +| --- | --- | --- | +| `template_id` | integer | Server-assigned identifier. Use it as-is with `POST /V1/custom-email/send`. Read-only, and ignored if supplied in a request body. | +| `template_code` | string | Unique template name. Maximum 150 characters. | +| `template_subject` | string | Template subject, stored as raw, unrendered directive source. Maximum 200 characters. Supports the directive syntax described in [Supported template scenarios](#supported-template-scenarios). | +| `template_text` | string | Raw, unrendered template body. Directives such as `{{var}}` and `{{trans}}` are stored as-is and preserved verbatim. Not returned by the list endpoint. | +| `template_type` | string | `html` or `text`. Defaults to `html` on create. Switching to `text` forces `template_styles` to an empty string. | +| `template_styles` | string | CSS for the template. Empty string for text templates. Not returned by the list endpoint. | +| `added_at` | string | Creation timestamp. Read-only. | +| `modified_at` | string | Last-modified timestamp. Read-only. | + ### List custom email templates Use the following endpoint to list all custom email templates. @@ -125,14 +140,7 @@ The endpoint accepts standard `searchCriteria` parameters for pagination, sortin #### Response fields -| Field | Type | Description | -| --- | --- | --- | -| `template_id` | integer | Usable as-is with `POST /V1/custom-email/send`. | -| `template_code` | string | Template name. | -| `template_subject` | string | Template subject, as raw, unrendered directive source. | -| `template_type` | string | `html` or `text`. | -| `added_at` | string | Creation timestamp. | -| `modified_at` | string | Last-modified timestamp. | +The response includes the [template object](#template-object) fields, except `template_text` and `template_styles`. #### Example request @@ -170,12 +178,7 @@ Use the following endpoint to retrieve a single custom email template by its ID. - **URL** - `GET /rest/V1/custom-email/templates/{id}` -The response includes every field from the list response, plus: - -| Field | Type | Description | -| --- | --- | --- | -| `template_text` | string | Raw, unrendered template body. Directives such as `{{var}}` and `{{trans}}` are preserved, so the value can be sent back verbatim when creating another template. | -| `template_styles` | string | CSS for the template. Empty string for text templates. | +The response includes all [template object](#template-object) fields, including `template_text` and `template_styles`. #### Example request @@ -218,15 +221,12 @@ Commerce returns HTTP 200 (not 201) on success, consistent with other Commerce R #### Request body -Wrap the template fields in a `template` object. - -- **template_code** (string, required) – Unique template name. Maximum 150 characters. -- **template_subject** (string, required) – Maximum 200 characters. May contain directive syntax, as described in [Supported template scenarios](#supported-template-scenarios). -- **template_text** (string, required) – Raw template body. Directives are stored as-is and are not rendered at creation time. -- **template_type** (string, optional) – `html` (default) or `text`. -- **template_styles** (string, optional) – CSS for the template. Ignored, and forced to an empty string, when `template_type` is `text`. +Wrap the template fields in a `template` object. See [Template object](#template-object) for the full field definitions. -The API ignores any value supplied for `template_id`, `added_at`, or `modified_at`, Commerce assigns these automatically. +- **Required** - `template_code`, `template_subject`, and `template_text` +- **Optional** - `template_type` and `template_styles` +- **Read-only** - `template_id`, `added_at`, and `modified_at` + - Commerce assigns these automatically and ignores any supplied values. @@ -274,13 +274,10 @@ The `{id}` in the URL identifies the template to update. A `template_id` supplie #### Request body -Use a `template` object to contain the fields to update. This is a **partial update**, which means that only the fields present in the request body are changed. Fields that are not included keep their previous value. +Wrap the fields to change in a `template` object. The request accepts the same [template object](#template-object) fields as create, with these differences: -- **template_code** (string, optional) – Must remain unique across templates. Maximum 150 characters. The template being updated is excluded from the uniqueness check, so keeping the existing code is allowed. -- **template_subject** (string, optional) – Maximum 200 characters. Supports the same directive syntax as create, described in [Supported template scenarios](#supported-template-scenarios). -- **template_text** (string, optional) – Raw template body. Directives are stored as-is and are not rendered at update time. -- **template_type** (string, optional) – `html` or `text`. Switching to `text` forces `template_styles` to an empty string. -- **template_styles** (string, optional) – CSS for the template. Ignored when the `template_type` is `text`. +- All fields are **optional**. This is a **partial update**, so only the fields present in the request body are changed. Fields that are not included keep their previous value. +- `template_code` is excluded from its own uniqueness check, so keeping the existing code is allowed. From f19952e2f484f144a8a207ac916d89906896e1d0 Mon Sep 17 00:00:00 2001 From: Jared Hoover Date: Thu, 3 Sep 2026 12:58:17 -0500 Subject: [PATCH 17/23] heading change --- src/pages/rest/saas-integrations/custom-email/index.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/pages/rest/saas-integrations/custom-email/index.md b/src/pages/rest/saas-integrations/custom-email/index.md index cc086a71c..3625945ad 100644 --- a/src/pages/rest/saas-integrations/custom-email/index.md +++ b/src/pages/rest/saas-integrations/custom-email/index.md @@ -113,7 +113,7 @@ Use the following endpoints to list, retrieve, create, update, and delete custom Use the `template_id` returned by these endpoints with `POST /V1/custom-email/send` instead of looking up the ID manually. -### Template object +### Template object parameters The `template` object represents a custom email template. Create and update requests wrap these fields in a `template` object, while list and retrieve responses return the same fields at the top level of the response. @@ -140,7 +140,7 @@ The endpoint accepts standard `searchCriteria` parameters for pagination, sortin #### Response fields -The response includes the [template object](#template-object) fields, except `template_text` and `template_styles`. +The response includes the [template object](#template-object-parameters) fields, except `template_text` and `template_styles`. #### Example request @@ -178,7 +178,7 @@ Use the following endpoint to retrieve a single custom email template by its ID. - **URL** - `GET /rest/V1/custom-email/templates/{id}` -The response includes all [template object](#template-object) fields, including `template_text` and `template_styles`. +The response includes all [template object](#template-object-parameters) fields, including `template_text` and `template_styles`. #### Example request @@ -221,7 +221,7 @@ Commerce returns HTTP 200 (not 201) on success, consistent with other Commerce R #### Request body -Wrap the template fields in a `template` object. See [Template object](#template-object) for the full field definitions. +Wrap the template fields in a `template` object. See [Template object](#template-object-parameters) for the full field definitions. - **Required** - `template_code`, `template_subject`, and `template_text` - **Optional** - `template_type` and `template_styles` @@ -274,7 +274,7 @@ The `{id}` in the URL identifies the template to update. A `template_id` supplie #### Request body -Wrap the fields to change in a `template` object. The request accepts the same [template object](#template-object) fields as create, with these differences: +Wrap the fields to change in a `template` object. The request accepts the same [template object](#template-object-parameters) fields as create, with these differences: - All fields are **optional**. This is a **partial update**, so only the fields present in the request body are changed. Fields that are not included keep their previous value. - `template_code` is excluded from its own uniqueness check, so keeping the existing code is allowed. From 6478e50282f2c10a7bdc4c1f77648bcb0a86d1a8 Mon Sep 17 00:00:00 2001 From: Kevin Harper Date: Thu, 3 Sep 2026 13:28:19 -0500 Subject: [PATCH 18/23] 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 +\