Skip to main content
PUT
/
orders
Upsert Order
curl --request PUT \
  --url https://api.loopreturns.com/api/v1/orders \
  --header 'Content-Type: application/json' \
  --header 'X-Authorization: <api-key>' \
  --data '
{
  "name": "<string>",
  "external_id": "<string>",
  "secondary_identifier": "<string>",
  "channel": "<string>",
  "customer": {
    "id": 123
  },
  "taxes_included": true,
  "total_price_presentment": {
    "amount": 50000,
    "currency_code": "USD"
  },
  "total_discounts": {
    "amount": 50000,
    "currency_code": "USD"
  },
  "total_discounts_presentment": {
    "amount": 50000,
    "currency_code": "USD"
  },
  "total_taxes": {
    "amount": 50000,
    "currency_code": "USD"
  },
  "total_taxes_presentment": {
    "amount": 50000,
    "currency_code": "USD"
  },
  "order_discounts": [
    [
      {
        "external_id": "<string>",
        "name": "<string>",
        "code": "<string>",
        "reason": "<string>",
        "rate": 123
      }
    ]
  ],
  "shipping_lines": [
    {
      "title": "<string>",
      "discounts": {
        "external_id": "<string>",
        "name": "<string>",
        "code": "<string>",
        "reason": "<string>",
        "rate": 123
      },
      "tax_lines": [
        {
          "title": "<string>",
          "rate": 123
        }
      ]
    }
  ],
  "refunds": [
    [
      {
        "external_id": "<string>",
        "line_item": [
          {
            "id": 123,
            "quantity": 123,
            "restock": true
          }
        ],
        "created_at": "2023-04-25T13:25:00-05:00",
        "updated_at": "2023-04-25T13:25:00-05:00"
      }
    ]
  ],
  "line_items": [
    {
      "external_id": "<string>",
      "product": {
        "id": 123
      },
      "product_variant": {
        "id": 123
      },
      "quantity": 123,
      "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": "<string>",
          "rate": 123
        }
      ],
      "refunds": [
        {
          "external_id": "<string>",
          "line_item": [
            {
              "id": 123,
              "quantity": 123,
              "restock": true
            }
          ],
          "created_at": "2023-04-25T13:25:00-05:00",
          "updated_at": "2023-04-25T13:25:00-05:00"
        }
      ],
      "discounts": [
        {
          "external_id": "<string>",
          "name": "<string>",
          "code": "<string>",
          "reason": "<string>",
          "rate": 123
        }
      ],
      "duties": [
        {
          "hs_code": "<string>",
          "country_of_origin": "<string>",
          "tax_lines": [
            {
              "title": "<string>",
              "rate": 123
            }
          ]
        }
      ]
    }
  ],
  "fulfillments": [
    {
      "external_id": "<string>",
      "fulfilled_at": "2023-11-07T05:31:56Z",
      "shipping_carrier": "<string>",
      "location": {
        "id": 123
      },
      "fulfillment_line_items": [
        {
          "external_id": "<string>",
          "order_line_item_external_id": "<string>",
          "quantity": 123
        }
      ],
      "tracking_numbers": [
        "<string>"
      ]
    }
  ],
  "source": "<string>",
  "tags": [
    "<string>"
  ],
  "created_at": "2023-04-25T13:25:00-05:00",
  "updated_at": "2023-04-25T13:25:00-05:00",
  "cancelled_at": "2023-04-25T13:25:00-05:00"
}
'
{
  "order": {
    "id": 2,
    "external_id": "<string>",
    "name": "<string>",
    "secondary_identifier": "<string>",
    "source": "<string>",
    "channel": {
      "id": 123,
      "name": "<string>"
    },
    "customer": {
      "id": 123,
      "external_id": "<string>",
      "first_name": "<string>",
      "last_name": "<string>",
      "email": "<string>",
      "phone": "<string>"
    },
    "shipping_address": {
      "address1": "<string>",
      "city": "<string>",
      "country_code": "<string>",
      "name": "<string>",
      "company": "<string>",
      "address2": "<string>",
      "region": "<string>",
      "postal_code": "<string>"
    },
    "billing_address": {
      "address1": "<string>",
      "city": "<string>",
      "country_code": "<string>",
      "name": "<string>",
      "company": "<string>",
      "address2": "<string>",
      "region": "<string>",
      "postal_code": "<string>"
    },
    "taxes_included": true,
    "total_price": {
      "amount": 123,
      "currency_code": "USD"
    },
    "total_price_presentment": {
      "amount": 123,
      "currency_code": "USD"
    },
    "total_discounts": {
      "amount": 123,
      "currency_code": "USD"
    },
    "total_discounts_presentment": {
      "amount": 123,
      "currency_code": "USD"
    },
    "shipping_lines": [
      {
        "title": "<string>",
        "price": {
          "amount": 123,
          "currency_code": "USD"
        },
        "discounts": {
          "external_id": "<string>",
          "name": "<string>",
          "code": "<string>",
          "reason": "<string>",
          "rate": 123,
          "net_adjustment_money": {
            "amount": 123,
            "currency_code": "USD"
          },
          "tax_adjustment_money": {
            "amount": 123,
            "currency_code": "USD"
          }
        },
        "tax_lines": [
          {
            "title": "<string>",
            "rate": 123,
            "price": {
              "amount": 123,
              "currency_code": "USD"
            }
          }
        ]
      }
    ],
    "order_discounts": [
      {
        "external_id": "<string>",
        "name": "<string>",
        "code": "<string>",
        "reason": "<string>",
        "rate": 123,
        "tax_adjustment_money": {
          "amount": 123,
          "currency_code": "USD"
        },
        "net_adjustment_money": {
          "amount": 123,
          "currency_code": "USD"
        }
      }
    ],
    "total_taxes": {
      "amount": 123,
      "currency_code": "USD"
    },
    "total_taxes_presentment": {
      "amount": 123,
      "currency_code": "USD"
    },
    "tags": [
      "<string>"
    ],
    "refunds": [
      [
        [
          {
            "external_id": "<string>",
            "amount": {
              "amount": 123,
              "currency_code": "USD"
            },
            "line_item": [
              {
                "id": 123,
                "quantity": 123,
                "restock": true
              }
            ],
            "created_at": "2023-04-25T13:25:00-05:00",
            "updated_at": "2023-04-25T13:25:00-05:00"
          }
        ]
      ]
    ],
    "line_items": [
      {
        "id": 2,
        "external_id": "<string>",
        "product": {
          "id": 123
        },
        "product_variant": {
          "id": 123
        },
        "quantity": 123,
        "unit_price": {
          "amount": 123,
          "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": "<string>",
            "rate": 123,
            "price": {
              "amount": 123,
              "currency_code": "USD"
            }
          }
        ],
        "refunds": [
          {
            "external_id": "<string>",
            "amount": {
              "amount": 123,
              "currency_code": "USD"
            },
            "line_item": [
              {
                "id": 123,
                "quantity": 123,
                "restock": true
              }
            ],
            "created_at": "2023-04-25T13:25:00-05:00",
            "updated_at": "2023-04-25T13:25:00-05:00"
          }
        ],
        "discounts": [
          {
            "external_id": "<string>",
            "name": "<string>",
            "code": "<string>",
            "reason": "<string>",
            "rate": 123,
            "tax_adjustment_money": {
              "amount": 123,
              "currency_code": "USD"
            },
            "net_adjustment_money": {
              "amount": 123,
              "currency_code": "USD"
            }
          }
        ],
        "duties": [
          {
            "hs_code": "<string>",
            "country_of_origin": "<string>",
            "price": {
              "amount": 123,
              "currency_code": "USD"
            },
            "tax_lines": [
              {
                "title": "<string>",
                "rate": 123,
                "price": {
                  "amount": 123,
                  "currency_code": "USD"
                }
              }
            ]
          }
        ]
      }
    ],
    "fulfillments": [
      {
        "external_id": "<string>",
        "fulfilled_at": "2023-11-07T05:31:56Z",
        "shipping_carrier": "<string>",
        "location": {
          "id": 123
        },
        "fulfillment_line_items": [
          {
            "external_id": "<string>",
            "order_line_item_external_id": "<string>",
            "quantity": 123
          }
        ],
        "tracking_numbers": [
          "<string>"
        ]
      }
    ],
    "created_at": "2023-04-25T13:25:00-05:00",
    "updated_at": "2023-04-25T13:25:00-05:00"
  }
}

Authorizations

​
X-Authorization
string
header
required

API Scope: "Order (write)"

Body

application/json
​
name
string
required

The name of the order.

Maximum string length: 100
​
status
enum<string>
required

Status of the Order.

Available options:
active,
archived,
cancelled,
unknown
​
external_id
string

External ID of the order.

Maximum string length: 100
Example:

"564400c7-7a6b-4f29-b6a5-7bb580b2992c"

​
secondary_identifier
string | null

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.

Maximum string length: 100
​
channel
string | null

If a channel with this name is not already associated with the shop, it will be used to create a new channel.

Maximum string length: 64
Example:

"shopify"

​
customer
object
​
shipping_address
object
Example:
{
  "name": "John Smith",
  "company": "Acme, Co",
  "address1": "123 Example St",
  "address2": "Box 123",
  "city": "Columbus",
  "region": "OH",
  "postal_code": 12345,
  "country_code": "US"
}
​
billing_address
object
Example:
{
  "name": "John Smith",
  "company": "Acme, Co",
  "address1": "123 Example St",
  "address2": "Box 123",
  "city": "Columbus",
  "region": "OH",
  "postal_code": 12345,
  "country_code": "US"
}
​
taxes_included
boolean
​
total_price
object

The price of the order in minor units, such as cents, with its corresponding currency.

Examples:
{ "amount": 50000, "currency_code": "USD" }
{ "amount": 25000 }
{ "amount": 1500, "currency_code": "EUR" }
​
total_price_presentment
object

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.

Example:
{ "amount": 50000, "currency_code": "USD" }
​
total_discounts
object

The deduction from the original order price as a way to promote sales, special offers, or customer loyalty rewards.

Example:
{ "amount": 50000, "currency_code": "USD" }
​
total_discounts_presentment
object

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.

Example:
{ "amount": 50000, "currency_code": "USD" }
​
total_taxes
object

The tax amount for the order.

Example:
{ "amount": 50000, "currency_code": "USD" }
​
total_taxes_presentment
object

The tax amount for the order according to the customer's local currency.

Example:
{ "amount": 50000, "currency_code": "USD" }
​
order_discounts
OrderDiscount · object[][] | null
​
shipping_lines
object[] | null
​
refunds
RefundItems · object[][]

List of refunds associated with the order.

​
line_items
object[]

List of order line items associated with the order.

​
fulfillments
object[] | null

Fulfillment information for the order.

​
source
string | null
Maximum string length: 255
​
tags
string[] | null
​
created_at
string<date-time> | null
Example:

"2023-04-25T13:25:00-05:00"

​
updated_at
string<date-time> | null
Example:

"2023-04-25T13:25:00-05:00"

​
cancelled_at
string<date-time> | null

Timestamp when the order was cancelled. Required when status is cancelled — include both fields together so Loop can reverse Checkout+ protection coverage.

Example:

"2023-04-25T13:25:00-05:00"

Response

OK

​
order
OrderResponse · object