---
title: "Upsert Order"
method: PUT
path: "/orders"
tags: ["Orders"]
---

# Upsert Order

`PUT /orders`

Upsert an order using the external_id.

## Request body

- UpsertOrderRequest
  - `external_id` string, required — External ID of the order.
  - `name` string, required — The name of the order.
  - `secondary_identifier` string, nullable — 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` string, required — If a channel with this name is not already associated with the shop, it will be used to create a new channel.
  - `customer` union
    - object
      - `id` integer — Global identifier of an existing customer. Required if additional customer details are not provided.
    - object
      - `external_id` string, nullable — 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` string, nullable — Customer first name.
      - `last_name` string, nullable — Customer last name.
      - `email` string, nullable — Customer email address.
      - `phone` string, nullable — Customer phone.
  - `status` 'active' | 'archived' | 'cancelled' | 'unknown', required — Status of the Order.
  - `shipping_address` Address
    - `id` integer
    - `hash` string
    - `created_at` string, date-time
    - `updated_at` string, date-time
    - `name` string
    - `company` string, nullable
    - `address1` string
    - `address2` string
    - `city` string
    - `state` string
    - `zip` string
    - `country` string
    - `country_code` string
    - `phone` string
    - `latitude` number
    - `longitude` number
  - `billing_address` Address
    - `id` integer
    - `hash` string
    - `created_at` string, date-time
    - `updated_at` string, date-time
    - `name` string
    - `company` string, nullable
    - `address1` string
    - `address2` string
    - `city` string
    - `state` string
    - `zip` string
    - `country` string
    - `country_code` string
    - `phone` string
    - `latitude` number
    - `longitude` number
  - `taxes_included` boolean, required
  - `total_price` MoneySet, required
    - `amount` integer, required
    - `currency_code` string, required
  - `total_price_presentment` MoneySet
    - `amount` integer, required
    - `currency_code` string, required
  - `total_discounts` MoneySet
    - `amount` integer, required
    - `currency_code` string, required
  - `total_discounts_presentment` MoneySet
    - `amount` integer, required
    - `currency_code` string, required
  - `total_taxes` MoneySet
    - `amount` integer, required
    - `currency_code` string, required
  - `total_taxes_presentment` MoneySet
    - `amount` integer, required
    - `currency_code` string, required
  - `order_discounts` OrderDiscounts[], nullable
    - OrderDiscount[]
      - `external_id` string, nullable
      - `name` string
      - `discount_type` 'amount' | 'bonus' | 'bonus_choice' | 'fixed_price' | 'free' | 'percentage' | 'percentage_off_options' | 'price_book_price' | 'total_fixed_price' — Type of discount.
      - `code` string
      - `reason` string
      - `rate` number
      - `tax_adjustment_money` MoneySet
        - `amount` integer, required
        - `currency_code` string, required
      - `net_adjustment_money` MoneySet
        - `amount` integer, required
        - `currency_code` string, required
  - `shipping_lines` ShippingLineData[], nullable
    - `title` string
    - `price` MoneySet
      - `amount` integer, required
      - `currency_code` string, required
    - `discounts` ShippingLineDiscount
      - `external_id` string, nullable
      - `name` string
      - `discount_type` 'amount' | 'bonus' | 'bonus_choice' | 'fixed_price' | 'free' | 'percentage' | 'percentage_off_options' | 'price_book_price' | 'total_fixed_price', nullable — Type of discount.
      - `code` string
      - `reason` string
      - `rate` number
      - `net_adjustment_money` MoneySet
        - `amount` integer, required
        - `currency_code` string, required
      - `tax_adjustment_money` MoneySet
        - `amount` integer, required
        - `currency_code` string, required
    - `tax_lines` TaxLine[]
      - `title` string, required
      - `rate` number, required — Tax rate as a decimal (e.g. `0.08` for 8%).
      - `price` MoneySet, required
        - `amount` integer, required
        - `currency_code` string, required
  - `refunds` RefundItems[] — List of refunds associated with the order.
    - object[]
      - `external_id` string, nullable
      - `type` 'line_item' | 'shipping' | 'other', nullable, required — Type of refund.
      - `amount` MoneySet, required
        - `amount` integer, required
        - `currency_code` string, required
      - `line_item` RefundLineItem
        - `id` integer, nullable
        - `quantity` integer, nullable
        - `restock` boolean, nullable
      - `created_at` string, date-time
      - `updated_at` string, date-time
  - `line_items` LineItem[], required — List of order line items associated with the order.
    - object[]
      - `line_item_id` string — The unique identifier associated with the line item.
      - `provider_line_item_id` string — The identifier from the commerce provider (e.g. Shopify) associated with the line item.
      - `product_id` string — The unique identifier associated with the product.
      - `variant_id` string — The unique identifier associated with the product variant.
      - `sku` string — The SKU associated with the product.
      - `title` string — The product's name.
      - `price` string — The product's price.
      - `discount` string — The discount amount associated with the line item.
      - `tax` string — The tax amount associated with the line item.
      - `refund` string — The refund amount associated with the line item.
      - `refund_item` string — The refund amount minus the tax amount.
      - `refund_tax` string — Equal to the refund.
      - `refund_shipping` string — This line's share of the original-order shipping reimbursement folded into `refund`.
      - `refund_excluding_shipping` string — This line's `refund` with shipping removed (`refund` minus `refund_shipping`).
      - `refund_shipping_tax` string — The tax portion of `refund_shipping`.
      - `refund_excluding_shipping_tax` string — The tax on the items excluding shipping. The existing `refund_tax` already excludes shipping tax, so this value equals `refund_tax`; the corrected total refund tax is `refund_tax` plus `refund_shipping_tax`.
      - `returned_at` string, date-time — The date and time at which the item was returned, using the ISO 8601 date format.
      - `exchange_variant` string — The product variant selected by the customer for exchange (if applicable).
      - `return_reason` string — The specific reason for return given by the customer.
      - `parent_return_reason` string — The general return reason category given by the customer.
      - `return_comment` string — The optional comment left by the customer when returning the product.
      - `barcode` string — The barcode of the product.
      - `outcome` 'reject' | 'donate' | 'review' | 'default' | 'keep' — The return outcome, as permitted by the merchant's return policy.
      - `provider_restock_location_id` string, nullable — The restock location for the return.
      - `consolidation_tracking` string — If a line item is part of a consolidated shipment of many return items, this value holds the tracking value for the consolidated shipment that contains this item such as the Happy Returns Outbound Shipment tracking number.
      - `consolidation_destination_id` string, nullable — If a line item is part of a consolidated shipment of many return items, this value holds the destination id for the consolidated shipment that contains this item such as the Happy Returns Outbound Shipment destination address id.
      - `condition` Condition, nullable
        - `description` string
        - `condition_category` 'grade_a' | 'grade_b' | 'grade_c' | 'grade_d' | 'incorrect_item' | 'missing' | 'junk', nullable
        - `return_processor` string, nullable
        - `note` string, nullable
        - `inspected_at` string, date-time
        - `images` Image[]
      - `disposition` Disposition, nullable
        - `disposition_outcome` 'back_to_stock' | 'resale_hold' | 'recycle' | 'donate' | 'missing'
        - `return_processor` string, nullable
        - `note` string, nullable
        - `inspected_at` string, date-time
  - `fulfillments` Fulfillment[], nullable — Fulfillment information for the order.
    - `external_id` string, nullable
    - `status` 'success' | 'failure' | 'cancelled' | 'pending' | 'open' | 'error', required — 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` string, date-time, nullable — Set this field to indicate that the line item has been fulfilled, so it is returnable.
    - `shipping_carrier` string
    - `location` object, nullable
      - `id` integer — Set to null to remove a location relationship or provide an existing location id. The id provided must belong to the authenticated users shop.
    - `fulfillment_line_items` FulfillmentLineItem[]
      - `external_id` string, nullable
      - `order_line_item_external_id` string
      - `quantity` integer
    - `tracking_numbers` string[], nullable
  - `source` object, required — The source system that created the order.
    - `name` string, required — Name of the source system (e.g. 'shopify', 'hubble').
  - `tags` TagRequestData[], nullable
  - `created_at` string, date-time
  - `updated_at` string, date-time
  - `cancelled_at` string, date-time
  - `financial_status` 'pending' | 'authorized' | 'partially_paid' | 'paid' | 'partially_refunded' | 'refunded' | 'voided' | 'null', nullable — The financial status of the order.
  - `cancel_reason` 'customer' | 'declined' | 'fraud' | 'inventory' | 'other' | 'staff' | 'null', nullable — The reason the order was cancelled, if applicable.
  - `processed_at` string, date-time
  - `browser_ip` union — The IP address of the browser used to place the order.
    - string, ipv4
    - string, ipv6
  - `client_details_user_agent` string, nullable — The user agent string of the browser used to place the order.
  - `total_tip_received` MoneySet
    - `amount` integer, required
    - `currency_code` string, required

## Response `200`

OK

- object
  - `order` OrderResponse
    - `id` integer
    - `external_id` string, nullable
    - `name` string
    - `secondary_identifier` string, nullable
    - `source` string, nullable
    - `sales_channel` string, nullable — The name of the channel.
    - `customer` object
      - `id` integer — The global identifier of the customer.
      - `external_id` string, nullable
      - `sales_channel` string, nullable — The name of the channel associated with the customer.
      - `first_name` string
      - `last_name` string
      - `email` string
      - `phone` string
    - `status` 'active' | 'archived' | 'cancelled' | 'unknown' — Status of the Order.
    - `shipping_address` Address
      - `id` integer
      - `hash` string
      - `created_at` string, date-time
      - `updated_at` string, date-time
      - `name` string
      - `company` string, nullable
      - `address1` string
      - `address2` string
      - `city` string
      - `state` string
      - `zip` string
      - `country` string
      - `country_code` string
      - `phone` string
      - `latitude` number
      - `longitude` number
    - `billing_address` Address
      - `id` integer
      - `hash` string
      - `created_at` string, date-time
      - `updated_at` string, date-time
      - `name` string
      - `company` string, nullable
      - `address1` string
      - `address2` string
      - `city` string
      - `state` string
      - `zip` string
      - `country` string
      - `country_code` string
      - `phone` string
      - `latitude` number
      - `longitude` number
    - `taxes_included` boolean
    - `total_price` MoneySet
      - `amount` integer, required
      - `currency_code` string, required
    - `total_price_presentment` MoneySet
      - `amount` integer, required
      - `currency_code` string, required
    - `total_discounts` MoneySet
      - `amount` integer, required
      - `currency_code` string, required
    - `total_discounts_presentment` MoneySet
      - `amount` integer, required
      - `currency_code` string, required
    - `shipping_lines` ShippingLine[]
      - `title` string
      - `price` MoneySet
        - `amount` integer, required
        - `currency_code` string, required
      - `discounts` ShippingLineDiscount
        - `external_id` string, nullable
        - `name` string
        - `discount_type` 'amount' | 'bonus' | 'bonus_choice' | 'fixed_price' | 'free' | 'percentage' | 'percentage_off_options' | 'price_book_price' | 'total_fixed_price', nullable — Type of discount.
        - `code` string
        - `reason` string
        - `rate` number
        - `net_adjustment_money` MoneySet
          - `amount` integer, required
          - `currency_code` string, required
        - `tax_adjustment_money` MoneySet
          - `amount` integer, required
          - `currency_code` string, required
      - `tax_lines` TaxLine[]
        - `title` string, required
        - `rate` number, required — Tax rate as a decimal (e.g. `0.08` for 8%).
        - `price` MoneySet, required
          - `amount` integer, required
          - `currency_code` string, required
    - `order_discounts` OrderDiscount[]
      - `external_id` string, nullable
      - `name` string
      - `discount_type` 'amount' | 'bonus' | 'bonus_choice' | 'fixed_price' | 'free' | 'percentage' | 'percentage_off_options' | 'price_book_price' | 'total_fixed_price' — Type of discount.
      - `code` string
      - `reason` string
      - `rate` number
      - `tax_adjustment_money` MoneySet
        - `amount` integer, required
        - `currency_code` string, required
      - `net_adjustment_money` MoneySet
        - `amount` integer, required
        - `currency_code` string, required
    - `total_taxes` MoneySet
      - `amount` integer, required
      - `currency_code` string, required
    - `total_taxes_presentment` MoneySet
      - `amount` integer, required
      - `currency_code` string, required
    - `tags` TagRequestData[], nullable
    - `refunds` RefundData[], nullable
      - RefundItems[]
        - object[]
          - `external_id` string, nullable
          - `type` 'line_item' | 'shipping' | 'other', nullable, required — Type of refund.
          - `amount` MoneySet, required
            - `amount` integer, required
            - `currency_code` string, required
          - `line_item` RefundLineItem
            - `id` integer, nullable
            - `quantity` integer, nullable
            - `restock` boolean, nullable
          - `created_at` string, date-time
          - `updated_at` string, date-time
    - `line_items` LineItem[]
      - object[]
        - `line_item_id` string — The unique identifier associated with the line item.
        - `provider_line_item_id` string — The identifier from the commerce provider (e.g. Shopify) associated with the line item.
        - `product_id` string — The unique identifier associated with the product.
        - `variant_id` string — The unique identifier associated with the product variant.
        - `sku` string — The SKU associated with the product.
        - `title` string — The product's name.
        - `price` string — The product's price.
        - `discount` string — The discount amount associated with the line item.
        - `tax` string — The tax amount associated with the line item.
        - `refund` string — The refund amount associated with the line item.
        - `refund_item` string — The refund amount minus the tax amount.
        - `refund_tax` string — Equal to the refund.
        - `refund_shipping` string — This line's share of the original-order shipping reimbursement folded into `refund`.
        - `refund_excluding_shipping` string — This line's `refund` with shipping removed (`refund` minus `refund_shipping`).
        - `refund_shipping_tax` string — The tax portion of `refund_shipping`.
        - `refund_excluding_shipping_tax` string — The tax on the items excluding shipping. The existing `refund_tax` already excludes shipping tax, so this value equals `refund_tax`; the corrected total refund tax is `refund_tax` plus `refund_shipping_tax`.
        - `returned_at` string, date-time — The date and time at which the item was returned, using the ISO 8601 date format.
        - `exchange_variant` string — The product variant selected by the customer for exchange (if applicable).
        - `return_reason` string — The specific reason for return given by the customer.
        - `parent_return_reason` string — The general return reason category given by the customer.
        - `return_comment` string — The optional comment left by the customer when returning the product.
        - `barcode` string — The barcode of the product.
        - `outcome` 'reject' | 'donate' | 'review' | 'default' | 'keep' — The return outcome, as permitted by the merchant's return policy.
        - `provider_restock_location_id` string, nullable — The restock location for the return.
        - `consolidation_tracking` string — If a line item is part of a consolidated shipment of many return items, this value holds the tracking value for the consolidated shipment that contains this item such as the Happy Returns Outbound Shipment tracking number.
        - `consolidation_destination_id` string, nullable — If a line item is part of a consolidated shipment of many return items, this value holds the destination id for the consolidated shipment that contains this item such as the Happy Returns Outbound Shipment destination address id.
        - `condition` Condition, nullable
          - `description` string
          - `condition_category` 'grade_a' | 'grade_b' | 'grade_c' | 'grade_d' | 'incorrect_item' | 'missing' | 'junk', nullable
          - `return_processor` string, nullable
          - `note` string, nullable
          - `inspected_at` string, date-time
          - `images` Image[]
        - `disposition` Disposition, nullable
          - `disposition_outcome` 'back_to_stock' | 'resale_hold' | 'recycle' | 'donate' | 'missing'
          - `return_processor` string, nullable
          - `note` string, nullable
          - `inspected_at` string, date-time
    - `fulfillments` Fulfillment[]
      - `external_id` string, nullable
      - `status` 'success' | 'failure' | 'cancelled' | 'pending' | 'open' | 'error', required — 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` string, date-time, nullable — Set this field to indicate that the line item has been fulfilled, so it is returnable.
      - `shipping_carrier` string
      - `location` object, nullable
        - `id` integer — Set to null to remove a location relationship or provide an existing location id. The id provided must belong to the authenticated users shop.
      - `fulfillment_line_items` FulfillmentLineItem[]
        - `external_id` string, nullable
        - `order_line_item_external_id` string
        - `quantity` integer
      - `tracking_numbers` string[], nullable
    - `created_at` string, date-time
    - `updated_at` string, date-time
    - `financial_status` 'pending' | 'authorized' | 'partially_paid' | 'paid' | 'partially_refunded' | 'refunded' | 'voided' | 'null', nullable — The financial status of the order.
    - `cancel_reason` 'customer' | 'declined' | 'fraud' | 'inventory' | 'other' | 'staff' | 'null', nullable — The reason the order was cancelled, if applicable.
    - `processed_at` string, date-time
    - `browser_ip` union — The IP address of the browser used to place the order.
      - string, ipv4
      - string, ipv6
    - `client_details_user_agent` string, nullable — The user agent string of the browser used to place the order.
    - `total_tip_received` MoneySet
      - `amount` integer, required
      - `currency_code` string, required
    - `warnings` object[], nullable — Non-fatal warnings about the order, surfaced after a successful write.
      - `code` string, required
      - `message` string, required

## Other responses

- `401` — Unauthorized

---

[API](https://skmtc.dev/loopreturns/apis/listings-api.md) · [All operations](https://skmtc.dev/loopreturns/apis/listings-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/loopreturns/listings-api/revisions/750e6012dbb8/schema)