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

HeaderTokenOAuth2 Authentication

AuthorizationstringRequired

Send Authorization: Parcellab-API-Token <encoded-token>.

<encoded-token> = base64(account_id:token) as provided in the portal.

Query parameters

accountinteger[]Optional

limitintegerOptional

Number of results to return per page.

offsetintegerOptional

The initial index from which to return the results.

orderingstringOptional

Order results by any response field. Prefix with - for descending (e.g. -id).

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

404Error

application/json

get/v4/returns/returns-configurations/

HTTPcURLJavaScriptPython

GET /v4/returns/returns-configurations/ HTTP/1.1
Authorization: Parcellab-API-Token YOUR_BASE64_ENCODED_API_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-07-18T13:23:07.152Z"
              }
            ],
            "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

HeaderTokenOAuth2 Authentication

AuthorizationstringRequired

Send Authorization: Parcellab-API-Token <encoded-token>.

<encoded-token> = base64(account_id:token) as provided in the portal.

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

Default client for this portal. Shopify Order API registrations override this with the *.myshopify.com domain.

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: Parcellab-API-Token YOUR_BASE64_ENCODED_API_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-07-18T13:23:07.152Z"
          }
        ],
        "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

HeaderTokenOAuth2 Authentication

AuthorizationstringRequired

Send Authorization: Parcellab-API-Token <encoded-token>.

<encoded-token> = base64(account_id:token) as provided in the portal.

Query parameters

accountinteger[]Optional

limitintegerOptional

Number of results to return per page.

offsetintegerOptional

The initial index from which to return the results.

orderingstringOptional

Order results by any response field. Prefix with - for descending (e.g. -id).

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

404Error

application/json

get/v4/returns/document-templates/

HTTPcURLJavaScriptPython

GET /v4/returns/document-templates/ HTTP/1.1
Authorization: Parcellab-API-Token YOUR_BASE64_ENCODED_API_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"
    }
  ]
}