> ## Documentation Index
> Fetch the complete documentation index at: https://docs.loopreturns.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Upsert Order

> Upsert an order using the external_id.



## OpenAPI

````yaml openapi/orders-api-2026-07.yaml put /orders
openapi: 3.1.0
info:
  title: Orders API
  version: v1
  description: >-
    The Orders API allows managing your shop's orders within the Loop Platform.


    This document describes the create, upsert and update operations as of API
    version `2026-07`

    (also used by `v1`). In `2026-07` the order `created_at` field is optional.
    From `2026-10` it is

    required.


    ### Resource identifier format


    Resource identifiers (the `id` field and related global-identifier fields)
    are returned as JSON

    integers by default. To receive them as strings instead, send the

    `X-Loop-Global-Identifier-Type: string` request header.
  contact:
    name: Loop Returns
    url: https://loopreturns.com/
servers:
  - url: https://api.loopreturns.com/api/2026-07
    description: 2026-07
security: []
tags:
  - name: Orders
paths:
  /orders:
    put:
      tags:
        - Orders
      summary: Upsert Order
      description: Upsert an order using the external_id.
      operationId: upsertOrder
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertOrderRequest'
            examples:
              multiLinePosRefund:
                summary: Order with multi-line POS refund
                value:
                  external_id: order-10042
                  name: '#10042'
                  status: active
                  taxes_included: false
                  total_price:
                    amount: 25400
                    currency_code: USD
                  sales_channel: online
                  created_at: '2026-08-07T09:15:00-07:00'
                  source:
                    name: newstore
                  line_items:
                    - external_id: line-item-a
                      product:
                        external_id: product-a
                      unit_price:
                        amount: 7800
                        currency_code: USD
                      taxable: true
                      quantity: 2
                    - external_id: line-item-b
                      product:
                        external_id: product-b
                      unit_price:
                        amount: 9800
                        currency_code: USD
                      taxable: true
                      quantity: 1
                  refunds:
                    - external_id: pos-refund-2026-0807-0042
                      type: line_item
                      amount:
                        amount: 17600
                        currency_code: USD
                      line_items:
                        - external_id: line-item-a
                          quantity: 1
                          restock: true
                        - external_id: line-item-b
                          quantity: 1
                          restock: false
                      created_at: '2026-08-07T14:32:00-07:00'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  order:
                    $ref: '#/components/schemas/OrderResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - write: []
components:
  schemas:
    UpsertOrderRequest:
      title: UpsertOrderRequest
      type: object
      properties:
        external_id:
          type:
            - string
          maxLength: 100
          examples:
            - 564400c7-7a6b-4f29-b6a5-7bb580b2992c
          description: External ID of the order.
        name:
          type:
            - string
          maxLength: 100
          description: The name of the order.
        secondary_identifier:
          type:
            - string
            - 'null'
          maxLength: 100
          description: >
            An optional secondary identifier for the order, enabling customer
            lookup by an alternate reference. Use this for any supplementary
            order ID your system tracks — for example a fulfillment system ID
            (e.g. NetSuite), a marketplace order number, or a confirmation
            number. Customers can look up their return using either name or
            secondary_identifier.
        sales_channel:
          type: string
          maxLength: 255
          examples:
            - shopify
          description: >-
            If a channel with this name is not already associated with the shop,
            it will be used to create a new channel.
        customer:
          type:
            - object
            - 'null'
          oneOf:
            - properties:
                id:
                  type: integer
                  format: int64
                  description: >
                    Global identifier of an existing customer. Required if
                    additional customer details are not provided.
            - properties:
                external_id:
                  type:
                    - string
                    - 'null'
                  maxLength: 100
                  examples:
                    - 564400c7-7a6b-4f29-b6a5-7bb580b2992c
                  description: >
                    If this is the only parameter, it will be used to associate
                    an existing customer with the order. If it is passed along
                    with the other properties, it will be used to create a new
                    customer.
                first_name:
                  type:
                    - string
                    - 'null'
                  maxLength: 50
                  description: Customer first name.
                last_name:
                  type:
                    - string
                    - 'null'
                  maxLength: 50
                  description: Customer last name.
                email:
                  type:
                    - string
                    - 'null'
                  maxLength: 255
                  description: Customer email address.
                phone:
                  type:
                    - string
                    - 'null'
                  maxLength: 30
                  description: Customer phone.
        status:
          type: string
          enum:
            - active
            - archived
            - cancelled
            - unknown
          description: Status of the Order.
        shipping_address:
          $ref: '#/components/schemas/Address'
        billing_address:
          $ref: '#/components/schemas/Address'
        taxes_included:
          type:
            - boolean
        total_price:
          $ref: '#/components/schemas/MoneySet'
          description: >
            The price of the order in minor units, such as cents, with its
            corresponding currency.
        total_price_presentment:
          anyOf:
            - $ref: '#/components/schemas/MoneySet'
            - type: 'null'
          description: >
            The price of the order in minor units, such as cents. This is
            included if the price was shown to the customer in an alternate
            currency.
        total_discounts:
          anyOf:
            - $ref: '#/components/schemas/MoneySet'
            - type: 'null'
          description: >
            The deduction from the original order price as a way to promote
            sales, special offers, or customer loyalty rewards.
        total_discounts_presentment:
          anyOf:
            - $ref: '#/components/schemas/MoneySet'
            - type: 'null'
          description: >
            The deduction from the original order price as a way to promote
            sales, special offers, or customer loyalty rewards. This price is
            discounted from the original price according to the customer's local
            currency.
        total_taxes:
          anyOf:
            - $ref: '#/components/schemas/MoneySet'
            - type: 'null'
          description: The tax amount for the order.
        total_taxes_presentment:
          anyOf:
            - $ref: '#/components/schemas/MoneySet'
            - type: 'null'
          description: >-
            The tax amount for the order according to the customer's local
            currency.
        order_discounts:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/OrderDiscounts'
        shipping_lines:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/ShippingLineData'
        refunds:
          type: array
          items:
            $ref: '#/components/schemas/RefundItems'
          description: List of refunds associated with the order.
        line_items:
          type: array
          items:
            $ref: '#/components/schemas/LineItem'
          description: List of order line items associated with the order.
        fulfillments:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/Fulfillment'
          description: Fulfillment information for the order.
        source:
          type: object
          description: The source system that created the order.
          required:
            - name
          properties:
            name:
              type: string
              maxLength: 255
              description: Name of the source system (e.g. 'shopify', 'hubble').
        tags:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/TagRequestData'
        created_at:
          oneOf:
            - $ref: '#/components/schemas/Date'
            - type: 'null'
          description: >-
            The date and time the order was created in the source system, in
            ATOM format (ISO 8601/RFC 3339). Optional in API version `2026-07`,
            so you can leave it out or send `null`. From `2026-10` this field is
            required.
        updated_at:
          oneOf:
            - $ref: '#/components/schemas/Date'
            - type: 'null'
        cancelled_at:
          oneOf:
            - $ref: '#/components/schemas/Date'
            - type: 'null'
          description: >
            Timestamp when the order was cancelled. Required when `status` is
            `cancelled` — include both fields together so Loop can reverse
            Checkout+ protection coverage.
        financial_status:
          type:
            - string
            - 'null'
          maxLength: 30
          enum:
            - pending
            - authorized
            - partially_paid
            - paid
            - partially_refunded
            - refunded
            - voided
            - null
          description: The financial status of the order.
        cancel_reason:
          type:
            - string
            - 'null'
          maxLength: 30
          enum:
            - customer
            - declined
            - fraud
            - inventory
            - other
            - staff
            - null
          description: The reason the order was cancelled, if applicable.
        processed_at:
          oneOf:
            - $ref: '#/components/schemas/Date'
            - type: 'null'
          description: The date and time when the order was processed in the source system.
        browser_ip:
          oneOf:
            - type: string
              format: ipv4
            - type: string
              format: ipv6
            - type: 'null'
          maxLength: 45
          description: The IP address of the browser used to place the order.
        client_details_user_agent:
          type:
            - string
            - 'null'
          maxLength: 1000
          description: The user agent string of the browser used to place the order.
        total_tip_received:
          anyOf:
            - $ref: '#/components/schemas/MoneySet'
            - type: 'null'
          description: The total tip amount received for the order.
        metadata:
          type:
            - array
            - 'null'
          description: >-
            Key/value metadata to attach to the order. A `return_id` key must
            reference a return that exists for the shop.
          items:
            type: object
            required:
              - key
              - value
            properties:
              key:
                type: string
                maxLength: 100
              value:
                description: Any value associated with the key.
        fees:
          type:
            - array
            - 'null'
          description: >-
            Fees associated with the order (for example, checkout-time
            protection offers).
          items:
            type: object
            required:
              - name
              - amount
            properties:
              name:
                type: string
                maxLength: 255
              amount:
                $ref: '#/components/schemas/MoneySet'
              presentment_amount:
                anyOf:
                  - $ref: '#/components/schemas/MoneySet'
                  - type: 'null'
              tax:
                anyOf:
                  - $ref: '#/components/schemas/MoneySet'
                  - type: 'null'
              accepted_offer_mode:
                type:
                  - array
                  - 'null'
                items:
                  type: string
              external_id:
                type:
                  - string
                  - 'null'
                maxLength: 100
      required:
        - external_id
        - name
        - status
        - taxes_included
        - total_price
        - line_items
        - source
        - sales_channel
      examples:
        - external_id: order-10042
          name: '#10042'
          status: active
          taxes_included: false
          total_price:
            amount: 25400
            currency_code: USD
          sales_channel: online
          created_at: '2026-08-07T09:15:00-07:00'
          source:
            name: newstore
          line_items:
            - external_id: line-item-a
              product:
                external_id: product-a
              unit_price:
                amount: 7800
                currency_code: USD
              taxable: true
              quantity: 2
            - external_id: line-item-b
              product:
                external_id: product-b
              unit_price:
                amount: 9800
                currency_code: USD
              taxable: true
              quantity: 1
          refunds:
            - external_id: pos-refund-2026-0807-0042
              type: line_item
              amount:
                amount: 17600
                currency_code: USD
              line_items:
                - external_id: line-item-a
                  quantity: 1
                  restock: true
                - external_id: line-item-b
                  quantity: 1
                  restock: false
              created_at: '2026-08-07T14:32:00-07:00'
    OrderResponse:
      title: OrderResponse
      type: object
      properties:
        id:
          type: integer
          format: int64
          minimum: 1
          examples:
            - 810772123123123
          readOnly: true
        external_id:
          type:
            - string
            - 'null'
          examples:
            - 564400c7-7a6b-4f29-b6a5-7bb580b2992c
        name:
          type: string
        secondary_identifier:
          type:
            - string
            - 'null'
        source:
          type:
            - string
            - 'null'
        sales_channel:
          type:
            - string
            - 'null'
          description: The name of the channel.
          examples:
            - shopify
        customer:
          type: object
          properties:
            id:
              type: integer
              description: The global identifier of the customer.
              examples:
                - 123123123123123
            external_id:
              type:
                - string
                - 'null'
              examples:
                - 564400c7-7a6b-4f29-b6a5-7bb580b2992c
            sales_channel:
              type:
                - string
                - 'null'
              description: The name of the channel associated with the customer.
              examples:
                - shopify
            first_name:
              type: string
            last_name:
              type: string
            email:
              type: string
            phone:
              type: string
        status:
          type: string
          enum:
            - active
            - archived
            - cancelled
            - unknown
          description: Status of the Order.
        shipping_address:
          $ref: '#/components/schemas/Address'
        billing_address:
          $ref: '#/components/schemas/Address'
        taxes_included:
          type: boolean
        total_price:
          $ref: '#/components/schemas/MoneySet'
          description: >
            The price of the order in minor units, such as cents, with its
            corresponding currency.
        total_price_presentment:
          $ref: '#/components/schemas/MoneySet'
          description: >
            The price of the order in minor units, such as cents. This is
            included if the price was shown to the customer in an alternate
            currency.
        total_discounts:
          $ref: '#/components/schemas/MoneySet'
          description: >
            The deduction from the original order price as a way to promote
            sales, special offers, or customer loyalty rewards.
        total_discounts_presentment:
          $ref: '#/components/schemas/MoneySet'
          description: >
            The deduction from the original order price as a way to promote
            sales, special offers, or customer loyalty rewards. This price is
            discounted from the original price according to the customer's local
            currency.
        shipping_lines:
          $ref: '#/components/schemas/ShippingLines'
          description: The shipping lines for the order.
        order_discounts:
          $ref: '#/components/schemas/OrderDiscounts'
          description: The discounts for the order.
        total_taxes:
          $ref: '#/components/schemas/MoneySet'
          description: The tax amount for the order.
        total_taxes_presentment:
          $ref: '#/components/schemas/MoneySet'
          description: >-
            The tax amount for the order according to the customer's local
            currency.
        tags:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/TagRequestData'
        refunds:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/RefundItemsResponse'
        line_items:
          type: array
          items:
            $ref: '#/components/schemas/LineItemResponse'
        fulfillments:
          type: array
          items:
            $ref: '#/components/schemas/FulfillmentResponse'
        created_at:
          oneOf:
            - $ref: '#/components/schemas/Date'
            - type: 'null'
        updated_at:
          oneOf:
            - $ref: '#/components/schemas/Date'
            - type: 'null'
        financial_status:
          type:
            - string
            - 'null'
          enum:
            - pending
            - authorized
            - partially_paid
            - paid
            - partially_refunded
            - refunded
            - voided
            - null
          description: The financial status of the order.
        cancel_reason:
          type:
            - string
            - 'null'
          enum:
            - customer
            - declined
            - fraud
            - inventory
            - other
            - staff
            - null
          description: The reason the order was cancelled, if applicable.
        processed_at:
          oneOf:
            - $ref: '#/components/schemas/Date'
            - type: 'null'
          description: The date and time when the order was processed in the source system.
        browser_ip:
          oneOf:
            - type: string
              format: ipv4
            - type: string
              format: ipv6
            - type: 'null'
          maxLength: 45
          description: The IP address of the browser used to place the order.
        client_details_user_agent:
          type:
            - string
            - 'null'
          maxLength: 1000
          description: The user agent string of the browser used to place the order.
        total_tip_received:
          anyOf:
            - $ref: '#/components/schemas/MoneySet'
            - type: 'null'
          description: The total tip amount received for the order.
        warnings:
          type:
            - array
            - 'null'
          description: >-
            Non-fatal warnings about the order, surfaced after a successful
            write.
          items:
            type: object
            required:
              - code
              - message
            properties:
              code:
                type: string
              message:
                type: string
    Address:
      type: object
      properties:
        name:
          type:
            - string
            - 'null'
          maxLength: 100
          description: Recipient name.
        company:
          type:
            - string
            - 'null'
          maxLength: 100
          description: Recipient company.
        address1:
          type: string
          maxLength: 125
          description: Address line 1.
        address2:
          type:
            - string
            - 'null'
          maxLength: 125
          description: Address line 2.
        city:
          type:
            - string
          maxLength: 100
          description: City.
        region:
          type:
            - string
            - 'null'
          maxLength: 100
          description: State or Region.
        postal_code:
          type:
            - string
            - 'null'
          maxLength: 16
          description: Postal Code.
        country_code:
          type: string
          maxLength: 2
          description: Must be a valid 2 character country code.
      required:
        - address1
        - city
        - country_code
      examples:
        - name: John Smith
          company: Acme, Co
          address1: 123 Example St
          address2: Box 123
          city: Columbus
          region: OH
          postal_code: 12345
          country_code: US
    MoneySet:
      type: object
      examples:
        - amount: 50000
          currency_code: USD
        - amount: 25000
        - amount: 1500
          currency_code: EUR
      properties:
        amount:
          type: integer
          format: int32
          examples:
            - 25000
        currency_code:
          type:
            - string
          default: USD
          examples:
            - EUR
      required:
        - amount
        - currency_code
    OrderDiscounts:
      title: OrderDiscounts
      type: array
      items:
        $ref: '#/components/schemas/OrderDiscount'
    ShippingLineData:
      type: object
      properties:
        title:
          type:
            - string
        price:
          $ref: '#/components/schemas/MoneySet'
        discounts:
          $ref: '#/components/schemas/ShippingLineDiscount'
        tax_lines:
          $ref: '#/components/schemas/TaxLines'
    RefundItems:
      title: RefundItems
      description: >
        Refunds attached at the order level. Write-once identity is
        `external_id` when it is set: a new id is appended; an identical replay
        is a no-op. A different shape for an existing id is skipped with no
        client error — the stored row is unchanged and the write still succeeds
        (same success path as an identical replay). `external_id` may be null;
        those rows are not write-once and each send inserts. Sending `refunds:
        [{new}]` appends that refund and leaves unmentioned refunds in place.
        Omitting `refunds` or sending `refunds: []` does not remove refunds
        already on the order.
      type: array
      items:
        $ref: '#/components/schemas/OrderRefund'
    LineItem:
      type: object
      properties:
        id:
          type: integer
          format: int64
          minimum: 1
          examples:
            - 810772123123125
          readOnly: true
        external_id:
          type:
            - string
            - 'null'
          maxLength: 100
          examples:
            - 564400c7-7a6b-4f29-b6a5-7bb580b2992c
        product:
          $ref: '#/components/schemas/Product'
        product_variant:
          anyOf:
            - $ref: '#/components/schemas/ProductVariant'
            - type: 'null'
        quantity:
          type:
            - integer
            - 'null'
        unit_price:
          $ref: '#/components/schemas/MoneySet'
          description: >
            The price of the order line item in minor units, such as cents, with
            its corresponding currency.
        unit_price_presentment:
          anyOf:
            - $ref: '#/components/schemas/MoneySet'
            - type: 'null'
          description: >
            The price of the order line item in minor units, such as cents. This
            is included if the price was shown to the customer in an alternate
            currency.
        unit_discounts:
          anyOf:
            - $ref: '#/components/schemas/MoneySet'
            - type: 'null'
          description: >
            The deduction from the original order line item price as a way to
            promote sales, special offers, or customer loyalty rewards.
        unit_discounts_presentment:
          anyOf:
            - $ref: '#/components/schemas/MoneySet'
            - type: 'null'
          description: >
            The deduction from the original order line item price as a way to
            promote sales, special offers, or customer loyalty rewards. This
            price is discounted from the original price according to the
            customer's local currency.
        taxable:
          type:
            - boolean
            - 'null'
        tax_lines:
          oneOf:
            - $ref: '#/components/schemas/TaxLines'
            - type: 'null'
        refunds:
          oneOf:
            - $ref: '#/components/schemas/LineItemRefundItems'
            - type: 'null'
        discounts:
          oneOf:
            - $ref: '#/components/schemas/OrderLineItemDiscounts'
            - type: 'null'
        duties:
          oneOf:
            - $ref: '#/components/schemas/Duties'
            - type: 'null'
        metadata:
          type:
            - array
            - 'null'
          description: >
            Key/value metadata to attach to the line item. Providing this array
            replaces the line item's entire stored metadata set: keys omitted
            from the array are removed, and included keys are inserted or
            updated. Omit the field to leave existing metadata unchanged; send
            an empty array or `null` to clear all metadata. Duplicate keys
            within a single line item are rejected (422).
          items:
            $ref: '#/components/schemas/LineItemMetadataEntry'
      examples:
        - external_id: 564400c7-7a6b-4f29-b6a5-7bb580b2992c
          product:
            id: 1073741824
          product_variant:
            id: 1073741824
          quantity: 500
          unit_price:
            amount: 50000,
            currency_code: USD,
          unit_price_presentment:
            amount: 50000,
            currency_code: USD,
          unit_discounts:
            amount: 50000,
            currency_code: USD,
          unit_discounts_presentment:
            amount: 50000,
            currency_code: USD,
          taxable: true
          tax_lines:
            title: OH State Tax
            rate: 2.5
            price:
              amount: 50000
              currency_code: USD
          refunds:
            - external_id: refund-external-id
              type: line_item
              amount:
                amount: 1000
                currency_code: USD
              line_item:
                quantity: 1
                restock: true
              created_at: '2023-04-25T13:25:00-05:00'
              updated_at: '2023-04-25T13:25:00-05:00'
          discounts:
            external_id: refund-external-id
            name: Discount Name
            discount_type: amount
            code: AB123
            reason: This is a discount reason.
            rate: 1.4
            discount_relation: x
            tax_adjustment_money:
              amount: 50000
              currency_code: USD
            net_adjustment_money:
              amount: 50000
              currency_code: USD
          duties:
            hs_code: HS1234
            country_of_origin: USA
            price:
              amount: 50000
              currency_code: USD
            tax_lines:
              title: OH Municipal Tax
              rate: 1.8
              price:
                amount: 50000
                currency_code: USD
    Fulfillment:
      type: object
      required:
        - status
      properties:
        external_id:
          type:
            - string
            - 'null'
          maxLength: 100
          examples:
            - 564400c7-7a6b-4f29-b6a5-7bb580b2992c
        status:
          type: string
          enum:
            - success
            - failure
            - cancelled
            - pending
            - open
            - error
          description: >
            Status of the fulfillment:

            - `success` - The fulfillment was successful.

            - `failure` - The fulfillment request failed.

            - `cancelled` - The fulfillment was cancelled.

            - `pending` - Loop has created the fulfillment and is waiting for
            the fulfillment
              service to transition it to `open` or `success`.

            - `open` - The fulfillment has been acknowledged by the fulfillment
            service and is being processed.

            - `error` - There was an error with the fulfillment request.
        fulfilled_at:
          type:
            - string
            - 'null'
          format: date-time
          examples:
            - '2023-04-25T13:25:00-05:00'
          description: >-
            Set this field to indicate that the line item has been fulfilled, so
            it is returnable.
        delivered_at:
          type:
            - string
            - 'null'
          format: date-time
          examples:
            - '2023-04-27T16:40:00-05:00'
          description: >
            The delivery time for this fulfillment, as an ATOM timestamp or
            null. This field is for a Commerce Data order. For a Shopify order,
            Loop gets the delivery time from Shopify.

            When a return policy starts the return window from the delivery
            date, Loop uses this time. When no delivery time is stored, Loop
            uses `fulfilled_at`.

            If you omit this key, Loop keeps the stored time. If you send null,
            Loop clears the stored time. If you send a timestamp, Loop replaces
            the stored time, also when it is earlier than `fulfilled_at`. If you
            send any other value, Loop rejects the request and does not change
            the order.
        shipping_carrier:
          type: string
        location:
          description: Set to null to remove a location relationship.
          anyOf:
            - type: 'null'
            - $ref: '#/components/schemas/FulfillmentLocation'
        fulfillment_line_items:
          $ref: '#/components/schemas/FulfillmentLineItems'
        tracking_numbers:
          type:
            - array
            - 'null'
          items:
            type: string
    TagRequestData:
      type: string
      description: A tag used to classify and group orders.
      examples:
        - VIP
    Date:
      type: string
      format: date-time
      examples:
        - '2023-04-25T13:25:00-05:00'
    ShippingLines:
      title: ShippingLines
      type: array
      items:
        $ref: '#/components/schemas/ShippingLine'
    RefundItemsResponse:
      title: RefundItemsResponse
      type: array
      items:
        $ref: '#/components/schemas/OrderRefundResponse'
    LineItemResponse:
      title: LineItemResponse
      type: object
      properties:
        id:
          type: integer
          format: int64
          minimum: 1
          readOnly: true
        external_id:
          type:
            - string
            - 'null'
          maxLength: 100
        product:
          $ref: '#/components/schemas/ProductResponse'
        product_variant:
          anyOf:
            - $ref: '#/components/schemas/ProductVariantResponse'
            - type: 'null'
        quantity:
          type:
            - integer
            - 'null'
        unit_price:
          $ref: '#/components/schemas/MoneySet'
          description: >
            The price of the order line item in minor units, such as cents, with
            its corresponding currency.
        unit_price_presentment:
          anyOf:
            - $ref: '#/components/schemas/MoneySet'
            - type: 'null'
          description: >
            The price of the order line item in minor units, such as cents. This
            is included if the price was shown to the customer in an alternate
            currency.
        unit_discounts:
          anyOf:
            - $ref: '#/components/schemas/MoneySet'
            - type: 'null'
          description: >
            The deduction from the original order line item price as a way to
            promote sales, special offers, or customer loyalty rewards.
        unit_discounts_presentment:
          anyOf:
            - $ref: '#/components/schemas/MoneySet'
            - type: 'null'
          description: >
            The deduction from the original order line item price as a way to
            promote sales, special offers, or customer loyalty rewards. This
            price is discounted from the original price according to the
            customer's local currency.
        taxable:
          type:
            - boolean
            - 'null'
        tax_lines:
          oneOf:
            - $ref: '#/components/schemas/TaxLines'
            - type: 'null'
        refunds:
          oneOf:
            - $ref: '#/components/schemas/LineItemRefundItemsResponse'
            - type: 'null'
        discounts:
          oneOf:
            - $ref: '#/components/schemas/OrderLineItemDiscounts'
            - type: 'null'
        duties:
          oneOf:
            - $ref: '#/components/schemas/Duties'
            - type: 'null'
        metadata:
          type:
            - array
            - 'null'
          description: >
            Key/value metadata stored on the line item, returned as an array of
            `{ key, value }` entries.
          items:
            $ref: '#/components/schemas/LineItemMetadataEntry'
    FulfillmentResponse:
      title: FulfillmentResponse
      type: object
      required:
        - status
      properties:
        id:
          type: integer
          format: int64
          readOnly: true
          description: The global identifier for the fulfillment.
        external_id:
          type:
            - string
            - 'null'
          maxLength: 100
        status:
          type: string
          enum:
            - success
            - failure
            - cancelled
            - pending
            - open
            - error
          description: >
            Status of the fulfillment:

            - `success` - The fulfillment was successful.

            - `failure` - The fulfillment request failed.

            - `cancelled` - The fulfillment was cancelled.

            - `pending` - Loop has created the fulfillment and is waiting for
            the fulfillment
              service to transition it to `open` or `success`.

            - `open` - The fulfillment has been acknowledged by the fulfillment
            service and is being processed.

            - `error` - There was an error with the fulfillment request.
        fulfilled_at:
          type:
            - string
            - 'null'
          format: date-time
          description: The date and time the line item was fulfilled.
        delivered_at:
          type:
            - string
            - 'null'
          format: date-time
          examples:
            - '2023-04-27T16:40:00-05:00'
          description: >
            The stored delivery time for this fulfillment, as an ATOM timestamp
            or null when none is stored.
        shipping_carrier:
          type: string
        location:
          anyOf:
            - type: 'null'
            - $ref: '#/components/schemas/FulfillmentLocationResponse'
        fulfillment_line_items:
          $ref: '#/components/schemas/FulfillmentLineItems'
        tracking_numbers:
          type:
            - array
            - 'null'
          items:
            type: string
    OrderDiscount:
      title: OrderDiscount
      type: object
      properties:
        external_id:
          type:
            - string
            - 'null'
          maxLength: 100
          examples:
            - 564400c7-7a6b-4f29-b6a5-7bb580b2992c
        name:
          type:
            - string
          maxLength: 64
        discount_type:
          type: string
          description: Type of discount.
          enum:
            - amount
            - bonus
            - bonus_choice
            - fixed_price
            - free
            - percentage
            - percentage_off_options
            - price_book_price
            - total_fixed_price
        code:
          type:
            - string
          maxLength: 100
        reason:
          type:
            - string
          maxLength: 512
        rate:
          type:
            - number
        tax_adjustment_money:
          $ref: '#/components/schemas/MoneySet'
        net_adjustment_money:
          $ref: '#/components/schemas/MoneySet'
    ShippingLineDiscount:
      title: ShippingLineDiscount
      type: object
      properties:
        external_id:
          type:
            - string
            - 'null'
          maxLength: 100
          examples:
            - 564400c7-7a6b-4f29-b6a5-7bb580b2992c
        name:
          type:
            - string
        discount_type:
          type:
            - string
            - 'null'
          description: Type of discount.
          enum:
            - amount
            - bonus
            - bonus_choice
            - fixed_price
            - free
            - percentage
            - percentage_off_options
            - price_book_price
            - total_fixed_price
        code:
          type:
            - string
        reason:
          type:
            - string
        rate:
          type:
            - number
        net_adjustment_money:
          $ref: '#/components/schemas/MoneySet'
        tax_adjustment_money:
          $ref: '#/components/schemas/MoneySet'
    TaxLines:
      title: TaxLines
      type: array
      items:
        $ref: '#/components/schemas/TaxLine'
    OrderRefund:
      title: OrderRefund
      type: object
      required:
        - type
        - amount
      properties:
        external_id:
          type:
            - string
            - 'null'
          maxLength: 100
          description: External identifier for the refund event.
        type:
          type:
            - string
            - 'null'
          description: Type of refund.
          enum:
            - line_item
            - shipping
            - other
        amount:
          $ref: '#/components/schemas/MoneySet'
        line_items:
          type: array
          description: >
            Refunded order line items when `type` is `line_item`. Each child
            `external_id` must match a `line_items[].external_id` on the order
            (this request or already stored). Each child `id` must be the global
            identifier of an existing order line item. Do not send `line_items`
            on refunds nested under `line_items[].refunds[]`.
          items:
            $ref: '#/components/schemas/RefundLineItem'
        line_item:
          description: >
            Accepted on write for backward compatibility; coerced to
            `line_items` when `line_items` is omitted. Do not send both unless
            they describe the same single child.
          anyOf:
            - $ref: '#/components/schemas/RefundLineItem'
            - type: 'null'
        created_at:
          oneOf:
            - $ref: '#/components/schemas/Date'
            - type: 'null'
        updated_at:
          oneOf:
            - $ref: '#/components/schemas/Date'
            - type: 'null'
      allOf:
        - if:
            properties:
              type:
                const: line_item
            required:
              - type
          then:
            anyOf:
              - required:
                  - line_items
                properties:
                  line_items:
                    minItems: 1
              - required:
                  - line_item
                properties:
                  line_item:
                    $ref: '#/components/schemas/RefundLineItem'
      examples:
        - external_id: pos-refund-2026-0807-0042
          type: line_item
          amount:
            amount: 17600
            currency_code: USD
          line_items:
            - external_id: line-item-a
              quantity: 1
              restock: true
            - external_id: line-item-b
              quantity: 1
              restock: false
          created_at: '2026-08-07T14:32:00-07:00'
    Product:
      description: >
        Identify a product by either `id` or `external_id`. These options are
        mutually exclusive.
      oneOf:
        - type: object
          required:
            - id
          properties:
            id:
              type: integer
              format: int64
              description: The global identifier for an existing product.
          additionalProperties: false
        - type: object
          required:
            - external_id
          properties:
            external_id:
              type: string
              maxLength: 100
              description: The external identifier for an existing product.
          additionalProperties: false
    ProductVariant:
      description: >
        Identify a product variant by either `id` or `external_id`. These
        options are mutually exclusive.
      oneOf:
        - type: object
          required:
            - id
          properties:
            id:
              type: integer
              format: int64
              description: The global identifier for an existing product variant.
          additionalProperties: false
        - type: object
          required:
            - external_id
          properties:
            external_id:
              type: string
              maxLength: 100
              description: The external identifier for an existing product variant.
          additionalProperties: false
    LineItemRefundItems:
      title: LineItemRefundItems
      description: |
        Refunds nested under a line item.
      type: array
      items:
        $ref: '#/components/schemas/LineItemRefund'
    OrderLineItemDiscounts:
      title: OrderLineItemDiscounts
      type: array
      items:
        $ref: '#/components/schemas/OrderLineItemDiscount'
    Duties:
      title: Duties
      type: array
      items:
        $ref: '#/components/schemas/Duty'
    LineItemMetadataEntry:
      title: LineItemMetadataEntry
      type: object
      required:
        - key
        - value
      properties:
        key:
          type: string
          maxLength: 512
          description: >
            The metadata key. Note this differs from order-level metadata, which
            caps keys at 100 characters.
        value:
          type:
            - string
            - boolean
            - object
          description: >
            The value associated with the key. Must be a string, boolean, or
            object; numbers (including integers such as 0 and 1) are rejected.
            When the value is an object, it must not contain the reserved key
            `__scalar_value`.
    FulfillmentLocation:
      description: >
        Identify a location by either `id` or `external_id`. These options are
        mutually exclusive.
      oneOf:
        - type: object
          required:
            - id
          properties:
            id:
              type: integer
              format: int64
              description: >
                The global identifier for an existing location. The id provided
                must belong to the authenticated user's shop.
          additionalProperties: false
        - type: object
          required:
            - external_id
          properties:
            external_id:
              type: string
              maxLength: 100
              description: The external identifier for an existing location.
          additionalProperties: false
    FulfillmentLineItems:
      title: FulfillmentLineItems
      type: array
      items:
        $ref: '#/components/schemas/FulfillmentLineItem'
    ShippingLine:
      title: ShippingLine
      type: object
      properties:
        title:
          type:
            - string
        price:
          $ref: '#/components/schemas/MoneySet'
        discounts:
          $ref: '#/components/schemas/ShippingLineDiscount'
        tax_lines:
          $ref: '#/components/schemas/TaxLines'
    OrderRefundResponse:
      title: OrderRefundResponse
      type: object
      properties:
        id:
          type: integer
          format: int64
          readOnly: true
          description: The global identifier for the refund.
        external_id:
          type:
            - string
            - 'null'
          maxLength: 100
          description: External identifier for the refund event.
        type:
          type:
            - string
            - 'null'
          description: Type of refund.
          enum:
            - line_item
            - shipping
            - other
        amount:
          $ref: '#/components/schemas/MoneySet'
        line_items:
          type: array
          description: >
            Always present on responses. Refunded order line items when `type`
            is `line_item`; empty otherwise.
          items:
            $ref: '#/components/schemas/RefundLineItemResponse'
        line_item:
          description: >
            Always present. The child object when `line_items` has exactly one
            entry; `null` when there are zero or more than one.
          anyOf:
            - $ref: '#/components/schemas/RefundLineItemResponse'
            - type: 'null'
        created_at:
          oneOf:
            - $ref: '#/components/schemas/Date'
            - type: 'null'
        updated_at:
          oneOf:
            - $ref: '#/components/schemas/Date'
            - type: 'null'
      required:
        - line_items
        - line_item
      examples:
        - external_id: pos-refund-2026-0807-0042
          type: line_item
          amount:
            amount: 17600
            currency_code: USD
          line_items:
            - id: 810772123123127
              external_id: line-item-a
              quantity: 1
              restock: true
            - id: 810772123123128
              external_id: line-item-b
              quantity: 1
              restock: false
          line_item: null
          created_at: '2026-08-07T14:32:00-07:00'
          updated_at: '2026-08-07T14:32:00-07:00'
    ProductResponse:
      title: ProductResponse
      type: object
      properties:
        id:
          type: integer
          format: int64
          readOnly: true
          description: The global identifier for the product.
        external_id:
          type:
            - string
            - 'null'
          maxLength: 100
          description: The external identifier for the product.
    ProductVariantResponse:
      title: ProductVariantResponse
      type: object
      properties:
        id:
          type: integer
          format: int64
          readOnly: true
          description: The global identifier for the product variant.
        external_id:
          type:
            - string
            - 'null'
          maxLength: 100
          description: The external identifier for the product variant.
    LineItemRefundItemsResponse:
      title: LineItemRefundItemsResponse
      description: |
        Refunds nested under a line item in an order response.
      type: array
      items:
        $ref: '#/components/schemas/LineItemRefundResponse'
    FulfillmentLocationResponse:
      title: FulfillmentLocationResponse
      type: object
      properties:
        id:
          type: integer
          format: int64
          readOnly: true
          description: The global identifier for the location.
        external_id:
          type:
            - string
            - 'null'
          maxLength: 100
          description: The external identifier for the location.
    TaxLine:
      title: TaxLine
      type: object
      required:
        - title
        - rate
        - price
      properties:
        title:
          type:
            - string
          maxLength: 100
        rate:
          type: number
          description: Tax rate as a decimal (e.g. `0.08` for 8%).
        price:
          $ref: '#/components/schemas/MoneySet'
    RefundLineItem:
      title: RefundLineItem
      description: >
        Identify an order line item by either `id` or `external_id`. These
        options are mutually exclusive; providing one prohibits the other. Used
        on refunds attached at the order level.
      oneOf:
        - title: Option 1
          type: object
          required:
            - id
          properties:
            id:
              type: integer
              format: int64
              description: >
                The global identifier for an existing order line item. Mutually
                exclusive with `external_id`.
            quantity:
              type:
                - integer
                - 'null'
            restock:
              type:
                - boolean
                - 'null'
          additionalProperties: false
        - title: Option 2
          type: object
          required:
            - external_id
          properties:
            external_id:
              type: string
              maxLength: 100
              description: >
                The external identifier for an existing order line item or a
                line item being created in the request.
            quantity:
              type:
                - integer
                - 'null'
            restock:
              type:
                - boolean
                - 'null'
          additionalProperties: false
    LineItemRefund:
      title: LineItemRefund
      type: object
      required:
        - type
        - amount
      properties:
        external_id:
          type:
            - string
            - 'null'
          maxLength: 100
        type:
          type:
            - string
            - 'null'
          description: Type of refund.
          enum:
            - line_item
            - shipping
            - other
        amount:
          $ref: '#/components/schemas/MoneySet'
        line_item:
          description: Required when `type` is `line_item`.
          anyOf:
            - $ref: '#/components/schemas/LineItemRefundLineItem'
            - type: 'null'
        created_at:
          oneOf:
            - $ref: '#/components/schemas/Date'
            - type: 'null'
        updated_at:
          oneOf:
            - $ref: '#/components/schemas/Date'
            - type: 'null'
      allOf:
        - if:
            properties:
              type:
                const: line_item
            required:
              - type
          then:
            required:
              - line_item
            properties:
              line_item:
                $ref: '#/components/schemas/LineItemRefundLineItem'
    OrderLineItemDiscount:
      title: OrderLineItemDiscount
      type: object
      properties:
        external_id:
          type:
            - string
            - 'null'
          maxLength: 100
          examples:
            - 564400c7-7a6b-4f29-b6a5-7bb580b2992c
        discount_type:
          type: string
          description: Type of discount.
          enum:
            - amount
            - bonus
            - bonus_choice
            - fixed_price
            - free
            - percentage
            - percentage_off_options
            - price_book_price
            - total_fixed_price
        discount_relation:
          type:
            - string
            - 'null'
          description: Discount Relation.
          enum:
            - prereq
            - entitled
            - x
            - 'y'
        name:
          type:
            - string
          maxLength: 64
        code:
          type:
            - string
          maxLength: 100
        reason:
          type:
            - string
          maxLength: 512
        rate:
          type:
            - number
        tax_adjustment_money:
          $ref: '#/components/schemas/MoneySet'
        net_adjustment_money:
          $ref: '#/components/schemas/MoneySet'
    Duty:
      title: Duty
      type: object
      properties:
        hs_code:
          type:
            - string
            - 'null'
          maxLength: 10
        country_of_origin:
          type:
            - string
            - 'null'
          maxLength: 2
          examples:
            - US
            - CA
        price:
          $ref: '#/components/schemas/MoneySet'
        tax_lines:
          $ref: '#/components/schemas/TaxLines'
    FulfillmentLineItem:
      title: FulfillmentLineItem
      type: object
      properties:
        external_id:
          type:
            - string
            - 'null'
          maxLength: 100
          examples:
            - 564400c7-7a6b-4f29-b6a5-7bb580b2992c
        order_line_item_external_id:
          type: string
          maxLength: 100
          examples:
            - 564400c7-7a6b-4f29-b6a5-7bb580b2992c
        quantity:
          type: integer
    RefundLineItemResponse:
      title: RefundLineItemResponse
      type: object
      properties:
        id:
          type:
            - integer
            - 'null'
          format: int64
          readOnly: true
          description: >
            The global identifier for the order line item. Write still requires
            each child to match an order line (`external_id` or `id`); unmatched
            children are rejected. `null` on read when a stored child cannot be
            mapped to a current order line (for example the line was removed
            after ingest). That is not a write-time acceptance of unknown
            children.
        external_id:
          type:
            - string
            - 'null'
          maxLength: 100
          description: The external identifier for the order line item.
        quantity:
          type:
            - integer
            - 'null'
        restock:
          type:
            - boolean
            - 'null'
    LineItemRefundResponse:
      title: LineItemRefundResponse
      type: object
      properties:
        id:
          type: integer
          format: int64
          readOnly: true
          description: The global identifier for the refund.
        external_id:
          type:
            - string
            - 'null'
        type:
          type:
            - string
            - 'null'
          description: Type of refund.
          enum:
            - line_item
            - shipping
            - other
        amount:
          $ref: '#/components/schemas/MoneySet'
        line_item:
          description: Present when `type` is `line_item`.
          anyOf:
            - $ref: '#/components/schemas/LineItemRefundLineItem'
            - type: 'null'
        created_at:
          oneOf:
            - $ref: '#/components/schemas/Date'
            - type: 'null'
        updated_at:
          oneOf:
            - $ref: '#/components/schemas/Date'
            - type: 'null'
    LineItemRefundLineItem:
      title: LineItemRefundLineItem
      type: object
      description: >
        Refund details when nested under a line item. Identifiers are not
        accepted; the parent line item provides the context.
      properties:
        quantity:
          type:
            - integer
            - 'null'
        restock:
          type:
            - boolean
            - 'null'
      additionalProperties: false
  responses:
    Unauthorized:
      description: >-
        Example response if request submitted without a valid API Key in
        X-Authorization.
      content:
        application/json:
          schema:
            type: object
            required:
              - errors
            properties:
              errors:
                type: string
                examples:
                  - Unauthorized.
      headers:
        X-Loop-Request-ID:
          schema:
            type: string
            examples:
              - 5a748e7c-5fcc-4fb0-a777-6a4d28e60d4c
            format: uuid
          description: UUID to aid in debugging API issues.
  securitySchemes:
    write:
      name: X-Authorization
      type: apiKey
      in: header
      description: 'API Scope: "Order (write)"'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.