Elastic Path Customer Cart Associations API

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


    There are two ways to access the cart: with a customer token and without one.


    ### With a `customer` token


    These endpoints are for users who authenticated implicitly and require a customer token in the header to access the customer cart associations APIs. For more information, see the [Customer Token](/docs/customer-management/customer-management-api/customer-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 a `customer` token


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


    This user acts as a system administrator and can call any customer cart association operations for any customer 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 customer` - Ensure that the type is `customer` and is present.


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


    * `403` - `Customer 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/customers:
    parameters: []
    post:
      tags:
      - Customer Cart Associations
      summary: Create a Customer Cart Association
      description: You can create associations between a customer and one or more carts. After cart associations exist for a customer, the customer can access those carts across any device.
      operationId: createCustomerCartAssociation
      parameters:
      - name: cartID
        in: path
        description: The ID for the cart created by the customer. Ensure that you follow the guidelines for [Safe Characters](/guides/Getting-Started/safe-characters).
        required: true
        style: simple
        schema:
          type: string
      - name: X-Moltin-Customer-Token
        in: header
        description: A customer token to access a specific customer's carts.
        style: simple
        schema:
          type: string
          examples:
          - '{{customerToken}}'
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/CartsRelationshipsCustomersData'
        required: false
      responses:
        '200':
          description: OK
          headers: {}
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/CartsRelationshipsCustomersData'
        '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'
        '422':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response.ErrorResponse'
                examples:
                  default:
                    summary: Invalid Association
                    value:
                      errors:
                      - detail: Unable to associate customers to carts with contact emails attached.
                        status: 400
                        title: Cannot associate customers to carts with contact emails
      deprecated: false
    delete:
      tags:
      - Customer Cart Associations
      summary: Delete Customer Cart Association
      description: You can delete an association between a customer and a cart.
      operationId: deleteCustomerCartAssociation
      parameters:
      - name: cartID
        in: path
        description: The ID for the cart created by the customer.
        required: true
        style: simple
        schema:
          type: string
      - name: X-Moltin-Customer-Token
        in: header
        description: A customer token to access a specific customer's carts.
        style: simple
        schema:
          type: string
          examples:
          - '{{customerToken}}'
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/CartsRelationshipsCustomersData'
        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
    CartsRelationshipsCustomersData:
      title: Carts Relationships Customers Data
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              id:
                description: The ID of the customer.
                type: string
                examples:
                - '{{customerID}}'
              type:
                description: The type of related object. Ensure that it is customer.
                type: string
                examples:
                - customer
    Response.ErrorResponse:
      type: object
      required:
      - errors
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Response.ErrorItem'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer