fabric LineItems API

openapi: 3.0.1
info:
  title: Cart Actions Endpoints LineItems 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: LineItems
  description: LineItem endpoints are used to performbasic lineItem operations, such as create, update, delete and more.
paths:
  /orchestrator/carts/{cartId}/items:
    post:
      summary: Add Items
      description: 'Add items 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.

        '
      operationId: addItemsToCart
      tags:
      - LineItems
      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.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddItemsToCartRequest'
      responses:
        '200':
          description: Items added to the 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'
    patch:
      summary: Update Items
      description: 'Updates the item information in 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: updateItems
      tags:
      - LineItems
      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.
      requestBody:
        description: Update line items
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateLineItemsRequest'
      responses:
        '200':
          description: Items updated to the 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'
    delete:
      summary: Delete Items
      description: 'Removes the items 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: deleteItems
      tags:
      - LineItems
      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: itemId
        in: query
        required: true
        schema:
          type: string
        description: Item ID of the item to remove.
      responses:
        '200':
          description: Items deleted from the 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'
  /orchestrator/carts/{cartId}/items/{itemId}/actions/split:
    post:
      summary: Split Line Items
      description: 'Splits the item associated with the corresponding cart into multiple line items based on quantity.


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


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

        '
      operationId: splitLineItems
      tags:
      - LineItems
      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: itemId
        in: path
        required: true
        schema:
          type: string
        description: The unique identifier for the line item that is the target of the split.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SplitLineItemsRequest'
        required: true
      responses:
        '200':
          description: Line items split 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:
    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
    OrderConfiguration:
      type: object
      properties:
        validate:
          $ref: '#/components/schemas/OrderValidateConfiguration'
      description: Configuration settings related to order validation and processing.
    UpdateLineItemFulfillmentPrice:
      type: object
      properties:
        amount:
          type: number
          description: The fulfillment amount
      required:
      - amount
    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.
    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
    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
    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.
    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: '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.
    Promotion:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the promotion.
          example: 6626c179627d450008a5b202
        title:
          type: string
          description: Promotion title
          example: Cart Promotion Fixed Price
        type:
          type: string
          description: The type of promotion, such as percentage or fixed value.
          example: QUANTITY
        value:
          type: number
          format: float
          description: The value of the promotion, indicating the amount of the discount applied. This can be a fixed amount or a percentage.
          example: 10
        attributes:
          type: object
          additionalProperties:
            type: string
          description: Custom attributes provide more context for the promotion.
          example:
            promotionStack: HIGHEST
    UpdateLineItemsRequest:
      type: object
      properties:
        lineItems:
          type: array
          items:
            $ref: '#/components/schemas/UpdateLineItem'
          description: A collection of items in the cart.
      required:
      - lineItems
    PIMValidationData:
      type: object
      properties:
        availableSkus:
          type: array
          description: An array containing product validation data.
          items:
            $ref: '#/components/schemas/SKUValidationData'
    TaxValidationData:
      type: object
      properties:
        updatedAt:
          type: string
          description: Latest date the tax was added to the cart.
          example: 2024-06-13 16:50:00.682000+00:00
      description: Tax validation data
    CartResponse:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the cart that was passed in the parameter.
          example: 0e49199c-5849-4211-abe6-a97a3c4dcc56
        attributes:
          $ref: '#/components/schemas/Attributes'
        configuration:
          $ref: '#/components/schemas/CartConfiguration'
        customerContext:
          $ref: '#/components/schemas/CustomerContext'
        status:
          type: string
          description: The cart status indicates whether the cart is active or deleted.
          example: ACTIVE
          enum:
          - ACTIVE
          - SOFT_DELETE
        state:
          type: array
          description: The resource state is stored in an array that holds information about the current status of the cart.
          items:
            $ref: '#/components/schemas/State'
        price:
          $ref: '#/components/schemas/PriceDetail'
        promotions:
          $ref: '#/components/schemas/Promotions'
        fees:
          $ref: '#/components/schemas/Fee'
        adjustments:
          $ref: '#/components/schemas/AdjustmentCollection'
        addresses:
          type: object
          properties:
            a8577d7f0d4d4b228e857b4a2e90dc93:
              $ref: '#/components/schemas/Address'
          description: A map of addresses added to the cart.
        lineItems:
          $ref: '#/components/schemas/ItemCollection'
        summary:
          $ref: '#/components/schemas/Summary'
        fulfillments:
          type: object
          properties:
            d6229cdb0c5b4885b1b213b94d02488e:
              $ref: '#/components/schemas/Fulfillment'
          description: A map of fulfillments added to the cart.
        coupons:
          type: array
          description: An array containing all coupons added to the cart.
          items:
            $ref: '#/components/schemas/Coupon'
        appliedCoupons:
          type: array
          description: An array containing all coupons applied to the cart.
          items:
            $ref: '#/components/schemas/Coupon'
        notAppliedCoupons:
          type: array
          description: An array containing any coupons that were ineligible and not applied to the cart.
          items:
            $ref: '#/components/schemas/Coupon'
        validations:
          $ref: '#/components/schemas/ValidationData'
        payments:
          $ref: '#/components/schemas/PaymentCollection'
        channelId:
          type: string
          description: Channel ID
          example: '12'
        currency:
          type: string
          description: The currency that the cart will use when an order is created.
          example: USD
        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 when a cart was created.
          example: 2024-06-13 16:50:00.682000+00:00
        suggestedProducts:
          type: array
          items:
            $ref: '#/components/schemas/SuggestedProduct'
        promotionMessages:
          type: array
          items:
            $ref: '#/components/schemas/PromotionMessage'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
    Tax:
      type: object
      properties:
        amount:
          type: number
          description: Tax amount
          example: 3
        attributes:
          type: object
          additionalProperties:
            type: object
            description: Custom attributes to provide more context to the tax, such as the rate and the type of tax.
            example:
              rate: '5.0'
              type: COUNTY
          description: Custom attributes to provide more context to the tax, such as the rate and the type of tax.
          example:
            rate: '5.0'
            type: COUNTY
      description: Tax
    PriceDetail:
      type: object
      properties:
        total:
          type: number
          format: float
          description: The grand total, inclusive of all charges and discounts.
          example: 1570
        subtotal:
          type: number
          format: float
          description: The subtotal of all items.
          example: 1530
        tax:
          type: number
          format: float
          description: The total tax calculated amount.
          example: 0
        fulfillments:
          type: number
          format: float
          description: The total fulfillments amount.
          example: 40
        discounts:
          type: number
          format: float
          description: The total discounts amount.
          example: 0
        fees:
          type: number
          format: float
          description: The total fees amount.
          example: 0
        adjustments:
          type: number
          format: float
          description: The total adjustments amount.
          example: 0
      description: The sum of the total amount of the cart.
    PickupPerson:
      type: object
      properties:
        primary:
          $ref: '#/components/schemas/Person'
        secondary:
          type: array
          description: An array containing secondary people for pickup.
          items:
            $ref: '#/components/schemas/Person'
      description: Pickup person details
    PaymentAuthorization:
      required:
      - amount
      type: object
      properties:
        amount:
          minimum: 0
          exclusiveMinimum: true
          type: number
          description: The amount for which the payment has been authorized.
          example: 8
        expiry:
          type: string
          description: The date when the payment authorization expires.
          example: 2024-06-13 16:50:00.682000+00:00
        verifier:
          $ref: '#/components/schemas/Verifier'
      description: Payment authorization
    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
    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.
    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
    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
    AddItemPayload:
      type: object
      properties:
        itemId:
          type: string
          description: "Item ID of the item to add. \n\nIf you are using fabric, the ID can be obtained from the [Get products by SKU](/v3/api-reference/product-catalog/general-product-operations/get-products-list) endpoint.\n\nIf you are not using fabric, then locate the ID in your database.\n"
        sku:
          type: string
          description: The Stock Keeping Unit (SKU) associated with the item, used for inventory tracking and management.
        priceListId:
          type: string
          description: The unique identifier for a price list, used to reference and manage pricing information.
        price:
          $ref: '#/components/schemas/PriceDetail'
        fulfillment:
          $ref: '#/components/schemas/Fulfillment'
        quantity:
          type: integer
          description: An integer that displays the total quantity of the item. to add to the corresponding cart.
      required:
      - sku
      - quantity
    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.
    Error:
      type: object
      properties:
        code:
          type: string
          description: The error code as a result of the error.
          example: ERR001
        message:
          type: stri

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