fabric Carts API

openapi: 3.0.1
info:
  title: Cart Actions Endpoints Carts 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: Carts
  description: Cart endpoints are used to perform basic cart operations, such as create, update, delete and more.
paths:
  /orchestrator/carts/{cartId}:
    get:
      summary: Get the Cart
      description: 'Retrieves the cart information corresponding to the provided cart ID.


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

        '
      operationId: getCart
      tags:
      - Carts
      parameters:
      - $ref: '#/components/parameters/XFabricTenantId'
      - $ref: '#/components/parameters/XFabricRequestId'
      - $ref: '#/components/parameters/XFabricChannelId'
      - 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/api-reference/carts-v3/carts/carts) endpoint.
      responses:
        '200':
          description: Get entire cart
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CartResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          description: Unprocessable Orchestration Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableOrchestrationError'
    delete:
      summary: Delete Cart
      description: 'Removes the cart corresponding to the provided cart ID.


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

        '
      operationId: deleteCart
      tags:
      - Carts
      parameters:
      - $ref: '#/components/parameters/XFabricTenantId'
      - $ref: '#/components/parameters/XFabricRequestId'
      - $ref: '#/components/parameters/XFabricChannelId'
      - 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/api-reference/carts-v3/carts/carts) endpoint.
      responses:
        '204':
          description: Delete entire cart
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          description: Unprocessable Orchestration Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableOrchestrationError'
  /orchestrator/carts/{cartId}/coupons/{couponCode}:
    post:
      summary: Apply Coupon
      description: 'Apply a coupon code to the corresponding cart.


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


        The coupon code generated when [creating a custom coupon](/v3/api-reference/carts-v3/carts-adjustments/create-adjustments) in Copilot is used in the path parameter.

        '
      operationId: applyCoupon
      tags:
      - Carts
      parameters:
      - $ref: '#/components/parameters/XFabricTenantId'
      - $ref: '#/components/parameters/XFabricRequestId'
      - $ref: '#/components/parameters/XFabricChannelId'
      - 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/api-reference/carts-v3/carts/carts) endpoint.
      - name: couponCode
        in: path
        required: true
        schema:
          type: string
        description: The coupon code generated when [creating a custom coupon](/v3/offers/user-guides/offers/coupons/overview) in Copilot.
      responses:
        '200':
          description: Applies coupon to the cart
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CartResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          description: Unprocessable Orchestration Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableOrchestrationError'
    delete:
      summary: Removes Coupon
      description: 'Removes the coupon from the corresponding cart.


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

        '
      operationId: removeCoupon
      tags:
      - Carts
      parameters:
      - $ref: '#/components/parameters/XFabricTenantId'
      - $ref: '#/components/parameters/XFabricRequestId'
      - $ref: '#/components/parameters/XFabricChannelId'
      - 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/api-reference/carts-v3/carts/carts) endpoint.
      - name: couponCode
        in: path
        required: true
        schema:
          type: string
        description: The coupon code generated when [creating a custom coupon](/v3/offers/user-guides/offers/coupons/overview) in Copilot.
      responses:
        '200':
          description: Coupon is removed from cart successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CartResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          description: Unprocessable Orchestration Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableOrchestrationError'
components:
  schemas:
    Coupon:
      type: object
      properties:
        code:
          type: string
          description: Coupon code
          example: VALID_COUPON
        updatedAt:
          type: string
          description: The date when the coupon was added to the cart.
          example: 2024-06-13 16:50:00.682000+00:00
      description: Coupon
    State:
      type: object
      properties:
        resource:
          type: string
          description: The type of resource indicating its current state, such as a cart.
          example: CART
          enum:
          - ITEM
          - CART
          - FULFILLMENT
          - PAYMENT
          - FEE
          - VALIDATION
        resourceId:
          type: string
          description: The ID used to reference the resource's state, such as a cart.
          example: c86f777b-1885-4ddf-961d-542ba80a69b8
        key:
          type: string
          description: The key used to map the state of the resource.
          example: MISSING_PAYMENT_DETAILS
        description:
          type: string
          description: A detailed description of the resource's current state, such as the absence of payment details.
          example: No payment details have been added to this Cart
      description: Cart State
    Address:
      type: object
      properties:
        id:
          type: string
          description: The Address ID generated when an address was created using the [Create address](/v3/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
    TaxCollection:
      type: object
      properties:
        total:
          type: number
          description: Tax total in the collection.
          example: 3
        collection:
          type: array
          description: An array containing taxes in a collection.
          items:
            $ref: '#/components/schemas/Tax'
      description: A collection of taxes.
    AdjustmentCollection:
      type: object
      properties:
        total:
          type: number
          description: Adjustments total in a collection.
          example: 2
        collection:
          type: array
          description: An array containing adjustments in the collection.
          items:
            $ref: '#/components/schemas/Adjustment'
      description: A collection of adjustments made to the cart.
    Person:
      required:
      - name
      type: object
      properties:
        name:
          $ref: '#/components/schemas/Name'
        email:
          type: string
          description: Email of the pickup person.
          example: john@test.com
        phone:
          $ref: '#/components/schemas/Phone'
      description: Name of the pickup person.
    ItemPromotion:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the promotion.
          example: bb44db95-6fbd-4eed-a1ed-4d99bc91250f
        amount:
          type: number
          description: The discount amount applied to the item, excluding quantity.
          example: 15
        quantity:
          type: integer
          description: The An integer that displays the total quantity of the item. for which the discount is applicable.
          format: int32
          example: 3
        proration:
          $ref: '#/components/schemas/ProrationSpread'
      description: Item Promotion
    OrderValidateConfiguration:
      type: object
      properties:
        paymentsRemaining:
          type: string
          description: 'The behavior that is executed based on the selected configuration.


            The default setting is BLOCK.

            '
          enum:
          - BLOCK
          - NONE
        taxRemaining:
          type: string
          description: 'The behavior that is executed based on the selected configuration.


            The default setting is BLOCK.

            '
          enum:
          - BLOCK
          - NONE
        invalidItem:
          type: string
          description: 'The behavior that is executed based on the selected configuration.


            The default setting is BLOCK.

            '
          enum:
          - BLOCK
          - NONE
        itemOutOfStock:
          type: string
          description: 'The behavior that is executed based on the selected configuration.


            The default setting is BLOCK.

            '
          enum:
          - BLOCK
          - NONE
      description: Order validate determines the blocking behavior when creating an order draft.
    ItemPrice:
      type: object
      properties:
        unit:
          type: number
          description: The unit price of the item.
          example: 10
        amount:
          type: number
          description: The total price of the item, inclusive of quantity.
          example: 100
      description: Item price
    ItemPromotionsCollection:
      type: object
      properties:
        total:
          type: number
          description: Discount total in the collection.
          example: 2
        collection:
          type: array
          description: An array containing promotions in the collection.
          items:
            $ref: '#/components/schemas/ItemPromotion'
      description: Collection of item promotions.
    OrderConfiguration:
      type: object
      properties:
        validate:
          $ref: '#/components/schemas/OrderValidateConfiguration'
      description: Configuration settings related to order validation and processing.
    Payment:
      type: object
      properties:
        id:
          type: string
          description: The Payment ID that was generated when a payment was created using the [Create payment](/v3/api-reference/carts-v3/payments/create-payments) endpoint.
          example: 6ef2067a-5d6b-4785-a090-96ea0078220d
        provider:
          type: string
          description: The payment provider, such as Verifone, that offers functions like transaction processing, gateway management, and other financial services.
          example: verifone
        processor:
          type: string
          description: The payment processor, such as Stripe, responsible for handling and processing payment transactions by facilitating communication between the merchant and the issuing bank.
          example: stripe
        method:
          type: string
          description: Payment method, such as Apple Pay, used for processing transactions.
          example: apple pay
        methodType:
          type: string
          description: Payment method type, such as a credit card.
          example: credit card
        state:
          type: string
          description: Payment state indicates whether the payment has been successfully processed.
          example: PENDING
          enum:
          - PENDING
          - AUTHORIZED
          - CAPTURED
          - FAILED
        authorization:
          $ref: '#/components/schemas/PaymentAuthorization'
        billToAddress:
          type: string
          description: The Address ID that was generated when an address was created using the [Create address](/v3/api-reference/carts-v3/addresses/create-addresses) endpoint.
          example: a8577d7f-0d4d-4b22-8e85-7b4a2e90dc93
        cardDetails:
          type: object
          description: Information about the card used for payment, such as gift card details.
          additionalProperties:
            type: object
            description: Information about the card used for payment, such as gift card details.
        attributes:
          type: object
          additionalProperties:
            type: object
            description: Custom attributes associated with the transaction, such as the name of the gift card used.
            example:
              gift-card-name: custom name
          description: Custom attributes associated with the transaction, such as the name of the gift card used.
          example:
            gift-card-name: custom name
      description: Cart Payment
    Promotions:
      type: object
      properties:
        total:
          type: number
          format: float
          description: The total value of all applied promotions.
          example: 0
        collection:
          type: array
          description: An array containing promotions in the collection.
          items:
            $ref: '#/components/schemas/Promotion'
      description: A collection of promotions applied to the cart.
    SegmentObject:
      type: object
      properties:
        name:
          type: string
          description: Segment name
          example: membership
        value:
          type: array
          description: Segment values
          example:
          - gold
          - silver
          items:
            type: string
            description: Segment values
            example: '["gold","silver"]'
    Name:
      type: object
      properties:
        first:
          type: string
          description: First name
          example: John
        last:
          type: string
          description: Last name
          example: Doe
    LineItemValidationData:
      type: object
      properties:
        sku:
          type: string
          description: The SKU of the item.
          example: SKU3
        inventory:
          $ref: '#/components/schemas/InventoryValidationData'
      description: An object that contains item validation data.
    PromotionMessage:
      type: object
      properties:
        message:
          type: string
          description: The promotional message.
          example: Buy one get one free
        code:
          type: string
          description: The promotional code.
          example: BOGO
      description: An object containng various promotions associated with the cart.
    Proration:
      type: object
      properties:
        amount:
          type: number
          description: Proration amount for the item
          example: 5
        quantity:
          type: integer
          description: Proration quantity the amount is applicable for
          format: int32
          example: 3
      description: Proration details of the item used for returns in an OMS system
    FeeTaxDetails:
      type: object
      properties:
        destinationAddress:
          type: string
          description: The destination address where the item will be delivered.
          example: c86f777b-1885-4ddf-961d-542ba80a69b8
        originAddress:
          type: string
          description: The origin address from which the item will be fulfilled.
          example: c86f777b-1885-4ddf-961d-542ba80a69b8
      description: Tax details used to determine tax for a cart fee.
    Summary:
      type: object
      properties:
        totalItems:
          type: integer
          description: The total number of items in the cart, inclusive of quantity.
          format: int32
          example: 1
        totalUniqueItems:
          type: integer
          description: The total number of unique items in the cart.
          format: int32
          example: 1
      description: A summary of items in the cart.
    ResourcePrice:
      required:
      - amount
      type: object
      properties:
        amount:
          minimum: 0
          exclusiveMinimum: false
          type: number
          description: Total resource amount
          example: 12.99
      description: Price details
    ProrationSpread:
      type: object
      properties:
        spread:
          type: array
          description: An array containing details about adjustments made to charges based on partial usage. Each entry in the array represents a specific proration adjustment, including the amount.
          items:
            $ref: '#/components/schemas/Proration'
      description: Prorations
    TaxBehaviour:
      type: object
      properties:
        cacheExpiry:
          type: string
          description: 'The behavior that is executed based on the selected configuration.


            The default behavior is WARN.

            '
          example: WARN
          enum:
          - WARN
          - NONE
      description: Tax behaviors
    MaxQtyConfiguration:
      type: object
      properties:
        limit:
          type: integer
          description: The maximum quantity of an individual line item that can be added to the cart.
          format: int32
          example: 100
        behaviors:
          $ref: '#/components/schemas/MaxQtyBehaviour'
      description: Item max quantity configurations
    ItemResponseDto:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the item.
          example: a8577d7f-0d4d-4b22-8e85-7b4a2e90dc93
        sku:
          type: string
          description: The Stock Keeping Unit (SKU) associated with the item, used for inventory tracking and management.
          example: SKU3
        refId:
          type: string
          description: An alternative identifier associated with the item, used for additional tracking or referencing.
          example: '41'
        quantity:
          type: integer
          description: An integer that displays the total quantity of the item.
          format: int32
          example: 10
        priceListId:
          type: string
          description: The unique identifier for a price list, used to reference and manage pricing information.
          example: '10001'
        position:
          type: integer
          description: Position of item in a cart.
          format: int32
          example: 1
        price:
          $ref: '#/components/schemas/ItemPrice'
        fees:
          $ref: '#/components/schemas/FeesCollection'
        promotions:
          $ref: '#/components/schemas/ItemPromotionsCollection'
        adjustments:
          $ref: '#/components/schemas/AdjustmentCollection'
        fulfillment:
          $ref: '#/components/schemas/ItemFulfillment'
        attributes:
          type: object
          additionalProperties:
            type: object
            description: Custom attributes to provide more context for the item.
            example:
              name: item-custom
          description: Custom attributes to provide more context for the item.
          example:
            name: item-custom
        tax:
          $ref: '#/components/schemas/TaxCollection'
        taxCode:
          type: string
          description: The code used to identify and apply tax rates for transactions.
          example: '10001'
        updatedAt:
          type: string
          description: The date and time in UTC when the cart was last updated.
          example: 2024-06-13 16:50:00.682000+00:00
        createdAt:
          type: string
          description: The date and time in UTC when the cart was last updated.
          example: 2024-06-13 16:50:00.682000+00:00
      description: Item Response
    PromotionsConfiguration:
      type: object
      description: Configuration settings related to promotions and their cache expiry.
      properties:
        cacheExpiry:
          type: integer
          example: 86400
        behaviors:
          $ref: '#/components/schemas/Behavior'
    InventoryValidationData:
      type: object
      properties:
        channels:
          type: object
          additionalProperties:
            type: string
            description: The inventory channels associated with the item.
            example: '{"networkCode":"ShipToHome"}'
          description: The inventory channels associated with the item.
          example:
            networkCode: ShipToHome
        counters:
          type: object
          additionalProperties:
            type: integer
            description: The inventory counters available for the item.
            format: int32
          description: The inventory counters available for the item.
          example:
            backOrder: 15
            preOrder: 100
        updatedAt:
          type: string
          description: The latest date when inventory was added to the cart.
          example: 2024-06-13 16:50:00.682000+00:00
      description: Inventory validation details
    ProductBehaviour:
      type: object
      properties:
        add:
          type: string
          description: 'The behavior that is executed based on the selected configuration.


            The default behavior is REJECT.

            '
          example: REJECT
          enum:
          - WARN
          - DROP
          - REJECT
          - NONE
        update:
          type: string
          description: 'The behavior that is executed based on the selected configuration.


            The default behavior is WARN.

            '
          example: WARN
          enum:
          - WARN
          - DROP
          - REJECT
          - NONE
        get:
          type: string
          description: 'The behavior that is executed based on the selected configuration.


            The default behavior is WARN.

            '
          example: WARN
          enum:
          - WARN
          - DROP
          - REJECT
          - NONE
        cacheExpiry:
          type: string
          description: 'The behavior that is executed based on the selected configuration.


            The default behavior is WARN.

            '
          example: WARN
          enum:
          - WARN
          - DROP
          - REJECT
          - NONE
      description: Behaviors related to inventory actions, such as adding the item or removing the item.
    SuggestedProduct:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for the suggested product.
          example: '12345'
        name:
          type: string
          description: The name of the suggested product.
          example: Wireless Mouse
        description:
          type: string
          description: The name of the suggested product.
          example: A high-quality wireless mouse with ergonomic design.
        price:
          type: number
          format: float
          description: The price of the suggested product.
          example: 29.99
    InventoryConfiguration:
      type: object
      properties:
        cacheExpiry:
          type: integer
          description: Duration in seconds until inventory validation data expires.
          format: int64
          example: 7776000
        behaviors:
          $ref: '#/components/schemas/InventoryBehaviour'
        check:
          type: string
          description: This setting is used to determine how you check inventory. The options are SKU or LINE_ITEM.
          example: SKU
          enum:
          - SKU
          - LINE_ITEM
      description: Configuration settings related to inventory management and checks.
    FeesCollection:
      type: object
      properties:
        total:
          type: number
          description: The total fees amount in the collection.
          example: 5
        collection:
          type: array
          description: An array containing all fees and their details in a collection.
          items:
            $ref: '#/components/schemas/Fee'
      description: A collection of fees associated with the cart.
    CustomerContext:
      type: object
      properties:
        id:
          type: string
          description: The Customer ID that was added to the customer attribute when using the [Update customer](/v3/api-reference/carts-v3/customer/update-customer) endpoint.
          example: '109840938'
        segments:
          type: array
          description: An array containing segments of customer information.
          items:
            $ref: '#/components/schemas/SegmentObject'
        attributes:
          type: object
          additionalProperties:
            type: object
            description: Customer attributes such as email.
            example:
              email: test@gmail.com
          description: Customer attributes such as email.
          example:
            email: test@gmail.com
        sessionId:
          type: string
          description: Session ID of the customer.
          example: 3a5fd2d3-5c96-4e57-b069-7ff2a88c1119
      description: Customer context object containing customer information.
    Error:
      type: object
      properties:
        code:
          type: string
          description: The error code as a result of the error.
          example: ERR001
        message:
          type: string
          description: The error message to provide more context for the error.
          example: Invalid input
      description: An object containing the error code and message.
    ProductConfiguration:
      type: object
      properties:
        cacheExpiry:
          type: integer
          description: Duration in seconds until product validation data expires.
          format: int64
          example: 7776000
        behaviors:
          $ref: '#/components/schemas/ProductBehaviour'
        maxQuantity:
          $ref: '#/components/schemas/MaxQtyConfiguration'
      description: Configuration settings related to product behavior and cache expiry.
    ValidationData:
      type: object
      properties:
        promotions:
          $ref: '#/components/schemas/PromotionValidationData'
        lineItems:
          type: array
          items:
            $ref: '#/components/schemas/LineItemValidationData'
        product:
          $ref: '#/components/schemas/PIMValidationData'
        tax:
          $ref: '#/components/schemas/TaxValidationData'
    PromotionValidationData:
      type: object
      properties:
        updatedAt:
          type: string
          description: The latest date when promotions data was added to the cart.
          example: 2024-06-13 16:50:00.682000+00:00
        appliedCoupons:
          type: array
          description: An array containing coupons that have been added to the cart.
          example:
          - TEST_COUPON
          items:
            type: string
            description: Coupons that have been added to the cart.
            example: '["TEST_COUPON"]'
        refreshRequired:
          type: boolean
          description: A boolean value that determines whether promotions require a refresh.
          example: false
      description: An object that contains promotion validation data.
    SKUValidationData:
      type: object
      properties:
        sku:
          type: string
          description: The SKU that exists within a Product Information Management (PIM) service.
          example: SKU3
        updatedAt:
          type: string
          description: The latest date when product data was added to the cart.
          example: 2024-06-13 16:50:00.682000+00:00
        maxQuantity:
          type: integer
          description: The maximum quantity allowed for a SKU.
          format: int32
          example: 100
      description: Product validation data to determine product existence
    InventoryBehaviour:
      type: object
      properties:
        add:
          type: string
          description: 'The behavior that is executed based on the selected configuration.


            The default behavior is REJECT.

            '
          example: REJECT
          enum:
          - WARN
          - DROP
          - REJECT
          - NONE
        update:
          type: string
          description: 'The behavior that is executed based on the selected configuration.


            The default behavior is WARN.

            '
          example: WARN
          enum:
          - WARN
          - DROP
          - REJECT
          - NONE
        get:
          type: string
          description: 'The behavior that is executed based on the selected configuration.


            The default behavior is WARN.

            '
          example: WARN
          enum:
          - WARN
          - DROP
          - REJECT
          - NONE
        cacheExpiry:
          type: string
          description: 

# --- truncated at 32 KB (53 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/fabric-com/refs/heads/main/openapi/fabric-com-carts-api-openapi.yml