Elastic Path Account Cart Associations API

openapi: 3.2.0
info:
  title: Carts, Checkout, Orders Introduction Account Cart Associations 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: Account Cart Associations
  description: 'You can create associations between an account and one or more carts. After cart associations exist for an account, those carts are accessible across any device. You can delete associations as required.


    There are two ways to access the cart: with an [Account Management Authentication Tokens](/docs/api/accounts/post-v-2-account-members-tokens) and without one.


    ### With an `Account Management Authentication` token


    These endpoints are for users who authenticated implicitly and require an Account Management Authentication token in the header to access the account cart associations APIs. For more information, see the [Account Token](/docs/api/accounts/post-v-2-account-members-tokens) documentation.


    #### Cart creation


    Shoppers create carts and can use any of the carts that they created to check out an order.


    :::note


    You can create a cart id, name, and description for the cart. The cart requires a name. Ensure that the string length is greater than or equal to one. Use any symbol in the name and description. For cart id, ensure that you follow the guidelines for safe characters. For more information about cart id naming requirements, see [Safe Characters](/guides/Getting-Started/safe-characters).


    :::


    ### Without an `Account Management Authentication` token


    These endpoints are for users who use the Client Credentials Token and do not require an account management authentication token in the header to access the account cart associations APIs. For more information, see the [Authentication](/docs/authentication/security) documentation.


    This user acts as a system administrator and can call any account cart association operations for any account and cart.


    ### Error Codes


    You might encounter the following response codes, depending on the scenario:


    * `400` - `The type does not exist or is not listed as account` - Ensure that the type is `account` and is present.


    * `403` - `Cannot associate more than one account`.


    * `403` - `Account does not have the required permissions to fulfill this request`.


    * `403` - `Invalid json payload` - Check JSON input. The request body must be an array `[]`. If the request body is an object, the error is generated.

    '
paths:
  /v2/carts/{cartID}/relationships/accounts:
    parameters: []
    post:
      tags:
      - Account Cart Associations
      summary: Create an Account Cart Association
      description: You can create associations between an account and one or more carts. After cart associations exist for an account, the account can access those carts across any device.
      operationId: createAccountCartAssociation
      parameters:
      - name: cartID
        in: path
        description: The ID for the cart created by the account. Ensure that you follow the guidelines for [Safe Characters](/guides/Getting-Started/safe-characters).
        required: true
        style: simple
        schema:
          type: string
      - name: EP-Account-Management-Authentication-Token
        in: header
        description: An Account Management Authentication token to access a specific account's carts.
        style: simple
        schema:
          type: string
          examples:
          - '{{accountToken}}'
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/CartsRelationshipsAccountsData'
        required: false
      responses:
        '200':
          description: OK
          headers: {}
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/CartsRelationshipsAccountsData'
        '204':
          description: No Content is sent back in case the account has already been associated to the cart.
          headers: {}
          content: {}
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response.ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response.ErrorResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response.ErrorResponse'
                examples:
                  default:
                    summary: Invalid Association
                    value:
                      errors:
                      - detail: Unable to associate accounts to carts with contact emails attached.
                        status: 400
                        title: Cannot associate accounts to carts with contact emails
      deprecated: false
    delete:
      tags:
      - Account Cart Associations
      summary: Delete Account Cart Association
      description: You can delete an association between an account and a cart.
      operationId: deleteAccountCartAssociation
      parameters:
      - name: cartID
        in: path
        description: The ID for the cart created by the account.
        required: true
        style: simple
        schema:
          type: string
      - name: EP-Account-Management-Authentication-Token
        in: header
        description: An Account Management Authentication token to access a specific account's carts.
        style: simple
        schema:
          type: string
          examples:
          - '{{accountToken}}'
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/CartsRelationshipsAccountsData'
        required: false
      responses:
        '204':
          description: No Content
          headers: {}
          content: {}
        '400':
          description: Bad Request
          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'
    CartsRelationshipsAccountsData:
      title: Carts Relationships Accounts Data
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              id:
                description: The ID of the account.
                type: string
                examples:
                - '{{accountID}}'
              type:
                description: The type of related object. Ensure that it is account.
                type: string
                examples:
                - account
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer