Skip to main content
{
    "reference": "ORD-12345",
    "link_expires_at": 30,
    "line_items": [{
        "product_id": 1
    }],
    "name": "Schaefer, Nolan and Wehner",
    "email": "dave45@gmail.com",
    "phone": "+12069536978",
    "line_1": "492 Quitzon Avenue Apt. 157",
    "line_2": "Apt. 027",
    "city": "Gustside",
    "region": "Massachusetts",
    "post_code": "17594-7013",
    "country": 1
}

{
    "id": 10011,
    "return_url": "https://app.returnpilot.co/..."
}

​
Overview

This endpoint can be used to create a new order. Endpoint: /api/v1/orders Method: POST
After the order is created, the customer will receive an email containing their return link. You do not need to send it to them.

​
Request

​
reference
string
required
The unique number or reference code for the order.Minimum character length: 2Maximum character length: 50
​
link_expires_at
integer
The number of days from now when a return can no longer be scheduled.If not supplied, then the organization default will be used.Minimum: 10Maximum: 365
​
line_items
array
required
An array of line items that are being returned.An order may contain up to 100 line items.
​
name
string
required
The customer name.For example, “John Smith” or “Acme Products”.Minimum character length: 2Maximum character length: 50
​
email
string
required
The customer email address.Carriers may send one or more shipment tracking notifications to this email address.Minimum character length: 6Maximum character length: 100
​
phone
string
The customer phone number.This must be formatted using the E.164 standard.Minimum character length: 7Maximum character length: 30
​
line_1
string
required
Line 1 of the customer address.Minimum character length: 2Maximum character length: 35
​
line_2
string
Line 2 of the customer address.Minimum character length: 2Maximum character length: 35
​
city
string
required
The customer address’ town or city.Minimum character length: 2Maximum character length: 35
​
region
string
required
The customer address’ state, province, or region.Minimum character length: 2Maximum character length: 30
​
post_code
string
required
The customer address’ post or zip code.Minimum character length: 2Maximum character length: 16
​
country
integer
required
A Country enum representing the customer address’ country.This must match your organization’s country.

​
Response

If the order is successfully created, the API will return a 201 Created status code. The response will contain the following content:
​
id
integer
required
The ID of the newly created order.
​
return_url
string
required
The self-expiring link used to schedule a return.
{
    "reference": "ORD-12345",
    "link_expires_at": 30,
    "line_items": [{
        "product_id": 1
    }],
    "name": "Schaefer, Nolan and Wehner",
    "email": "dave45@gmail.com",
    "phone": "+12069536978",
    "line_1": "492 Quitzon Avenue Apt. 157",
    "line_2": "Apt. 027",
    "city": "Gustside",
    "region": "Massachusetts",
    "post_code": "17594-7013",
    "country": 1
}

{
    "id": 10011,
    "return_url": "https://app.returnpilot.co/..."
}