Return Configurations

Our API allows you to retrieve return configuration sets that are linked to return registrations.

Overview

These requests allow you to get return configuration sets, which include configuration about supported carriers, smart return segments, and other configuration entities with a single HTTPS request.

You can retrieve return configurations associated with your account and a specific return configuration set using its unique ID through these APIs. Additionally, you can retrieve document templates that are used to generate return labels, packing slips, and other documents for return registrations.

Get Return Configuration Sets

You can retrieve a list of return configuration sets for your account using the v4/returns/returns-configurations endpoint.

List Return Configuration

get

Return configuration (sets) represent a bundle of configurations, that are available with that configuration code on an account. The configuration set for instance groups configurations, such as Courier APIs for a specific country or language.

Authorizations

OAuth2 AuthenticationHeaderToken

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

accountinteger[]Optional

limitintegerOptional

Number of results to return per page.

offsetintegerOptional

The initial index from which to return the results.

orderingstringOptional

Which field to use when ordering the results.

Responses

200Success

application/json

countintegerRequiredExample: 123

nextstring · uri · nullableOptionalExample: http://api.example.org/accounts/?offset=400&limit=100

previousstring · uri · nullableOptionalExample: http://api.example.org/accounts/?offset=200&limit=100

400Error

application/json

403Error

application/json

get

/v4/returns/returns-configurations/

HTTPcURLJavaScriptPython

GET /v4/returns/returns-configurations/ HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "id": 1,
      "account": 1,
      "code": "text",
      "client": null,
      "courier_mappings": [
        {
          "courier_api": {
            "account": 1,
            "name": "text",
            "courier_code": "text",
            "identifier": "text",
            "has_oauth_credential": true,
            "service_levels": [
              {
                "key": "text",
                "name": "text",
                "type": "destination-country-iso3",
                "updated_at": "2026-02-21T12:01:31.167Z"
              }
            ],
            "service_name": "text",
            "service_config": "text"
          },
          "filter": {}
        }
      ],
      "returns_order_api": null,
      "returns_rules": null,
      "returnable_periods": [
        {
          "description": "text",
          "trial_period": 1,
          "grace_period": 1,
          "grace_period_shipping_date": 1,
          "is_warranty_period": true,
          "filter": {}
        }
      ]
    }
  ]
}

Get a Return Configuration

You can retrieve a specific return configuration set using the v4/returns/returns-configurations/{id} endpoint.

Retrieve Return Configuration

get

Return configuration (sets) represent a bundle of configurations, that are available with that configuration code on an account. The configuration set for instance groups configurations, such as Courier APIs for a specific country or language.

Authorizations

OAuth2 AuthenticationHeaderToken

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

idintegerRequired

A unique integer value identifying this Returns Portal.

Responses

200Success

application/json

Represents a return configuration set, including courier mappings and returnable periods

idintegerRead-onlyRequired

accountintegerRequired

codestring · max: 128Required

Configuration code of the return configuration

clientinteger · nullableOptional

returns_order_apiinteger · nullableOptional

The API to be used to fetch order information

returns_rulesinteger · nullableOptional

Returns reasons to use for this portal

400Error

application/json

403Error

application/json

404Error

application/json

get

/v4/returns/returns-configurations/{id}/

HTTPcURLJavaScriptPython

GET /v4/returns/returns-configurations/{id}/ HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": 1,
  "account": 1,
  "code": "text",
  "client": null,
  "courier_mappings": [
    {
      "courier_api": {
        "account": 1,
        "name": "text",
        "courier_code": "text",
        "identifier": "text",
        "has_oauth_credential": true,
        "service_levels": [
          {
            "key": "text",
            "name": "text",
            "type": "destination-country-iso3",
            "updated_at": "2026-02-21T12:01:31.167Z"
          }
        ],
        "service_name": "text",
        "service_config": "text"
      },
      "filter": {}
    }
  ],
  "returns_order_api": null,
  "returns_rules": null,
  "returnable_periods": [
    {
      "description": "text",
      "trial_period": 1,
      "grace_period": 1,
      "grace_period_shipping_date": 1,
      "is_warranty_period": true,
      "filter": {}
    }
  ]
}

Get Document Templates

You can retrieve return-related document templates using the v4/returns/document-templates endpoint.

List Document Templates

get

Document templates are used to generate return labels, packing slips, and other documents for return registrations.

Authorizations

OAuth2 AuthenticationHeaderToken

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

accountinteger[]Optional

limitintegerOptional

Number of results to return per page.

offsetintegerOptional

The initial index from which to return the results.

orderingstringOptional

Which field to use when ordering the results.

Responses

200Success

application/json

countintegerRequiredExample: 123

nextstring · uri · nullableOptionalExample: http://api.example.org/accounts/?offset=400&limit=100

previousstring · uri · nullableOptionalExample: http://api.example.org/accounts/?offset=200&limit=100

400Error

application/json

403Error

application/json

get

/v4/returns/document-templates/

HTTPcURLJavaScriptPython

GET /v4/returns/document-templates/ HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "id": 1,
      "account": 1,
      "key": "text",
      "content": "text",
      "client_key": null,
      "identifier": "text"
    }
  ]
}