Returnless API REST Reference

https://docs.returnless.com/docs/api-rest-reference/
Admin
The Returnless API REST Reference provides comprehensive documentation for integrating with the...
Tokens:5,909
Snippets:62
Trust Score:9.4
Update:1 month ago
Show doc for...
Tokens:
Raw
### Example query with filter[order_number]

Source: https://docs.returnless.com/docs/api-rest-reference/q3nvwmo5qt427-filtering

Shows the basic filter syntax for Returnless API listing endpoints. The filter parameter is passed as a query parameter using the format filter[FILTER_NAME]=VALUE.

```http
https://api-v2.returnless.com/2025-01/return-orders?filter[order_number]=1234
```

--------------------------------

### List response with cursor state in links and meta

Source: https://docs.returnless.com/docs/api-rest-reference/ez0l8yglncr1t-pagination

Example response from a list endpoint (e.g., return-orders) showing the embedded cursor state in the links and meta objects. The next field contains a ready-to-use URL for the following page, and meta.next_cursor holds the opaque cursor token to pass back. first and last are always null with cursor-based pagination.

```json
{
    "data": [],
    "links": {
        "first": null,
        "last": null,
        "prev": null,
        "next": "https://api-v2.returnless.com/2025-01/return-orders?cursor=CURSOR_ID"
    },
    "meta": {
        "path": "https://api-v2.returnless.com/2025-01/return-orders",
        "per_page": 25,
        "next_cursor": "CURSOR_ID",
        "prev_cursor": null
    }
}
```

--------------------------------

### URL-encoded timezone offset for created_at

Source: https://docs.returnless.com/docs/api-rest-reference/q3nvwmo5qt427-filtering

Example of a date filter with a timezone offset. The plus sign in the offset must be URL-encoded as %2B because a literal + is interpreted as a space in query strings.

```http
https://api-v2.returnless.com/2025-01/return-orders?filter[created_at][gte]=2026-06-01T00:00:00%2B02:00
```

--------------------------------

### Authenticated GET request to /account

Source: https://docs.returnless.com/docs/api-rest-reference/vlfd96x8lqzgf-authentication

Authenticated call to retrieve the current logged account. Replace YOUR_API_KEY with your API token in the Authorization header. A 200 OK response indicates successful authentication.

```http
GET
https://api-v2.returnless.com/2023-01/account
```

--------------------------------

### Date filter operators for created_at

Source: https://docs.returnless.com/docs/api-rest-reference/q3nvwmo5qt427-filtering

Examples of date range filters using the operators lt, lte, gt, and gte. Values must be full ISO 8601 timestamps with timezone; date-only values are not accepted.

```http
https://api-v2.returnless.com/2025-01/return-orders?filter[created_at][lt]=2026-06-01T00:00:00Z
```

```http
https://api-v2.returnless.com/2025-01/return-orders?filter[created_at][lte]=2026-06-01T00:00:00Z
```

```http
https://api-v2.returnless.com/2025-01/return-orders?filter[created_at][gt]=2026-06-01T00:00:00Z
```

```http
https://api-v2.returnless.com/2025-01/return-orders?filter[created_at][gte]=2026-06-01T00:00:00Z
```

--------------------------------

### Range filter combining gte and lt

Source: https://docs.returnless.com/docs/api-rest-reference/q3nvwmo5qt427-filtering

Combines two operators to filter within a range. This example filters records created within June 2026 by using gte and lt together.

```http
https://api-v2.returnless.com/2025-01/return-orders?filter[created_at][gte]=2026-06-01T00:00:00Z&filter[created_at][lt]=2026-07-01T00:00:00Z
```

--------------------------------

### cURL request to create a return instruction

Source: https://docs.returnless.com/docs/api-rest-reference/8e37bc0bca346-create-a-2025-01-return-instruction

Sample cURL command for the POST /2025-01/return-instructions endpoint. Requires Bearer authentication and sends JSON content type.

```shell
curl --request POST \
  --url https://api-v2.returnless.com/2025-01/return-instructions \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'
```

--------------------------------

### PATCH /2025-01/return-instructions/{returnInstruction}

Source: https://docs.returnless.com/docs/api-rest-reference/4a001d3f98eb0-modify-a-2025-01-return-instruction

Updates an existing return instruction. The return instruction ID is required as a path parameter. Authentication is via Bearer token.

```APIDOC
## PATCH /2025-01/return-instructions/{returnInstruction}

### Description
Updates an existing return instruction identified by the return instruction ID.

### Method
PATCH

### Endpoint
https://api-v2.returnless.com/2025-01/return-instructions/{returnInstruction}

### Parameters
#### Path Parameters
- **returnInstruction** (string) - Required - The unique identifier of the return instruction to modify.

### Request Example
```
curl --request PATCH \
  --url https://api-v2.returnless.com/2025-01/return-instructions/{returnInstruction} \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'
```

### Response
#### Success Response (200)
No response body details provided.

#### Error Response (401)
Unauthorized - authentication failed or missing.

```

--------------------------------

### POST /2025-01/return-instructions

Source: https://docs.returnless.com/docs/api-rest-reference/8e37bc0bca346-create-a-2025-01-return-instruction

Creates a return instruction for a return order in the Returnless system.

```APIDOC
## POST /2025-01/return-instructions

### Description
Creates a return instruction for a return order in the Returnless system.

### Method
POST

### Endpoint
https://api-v2.returnless.com/2025-01/return-instructions

### Security
Bearer Auth

### Request Example
```
curl --request POST \
  --url https://api-v2.returnless.com/2025-01/return-instructions \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'
```

### Responses
- 200: Success
- 401: Unauthorized
```

--------------------------------

### Fetch next page with cursor query parameter

Source: https://docs.returnless.com/docs/api-rest-reference/ez0l8yglncr1t-pagination

Fetch the next page by adding the cursor query parameter with the value from meta.next_cursor. Alternatively, call the URL held in links.next. The cursor is an opaque token; do not build or modify it yourself.

```http
https://api-v2.returnless.com/2025-01/return-orders?cursor=CURSOR_ID
```

--------------------------------

### POST /2025-01/shipping-instructions

Source: https://docs.returnless.com/docs/api-rest-reference/0828825f0e863-create-a-2025-01-shipping-instruction

Creates a new shipping instruction. This endpoint requires Bearer authentication and accepts a JSON request body.

```APIDOC
## POST /2025-01/shipping-instructions

### Description
Creates a new shipping instruction in the Returnless system.

### Method
POST

### Endpoint
https://api-v2.returnless.com/2025-01/shipping-instructions

### Security
Bearer Auth

### Request Example
```
curl --request POST \
  --url https://api-v2.returnless.com/2025-01/shipping-instructions \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'
```

### Responses
#### Success Response (200)
Successful creation of the shipping instruction.

#### Unauthorized (401)
Authentication failed or missing credentials.

```

--------------------------------

### Create a 2025-01 Shipping Instruction with cURL

Source: https://docs.returnless.com/docs/api-rest-reference/0828825f0e863-create-a-2025-01-shipping-instruction

Sends a POST request to create a shipping instruction using the Returnless API v2 2025-01 endpoint. Requires Bearer authentication and includes Accept and Content-Type headers for JSON.

```shell
curl --request POST \
  --url https://api-v2.returnless.com/2025-01/shipping-instructions \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'
```

--------------------------------

### Combining filters with sort

Source: https://docs.returnless.com/docs/api-rest-reference/q3nvwmo5qt427-filtering

Shows how to combine multiple filters in a single request. Filters are applied together using logical AND, and can be combined with sorting and cursor pagination.

```http
https://api-v2.returnless.com/2025-01/return-orders?filter[return_status]=8c3e…&filter[is_test_record]=false&sort=-created_at
```

--------------------------------

### cURL request to update a return instruction

Source: https://docs.returnless.com/docs/api-rest-reference/4a001d3f98eb0-modify-a-2025-01-return-instruction

Use this cURL command to send a PATCH request to the Returnless API to update a return instruction. The request requires Bearer authentication and includes the returnInstruction path parameter. The request body is not shown in the sample.

```shell
curl --request PATCH \
  --url https://api-v2.returnless.com/2025-01/return-instructions/{returnInstruction} \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'

```

--------------------------------

### cURL request to create a note template

Source: https://docs.returnless.com/docs/api-rest-reference/cd11de6386867-create-a-2025-01-note-template

Use this cURL command to create a note template. It requires Bearer authentication and sends a POST request to the /2025-01/note-templates endpoint with JSON headers.

```shell
curl --request POST \
  --url https://api-v2.returnless.com/2025-01/note-templates \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'

```

--------------------------------

### POST /note-templates

Source: https://docs.returnless.com/docs/api-rest-reference/cd11de6386867-create-a-2025-01-note-template

Creates a new note template. This endpoint requires Bearer authentication and accepts a JSON request body.

```APIDOC
## POST /note-templates

### Description
Creates a new note template.

### Method
POST

### Endpoint
https://api-v2.returnless.com/2025-01/note-templates

### Authentication
Bearer Auth

### Request Example
```
curl --request POST \
  --url https://api-v2.returnless.com/2025-01/note-templates \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'
```

### Responses
#### Success Response (200)
Successful creation.

#### Error Response (401)
Unauthorized - invalid or missing authentication credentials.

```

--------------------------------

### PATCH /2025-01/shipping-instructions/{shippingInstruction}

Source: https://docs.returnless.com/docs/api-rest-reference/ad704bf1de6ae-modify-a-2025-01-shipping-instruction

Updates a shipping instruction identified by the provided shippingInstruction ID. Requires Bearer authentication.

```APIDOC
## PATCH /2025-01/shipping-instructions/{shippingInstruction}

### Description
Updates a shipping instruction. This endpoint is used to modify the details of an existing shipping instruction.

### Method
PATCH

### Endpoint
https://api-v2.returnless.com/2025-01/shipping-instructions/{shippingInstruction}

### Parameters
#### Path Parameters
- **shippingInstruction** (string) - Required - The unique identifier of the shipping instruction to modify.

### Security
- **Bearer Auth** - Required

### Request Example
```shell
curl --request PATCH \
  --url https://api-v2.returnless.com/2025-01/shipping-instructions/{shippingInstruction} \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'
```

### Responses
#### Success Response (200)
Success.

#### Unauthorized Response (401)
Authentication failed.

```

--------------------------------

### Change page size with per_page query parameter

Source: https://docs.returnless.com/docs/api-rest-reference/ez0l8yglncr1t-pagination

Set the number of records per page with the per_page query parameter. The default page size is 25 and the maximum is 100; requesting more than 100 caps the page size at 100.

```http
https://api-v2.returnless.com/2025-01/return-orders?per_page=50
```

--------------------------------

### cURL request to update a shipping instruction

Source: https://docs.returnless.com/docs/api-rest-reference/ad704bf1de6ae-modify-a-2025-01-shipping-instruction

Use this cURL command to send a PATCH request to the v2.shipping-instructions.update endpoint. The request requires Bearer authentication and includes Accept and Content-Type headers. Replace {shippingInstruction} with the actual shipping instruction ID.

```shell
curl --request PATCH \
  --url https://api-v2.returnless.com/2025-01/shipping-instructions/{shippingInstruction} \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'
```

--------------------------------

### Filtering on multiple values with filter[id]

Source: https://docs.returnless.com/docs/api-rest-reference/q3nvwmo5qt427-filtering

Demonstrates filtering on multiple values using a comma-separated list. The endpoint returns any record that matches one of the provided values.

```http
https://api-v2.returnless.com/2025-01/return-orders?filter[id]=returnorder_00ZgbJ0gv22BcE1D7oQwXtQ4,returnorder_00bVWQp4doJGiE1yZgOJougy,returnorder_01O18AQlP3e2FE1m6a3oQcr8
```

--------------------------------

### PATCH /2025-01/note-templates/{noteTemplate}

Source: https://docs.returnless.com/docs/api-rest-reference/bb70e5e1ca281-modify-a-2025-01-note-template

Updates an existing note template. The noteTemplate path parameter is required and represents the identifier of the note template to modify.

```APIDOC
## [PATCH] /2025-01/note-templates/{noteTemplate}

### Description
Updates an existing note template. The noteTemplate path parameter identifies the template to modify.

### Method
PATCH

### Endpoint
https://api-v2.returnless.com/2025-01/note-templates/{noteTemplate}

### Parameters

#### Path Parameters
- **noteTemplate** (string) - Required - The identifier of the note template to update.

### Request Example
```
curl --request PATCH \
  --url https://api-v2.returnless.com/2025-01/note-templates/{noteTemplate} \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'
```

### Response
#### Success Response (200)
- **OK** - The update was successful.

#### Error Response (401)
- **Unauthorized** - Authentication failed.
```

--------------------------------

### cURL request to update a note template

Source: https://docs.returnless.com/docs/api-rest-reference/bb70e5e1ca281-modify-a-2025-01-note-template

Use this cURL command to send a PATCH request to the note-templates endpoint. It requires Bearer authentication and includes the noteTemplate path parameter. The request includes Accept and Content-Type headers set to application/json.

```shell
curl --request PATCH \
  --url https://api-v2.returnless.com/2025-01/note-templates/{noteTemplate} \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'

```

--------------------------------

### PATCH /2025-01/email-templates/{emailTemplate}

Source: https://docs.returnless.com/docs/api-rest-reference/fa067f9fd720e-modify-a-2025-01-email-template

Documentation for the PATCH endpoint that modifies an email template in the Returnless API.

```APIDOC
## PATCH /2025-01/email-templates/{emailTemplate}

### Description
Modifies an existing email template for the 2025-01 API version.

### Method
PATCH

### Endpoint
https://api-v2.returnless.com/2025-01/email-templates/{emailTemplate}

### Parameters
#### Path Parameters
- **emailTemplate** (string) - Required - The identifier of the email template to modify.

### Request Example
```
curl --request PATCH \
  --url https://api-v2.returnless.com/2025-01/email-templates/{emailTemplate} \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'
```

### Response
#### Success Response (200)
Successful modification.

#### Error Response (401)
Unauthorized - authentication failed.

```

--------------------------------

### cURL request to update an email template

Source: https://docs.returnless.com/docs/api-rest-reference/fa067f9fd720e-modify-a-2025-01-email-template

Use this cURL command to send a PATCH request to the Returnless API to update an email template. The request requires Bearer authentication and includes Accept and Content-Type headers. The emailTemplate path parameter must be replaced with the actual template ID.

```shell
curl --request PATCH \
  --url https://api-v2.returnless.com/2025-01/email-templates/{emailTemplate} \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'

```
Tokens:
Raw