Upsert Order
curl --request PUT \
--url https://api.loopreturns.com/api/v1/orders \
--header 'Content-Type: application/json' \
--header 'X-Authorization: <api-key>' \
--data '
{
"external_id": "order-10042",
"name": "#10042",
"status": "active",
"taxes_included": false,
"total_price": {
"amount": 25400,
"currency_code": "USD"
},
"sales_channel": "online",
"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"
}
]
}
'import requests
url = "https://api.loopreturns.com/api/v1/orders"
payload = {
"external_id": "order-10042",
"name": "#10042",
"status": "active",
"taxes_included": False,
"total_price": {
"amount": 25400,
"currency_code": "USD"
},
"sales_channel": "online",
"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"
}
]
}
headers = {
"X-Authorization": "<api-key>",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PUT',
headers: {'X-Authorization': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
external_id: 'order-10042',
name: '#10042',
status: 'active',
taxes_included: false,
total_price: {amount: 25400, currency_code: 'USD'},
sales_channel: 'online',
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'
}
]
})
};
fetch('https://api.loopreturns.com/api/v1/orders', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.loopreturns.com/api/v1/orders",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => json_encode([
'external_id' => 'order-10042',
'name' => '#10042',
'status' => 'active',
'taxes_included' => false,
'total_price' => [
'amount' => 25400,
'currency_code' => 'USD'
],
'sales_channel' => 'online',
'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'
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-Authorization: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.loopreturns.com/api/v1/orders"
payload := strings.NewReader("{\n \"external_id\": \"order-10042\",\n \"name\": \"#10042\",\n \"status\": \"active\",\n \"taxes_included\": false,\n \"total_price\": {\n \"amount\": 25400,\n \"currency_code\": \"USD\"\n },\n \"sales_channel\": \"online\",\n \"source\": {\n \"name\": \"newstore\"\n },\n \"line_items\": [\n {\n \"external_id\": \"line-item-a\",\n \"product\": {\n \"external_id\": \"product-a\"\n },\n \"unit_price\": {\n \"amount\": 7800,\n \"currency_code\": \"USD\"\n },\n \"taxable\": true,\n \"quantity\": 2\n },\n {\n \"external_id\": \"line-item-b\",\n \"product\": {\n \"external_id\": \"product-b\"\n },\n \"unit_price\": {\n \"amount\": 9800,\n \"currency_code\": \"USD\"\n },\n \"taxable\": true,\n \"quantity\": 1\n }\n ],\n \"refunds\": [\n {\n \"external_id\": \"pos-refund-2026-0807-0042\",\n \"type\": \"line_item\",\n \"amount\": {\n \"amount\": 17600,\n \"currency_code\": \"USD\"\n },\n \"line_items\": [\n {\n \"external_id\": \"line-item-a\",\n \"quantity\": 1,\n \"restock\": true\n },\n {\n \"external_id\": \"line-item-b\",\n \"quantity\": 1,\n \"restock\": false\n }\n ],\n \"created_at\": \"2026-08-07T14:32:00-07:00\"\n }\n ]\n}")
req, _ := http.NewRequest("PUT", url, payload)
req.Header.Add("X-Authorization", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.put("https://api.loopreturns.com/api/v1/orders")
.header("X-Authorization", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"external_id\": \"order-10042\",\n \"name\": \"#10042\",\n \"status\": \"active\",\n \"taxes_included\": false,\n \"total_price\": {\n \"amount\": 25400,\n \"currency_code\": \"USD\"\n },\n \"sales_channel\": \"online\",\n \"source\": {\n \"name\": \"newstore\"\n },\n \"line_items\": [\n {\n \"external_id\": \"line-item-a\",\n \"product\": {\n \"external_id\": \"product-a\"\n },\n \"unit_price\": {\n \"amount\": 7800,\n \"currency_code\": \"USD\"\n },\n \"taxable\": true,\n \"quantity\": 2\n },\n {\n \"external_id\": \"line-item-b\",\n \"product\": {\n \"external_id\": \"product-b\"\n },\n \"unit_price\": {\n \"amount\": 9800,\n \"currency_code\": \"USD\"\n },\n \"taxable\": true,\n \"quantity\": 1\n }\n ],\n \"refunds\": [\n {\n \"external_id\": \"pos-refund-2026-0807-0042\",\n \"type\": \"line_item\",\n \"amount\": {\n \"amount\": 17600,\n \"currency_code\": \"USD\"\n },\n \"line_items\": [\n {\n \"external_id\": \"line-item-a\",\n \"quantity\": 1,\n \"restock\": true\n },\n {\n \"external_id\": \"line-item-b\",\n \"quantity\": 1,\n \"restock\": false\n }\n ],\n \"created_at\": \"2026-08-07T14:32:00-07:00\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.loopreturns.com/api/v1/orders")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["X-Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"external_id\": \"order-10042\",\n \"name\": \"#10042\",\n \"status\": \"active\",\n \"taxes_included\": false,\n \"total_price\": {\n \"amount\": 25400,\n \"currency_code\": \"USD\"\n },\n \"sales_channel\": \"online\",\n \"source\": {\n \"name\": \"newstore\"\n },\n \"line_items\": [\n {\n \"external_id\": \"line-item-a\",\n \"product\": {\n \"external_id\": \"product-a\"\n },\n \"unit_price\": {\n \"amount\": 7800,\n \"currency_code\": \"USD\"\n },\n \"taxable\": true,\n \"quantity\": 2\n },\n {\n \"external_id\": \"line-item-b\",\n \"product\": {\n \"external_id\": \"product-b\"\n },\n \"unit_price\": {\n \"amount\": 9800,\n \"currency_code\": \"USD\"\n },\n \"taxable\": true,\n \"quantity\": 1\n }\n ],\n \"refunds\": [\n {\n \"external_id\": \"pos-refund-2026-0807-0042\",\n \"type\": \"line_item\",\n \"amount\": {\n \"amount\": 17600,\n \"currency_code\": \"USD\"\n },\n \"line_items\": [\n {\n \"external_id\": \"line-item-a\",\n \"quantity\": 1,\n \"restock\": true\n },\n {\n \"external_id\": \"line-item-b\",\n \"quantity\": 1,\n \"restock\": false\n }\n ],\n \"created_at\": \"2026-08-07T14:32:00-07:00\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"order": {
"id": 2,
"external_id": "<string>",
"name": "<string>",
"secondary_identifier": "<string>",
"source": "<string>",
"sales_channel": "<string>",
"customer": {
"id": 123,
"external_id": "<string>",
"sales_channel": "<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": [
[
{
"line_items": [
{
"id": 123,
"external_id": "<string>",
"quantity": 123,
"restock": true
}
],
"line_item": {
"id": 123,
"external_id": "<string>",
"quantity": 123,
"restock": true
},
"id": 123,
"external_id": "<string>",
"amount": {
"amount": 123,
"currency_code": "USD"
},
"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,
"external_id": "<string>"
},
"product_variant": {
"id": 123,
"external_id": "<string>"
},
"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": [
{
"id": 123,
"external_id": "<string>",
"amount": {
"amount": 123,
"currency_code": "USD"
},
"line_item": {
"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": [
{
"id": 123,
"external_id": "<string>",
"fulfilled_at": "2023-11-07T05:31:56Z",
"shipping_carrier": "<string>",
"location": {
"id": 123,
"external_id": "<string>"
},
"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",
"processed_at": "2023-04-25T13:25:00-05:00",
"browser_ip": "127.0.0.1",
"client_details_user_agent": "<string>",
"total_tip_received": {
"amount": 50000,
"currency_code": "USD"
},
"warnings": [
{
"code": "<string>",
"message": "<string>"
}
]
}
}{
"errors": "<string>"
}Orders
Upsert Order
Upsert an order using the external_id.
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 '
{
"external_id": "order-10042",
"name": "#10042",
"status": "active",
"taxes_included": false,
"total_price": {
"amount": 25400,
"currency_code": "USD"
},
"sales_channel": "online",
"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"
}
]
}
'import requests
url = "https://api.loopreturns.com/api/v1/orders"
payload = {
"external_id": "order-10042",
"name": "#10042",
"status": "active",
"taxes_included": False,
"total_price": {
"amount": 25400,
"currency_code": "USD"
},
"sales_channel": "online",
"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"
}
]
}
headers = {
"X-Authorization": "<api-key>",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PUT',
headers: {'X-Authorization': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
external_id: 'order-10042',
name: '#10042',
status: 'active',
taxes_included: false,
total_price: {amount: 25400, currency_code: 'USD'},
sales_channel: 'online',
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'
}
]
})
};
fetch('https://api.loopreturns.com/api/v1/orders', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.loopreturns.com/api/v1/orders",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => json_encode([
'external_id' => 'order-10042',
'name' => '#10042',
'status' => 'active',
'taxes_included' => false,
'total_price' => [
'amount' => 25400,
'currency_code' => 'USD'
],
'sales_channel' => 'online',
'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'
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-Authorization: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.loopreturns.com/api/v1/orders"
payload := strings.NewReader("{\n \"external_id\": \"order-10042\",\n \"name\": \"#10042\",\n \"status\": \"active\",\n \"taxes_included\": false,\n \"total_price\": {\n \"amount\": 25400,\n \"currency_code\": \"USD\"\n },\n \"sales_channel\": \"online\",\n \"source\": {\n \"name\": \"newstore\"\n },\n \"line_items\": [\n {\n \"external_id\": \"line-item-a\",\n \"product\": {\n \"external_id\": \"product-a\"\n },\n \"unit_price\": {\n \"amount\": 7800,\n \"currency_code\": \"USD\"\n },\n \"taxable\": true,\n \"quantity\": 2\n },\n {\n \"external_id\": \"line-item-b\",\n \"product\": {\n \"external_id\": \"product-b\"\n },\n \"unit_price\": {\n \"amount\": 9800,\n \"currency_code\": \"USD\"\n },\n \"taxable\": true,\n \"quantity\": 1\n }\n ],\n \"refunds\": [\n {\n \"external_id\": \"pos-refund-2026-0807-0042\",\n \"type\": \"line_item\",\n \"amount\": {\n \"amount\": 17600,\n \"currency_code\": \"USD\"\n },\n \"line_items\": [\n {\n \"external_id\": \"line-item-a\",\n \"quantity\": 1,\n \"restock\": true\n },\n {\n \"external_id\": \"line-item-b\",\n \"quantity\": 1,\n \"restock\": false\n }\n ],\n \"created_at\": \"2026-08-07T14:32:00-07:00\"\n }\n ]\n}")
req, _ := http.NewRequest("PUT", url, payload)
req.Header.Add("X-Authorization", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.put("https://api.loopreturns.com/api/v1/orders")
.header("X-Authorization", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"external_id\": \"order-10042\",\n \"name\": \"#10042\",\n \"status\": \"active\",\n \"taxes_included\": false,\n \"total_price\": {\n \"amount\": 25400,\n \"currency_code\": \"USD\"\n },\n \"sales_channel\": \"online\",\n \"source\": {\n \"name\": \"newstore\"\n },\n \"line_items\": [\n {\n \"external_id\": \"line-item-a\",\n \"product\": {\n \"external_id\": \"product-a\"\n },\n \"unit_price\": {\n \"amount\": 7800,\n \"currency_code\": \"USD\"\n },\n \"taxable\": true,\n \"quantity\": 2\n },\n {\n \"external_id\": \"line-item-b\",\n \"product\": {\n \"external_id\": \"product-b\"\n },\n \"unit_price\": {\n \"amount\": 9800,\n \"currency_code\": \"USD\"\n },\n \"taxable\": true,\n \"quantity\": 1\n }\n ],\n \"refunds\": [\n {\n \"external_id\": \"pos-refund-2026-0807-0042\",\n \"type\": \"line_item\",\n \"amount\": {\n \"amount\": 17600,\n \"currency_code\": \"USD\"\n },\n \"line_items\": [\n {\n \"external_id\": \"line-item-a\",\n \"quantity\": 1,\n \"restock\": true\n },\n {\n \"external_id\": \"line-item-b\",\n \"quantity\": 1,\n \"restock\": false\n }\n ],\n \"created_at\": \"2026-08-07T14:32:00-07:00\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.loopreturns.com/api/v1/orders")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["X-Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"external_id\": \"order-10042\",\n \"name\": \"#10042\",\n \"status\": \"active\",\n \"taxes_included\": false,\n \"total_price\": {\n \"amount\": 25400,\n \"currency_code\": \"USD\"\n },\n \"sales_channel\": \"online\",\n \"source\": {\n \"name\": \"newstore\"\n },\n \"line_items\": [\n {\n \"external_id\": \"line-item-a\",\n \"product\": {\n \"external_id\": \"product-a\"\n },\n \"unit_price\": {\n \"amount\": 7800,\n \"currency_code\": \"USD\"\n },\n \"taxable\": true,\n \"quantity\": 2\n },\n {\n \"external_id\": \"line-item-b\",\n \"product\": {\n \"external_id\": \"product-b\"\n },\n \"unit_price\": {\n \"amount\": 9800,\n \"currency_code\": \"USD\"\n },\n \"taxable\": true,\n \"quantity\": 1\n }\n ],\n \"refunds\": [\n {\n \"external_id\": \"pos-refund-2026-0807-0042\",\n \"type\": \"line_item\",\n \"amount\": {\n \"amount\": 17600,\n \"currency_code\": \"USD\"\n },\n \"line_items\": [\n {\n \"external_id\": \"line-item-a\",\n \"quantity\": 1,\n \"restock\": true\n },\n {\n \"external_id\": \"line-item-b\",\n \"quantity\": 1,\n \"restock\": false\n }\n ],\n \"created_at\": \"2026-08-07T14:32:00-07:00\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"order": {
"id": 2,
"external_id": "<string>",
"name": "<string>",
"secondary_identifier": "<string>",
"source": "<string>",
"sales_channel": "<string>",
"customer": {
"id": 123,
"external_id": "<string>",
"sales_channel": "<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": [
[
{
"line_items": [
{
"id": 123,
"external_id": "<string>",
"quantity": 123,
"restock": true
}
],
"line_item": {
"id": 123,
"external_id": "<string>",
"quantity": 123,
"restock": true
},
"id": 123,
"external_id": "<string>",
"amount": {
"amount": 123,
"currency_code": "USD"
},
"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,
"external_id": "<string>"
},
"product_variant": {
"id": 123,
"external_id": "<string>"
},
"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": [
{
"id": 123,
"external_id": "<string>",
"amount": {
"amount": 123,
"currency_code": "USD"
},
"line_item": {
"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": [
{
"id": 123,
"external_id": "<string>",
"fulfilled_at": "2023-11-07T05:31:56Z",
"shipping_carrier": "<string>",
"location": {
"id": 123,
"external_id": "<string>"
},
"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",
"processed_at": "2023-04-25T13:25:00-05:00",
"browser_ip": "127.0.0.1",
"client_details_user_agent": "<string>",
"total_tip_received": {
"amount": 50000,
"currency_code": "USD"
},
"warnings": [
{
"code": "<string>",
"message": "<string>"
}
]
}
}{
"errors": "<string>"
}Authorizations
API Scope: "Order (write)"
Body
application/json
External ID of the order.
Maximum string length:
100Example:
"564400c7-7a6b-4f29-b6a5-7bb580b2992c"
The name of the order.
Maximum string length:
100If a channel with this name is not already associated with the shop, it will be used to create a new channel.
Maximum string length:
255Example:
"shopify"
Status of the Order.
Available options:
active, archived, cancelled, unknown The price of the order in minor units, such as cents, with its corresponding currency.
Show child attributes
Show child attributes
Examples:
{ "amount": 50000, "currency_code": "USD" }
{ "amount": 25000 }
{ "amount": 1500, "currency_code": "EUR" }
List of order line items associated with the order.
Show child attributes
Show child attributes
The source system that created the order.
Show child attributes
Show child attributes
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- Option 1
- Option 2
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Example:
{
"name": "John Smith",
"company": "Acme, Co",
"address1": "123 Example St",
"address2": "Box 123",
"city": "Columbus",
"region": "OH",
"postal_code": 12345,
"country_code": "US"
}
Show child attributes
Show child attributes
Example:
{
"name": "John Smith",
"company": "Acme, Co",
"address1": "123 Example St",
"address2": "Box 123",
"city": "Columbus",
"region": "OH",
"postal_code": 12345,
"country_code": "US"
}
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.
Show child attributes
Show child attributes
Example:
{ "amount": 50000, "currency_code": "USD" }
The deduction from the original order price as a way to promote sales, special offers, or customer loyalty rewards.
Show child attributes
Show child attributes
Example:
{ "amount": 50000, "currency_code": "USD" }
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.
Show child attributes
Show child attributes
Example:
{ "amount": 50000, "currency_code": "USD" }
The tax amount for the order.
Show child attributes
Show child attributes
Example:
{ "amount": 50000, "currency_code": "USD" }
The tax amount for the order according to the customer's local currency.
Show child attributes
Show child attributes
Example:
{ "amount": 50000, "currency_code": "USD" }
Show child attributes
Show child attributes
Show child attributes
Show child attributes
List of refunds associated with the order.
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.
Show child attributes
Show child attributes
Fulfillment information for the order.
Show child attributes
Show child attributes
A tag used to classify and group orders.
The date and time the order was created in the source system. Required in the unstable API version; will become required in a future stable version.
Example:
"2023-04-25T13:25:00-05:00"
Example:
"2023-04-25T13:25:00-05:00"
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"
The financial status of the order.
Available options:
pending, authorized, partially_paid, paid, partially_refunded, refunded, voided, null Maximum string length:
30The reason the order was cancelled, if applicable.
Available options:
customer, declined, fraud, inventory, other, staff, null Maximum string length:
30The date and time when the order was processed in the source system.
Example:
"2023-04-25T13:25:00-05:00"
The IP address of the browser used to place the order.
Maximum string length:
45The user agent string of the browser used to place the order.
Maximum string length:
1000The total tip amount received for the order.
Show child attributes
Show child attributes
Example:
{ "amount": 50000, "currency_code": "USD" }
Response
OK
Show child attributes
Show child attributes
⌘I