> For the complete documentation index, see [llms.txt](https://developer.emporix.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.emporix.io/api-references/readme/api-reference-5/execute.md). # Execute Run a chain of existing cart operations in one request. ## Executing a chain of cart commands > Runs a sequence of existing cart operations in one HTTP request. Cart, item, and discount REST endpoints stay unchanged.\ > \`POST /cart/{tenant}/carts/{cartId}/execute\` is an additional, opt-in way to call the same operations. The cart id is the path\ > parameter. The service copies it onto every command. One request is one cart.\ > \ > A typical storefront flow is \`AddCartItem\` followed by \`GetCart\` with \`expandCalculation\` set to \`true\`. The 207 \`results\`\ > array already contains the created item and the calculated cart, so the client does not send a second \`GET\` unless it wants a\ > later refresh. The two-call sequence (\`POST .../items\` then \`GET .../carts/{cartId}\`) continues to work.\ > \ > Request duration is approximately the sum of the chained commands. The client saves a network round trip, not the calculation\ > work. Clients and API gateways must set timeouts for the full chain, especially when a command runs cart calculation.\ > \ > The service does not send HTTP requests to the existing REST URLs. Downstream calls inside those operations (price, product,\ > cart calculation) still happen, the same as in the equivalent REST calls.\ > \ > For command types, error handling, session and legal entity, versioning, and whole-request validation errors, see\ > \[How to add an item and retrieve the calculated cart in one request]\( > \ > \### Additional scopes information\ > \ > \* \`cart.cart\_manage\` – Use when a service token manages carts that do not belong to the request customer.\ > \* \`cart.cart\_manage\_external\_prices\` – Use when a command payload includes an external price, product, fee, or discount. ```json {"openapi":"3.0.0","info":{"title":"Cart Service","version":"0.0.1"},"tags":[{"name":"Execute","description":"Run a chain of existing cart operations in one request."}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"CustomerAccessToken":[]},{"OAuth2":["cart.cart_manage"]}],"components":{"securitySchemes":{"CustomerAccessToken":{"type":"http","scheme":"bearer"},"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"cart.cart_manage":"Needed to manage carts. This scope is only required for OAuth2 authorization method to authorize the request with the `access_token`.","cart.cart_manage_external_prices":"Needed to manage external prices, products, fees and discounts. It's required only when an external price, product, fee or discount is provided."}}}}},"parameters":{"trait_tenant":{"name":"tenant","in":"path","required":true,"description":"Your Emporix tenant name.\n\n**Note**: The tenant should always be written in lowercase.\n","schema":{"pattern":"^[a-z][a-z0-9]+$","minLength":3,"maxLength":16,"type":"string"}}},"schemas":{"executeRequest":{"type":"object","description":"Body of `POST /cart/{tenant}/carts/{cartId}/execute`. Between 1 and 10 commands.","required":["commands"],"properties":{"commands":{"type":"array","minItems":1,"maxItems":10,"description":"Commands to run sequentially. Maximum 10. Request duration is approximately the sum of the chained commands.\n\nEach item needs `type`. `data` is the REST request body and is omitted for commands that have no body. The cart id is the path parameter. `options` holds remaining path and query equivalents (`itemId`, `partial`, `expandCalculation`, `zipCode`, `countryCode`, `resourceVersion`, `codes`, `discountIndex`).\n","items":{"$ref":"#/components/schemas/executeCommand"}}}},"executeCommand":{"type":"object","description":"One operation in the execute chain. `type` selects the REST equivalent. `data` is that endpoint’s request body. The cart id is the execute path parameter. `options` fields are remaining path and query equivalents (`itemId`, `partial`, `expandCalculation`, `zipCode`, `countryCode`, `resourceVersion`, `codes`, `discountIndex`).\n\nSession and legal-entity identity are request headers, not command fields.\n","required":["type"],"properties":{"type":{"type":"string","description":"Operation to run.\n\nPossible values:\n* `AddCartItem`\n* `UpdateCartItem`\n* `DeleteCartItem`\n* `DeleteCartItems`\n* `GetCart`\n* `AddCartItemsBatch`\n* `UpdateCartItemsBatch`\n* `UpdateCart`\n* `ApplyCartDiscount`\n* `GetCartDiscounts`\n* `DeleteCartDiscounts`\n* `DeleteCartDiscount`\n* `RefreshCart`\n* `ValidateCart`\n","enum":["AddCartItem","UpdateCartItem","DeleteCartItem","DeleteCartItems","GetCart","AddCartItemsBatch","UpdateCartItemsBatch","UpdateCart","ApplyCartDiscount","GetCartDiscounts","DeleteCartDiscounts","DeleteCartDiscount","RefreshCart","ValidateCart"]},"data":{"description":"Request body of the equivalent REST operation.\n\n* `AddCartItem` – cart item body\n* `UpdateCartItem` – cart item update body\n* `AddCartItemsBatch` – list of cart item bodies\n* `UpdateCartItemsBatch` – list of cart item updates (maximum 50)\n* `UpdateCart` – cart update body\n* `ApplyCartDiscount` – discount body\n\nOmit `data` for `GetCart`, `RefreshCart`, `ValidateCart`, deletes, `GetCartDiscounts`, `DeleteCartDiscounts`, and `DeleteCartDiscount`.\n\nThe service selects the body type from `type`. A single item body is an object. Batch commands send an array.\n","oneOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{"type":"object","additionalProperties":true}}]},"options":{"$ref":"#/components/schemas/executeCommandOptions"}}},"executeCommandOptions":{"type":"object","description":"Remaining path and query equivalents for the command. Required fields depend on `type`. The cart id is the execute path parameter, not an option.","properties":{"itemId":{"type":"string","description":"Cart item unique identifier generated when the product is added to the cart.\n\nRequired for `UpdateCartItem` and `DeleteCartItem`.\n"},"partial":{"type":"boolean","default":false,"description":"When `true`, only the provided item or batch fields are updated. Same default as the REST `partial` query parameter (`false`).\n\nUsed by `UpdateCartItem` and `UpdateCartItemsBatch`.\n"},"expandCalculation":{"type":"boolean","default":true,"description":"When `true`, `GetCart` returns a fully calculated cart. Same default as the REST `expandCalculation` query parameter (`true`).\n\nUsed by `GetCart`.\n"},"zipCode":{"type":"string","minLength":1,"maxLength":9,"description":"Zip code of the shipping address, used for tax calculations, shipping cost estimations, and pricing. Provide together with `countryCode` if either is specified.\n\nUsed by `GetCart`.\n"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"Two-letter country code of the shipping address. Provide together with `zipCode` if either is specified.\n\nUsed by `GetCart`.\n"},"resourceVersion":{"type":"integer","description":"Cart resource version used as If-Match for participating writes (`AddCartItem`, `UpdateCartItem`, `UpdateCart`, `ApplyCartDiscount`).\n\n* `versioning=skip` – ignored\n* `versioning=explicit` – required on every participating command (whole-request preflight)\n* `versioning=follow` – required to seed the first participating write; omit on later writes\n\nExtra `resourceVersion` on `GetCart`, `ValidateCart`, `RefreshCart`, deletes, and itemsBatch is ignored.\n"},"codes":{"type":"array","items":{"type":"string"},"description":"Discount codes to remove. If omitted, `DeleteCartDiscounts` removes all discounts. Same meaning as the REST `codes` query parameter.\n\nUsed by `DeleteCartDiscounts`.\n"},"discountIndex":{"type":"string","description":"Index of the discount in the cart discounts array.\n\nRequired for `DeleteCartDiscount`.\n"}}},"executeResponse":{"type":"object","description":"Body of a 207 execute response. Present only when the chain was accepted and executed.","required":["results"],"properties":{"results":{"type":"array","description":"Ordered results for commands that ran. With `onError=fail`, the array stops after the first non-2xx command.\n","items":{"$ref":"#/components/schemas/executeCommandResult"}}}},"executeCommandResult":{"type":"object","description":"Result of one command in the execute chain. `data` matches the REST response body for that command.","required":["index","type","code","status"],"properties":{"index":{"type":"integer","minimum":0,"description":"Zero-based index of the command in the request `commands` array."},"type":{"type":"string","description":"Command type that produced this result."},"code":{"type":"integer","description":"HTTP status code of the equivalent REST operation."},"status":{"type":"string","description":"HTTP reason phrase that matches `code`."},"data":{"description":"Response body of the equivalent REST operation. Omitted when that endpoint returns 204.\n\nA single-object body (`AddCartItem`, `GetCart`, `ApplyCartDiscount`, `ValidateCart`, or an error) is an object. `GetCartDiscounts`, `AddCartItemsBatch`, and `UpdateCartItemsBatch` return an array. Failures use the same error shape as REST (`code`, `status`, `message`).\n","nullable":true,"oneOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{"type":"object","additionalProperties":true}}]},"headers":{"type":"object","additionalProperties":{"type":"string"},"description":"Response headers for this command.\n\nWhen a participating write applied If-Match, this object contains `hybris-resource-version` set to the version after the write. `versioning=skip` does not send If-Match, so the header is absent.\n\n`AddCartItemsBatch` does not use this object for item locations. Each created item's `data[].headers.location` uses the same location as REST `POST .../itemsBatch`.\n"}}},"ErrorMessage":{"title":"error","description":"Schema for API-specific errors.","type":"object","properties":{"code":{"description":"Original HTTP error code. It should be consistent with the HTTP response code.","type":"integer"},"status":{"description":"HTTP Status","type":"string"},"message":{"description":"Descriptive error message for debugging purposes.","type":"string"}}}},"responses":{"trait_401":{"description":"Given request is unauthorized - the authorization token is invalid or has expired.\n\nDetails will be provided in the response payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"trait_403":{"description":"Given authorization scopes are not sufficient and do not match scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"trait_500":{"description":"Some server-side error occurred. Details will be provided in the response payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}}},"paths":{"/cart/{tenant}/carts/{cartId}/execute":{"post":{"tags":["Execute"],"summary":"Executing a chain of cart commands","operationId":"POST-cart-execute","description":"Runs a sequence of existing cart operations in one HTTP request. Cart, item, and discount REST endpoints stay unchanged.\n`POST /cart/{tenant}/carts/{cartId}/execute` is an additional, opt-in way to call the same operations. The cart id is the path\nparameter. The service copies it onto every command. One request is one cart.\n\nA typical storefront flow is `AddCartItem` followed by `GetCart` with `expandCalculation` set to `true`. The 207 `results`\narray already contains the created item and the calculated cart, so the client does not send a second `GET` unless it wants a\nlater refresh. The two-call sequence (`POST .../items` then `GET .../carts/{cartId}`) continues to work.\n\nRequest duration is approximately the sum of the chained commands. The client saves a network round trip, not the calculation\nwork. Clients and API gateways must set timeouts for the full chain, especially when a command runs cart calculation.\n\nThe service does not send HTTP requests to the existing REST URLs. Downstream calls inside those operations (price, product,\ncart calculation) still happen, the same as in the equivalent REST calls.\n\nFor command types, error handling, session and legal entity, versioning, and whole-request validation errors, see\n[How to add an item and retrieve the calculated cart in one request](https://developer.emporix.io/api-documentation/api-guides/checkout/cart/cart#how-to-add-an-item-and-retrieve-the-calculated-cart-in-one-request).\n\n### Additional scopes information\n\n* `cart.cart_manage` – Use when a service token manages carts that do not belong to the request customer.\n* `cart.cart_manage_external_prices` – Use when a command payload includes an external price, product, fee, or discount.","parameters":[{"$ref":"#/components/parameters/trait_tenant"},{"name":"onError","in":"query","required":false,"description":"Controls whether the chain stops after the first non-2xx command.\n\nPossible values:\n* `fail` – Stop after the first non-2xx command. `results` contains only the commands that ran, including the failed one.\n* `resume` – Run every command. Later commands still see earlier successful mutations.\n\nAn invalid value returns **400** for the whole request before any command runs.\n","schema":{"type":"string","enum":["fail","resume"],"default":"fail"}},{"name":"versioning","in":"query","required":false,"description":"If-Match strategy for participating writes (`AddCartItem`, `UpdateCartItem`, `UpdateCart`, `ApplyCartDiscount`).\n\nPossible values:\n* `skip` – Never pass a version. Ignore `options.resourceVersion` if present.\n* `explicit` – Every participating command must send `options.resourceVersion`. Missing version on any participating write returns **400** for the whole request (preflight). This is not `skip`.\n* `follow` – Seed from the first participating write, then use that cursor for later writes. After the cursor exists, a successful `RefreshCart`, delete, or itemsBatch also bumps it.\n\nAn invalid value returns **400** for the whole request before any command runs.\n","schema":{"type":"string","enum":["skip","explicit","follow"],"default":"skip"}},{"name":"session-id","in":"header","required":false,"schema":{"type":"string"},"description":"Anonymous customer unique session identifier. Shared by every command in the chain. Commands cannot override this header.\n"},{"name":"legal-entity-id","in":"header","required":false,"schema":{"type":"string"},"description":"Legal entity of the shopper context. Shared by every command in the chain. Commands cannot override this header. To act as a different legal entity, send another request.\n"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/executeRequest"}}}},"responses":{"207":{"description":"The command chain was accepted and executed. `results` lists each command that ran. This status is used for all-2xx chains and for partial failures.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/executeResponse"}}}},"400":{"description":"The execute request is invalid. No command ran. `results` is not returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"401":{"$ref":"#/components/responses/trait_401"},"403":{"$ref":"#/components/responses/trait_403"},"500":{"$ref":"#/components/responses/trait_500"}}}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://developer.emporix.io/api-references/readme/api-reference-5/execute.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.