Ctrlk
CommunitySupport PortalYouTubeFree trialSign Up!
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Execute

Run a chain of existing cart operations in one request.

Executing a chain of cart commands

post

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.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
cartIdstringRequired

Cart unique identifier generated when a cart is created.

tenantstring · min: 3 · max: 16Required

Your Emporix tenant name.

Note: The tenant should always be written in lowercase.

Pattern: ^[a-z][a-z0-9]+$
Query parameters
onErrorstring · enumOptional

Controls whether the chain stops after the first non-2xx command.

Possible values:

  • fail – Stop after the first non-2xx command. results contains only the commands that ran, including the failed one.
  • resume – Run every command. Later commands still see earlier successful mutations.

An invalid value returns 400 for the whole request before any command runs.

Default: failPossible values:
versioningstring · enumOptional

If-Match strategy for participating writes (AddCartItem, UpdateCartItem, UpdateCart, ApplyCartDiscount).

Possible values:

  • skip – Never pass a version. Ignore options.resourceVersion if present.
  • 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.
  • 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.

An invalid value returns 400 for the whole request before any command runs.

Default: skipPossible values:
Header parameters
session-idstringOptional

Anonymous customer unique session identifier. Shared by every command in the chain. Commands cannot override this header.

legal-entity-idstringOptional

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.

Body

Body of POST /cart/{tenant}/carts/{cartId}/execute. Between 1 and 10 commands.

Responses
207

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.

application/json

Body of a 207 execute response. Present only when the chain was accepted and executed.

post/cart/{tenant}/carts/{cartId}/execute
POST /cart/{tenant}/carts/{cartId}/execute HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 304

{
  "commands": [
    {
      "type": "AddCartItem",
      "data": {
        "itemYrn": "urn:yaas:saasag:caasproduct:product:yourTenant;mobile-phone-s24-gross",
        "quantity": 2,
        "price": {
          "priceId": "679ca63dbcdefe5b380c98bc",
          "originalAmount": 350,
          "effectiveAmount": 350,
          "currency": "EUR"
        }
      }
    },
    {
      "type": "GetCart",
      "options": {
        "expandCalculation": true
      }
    }
  ]
}
{
  "results": [
    {
      "index": 0,
      "type": "AddCartItem",
      "code": 201,
      "status": "Created",
      "data": {
        "itemId": "3",
        "yrn": "urn:yaas:saasag:caascart:item:yourTenant;6a86b20c2f5961330a8b3eb6;3"
      }
    },
    {
      "index": 1,
      "type": "GetCart",
      "code": 200,
      "status": "OK",
      "data": {
        "id": "6a86b20c2f5961330a8b3eb6",
        "currency": "EUR",
        "siteCode": "main",
        "type": "shopping",
        "items": [
          {
            "id": "3",
            "quantity": 2,
            "effectiveQuantity": 2,
            "itemYrn": "urn:yaas:saasag:caasproduct:product:yourTenant;mobile-phone-s24-gross",
            "unitPrice": {
              "netValue": 294.118,
              "grossValue": 350,
              "taxValue": 55.882,
              "taxCode": "STANDARD",
              "taxRate": 19
            },
            "calculatedPrice": {
              "price": {
                "netValue": 588.235,
                "grossValue": 700,
                "taxValue": 111.765,
                "taxCode": "STANDARD",
                "taxRate": 19,
                "calculated": "INTERNAL"
              },
              "finalPrice": {
                "netValue": 588.235,
                "grossValue": 700,
                "taxValue": 111.765,
                "taxCode": "STANDARD",
                "taxRate": 19,
                "calculated": "INTERNAL"
              }
            }
          }
        ],
        "calculatedPrice": {
          "price": {
            "netValue": 588.235,
            "grossValue": 700,
            "taxValue": 111.765
          },
          "finalPrice": {
            "netValue": 588.235,
            "grossValue": 700,
            "taxValue": 111.765
          }
        }
      }
    }
  ]
}
PreviousDiscounts
NextModels

Last updated

Was this helpful?