openapi: 3.0.1
info:
  title: Cart Actions Endpoints Addresses API
  description: fabric's **Cart API** lets you add, update, and remove items from your Storefront cart, either as a guest user or as a logged-in user. It also provides functionality to merge carts when you switch from guest user to logged-in user, and apply coupons and other attributes (for example, gift wrapping) to the line items. Additionally, the API supports more advanced tasks such as using multiple carts within a B2B organization, sharing carts, and supporting a unified cart experience for multi-region and multi-brand businesses.<p>The Cart API provides high performance, scalability, multi-tenancy, and configurability to the end-to-end order processing actions that start from the item being added to the cart; through the pre-checkout stage that includes billing, shipping, and payment details; to the checkout stage where the order is processed and confirmed by fabric's Order Management System (OMS)
  contact:
    name: Cart Support
    email: support.cnc@fabric.inc
  license:
    name: fabric API License
    url: https://fabric.inc/api-license
  version: 3.0.0
servers:
- url: https://api.fabric.inc/v3
security:
- bearerAuth: []
tags:
- name: Addresses
  description: Address endpoints are used to add add, update and remove addresses from the Cart.
paths:
  /carts/{cartId}/addresses:
    post:
      tags:
      - Addresses
      summary: Create Address
      description: 'Adds a billing address to the corresponding cart.


        The Cart ID from the [Create cart](/v3/cart-and-checkout/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.

        '
      operationId: createAddress
      parameters:
      - name: cartId
        in: path
        required: true
        schema:
          type: string
          description: The 24-character system-generated Cart ID. This ID is generated using the [Create cart](/v3/cart-and-checkout/api-reference/carts-v3/carts/carts) endpoint.
      - name: x-fabric-tenant-id
        in: header
        description: "A header used by fabric to identify the tenant making the request. You must include tenant id in the authentication header for an API request to access any of fabric’s endpoints. You can retrieve the tenant id , which is also called account id, from [Copilot](/v3/platform/settings/account-details/getting-the-account-id). This header is required. \n"
        required: true
        schema:
          type: string
          example: 617329dfd5288b0011332311
      - name: x-fabric-request-id
        in: header
        description: ' Unique request ID for tracking.'
        required: false
        schema:
          type: string
          example: 263e731c-45c8-11ed-b878-0242ac120002
      - name: x-fabric-channel-id
        in: header
        description: x-fabric-channel-id identifies the sales channel through which the API request is being made; primarily for multichannel use cases. It is a required field. The default US channel is 12 while the default Canada channel is 11.
        required: false
        schema:
          type: string
          example: '12'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAddressRequest'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewAddress'
        '400':
          description: Client error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '404':
          description: Cart not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
  /carts/{cartId}/addresses/{addressId}:
    get:
      tags:
      - Addresses
      summary: Get Address
      description: 'Gets the billing address associated the cart.


        The Cart ID from the [Create cart](/v3/cart-and-checkout/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.


        The Address ID from the [Create address](/v3/cart-and-checkout/api-reference/carts-v3/addresses/create-addresses) endpoint is used in the path parameter.

        '
      operationId: getAddress
      parameters:
      - name: cartId
        in: path
        required: true
        schema:
          type: string
          description: The 24-character system-generated Cart ID. This ID is generated using the [Create cart](/v3/cart-and-checkout/api-reference/carts-v3/carts/carts) endpoint.
      - name: addressId
        in: path
        required: true
        schema:
          type: string
          description: The Address ID that was generated when an address was created using the [Create address](/v3/cart-and-checkout/api-reference/carts-v3/addresses/create-addresses) endpoint.
      - name: x-fabric-tenant-id
        in: header
        description: "A header used by fabric to identify the tenant making the request. You must include tenant id in the authentication header for an API request to access any of fabric’s endpoints. You can retrieve the tenant id , which is also called account id, from [Copilot](/v3/platform/settings/account-details/getting-the-account-id). This header is required. \n"
        required: true
        schema:
          type: string
          example: 617329dfd5288b0011332311
      - name: x-fabric-request-id
        in: header
        description: ' Unique request ID for tracking.'
        required: false
        schema:
          type: string
          example: 263e731c-45c8-11ed-b878-0242ac120002
      - name: x-fabric-channel-id
        in: header
        description: x-fabric-channel-id identifies the sales channel through which the API request is being made; primarily for multichannel use cases. It is a required field. The default US channel is 12 while the default Canada channel is 11.
        required: false
        schema:
          type: string
          example: '12'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Address'
        '400':
          description: Client error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '404':
          description: Cart not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
    delete:
      tags:
      - Addresses
      summary: Delete Address
      description: 'Removes the billing address associated with the corresponding cart.


        The Cart ID from the [Create cart](/v3/cart-and-checkout/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.


        The Address ID from the [Create address](/v3/cart-and-checkout/api-reference/carts-v3/addresses/create-addresses) endpoint is used in the path parameter.

        '
      operationId: deleteAddress
      parameters:
      - name: cartId
        in: path
        required: true
        schema:
          type: string
          description: The 24-character system-generated Cart ID. This ID is generated using the [Create cart](/v3/cart-and-checkout/api-reference/carts-v3/carts/carts) endpoint.
      - name: addressId
        in: path
        required: true
        schema:
          type: string
          description: The Address ID that was generated when an address was created using the [Create address](/v3/cart-and-checkout/api-reference/carts-v3/addresses/create-addresses) endpoint.
      - name: x-fabric-tenant-id
        in: header
        description: "A header used by fabric to identify the tenant making the request. You must include tenant id in the authentication header for an API request to access any of fabric’s endpoints. You can retrieve the tenant id , which is also called account id, from [Copilot](/v3/platform/settings/account-details/getting-the-account-id). This header is required. \n"
        required: true
        schema:
          type: string
          example: 617329dfd5288b0011332311
      - name: x-fabric-request-id
        in: header
        description: ' Unique request ID for tracking.'
        required: false
        schema:
          type: string
          example: 263e731c-45c8-11ed-b878-0242ac120002
      - name: x-fabric-channel-id
        in: header
        description: x-fabric-channel-id identifies the sales channel through which the API request is being made; primarily for multichannel use cases. It is a required field. The default US channel is 12 while the default Canada channel is 11.
        required: false
        schema:
          type: string
          example: '12'
      responses:
        '204':
          description: No Content
        '400':
          description: Client error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '404':
          description: Cart not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
    patch:
      tags:
      - Addresses
      summary: Update Address
      description: 'Updates the billing address associated with the corresponding cart.


        The Cart ID from the [Create cart](/v3/cart-and-checkout/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.


        The Address ID from the [Create address](/v3/cart-and-checkout/api-reference/carts-v3/addresses/create-addresses) endpoint is used in the path parameter.

        '
      operationId: updateAddress
      parameters:
      - name: cartId
        in: path
        required: true
        schema:
          type: string
          description: The 24-character system-generated Cart ID. This ID is generated using the [Create cart](/v3/cart-and-checkout/api-reference/carts-v3/carts/carts) endpoint.
      - name: addressId
        in: path
        required: true
        schema:
          type: string
          description: The Address ID that was generated when an address was created using the [Create address](/v3/cart-and-checkout/api-reference/carts-v3/addresses/create-addresses) endpoint.
      - name: x-fabric-tenant-id
        in: header
        description: "A header used by fabric to identify the tenant making the request. You must include tenant id in the authentication header for an API request to access any of fabric’s endpoints. You can retrieve the tenant id , which is also called account id, from [Copilot](/v3/platform/settings/account-details/getting-the-account-id). This header is required. \n"
        required: true
        schema:
          type: string
          example: 617329dfd5288b0011332311
      - name: x-fabric-request-id
        in: header
        description: ' Unique request ID for tracking.'
        required: false
        schema:
          type: string
          example: 263e731c-45c8-11ed-b878-0242ac120002
      - name: x-fabric-channel-id
        in: header
        description: x-fabric-channel-id identifies the sales channel through which the API request is being made; primarily for multichannel use cases. It is a required field. The default US channel is 12 while the default Canada channel is 11.
        required: false
        schema:
          type: string
          example: '12'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAddressRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Address'
        '400':
          description: Client error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '404':
          description: Cart not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
components:
  schemas:
    UpdateAddressRequest:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/ForUpdate'
        email:
          type: string
          description: Email
          example: john@test.com
        phone:
          $ref: '#/components/schemas/ForUpdate'
        addressLine1:
          type: string
          description: Address line 1
          example: 123 Park Road
        addressLine2:
          type: string
          description: Address line 2
        addressLine3:
          type: string
          description: Address line 3
        addressLine4:
          type: string
          description: Address line 4
        city:
          type: string
          description: City
          example: Santa Cruz
        region:
          type: string
          description: State, Province or Area
          example: California
        country:
          type: string
          description: Country
          example: USA
        postalCode:
          type: string
          description: Postal code or zip code
          example: '12345'
      description: Address
    ForUpdate:
      type: object
      properties:
        number:
          type: string
          description: Phone Number
          example: 123-456-7890
        type:
          type: string
          description: Phone Number Type
          example: MOBILE
          enum:
          - MOBILE
          - BUSINESS
          - HOME
    NewAddress:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of an address that was generated by this endpoint. This Address ID is used for other endpoints.
          example: a8577d7f-0d4d-4b22-8e85-7b4a2e90dc93
        name:
          $ref: '#/components/schemas/Name'
        email:
          type: string
          description: Email
          example: john@test.com
        phone:
          $ref: '#/components/schemas/Phone'
        addressLine1:
          type: string
          description: Address line 1
          example: 123 Park Road
        addressLine2:
          type: string
          description: Address line 2
        addressLine3:
          type: string
          description: Address line 3
        addressLine4:
          type: string
          description: Address line 4
        city:
          type: string
          description: City
          example: Santa Cruz
        region:
          type: string
          description: State, Province or Area
          example: California
        country:
          type: string
          description: Country
          example: USA
        postalCode:
          type: string
          description: Postal code or zip code
          example: '12345'
        updatedAt:
          type: string
          description: The date and time the address was last updated.
          example: 2024-06-13 16:50:00.682000+00:00
        createdAt:
          type: string
          description: The date and time the address was created.
          example: 2024-06-13 16:50:00.682000+00:00
      description: Address
    NotFound:
      type: object
      properties:
        type:
          type: string
          description: Error code, meant for machine consumption
          example: CART_NOT_FOUND
        message:
          type: string
          description: Human-readable error description
          example: Cart not found
      description: Resource Not Found
    CreateAddressRequest:
      required:
      - addressLine1
      - city
      - country
      - postalCode
      - region
      type: object
      properties:
        name:
          $ref: '#/components/schemas/ForCreateName'
        email:
          type: string
          description: Email
          example: john@test.com
        phone:
          $ref: '#/components/schemas/ForCreate'
        addressLine1:
          type: string
          description: Address line 1
          example: 123 Park Road
        addressLine2:
          type: string
          description: Address line 2
        addressLine3:
          type: string
          description: Address line 3
        addressLine4:
          type: string
          description: Address line 4
        city:
          type: string
          description: City
          example: Santa Cruz
        region:
          type: string
          description: State, Province or Area
          example: California
        country:
          type: string
          description: Country
          example: USA
        postalCode:
          type: string
          description: Postal code or zip code
          example: '12345'
      description: Address
    Address:
      type: object
      properties:
        id:
          type: string
          description: The Address ID generated when an address was created using the [Create address](/v3/cart-and-checkout/api-reference/carts-v3/addresses/create-addresses) endpoint.
          example: a8577d7f-0d4d-4b22-8e85-7b4a2e90dc93
        name:
          $ref: '#/components/schemas/Name'
        email:
          type: string
          description: Email
          example: john@test.com
        phone:
          $ref: '#/components/schemas/Phone'
        addressLine1:
          type: string
          description: Address line 1
          example: 123 Park Road
        addressLine2:
          type: string
          description: Address line 2
        addressLine3:
          type: string
          description: Address line 3
        addressLine4:
          type: string
          description: Address line 4
        city:
          type: string
          description: City
          example: Santa Cruz
        region:
          type: string
          description: State, Province or Area
          example: California
        country:
          type: string
          description: Country
          example: USA
        postalCode:
          type: string
          description: Postal code or zip code
          example: '12345'
        updatedAt:
          type: string
          description: The date and time the address was last updated.
          example: 2024-06-13 16:50:00.682000+00:00
        createdAt:
          type: string
          description: The date and time the address was created.
          example: 2024-06-13 16:50:00.682000+00:00
      description: Address
    ClientError:
      type: object
      properties:
        type:
          type: string
          description: Error code, meant for machine consumption
          example: BAD_REQUEST
        message:
          type: string
          description: Human-readable error description
          example: x-fabric-tenant-id is required
      description: Client error details
    ForCreate:
      required:
      - number
      - type
      type: object
      properties:
        number:
          type: string
          description: Phone Number
          example: 123-456-7890
        type:
          type: string
          description: Phone Number Type
          example: MOBILE
          enum:
          - MOBILE
          - BUSINESS
          - HOME
      description: Phone details
    Phone:
      type: object
      properties:
        number:
          type: string
          description: Phone Number
          example: 123-456-7890
        type:
          type: string
          description: Phone Number Type
          example: MOBILE
          enum:
          - MOBILE
          - BUSINESS
          - HOME
      description: Phone
    Name:
      type: object
      properties:
        first:
          type: string
          description: First name
          example: John
        middle:
          type: string
          description: Middle name
          example: S
        last:
          type: string
          description: Last name
          example: Doe
      description: Name of the recipient of the order.
    ForCreateName:
      required:
      - first
      - last
      type: object
      properties:
        first:
          type: string
          description: First name on the address.
          example: John
        last:
          type: string
          description: Last name on the address.
          example: Doe
      description: Name details
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'This is the authorization token used to authenticate the request. You must pass the access token generated from the system app. For more information, see the [Making your first API request](/v3/api-reference/getting-started/getting-started-with-fabric-apis#procedure) section.

        '