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 tags: - name: Orders paths: "/orders": post: summary: "Create Order" operationId: create-order description: "Create a new order." responses: "200": description: OK content: application/json: schema: type: object properties: order: $ref: "#/components/schemas/OrderResponse" "401": $ref: "#/components/responses/Unauthorized" tags: - Orders parameters: [] security: - write: [] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CreateOrderRequest" 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" put: summary: "Upsert Order" operationId: upsertOrder description: "Upsert an order using the external_id." responses: "200": description: OK content: application/json: schema: type: object properties: order: $ref: "#/components/schemas/OrderResponse" "401": $ref: "#/components/responses/Unauthorized" tags: - Orders parameters: [] security: - write: [] 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" "/orders/{id}": put: summary: Update Order description: "Update a specific order." operationId: update-order parameters: - in: path name: id schema: type: integer required: true description: "Identifier of the order." tags: - Orders security: - write: [] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/UpdateOrderRequest" responses: "200": description: OK content: application/json: schema: type: object properties: order: $ref: "#/components/schemas/OrderResponse" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" components: schemas: ShippingLineData: type: object properties: title: type: - string price: $ref: "#/components/schemas/MoneySet" discounts: $ref: "#/components/schemas/ShippingLineDiscount" tax_lines: $ref: "#/components/schemas/TaxLines" Date: type: string format: date-time examples: - "2023-04-25T13:25:00-05:00" 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 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 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 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 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 FulfillmentLineItems: title: FulfillmentLineItems type: array items: $ref: "#/components/schemas/FulfillmentLineItem" 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 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" LineItemRefundItems: title: LineItemRefundItems description: > Refunds nested under a line item. type: array items: $ref: "#/components/schemas/LineItemRefund" 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" CreateRefundItems: title: CreateRefundItems description: > Refunds attached at the order level when creating an order. Send each outside-Loop refund event in this array. Prefer a unique `external_id` per event (write-once identity); `external_id` may be null. For ingest on an existing order, see `RefundItems`. type: array items: $ref: "#/components/schemas/CreateOrderRefund" CreateOrderRefund: title: CreateOrderRefund 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` in the same request. Do not send `line_items` on refunds nested under `line_items[].refunds[]`. items: $ref: "#/components/schemas/CreateRefundLineItem" line_item: description: > Accepted 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/CreateRefundLineItem" - 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/CreateRefundLineItem" 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" CreateRefundLineItem: title: CreateRefundLineItem type: object description: > Identify an order line item by `external_id` when creating an order. The global identifier is not available because the line item has not been created yet. required: - external_id properties: external_id: type: string maxLength: 100 description: > The external identifier for 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" 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 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 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`. CreateLineItem: type: object required: - product - unit_price - taxable properties: 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: anyOf: - $ref: "#/components/schemas/TaxLines" - type: "null" refunds: anyOf: - $ref: "#/components/schemas/LineItemRefundItems" - type: "null" description: "Attach a refund to this line item." discounts: oneOf: - $ref: "#/components/schemas/OrderLineItemDiscounts" - type: "null" # properties: intentionally undocumented / commented out. # Accepted by the Orders API for Loop-internal Order Protection / Seel use cases. # Not public yet - unclear whether merchants should write properties vs whether # Loop/connectors own them; publishing now would create confusion with metadata. # properties: # type: [array, "null"] # items: # type: object # required: [key, value] # properties: # key: { type: string, maxLength: 512 } # value: {} 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: "B1234" reason: "This is a discount reason." rate: 1.2 discount_relation: "x" tax_adjustment_money: amount: 50000 currency_code: USD net_adjustment_money: amount: 50000 currency_code: USD duties: hs_code: "AB123" country_of_origin: "USA" price: amount: 50000 currency_code: USD tax_lines: title: "OH Municipal Tax" rate: 2.1 price: amount: 50000 currency_code: USD 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 UpdateLineItem: type: object description: > An order line item to update. Identify the target line item with exactly one of `id` or `external_id`; sending both, or sending neither, returns a 422 validation error. properties: id: type: integer format: int64 minimum: 1 description: > Global identifier of an existing line item on the order. Mutually exclusive with `external_id`. examples: - 810772123123125 external_id: type: string maxLength: 100 description: > External identifier of the line item. Mutually exclusive with `id`. 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/RefundItems" - 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" oneOf: - required: - id - required: - external_id OrderDiscounts: title: OrderDiscounts type: array items: $ref: "#/components/schemas/OrderDiscount" 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" OrderLineItemDiscounts: title: OrderLineItemDiscounts type: array items: $ref: "#/components/schemas/OrderLineItemDiscount" 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" ShippingLines: title: ShippingLines type: array items: $ref: "#/components/schemas/ShippingLine" 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" ShippingLineDiscounts: title: ShippingLineDiscounts type: array items: $ref: "#/components/schemas/ShippingLineDiscount" 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" Duties: title: Duties type: array items: $ref: "#/components/schemas/Duty" 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" TaxLines: title: TaxLines type: array items: $ref: "#/components/schemas/TaxLine" 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" TagRequestData: type: string description: "A tag used to classify and group orders." examples: - VIP CreateOrderRequest: title: CreateOrderRequest type: object properties: external_id: type: - string - "null" maxLength: 100 examples: - 564400c7-7a6b-4f29-b6a5-7bb580b2992c name: type: string maxLength: 100 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: - online - mobile description: > Used to identify the sales channel that the order was created in. 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 - "null" 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 items: $ref: "#/components/schemas/OrderDiscounts" description: "List of discounts associated with the order." shipping_lines: type: array items: $ref: "#/components/schemas/ShippingLines" description: "List of shipping line items associated with the order." refunds: type: array items: $ref: "#/components/schemas/CreateRefundItems" description: "List of refunds associated with the order." line_items: type: array items: $ref: "#/components/schemas/CreateLineItem" 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" 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." # properties: intentionally undocumented / commented out. # Accepted by the Orders API for Loop-internal Order Protection / Seel use cases. # Not public yet - unclear whether merchants should write properties vs whether # Loop/connectors own them; publishing now would create confusion with metadata. # properties: # type: [array, "null"] # items: # type: object # required: [key, value] # properties: # key: { type: string, maxLength: 512 } # value: {} 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: - 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" 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." # properties: intentionally undocumented / commented out. # Accepted by the Orders API for Loop-internal Order Protection / Seel use cases. # Not public yet - unclear whether merchants should write properties vs whether # Loop/connectors own them; publishing now would create confusion with metadata. # properties: # type: [array, "null"] # items: # type: object # required: [key, value] # properties: # key: { type: string, maxLength: 512 } # value: {} 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" UpdateOrderRequest: title: UpdateOrderRequest type: object properties: external_id: type: - string - "null" maxLength: 100 examples: - 564400c7-7a6b-4f29-b6a5-7bb580b2992c name: type: string maxLength: 100 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" properties: id: type: - integer - "null" description: "Must be the only parameter in the request. Set to null to remove a customer relationship or provide an existing customer id to associate the customer with the order" external_id: type: - string - "null" maxLength: 100 description: "Must be the only parameter in the request. Provide an existing customer external_id to associate the customer with the order" 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 - "null" 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." shipping_lines: type: array items: $ref: "#/components/schemas/ShippingLines" description: "List of shipping line items associated with the order." refunds: type: array items: $ref: "#/components/schemas/RefundItems" description: "List of refunds associated with the order." line_items: type: array items: $ref: "#/components/schemas/UpdateLineItem" 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." # properties: intentionally undocumented / commented out. # Accepted by the Orders API for Loop-internal Order Protection / Seel use cases. # Not public yet - unclear whether merchants should write properties vs whether # Loop/connectors own them; publishing now would create confusion with metadata. # properties: # type: [array, "null"] # items: # type: object # required: [key, value] # properties: # key: { type: string, maxLength: 512 } # value: {} 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." required: - source - sales_channel 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." 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." 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" 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" RefundItemsResponse: title: RefundItemsResponse type: array items: $ref: "#/components/schemas/OrderRefundResponse" 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" LineItemRefundItemsResponse: title: LineItemRefundItemsResponse description: > Refunds nested under a line item in an order response. type: array items: $ref: "#/components/schemas/LineItemRefundResponse" 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 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 description: "Status of the Order." enum: - active - archived - cancelled - unknown 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 OrderDeleteResponse: title: OrderDeleteResponse type: object properties: id: type: integer format: int64 examples: - 77892011 minimum: 1 success: type: boolean readOnly: true OrderDeleteByExternalIdResponse: title: OrderDeleteByExternalIdResponse type: object required: - id - external_id - success properties: id: type: integer format: int64 examples: - 77892011 minimum: 1 external_id: type: string description: "The identifier used by an external source to identify the order." success: type: boolean readOnly: true ReturnEligibilityLookupRequest: title: ReturnEligibilityLookupRequest type: object required: - order_name properties: order_name: type: string description: "The order name, as accepted by draft initialize." examples: - "#1001" ReturnEligibilityResponse: title: ReturnEligibilityResponse type: object required: - return_eligibility properties: return_eligibility: $ref: "#/components/schemas/ReturnEligibility" ReturnEligibility: title: ReturnEligibility type: object required: - order_id - as_of - advisory - items properties: order_id: type: integer format: int64 minimum: 1 description: >- Identifier of the order. When the order is in Commerce Data, this is its global identifier, the same value as the order's `id` on Get Order. Returned as a string when the `X-Loop-Global-Identifier-Type: string` header is sent. examples: - 390519090 as_of: type: string format: date-time description: "ISO 8601 UTC time the eligibility was evaluated." examples: - "2026-09-30T16:00:00Z" advisory: type: boolean description: >- Marks the result as advisory. A draft return created afterwards stays authoritative and may disagree. items: type: array items: $ref: "#/components/schemas/ReturnEligibilityItem" ReturnEligibilityItem: title: ReturnEligibilityItem type: object required: - id - external_id - eligible - expiration - ineligibility_code - return_reason_group_id properties: id: type: integer format: int64 minimum: 1 description: >- Identifier of the line item. When the order is in Commerce Data, this is its global identifier, the same value as `line_items[].id` on Get Order. Returned as a string when the `X-Loop-Global-Identifier-Type: string` header is sent. examples: - 390519093 external_id: type: - string - "null" description: >- The commerce platform's line item id. When the order is in Commerce Data, the same value as `line_items[].external_id` on Get Order. `null` when the line item has none. examples: - "44580305076398" eligible: type: boolean expiration: type: - string - "null" format: date description: >- `Y-m-d` end of the return window. Set for eligible items and for items whose window closed. examples: - "2026-10-23" ineligibility_code: anyOf: - $ref: "#/components/schemas/ReturnIneligibilityCode" - type: "null" return_reason_group_id: type: - integer - "null" description: "Set for eligible items only." examples: - 12 ReturnIneligibilityCode: title: ReturnIneligibilityCode type: string description: "Why the line item is not eligible for return." enum: - final-sale - does-not-meet-conditions-for-return - unavailable-for-return - already-returned - not-fulfilled - not-delivered - return-window-closed - has-shipping-protection-claim ReturnEligibilityErrorResponse: title: ReturnEligibilityErrorResponse type: object required: - errors properties: errors: type: array items: type: object required: - code - message properties: code: type: string examples: - returns-unavailable-for-order message: type: string examples: - Returns are unavailable for this order. ValidationErrorResponse: title: ValidationErrorResponse type: object properties: message: type: string errors: type: object description: "Validation messages keyed by the request field that failed." additionalProperties: type: array items: type: string securitySchemes: read: type: apiKey in: header name: X-Authorization description: 'API Scope: "Order (read)"' x-scope: Order (Read) write: name: X-Authorization type: apiKey in: header description: 'API Scope: "Order (write)"' orders: type: apiKey in: header name: X-Authorization description: 'API Scope: "Orders"' x-scope: Orders responses: ReturnEligibility: description: OK content: application/json: schema: $ref: "#/components/schemas/ReturnEligibilityResponse" example: return_eligibility: order_id: 390519090 as_of: "2026-09-30T16:00:00Z" advisory: true items: - id: 390519093 external_id: "44580305076398" eligible: true expiration: "2026-10-23" ineligibility_code: null return_reason_group_id: 12 - id: 390519094 external_id: "44580305076399" eligible: false expiration: "2026-09-15" ineligibility_code: return-window-closed return_reason_group_id: null - id: 390519095 external_id: null eligible: false expiration: null ineligibility_code: final-sale return_reason_group_id: null ReturnEligibilityOrderCancelled: description: "The order has been cancelled." content: application/json: schema: $ref: "#/components/schemas/ReturnEligibilityErrorResponse" example: errors: - code: order-has-been-cancelled message: The order has been cancelled. 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." NotFound: description: "The requested entity could not be found." content: application/json: schema: type: object required: - message properties: message: type: string examples: - "Resource not found." headers: X-Loop-Request-ID: schema: type: string description: "UUID to aid in debugging API issues." ValidationError: description: "The request was not valid." content: application/json: schema: $ref: "#/components/schemas/ValidationErrorResponse" example: message: "The name field is required." errors: name: - "The name field is required." requestBodies: {} parameters: {}