Commerce Layer line_items API

openapi: 3.1.0
info:
  title: Commerce Layer addresses line_items API
  version: 7.10.1
  contact:
    name: API Support
    url: https://commercelayer.io
    email: support@commercelayer.io
  description: Headless Commerce for Global Brands.
servers:
- url: https://{your_organization_slug}.commercelayer.io/api
  description: API
- url: https://core.commercelayer.io/users/sign_in
  description: Sign in
- url: https://docs.commercelayer.io/api
  description: API reference
security:
- bearerAuth: []
tags:
- name: line_items
  description: resource type
paths:
  /line_item_options/{lineItemOptionId}/line_item:
    get:
      operationId: GET/lineItemOptionId/line_item
      summary: Retrieve the line item associated to the line item option
      description: Retrieve the line item associated to the line item option
      tags:
      - line_items
      parameters:
      - name: lineItemOptionId
        in: path
        schema:
          type: string
        required: true
        description: The resource's id
      responses:
        '200':
          description: The line_item associated to the line item option
  /line_items:
    get:
      operationId: GET/line_items
      summary: List all line items
      description: List all line items
      tags:
      - line_items
      responses:
        '200':
          description: A list of line item objects
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/lineItemResponseList'
    post:
      operationId: POST/line_items
      summary: Create a line item
      description: Create a line item
      tags:
      - line_items
      requestBody:
        required: true
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/lineItemCreate'
      responses:
        '201':
          description: The created line item object
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/lineItemResponse'
  /line_items/{lineItemId}:
    get:
      operationId: GET/line_items/lineItemId
      summary: Retrieve a line item
      description: Retrieve a line item
      tags:
      - line_items
      parameters:
      - name: lineItemId
        in: path
        schema:
          type: string
        required: true
        description: The resource's id
      responses:
        '200':
          description: The line item object
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/lineItemResponse'
    patch:
      operationId: PATCH/line_items/lineItemId
      summary: Update a line item
      description: Update a line item
      tags:
      - line_items
      parameters:
      - name: lineItemId
        in: path
        schema:
          type: string
        required: true
        description: The resource's id
      requestBody:
        required: true
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/lineItemUpdate'
      responses:
        '200':
          description: The updated line item object
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/lineItemResponse'
    delete:
      operationId: DELETE/line_items/lineItemId
      summary: Delete a line item
      description: Delete a line item
      tags:
      - line_items
      parameters:
      - name: lineItemId
        in: path
        schema:
          type: string
        required: true
        description: The resource's id
      responses:
        '204':
          description: No content
  /order_subscription_items/{orderSubscriptionItemId}/source_line_item:
    get:
      operationId: GET/orderSubscriptionItemId/source_line_item
      summary: Retrieve the source line item associated to the order subscription item
      description: Retrieve the source line item associated to the order subscription item
      tags:
      - line_items
      parameters:
      - name: orderSubscriptionItemId
        in: path
        schema:
          type: string
        required: true
        description: The resource's id
      responses:
        '200':
          description: The source_line_item associated to the order subscription item
  /orders/{orderId}/line_items:
    get:
      operationId: GET/orderId/line_items
      summary: Retrieve the line items associated to the order
      description: Retrieve the line items associated to the order
      tags:
      - line_items
      parameters:
      - name: orderId
        in: path
        schema:
          type: string
        required: true
        description: The resource's id
      responses:
        '200':
          description: The line_items associated to the order
  /return_line_items/{returnLineItemId}/line_item:
    get:
      operationId: GET/returnLineItemId/line_item
      summary: Retrieve the line item associated to the return line item
      description: Retrieve the line item associated to the return line item
      tags:
      - line_items
      parameters:
      - name: returnLineItemId
        in: path
        schema:
          type: string
        required: true
        description: The resource's id
      responses:
        '200':
          description: The line_item associated to the return line item
  /shipments/{shipmentId}/line_items:
    get:
      operationId: GET/shipmentId/line_items
      summary: Retrieve the line items associated to the shipment
      description: Retrieve the line items associated to the shipment
      tags:
      - line_items
      parameters:
      - name: shipmentId
        in: path
        schema:
          type: string
        required: true
        description: The resource's id
      responses:
        '200':
          description: The line_items associated to the shipment
  /stock_line_items/{stockLineItemId}/line_item:
    get:
      operationId: GET/stockLineItemId/line_item
      summary: Retrieve the line item associated to the stock line item
      description: Retrieve the line item associated to the stock line item
      tags:
      - line_items
      parameters:
      - name: stockLineItemId
        in: path
        schema:
          type: string
        required: true
        description: The resource's id
      responses:
        '200':
          description: The line_item associated to the stock line item
  /stock_reservations/{stockReservationId}/line_item:
    get:
      operationId: GET/stockReservationId/line_item
      summary: Retrieve the line item associated to the stock reservation
      description: Retrieve the line item associated to the stock reservation
      tags:
      - line_items
      parameters:
      - name: stockReservationId
        in: path
        schema:
          type: string
        required: true
        description: The resource's id
      responses:
        '200':
          description: The line_item associated to the stock reservation
  /stock_transfers/{stockTransferId}/line_item:
    get:
      operationId: GET/stockTransferId/line_item
      summary: Retrieve the line item associated to the stock transfer
      description: Retrieve the line item associated to the stock transfer
      tags:
      - line_items
      parameters:
      - name: stockTransferId
        in: path
        schema:
          type: string
        required: true
        description: The resource's id
      responses:
        '200':
          description: The line_item associated to the stock transfer
components:
  schemas:
    lineItemUpdate:
      required:
      - data
      type: object
      properties:
        data:
          type: object
          required:
          - type
          - id
          - attributes
          properties:
            type:
              type: string
              description: The resource's type
              enum:
              - line_items
            id:
              type: string
              description: Unique identifier for the resource (hash).
              example: XAyRWNUzyN
            attributes:
              type: object
              properties:
                sku_code:
                  type: string
                  description: The code of the associated SKU.
                  example: TSHIRTMM000000FFFFFFXLXX
                  nullable: true
                bundle_code:
                  type: string
                  description: The code of the associated bundle.
                  example: BUNDLEMM000000FFFFFFXLXX
                  nullable: true
                quantity:
                  type: integer
                  description: The line item quantity.
                  example: 4
                  nullable: false
                _external_price:
                  type: boolean
                  description: When creating or updating a new line item, set this attribute to '1' if you want to inject the unit_amount_cents price from an external source. Any successive price computation will be done externally, until the attribute is reset to '0'.
                  example: true
                  nullable: false
                _reserve_stock:
                  type: boolean
                  description: Send this attribute if you want to reserve the stock for the line item's SKUs quantity. Stock reservations expiration depends on the inventory model's cutoff. When used on update the existing active stock reservations are renewed. Cannot be passed by sales channels.
                  example: true
                  nullable: false
                _reset_restocked_quantity:
                  type: boolean
                  description: Send this attribute if you want to reset the quantity restocked by a return or by an order/shipment cancel. This will allow for multiple returns, albeit you need to adjust the stock manually. Cannot be passed by sales channels.
                  example: true
                  nullable: false
                unit_amount_cents:
                  type: integer
                  description: The unit amount of the line item, in cents. Can be specified only via an integration application, or when the item is missing, otherwise is automatically computed by using one of the available methods. Cannot be passed by sales channels.
                  example: 10000
                  nullable: true
                compare_at_amount_cents:
                  type: integer
                  description: The compared price amount, in cents. Useful to display a percentage discount.
                  example: 13000
                  nullable: true
                options_amount_cents:
                  type: integer
                  description: The options amount of the line item, in cents. Cannot be passed by sales channels.
                  example: 1000
                  nullable: true
                name:
                  type: string
                  description: The name of the line item. When blank, it gets populated with the name of the associated item (if present).
                  example: Men's Black T-shirt with White Logo (XL)
                  nullable: true
                image_url:
                  type: string
                  description: The image_url of the line item. When blank, it gets populated with the image_url of the associated item (if present, SKU only).
                  example: https://img.yourdomain.com/skus/xYZkjABcde.png
                  nullable: true
                frequency:
                  type: string
                  description: The frequency which generates a subscription. Must be supported by existing associated subscription_model.
                  example: monthly
                  nullable: true
                _reset_circuit:
                  type: boolean
                  description: Send this attribute if you want to reset the circuit breaker associated to this resource to 'closed' state and zero failures count. Cannot be passed by sales channels.
                  example: true
                  nullable: false
                _add_tags:
                  type: string
                  description: Comma separated list of tags to be added. Duplicates, invalid and non existing ones are discarded. Cannot be passed by sales channels.
                _remove_tags:
                  type: string
                  description: Comma separated list of tags to be removed. Duplicates, invalid and non existing ones are discarded. Cannot be passed by sales channels.
                reference:
                  type: string
                  description: A string that you can use to add any external identifier to the resource. This can be useful for integrating the resource to an external system, like an ERP, a marketing tool, a CRM, or whatever.
                  example: ANY-EXTERNAL-REFEFERNCE
                  nullable: true
                reference_origin:
                  type: string
                  description: Any identifier of the third party system that defines the reference code.
                  example: ANY-EXTERNAL-REFEFERNCE-ORIGIN
                  nullable: true
                metadata:
                  type: object
                  description: Set of key-value pairs that you can attach to the resource. This can be useful for storing additional information about the resource in a structured format.
                  example:
                    foo: bar
                  nullable: true
            relationships:
              type: object
              properties:
                tags:
                  required:
                  - data
                  type: object
                  properties:
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - tags
                        id:
                          type: string
                          description: Unique identifier for the resource (hash).
                          example: XAyRWNUzyN
    lineItemCreate:
      required:
      - data
      type: object
      properties:
        data:
          type: object
          required:
          - type
          - attributes
          properties:
            type:
              type: string
              description: The resource's type
              enum:
              - line_items
            attributes:
              type: object
              properties:
                sku_code:
                  type: string
                  description: The code of the associated SKU.
                  example: TSHIRTMM000000FFFFFFXLXX
                bundle_code:
                  type: string
                  description: The code of the associated bundle.
                  example: BUNDLEMM000000FFFFFFXLXX
                quantity:
                  type: integer
                  description: The line item quantity.
                  example: 4
                _external_price:
                  type: boolean
                  description: When creating or updating a new line item, set this attribute to '1' if you want to inject the unit_amount_cents price from an external source. Any successive price computation will be done externally, until the attribute is reset to '0'.
                  example: true
                _update_quantity:
                  type: boolean
                  description: When creating a new line item, set this attribute to '1' if you want to update the line item quantity (if present) instead of creating a new line item for the same SKU.
                  example: true
                _reserve_stock:
                  type: boolean
                  description: Send this attribute if you want to reserve the stock for the line item's SKUs quantity. Stock reservations expiration depends on the inventory model's cutoff. When used on update the existing active stock reservations are renewed. Cannot be passed by sales channels.
                  example: true
                _reset_restocked_quantity:
                  type: boolean
                  description: Send this attribute if you want to reset the quantity restocked by a return or by an order/shipment cancel. This will allow for multiple returns, albeit you need to adjust the stock manually. Cannot be passed by sales channels.
                  example: true
                unit_amount_cents:
                  type: integer
                  description: The unit amount of the line item, in cents. Can be specified only via an integration application, or when the item is missing, otherwise is automatically computed by using one of the available methods. Cannot be passed by sales channels.
                  example: 10000
                compare_at_amount_cents:
                  type: integer
                  description: The compared price amount, in cents. Useful to display a percentage discount.
                  example: 13000
                name:
                  type: string
                  description: The name of the line item. When blank, it gets populated with the name of the associated item (if present).
                  example: Men's Black T-shirt with White Logo (XL)
                image_url:
                  type: string
                  description: The image_url of the line item. When blank, it gets populated with the image_url of the associated item (if present, SKU only).
                  example: https://img.yourdomain.com/skus/xYZkjABcde.png
                item_type:
                  type: string
                  description: The type of the associated item. One of 'skus', 'bundles', 'gift_cards', 'shipments', 'payment_methods', 'adjustments', 'discount_engine_items', 'percentage_discount_promotions', 'free_shipping_promotions', 'buy_x_pay_y_promotions', 'free_gift_promotions', 'fixed_price_promotions', 'external_promotions', 'fixed_amount_promotions', or 'flex_promotions'.
                  example: skus
                  enum:
                  - skus
                  - bundles
                  - gift_cards
                  - shipments
                  - payment_methods
                  - adjustments
                  - discount_engine_items
                  - percentage_discount_promotions
                  - free_shipping_promotions
                  - buy_x_pay_y_promotions
                  - free_gift_promotions
                  - fixed_price_promotions
                  - external_promotions
                  - fixed_amount_promotions
                  - flex_promotions
                frequency:
                  type: string
                  description: The frequency which generates a subscription. Must be supported by existing associated subscription_model.
                  example: monthly
                reference:
                  type: string
                  description: A string that you can use to add any external identifier to the resource. This can be useful for integrating the resource to an external system, like an ERP, a marketing tool, a CRM, or whatever.
                  example: ANY-EXTERNAL-REFEFERNCE
                reference_origin:
                  type: string
                  description: Any identifier of the third party system that defines the reference code.
                  example: ANY-EXTERNAL-REFEFERNCE-ORIGIN
                metadata:
                  type: object
                  description: Set of key-value pairs that you can attach to the resource. This can be useful for storing additional information about the resource in a structured format.
                  example:
                    foo: bar
              required:
              - quantity
            relationships:
              type: object
              properties:
                order:
                  required:
                  - data
                  type: object
                  properties:
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - orders
                        id:
                          type: string
                          description: Unique identifier for the resource (hash).
                          example: XAyRWNUzyN
                item:
                  required:
                  - data
                  type: object
                  properties:
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - skus
                          - bundles
                          - gift_cards
                          - shipments
                          - payment_methods
                          - adjustments
                          - discount_engine_items
                          - percentage_discount_promotions
                          - free_shipping_promotions
                          - buy_x_pay_y_promotions
                          - free_gift_promotions
                          - fixed_price_promotions
                          - external_promotions
                          - fixed_amount_promotions
                          - flex_promotions
                        id:
                          type: string
                          description: Unique identifier for the resource (hash).
                          example: XAyRWNUzyN
                  oneOf:
                  - $ref: '#/components/schemas/sku'
                  - $ref: '#/components/schemas/bundle'
                  - $ref: '#/components/schemas/giftCard'
                  - $ref: '#/components/schemas/shipment'
                  - $ref: '#/components/schemas/paymentMethod'
                  - $ref: '#/components/schemas/adjustment'
                  - $ref: '#/components/schemas/discountEngineItem'
                  - $ref: '#/components/schemas/percentageDiscountPromotion'
                  - $ref: '#/components/schemas/freeShippingPromotion'
                  - $ref: '#/components/schemas/buyXPayYPromotion'
                  - $ref: '#/components/schemas/freeGiftPromotion'
                  - $ref: '#/components/schemas/fixedPricePromotion'
                  - $ref: '#/components/schemas/externalPromotion'
                  - $ref: '#/components/schemas/fixedAmountPromotion'
                  - $ref: '#/components/schemas/flexPromotion'
                tags:
                  required:
                  - data
                  type: object
                  properties:
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - tags
                        id:
                          type: string
                          description: Unique identifier for the resource (hash).
                          example: XAyRWNUzyN
              required:
              - order
    lineItemResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            id:
              type: string
              description: Unique identifier for the resource (hash).
              example: XAyRWNUzyN
            type:
              type: string
              description: The resource's type
              enum:
              - line_items
            links:
              type: object
              properties:
                self:
                  type: string
                  description: URL
            attributes:
              $ref: '#/components/schemas/lineItem/properties/data/properties/attributes'
            relationships:
              type: object
              properties:
                order:
                  type: object
                  properties:
                    links:
                      type: object
                      properties:
                        self:
                          type: string
                          description: URL
                        related:
                          type: string
                          description: URL
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - order
                        id:
                          type: string
                          description: The resource ID
                item:
                  type: object
                  properties:
                    links:
                      type: object
                      properties:
                        self:
                          type: string
                          description: URL
                        related:
                          type: string
                          description: URL
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - item
                        id:
                          type: string
                          description: The resource ID
                sku:
                  type: object
                  properties:
                    links:
                      type: object
                      properties:
                        self:
                          type: string
                          description: URL
                        related:
                          type: string
                          description: URL
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - sku
                        id:
                          type: string
                          description: The resource ID
                bundle:
                  type: object
                  properties:
                    links:
                      type: object
                      properties:
                        self:
                          type: string
                          description: URL
                        related:
                          type: string
                          description: URL
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - bundle
                        id:
                          type: string
                          description: The resource ID
                adjustment:
                  type: object
                  properties:
                    links:
                      type: object
                      properties:
                        self:
                          type: string
                          description: URL
                        related:
                          type: string
                          description: URL
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - adjustment
                        id:
                          type: string
                          description: The resource ID
                gift_card:
                  type: object
                  properties:
                    links:
                      type: object
                      properties:
                        self:
                          type: string
                          description: URL
                        related:
                          type: string
                          description: URL
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - gift_card
                        id:
                          type: string
                          description: The resource ID
                shipment:
                  type: object
                  properties:
                    links:
                      type: object
                      properties:
                        self:
                          type: string
                          description: URL
                        related:
                          type: string
                          description: URL
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - shipment
                        id:
                          type: string
                          description: The resource ID
                payment_method:
                  type: object
                  properties:
                    links:
                      type: object
                      properties:
                        self:
                          type: string
                          description: URL
                        related:
                          type: string
                          description: URL
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - payment_method
                        id:
                          type: string
                          description: The resource ID
                line_item_options:
                  type: object
                  properties:
                    links:
                      type: object
                      properties:
                        self:
                          type: string
                          description: URL
                        related:
                          type: string
                          description: URL
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - line_item_options
                        id:
                          type: string
                          description: The resource ID
                return_line_items:
                  type: object
                  properties:
                    links:
                      type: object
                      properties:
                        self:
                          type: string
                          description: URL
                        related:
                          type: string
                          description: URL
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - return_line_items
                        id:
                          type: string
                          description: The resource ID
                stock_reservations:
                  type: object
                  properties:
                    links:
            

# --- truncated at 32 KB (224 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/commerce-layer/refs/heads/main/openapi/commerce-layer-line-items-api-openapi.yml