Elastic Path Cart Settings API

openapi: 3.1.0
info:
  version: 25.1126.6886238
  x-version-timestamp: 2025-11-26 19:10:23+00:00
  title: Addresses Introduction Account Addresses Cart Settings API
  description: 'The Addresses API allows you to organize account addresses. Addresses are a sub-resource of `account` resources, an account can have multiple addresses, such as home, work, and neighbour.


    You can use an account address with either [client_credentials access token](/docs/api/authentication/create-an-access-token) or a combination of [implicit access token](/docs/api/authentication/create-an-access-token) and [Account Management authentication](/docs/api/accounts/post-v-2-account-members-tokens) token.

    '
  contact:
    name: Elastic Path
    url: https://www.elasticpath.com
    email: support@elasticpath.com
  license:
    url: https://elasticpath.dev
    name: MIT
servers:
- url: https://useast.api.elasticpath.com
  description: US East
- url: https://euwest.api.elasticpath.com
  description: EU West
security:
- BearerToken: []
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:
    BearerToken:
      type: http
      scheme: bearer