Elastic Path Customer Cart Associations 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 Customer Cart Associations 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: 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.ErrorResponse:
      type: object
      required:
      - errors
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Response.ErrorItem'
    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.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
  securitySchemes:
    BearerToken:
      type: http
      scheme: bearer