Elastic Path Cart Settings API

openapi: 3.2.0
info:
  title: Carts, Checkout, Orders Introduction Cart Settings API
  description: 'A cart contains a list of the products that a shopper adds to the cart while browsing your catalog. In the context of a cart, a selected product is called a cart item.


    A cart item identifies the product, the product price, the quantity selected, and the total price for the quantity selected. The cart displays a running total of the cost for the selected products plus the calculated tax.


    You can allow your shoppers to add custom text to a product when adding an item to their carts. This is useful, for example, if you have a product like a T-shirt that can be personalized. See [Add product to cart](/docs/api/carts/manage-carts#add-product-to-cart).


    After a shopper checks out, the cart is converted to an order, and you can manually delete the cart. If you don''t delete the cart, it is purged automatically after seven days.


    The preview cart feature allows you to set a future date for your shopping cart and view the promotions that will be available during that time period. This feature enables you to validate your promotion settings and observe how they will be applied in the cart. See [Create a Preview Cart](/docs/api/carts/create-a-cart#preview-cart).


    The following diagram shows a typical cart workflow:


    ![Shows a cart workflow, starting from adding the first item to a cart, through cart creation and checkout](/assets/cart-workflow.png)


    ### Multiple Carts


    Buyers often make purchases based on jobs that they need to perform or outcomes they need to achieve and therefore require more than one shopping cart. For example, a corporate buyer places orders for multiple locations. Each location has a different frequency of ordering and require different products. The buyer can create one cart per location, fill the carts, and then check out the carts quickly. Similarly, shoppers can also create multiple carts for the ease of managing various shopping experiences, such as birthdays or holidays.


    Each cart is discrete and separate. Any updates or changes to one cart has no effect on the other carts. A cart persists, that is, it stays with the buyer or shopper even after they use the cart in a checkout. Carts remain available after a checkout.

    '
  contact:
    name: Elastic Path
    url: https://elasticpath.com
  version: 26.0313.7324347
  x-version-timestamp: 2026-03-13 21:22:42+00:00
  license:
    name: MIT
    url: assets/LICENSE
servers:
- url: https://useast.api.elasticpath.com
  description: US East Production Server
  variables: {}
- url: https://euwest.api.elasticpath.com
  description: EU West Production Server
  variables: {}
security:
- bearerAuth: []
tags:
- name: Cart Settings
  description: 'Use Cart Settings to configure cart behavior for your store, including cart expiry, custom discounts, rule promotions, deferred inventory checks, and cart visibility for admins.

    '
paths:
  /v2/settings/cart:
    get:
      tags:
      - Cart Settings
      summary: Get Cart Settings
      description: Retrieves cart settings.
      operationId: get-v2-settings-cart
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettingsCart'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response.ErrorResponse'
      deprecated: false
    put:
      tags:
      - Cart Settings
      summary: Update Cart Settings
      description: "You can modify the cart expiry settings to set it to any number of days up to 365. Any existing carts default to the expiry of 7 days. To update cart settings in Commerce Manager, see [Updating Cart setting](/docs/commerce-manager/settings/general-settings#updating-cart-settings).\n\nWith update cart settings endpoint, you can:\n\n- Enable or disable custom discounts by setting the `custom_discounts_enabled` field to `true`. This allows you to activate your custom discounts from external services. By default, this setting is determined by the cart settings configured for the store.\n- Enable or disable the use of rule promotions within the cart. You can apply this setting either at the store level using the update cart setting endpoint or individually to a specific cart using the [update a cart](/docs/api/carts/update-a-cart) endpoint.\n- Enable or disable deferred inventory checks by setting `defer_inventory_check` to `true`. When set, stock levels are not verified for products in a cart until checkout.\n- Control whether admins can see all carts or only shopper-associated carts by setting `show_all_carts` to `true` or `false`.\n- Enable or disable location-based item separation by setting `separate_items_by_location` to `true`. When enabled, cart items with the same SKU but different locations are kept as separate line items instead of being merged.\n\n:::note\n\nYou cannot use both custom discounts and rule promotions at the same time.\n\n:::\n\n### Errors\n\nThe following error is received if you enable a cart to use both custom discounts and rule promotions:\n\n```json\n{\n    \"status\": 422,\n    \"title\": \"Cannot use both discounts together\",\n    \"detail\": \"Only one discount setting can be set to true at a time.\"\n}\n```"
      operationId: put-v2-settings-cart
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SettingsCart'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettingsCart'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response.ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response.ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response.ErrorResponse'
      deprecated: false
  /v2/settings/cart/{storeID}:
    parameters:
    - name: storeID
      in: path
      description: The store ID.
      required: true
      schema:
        type: string
    get:
      tags:
      - Cart Settings
      summary: Get Cart Settings by Store ID
      description: Retrieves cart settings for the specified store.
      operationId: get-v2-settings-cart-storeID
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettingsCart'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response.ErrorResponse'
      deprecated: false
    put:
      tags:
      - Cart Settings
      summary: Update Cart Settings by Store ID
      description: "You can modify the cart expiry settings to set it to any number of days up to 365. Any existing carts default to the expiry of 7 days. To update cart settings in Commerce Manager, see [Updating Cart setting](/docs/commerce-manager/settings/general-settings#updating-cart-settings).\n\nWith update cart settings endpoint, you can:\n\n- Enable or disable custom discounts by setting the `custom_discounts_enabled` field to `true`. This allows you to activate your custom discounts from external services. By default, this setting is determined by the cart settings configured for the store.\n- Enable or disable the use of rule promotions within the cart. You can apply this setting either at the store level using the update cart setting endpoint or individually to a specific cart using the [update a cart](/docs/api/carts/update-a-cart) endpoint.\n- Enable or disable deferred inventory checks by setting `defer_inventory_check` to `true`. When set, stock levels are not verified for products in a cart until checkout.\n- Control whether admins can see all carts or only shopper-associated carts by setting `show_all_carts` to `true` or `false`.\n- Enable or disable location-based item separation by setting `separate_items_by_location` to `true`. When enabled, cart items with the same SKU but different locations are kept as separate line items instead of being merged.\n\n:::note\n\nYou cannot use both custom discounts and rule promotions at the same time.\n\n:::\n\n### Errors\n\nThe following error is received if you enable a cart to use both custom discounts and rule promotions:\n\n```json\n{\n    \"status\": 422,\n    \"title\": \"Cannot use both discounts together\",\n    \"detail\": \"Only one discount setting can be set to true at a time.\"\n}\n```"
      operationId: put-v2-settings-cart-storeID
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SettingsCart'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettingsCart'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response.ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response.ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response.ErrorResponse'
      deprecated: false
components:
  schemas:
    Response.ErrorItem:
      type: object
      required:
      - status
      - title
      properties:
        title:
          type: string
          description: A brief summary of the error.
          examples:
          - Bad Request
        status:
          type:
          - string
          - integer
          description: The HTTP response code of the error.
          examples:
          - '400'
        detail:
          type: string
          description: Optional additional detail about the error.
          examples:
          - The field 'name' is required
        source:
          type: string
          description: The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity').
        meta:
          type: object
          description: Additional metadata associated with the error. May include arbitrary keys.
          properties:
            id:
              type: string
              description: The resource id associated with the error
            ids:
              type: array
              items:
                type: string
                description: The resource ids associated with the error
            item_ids:
              type: array
              items:
                type: string
                description: The cart_item ids associated with the error
            shipping_group_id:
              type: string
              description: The shipping group id associated with the error
            shipping_group_ids:
              type: array
              items:
                type: string
                description: The shipping group ids associated with the error
            cart_id:
              type: string
              description: The cart id associated with the error
            code:
              type: string
              description: The code associated with the error.
            order_id:
              type: string
              description: The order id associated with the error.
            sku:
              type: string
              description: The SKU associated with the error.
            email:
              type: string
              format: email
              description: The email address associated with the error.
            component_product_id:
              type: string
              format: uuid
              description: The component product ID associated with the error.
            error-meta-key:
              type: string
              description: Custom error metadata key used for additional error context (e.g., in payment rejections).
            value:
              description: The value associated with the error.
              oneOf:
              - type: string
              - type: integer
              - type: boolean
              - type: object
                additionalProperties: true
              - type: array
    Response.ErrorResponse:
      type: object
      required:
      - errors
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Response.ErrorItem'
    SettingsCart:
      type: object
      properties:
        data:
          type: object
          properties:
            type:
              type: string
              description: Describes the type of request payload you're sending. Set this value to `settings`.
              example: settings
            id:
              type: string
              description: The unique identifier for the cart settings.
              readOnly: true
              example: 15419118-44ce-5343-8ff6-574daf52bc6b
            cart_expiry_days:
              type: integer
              description: Indicates the number of days before a cart expires.
              example: 25
            discounts:
              type: object
              properties:
                custom_discounts_enabled:
                  description: When `true`, custom discounts are enabled. Default is false. This setting only affects the new empty carts while the existing active carts will not be affected.
                  type: boolean
                  example: false
                use_rule_promotions:
                  description: When set to `true`, this parameter allows the cart to use rule promotions.
                  type: boolean
                  example: false
            inventories:
              type: object
              properties:
                defer_inventory_check:
                  description: When `true`, inventory checks are not performed when adding products to a cart but still occur on checkout as normal. Default is false. This setting only affects the new empty carts while the existing active carts will not be affected.
                  type: boolean
                  example: false
            items:
              type: object
              properties:
                separate_items_by_location:
                  description: When `true`, cart items with the same SKU but different locations are kept as separate line items instead of being merged. When `false` (default), items with the same SKU are merged and the location is updated to the most recent value.
                  type: boolean
                  example: false
            show_all_carts:
              description: 'When `true`, admins (users with admin scope) can retrieve all carts in the store via `GET /v2/carts`, regardless of customer or account associations. When `false`, admins can only see carts that are registered (associated with customers or accounts).


                For new stores, this defaults to `true`. For existing stores created before this feature was introduced, this defaults to `false` to maintain backward compatibility.

                '
              type: boolean
              example: true
          required:
          - type
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer