fabric LineItems API

openapi: 3.2.0
info:
  title: Cart Orchestrator Line Items API
  description: API for managing shopping carts
  version: 3.0.0
servers:
- url: https://api.fabric.inc/v3
  description: Production server
- url: https://stg.api.fabric.inc/v3
  description: Staging server
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:
    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.
    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.
    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.
    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.
    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.
    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
    Fulfillment:
      type: object
      properties:
        id:
          type: string
          description: The Fulfillment ID generated when a fulfillment was created using the [Create fulfillment](/v3/api-reference/carts-v3/fulfillment/create-fulfillments) endpoint.
          example: d6229cdb-0c5b-4885-b1b2-13b94d02488e
        type:
          type: string
          description: Determines the type of fulfillment.
          example: SHIP_TO
          enum:
          - SHIP_TO
          - BOPIS
          - ROPIS
        refId:
          type: string
          description: An alternative identifier for fulfillments, used for additional tracking or referencing.
          example: '398427903843'
        attributes:
          type: object
          description: Custom attributes to provide more context to the fulfillment, such as where it was made.
          additionalProperties:
            type: object
            description: Custom attributes to provide more context to the fulfillment, such as where it was made.
            example:
              source: store
          example:
            source: store
        originAddress:
          type: string
          description: The identifier of the address where the item is being fulfilled.
          example: a8577d7f-0d4d-4b22-8e85-7b4a2e90dc93
        destinationAddress:
          type: string
          description: The identifier of the address where the item is being shipped.
          example: a8577d7f-0d4d-4b22-8e85-7b4a2e90dc93
        locationId:
          type: string
          description: Unique identifier of the store.
          example: CA
        pickupPerson:
          $ref: '#/components/schemas/PickupPerson'
        price:
          $ref: '#/components/schemas/ResourcePrice'
        promotions:
          $ref: '#/components/schemas/FulfillmentPromotionCollection'
        fees:
          $ref: '#/components/schemas/FeesCollection'
        adjustments:
          $ref: '#/components/schemas/AdjustmentCollection'
        tax:
          $ref: '#/components/schemas/TaxCollection'
      description: A fulfillment object containing important fulfillment information.
    Verifier:
      type: object
      properties:
        type:
          type: string
          description: The type of verification used, such as a token.
          example: TOKEN
        key:
          type: string
          description: The key used for payment verification.
          example: CH39082K439R0
      description: Payment verifier
    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.
    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.
    AddItemsToCartRequest:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/AddItemPayload'
          description: An array containing item objects with their information. One or more items can be added to the cart by passing multiple item objects into the array of the request body.
    Fee:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the fee associated with the cart that was generated when making [Create fee](/v3/api-reference/carts-v3/fees/create-fees) endpoint.
          example: a8577d7f-0d4d-4b22-8e85-7b4a2e90dc93
        name:
          type: string
          description: Name of the fee
          example: Eco Fee
        price:
          $ref: '#/components/schemas/ResourcePrice'
        taxable:
          type: boolean
          description: A boolean value that determines whether a fee is taxable.
          example: true
        attributes:
          type: object
          additionalProperties:
            type: object
            description: Custom attributes that provide more context for the fee, such as the source of the fee.
            example:
              source: eco
          description: Custom attributes that provide more context for the fee, such as the source of the fee.
          example:
            source: eco
        tax:
          $ref: '#/components/schemas/TaxCollection'
        updatedAt:
          type: string
          description: The date and time when the fee was last updated.
          example: 2024-06-13 16:50:00.682000+00:00
        createdAt:
          type: string
          description: The date and time when the fee was created.
          example: 2024-06-13 16:50:00.682000+00:00
        taxDetails:
          $ref: '#/components/schemas/FeeTaxDetails'
      description: A collection of fees associated with the cart.
    UpdateLineItemFulfillment:
      type: object
      properties:
        id:
          type: string
          description: The Fulfillment ID generated when a fulfillment was created using the [Create fulfillment](/v3/api-reference/carts-v3/fulfillment/create-fulfillments) endpoint.
        price:
          $ref: '#/components/schemas/UpdateLineItemFulfillmentPrice'
        inventory:
          $ref: '#/components/schemas/UpdateLineItemFulfillmentInventory'
    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
    UpdateLineItemFulfillmentPrice:
      type: object
      properties:
        amount:
          type: number
          description: The fulfillment amount
      required:
      - amount
    FulfillmentPromotion:
      type: object
      properties:
        id:
          type: string
          description: Identifier of a promotion
          example: bb44db95-6fbd-4eed-a1ed-4d99bc91250f
        amount:
          type: number
          description: The discount amount applied to a fulfillment.
          example: 15
      description: Fulfillment Promotion
    ConfigurationValue:
      type: string
      description: Configuration values that define [behavior actions](/v3/api-reference/carts-v3/configuration-behaviors).
      enum:
      - BLOCK
      - REJECT
      - WARN
      - NONE
    FulfillmentPromotionCollection:
      type: object
      properties:
        total:
          type: number
          description: The total discount applied within a collection.
          example: 15
        collection:
          type: array
          description: An array containing the promotions within a collection.
          items:
            $ref: '#/components/schemas/FulfillmentPromotion'
      description: A collection of promotions applied to the fulfillment.
    PIMValidationData:
      type: object
      properties:
        availableSkus:
          type: array
          description: An array containing product validation data.
          items:
            $ref: '#/components/schemas/SKUValidationData'
    MaxQtyBehaviour:
      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 setting is WARN.

            '
          example: WARN
          enum:
          - WARN
          - DROP
          - REJECT
          - NONE
      description: Max quantity behaviors
    UpdateLineItemFulfillmentInventory:
      type: object
      properties:
        type:
          type: string
          description: The type of inventory for fulfillment.
        channels:
          type: object
          description: The channel where the cart was fulfilled.
      required:
      - type
      - channels
    TaxConfiguration:
      type: object
      properties:
        cacheExpiry:
          type: integer
          description: Duration in seconds until the tax data expires.
          format: int64
          example: 7776000
        behaviors:
          $ref: '#/components/schemas/TaxBehaviour'
      description: Configuration settings for tax calculations and behaviors.
    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.
    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'
    OrderConfiguration:
      type: object
      properties:
        validate:
          $ref: '#/components/schemas/OrderValidateConfiguration'
      description: Configuration settings related to order validation and processing.
    PaymentCollection:
      type: object
      properties:
        authorized:
          type: number
          description: The payments that have been authorized within the collection.
          example: 800
        collection:
          type: array
          description: An array containing payments within the collection.
          items:
            $ref: '#/components/schemas/Payment'
      description: An object containing a collection of payments added to the cart.
    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
    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
    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.
    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
    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.
    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
    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
    PromotionsConfiguration:
      type: object
      description: Configuration settings related to promotions and their cache expiry.
      properties:
        cacheExpiry:
          type: integer
          example: 86400
        behaviors:
          $ref: '#/components/schemas/Behavior'
    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"]'
    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
    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
    UpdateLineItem:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the item.
        refId:
          type: string
          description: An alternative identifier associated with the item, used for additional tracking or referencing.
        priceListId:
          type: string
          description: The unique identifier for a price list, used to reference and manage pricing information.
        quantity:
          type: integer
          description: An integer that displays the total quantity of the item.
        price:
          $ref: '#/components/schemas/PriceDetail'
        fulfillment:
          $ref: '#/components/schemas/UpdateLineItemFulfillment'
        attributes:
          type: object
          description: Custom attributes to provide more context for the item.
      required:
      - id
    ItemFulfillment:
      type: object
      properties:
        id:
          type: string
          description: The identifier of the fulfillment linked to the item.
          example: 6d65755f-b1d9-4c9d-bb5b-118d317f8db4
        price:
          $ref: '#/components/schemas/ResourcePrice'
        inventory:
          $ref: '#/components/schemas/Inventory'
        tax:
          $ref: '#/components/schemas/TaxCollection'
      description: Item Fulfillment
    ProrationSpread:
      type: object
      properties:
        spread:
          type: array
          description: An array containing details about adjustments made to charges based on pa

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