Skip to main content
POST
/
orders
Create Order
curl --request POST \
  --url https://api.loopreturns.com/api/v1/orders \
  --header 'Content-Type: application/json' \
  --header 'X-Authorization: <api-key>' \
  --data '
{
  "name": "<string>",
  "sales_channel": "<string>",
  "taxes_included": true,
  "total_price": {
    "amount": 123,
    "currency_code": "USD"
  },
  "line_items": [
    {
      "product": {
        "id": 123
      },
      "unit_price": {
        "amount": 123,
        "currency_code": "USD"
      },
      "taxable": true,
      "external_id": "<string>",
      "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"
      },
      "tax_lines": [
        {
          "title": "<string>",
          "rate": 123
        }
      ],
      "refunds": [
        {
          "amount": {
            "amount": 123,
            "currency_code": "USD"
          },
          "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
            }
          ]
        }
      ]
    }
  ],
  "source": {
    "name": "<string>"
  },
  "external_id": "<string>",
  "secondary_identifier": "<string>",
  "customer": {
    "id": 123
  },
  "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": [
    [
      {
        "amount": {
          "amount": 123,
          "currency_code": "USD"
        },
        "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"
      }
    ]
  ],
  "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>"
      ]
    }
  ],
  "tags": [
    "<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"
  },
  "metadata": [
    {
      "key": "<string>",
      "value": "<unknown>"
    }
  ],
  "fees": [
    {
      "name": "<string>",
      "amount": {
        "amount": 123,
        "currency_code": "USD"
      },
      "presentment_amount": {
        "amount": 50000,
        "currency_code": "USD"
      },
      "tax": {
        "amount": 50000,
        "currency_code": "USD"
      },
      "accepted_offer_mode": [
        "<string>"
      ],
      "external_id": "<string>"
    }
  ]
}
'
{
  "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": [
      [
        [
          {
            "amount": {
              "amount": 123,
              "currency_code": "USD"
            },
            "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": [
      {
        "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": [
          {
            "amount": {
              "amount": 123,
              "currency_code": "USD"
            },
            "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,
            "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",
    "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>"
      }
    ]
  }
}

Authorizations

​
X-Authorization
string
header
required

API Scope: "Order (write)"

Body

application/json
​
name
string
required
Maximum string length: 100
​
sales_channel
string
required

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.

Maximum string length: 255
Examples:

"online"

"mobile"

​
status
enum<string>
required

Status of the Order.

Available options:
active,
archived,
cancelled,
unknown
​
taxes_included
boolean | null
required
​
total_price
object
required

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" }
​
line_items
object[]
required

List of order line items associated with the order.

​
source
object
required

The source system that created the order.

​
external_id
string | null
Maximum string length: 64
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
​
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"
}
​
total_price_presentment
object | null

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 | null

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 | null

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 | null

The tax amount for the order.

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

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

Example:
{ "amount": 50000, "currency_code": "USD" }
​
order_discounts
OrderDiscount · object[][]

List of discounts associated with the order.

​
shipping_lines
ShippingLine · object[][]

List of shipping line items associated with the order.

​
refunds
RefundItems · object[][]

List of refunds associated with the order.

​
fulfillments
object[] | null

Fulfillment information for the order.

​
tags
string[] | null

A tag used to classify and group orders.

​
created_at
string<date-time> | null

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"

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

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

​
financial_status
enum<string> | null

The financial status of the order.

Available options:
pending,
authorized,
partially_paid,
paid,
partially_refunded,
refunded,
voided,
null
Maximum string length: 30
​
cancel_reason
enum<string> | null

The reason the order was cancelled, if applicable.

Available options:
customer,
declined,
fraud,
inventory,
other,
staff,
null
Maximum string length: 30
​
processed_at
string<date-time> | null

The date and time when the order was processed in the source system.

Example:

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

​
browser_ip

The IP address of the browser used to place the order.

Maximum string length: 45
​
client_details_user_agent
string | null

The user agent string of the browser used to place the order.

Maximum string length: 1000
​
total_tip_received
object | null

The total tip amount received for the order.

Example:
{ "amount": 50000, "currency_code": "USD" }
​
metadata
object[] | null

Key/value metadata to attach to the order. A return_id key must reference a return that exists for the shop.

​
fees
object[] | null

Fees associated with the order (for example, checkout-time protection offers).

Response

OK

​
order
OrderResponse · object