# Return Configurations

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

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

```json
{"openapi":"3.1.0","info":{"title":"parcelLab API","version":"v4"},"security":[{"OAuth2 Authentication":[]},{"HeaderToken":[]}],"components":{"securitySchemes":{"OAuth2 Authentication":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"HeaderToken":{"type":"http","scheme":"bearer","bearerFormat":"Parcellab-API-Token base64(account_id:token)","description":"Send `Authorization: Parcellab-API-Token <encoded-token>`.\n\n`<encoded-token>` = `base64(account_id:token)` as provided in the portal."}},"schemas":{"PaginatedReturnConfigurationList":{"type":"object","required":["count","results"],"properties":{"count":{"type":"integer"},"next":{"type":"string","nullable":true,"format":"uri"},"previous":{"type":"string","nullable":true,"format":"uri"},"results":{"type":"array","items":{"$ref":"#/components/schemas/ReturnConfiguration"}}}},"ReturnConfiguration":{"type":"object","description":"Represents a return configuration set, including courier mappings and returnable periods","properties":{"id":{"type":"integer","readOnly":true},"account":{"type":"integer"},"code":{"type":"string","title":"Configuration Code","description":"Configuration code of the return configuration","maxLength":128},"client":{"type":["integer","null"]},"courier_mappings":{"type":"array","items":{"$ref":"#/components/schemas/ReturnCourierMapping"},"readOnly":true},"returns_order_api":{"type":["integer","null"],"description":"The API to be used to fetch order information"},"returns_rules":{"type":["integer","null"],"description":"Returns reasons to use for this portal"},"returnable_periods":{"type":"array","items":{"$ref":"#/components/schemas/ReturnablePeriod"},"readOnly":true}},"required":["account","code","courier_mappings","id","returnable_periods"]},"ReturnCourierMapping":{"type":"object","description":"Represents a courier mapping configuration","properties":{"courier_api":{"allOf":[{"$ref":"#/components/schemas/ReturnCourierAPI"}],"readOnly":true},"filter":{"type":"object"}},"required":["courier_api"]},"ReturnCourierAPI":{"type":"object","description":"Represents a courier API configuration","properties":{"account":{"type":"integer"},"name":{"type":"string","maxLength":255},"courier_code":{"type":"string","description":"Code used for the translation for the courier in the returns portal.","maxLength":255},"identifier":{"type":"string","description":"Identifier, for instance Warehouse code","maxLength":255},"has_oauth_credential":{"type":"boolean","readOnly":true},"service_levels":{"type":"array","items":{"$ref":"#/components/schemas/ReferenceItem"},"readOnly":true},"service_name":{"type":"string","readOnly":true},"service_config":{"type":"string","readOnly":true}},"required":["account","courier_code","has_oauth_credential","name","service_config","service_levels","service_name"]},"ReferenceItem":{"type":"object","description":"Public reference item (key/name/type) used in lookups and mappings.","properties":{"key":{"type":"string","maxLength":128},"name":{"type":"string","maxLength":200},"type":{"$ref":"#/components/schemas/ReferenceItemEnum"},"updated_at":{"type":"string","format":"date-time","readOnly":true}},"required":["key","name","type","updated_at"]},"ReferenceItemEnum":{"enum":["destination-country-iso3","client","courier","warehouse","courier-service-level","delivery-method","delivery-info-market","payment-method","order-status","claim-reason","return-reject-reason","delivery-timezone","delivery-region","delivery-location","delivery-status","delivery-exception","tracking-tags"],"type":"string","description":"* `destination-country-iso3` - Destination Country ISO3\n* `client` - Client\n* `courier` - Courier\n* `warehouse` - Warehouse\n* `courier-service-level` - Courier Service Level\n* `delivery-method` - Delivery Method\n* `delivery-info-market` - Delivery Info Market\n* `payment-method` - Payment Method\n* `order-status` - Order Status\n* `claim-reason` - Claim Reason\n* `return-reject-reason` - Return Reject Reason\n* `delivery-timezone` - Timezone (Delivery Info)\n* `delivery-region` - Region (Destination)\n* `delivery-location` - Delivery Location\n* `delivery-status` - Delivery Status\n* `delivery-exception` - Delivery Exception\n* `tracking-tags` - Tracking Tags"},"ReturnablePeriod":{"type":"object","description":"Represents a returnable period configuration","properties":{"description":{"type":"string","maxLength":100},"trial_period":{"type":"integer","maximum":2147483647,"minimum":-2147483648,"description":"in days"},"grace_period":{"type":"integer","maximum":2147483647,"minimum":-2147483648,"title":"Grace Period (order date)","description":"Grace period (OrderDate) in days is calculated from the OrderDate in days"},"grace_period_shipping_date":{"type":"integer","maximum":2147483647,"minimum":-2147483648,"title":"Grace Period (shipping date)","description":"Grace period (ShippingDate) in days is calculated from the ShippingDate in days"},"is_warranty_period":{"type":"boolean"},"filter":{"type":"object"}},"required":["description","grace_period","is_warranty_period","trial_period"]},"Error400Response":{"type":"object","properties":{"type":{"type":"string"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/GenericErrorItem"}}},"required":["errors","type"]},"GenericErrorItem":{"type":"object","properties":{"code":{"type":"string"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["code","detail"]},"ErrorResponse403":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ClientErrorEnum"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error403"}}},"required":["errors","type"]},"ClientErrorEnum":{"enum":["client_error"],"type":"string","description":"* `client_error` - Client Error"},"Error403":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode403Enum"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["attr","code","detail"]},"ErrorCode403Enum":{"enum":["permission_denied"],"type":"string","description":"* `permission_denied` - Permission Denied"}}},"paths":{"/v4/returns/returns-configurations/":{"get":{"operationId":"returns_returns_configurations_list","description":"Return configuration (sets) represent a bundle of configurations, that are available with that configuration code\non an account. The configuration set for instance groups configurations, such as Courier APIs for a specific country\nor language.","summary":"List Return Configuration","parameters":[{"in":"query","name":"account","schema":{"type":"array","items":{"type":"integer"}},"explode":true,"style":"form"},{"name":"limit","required":false,"in":"query","description":"Number of results to return per page.","schema":{"type":"integer"}},{"name":"offset","required":false,"in":"query","description":"The initial index from which to return the results.","schema":{"type":"integer"}},{"name":"ordering","required":false,"in":"query","description":"Which field to use when ordering the results.","schema":{"type":"string"}}],"tags":["Return Configuration Set"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedReturnConfigurationList"}}},"description":""},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400Response"}}},"description":""},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse403"}}},"description":""}}}}}}
```

## Get a Return Configuration

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

## Retrieve Return Configuration

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

```json
{"openapi":"3.1.0","info":{"title":"parcelLab API","version":"v4"},"security":[{"OAuth2 Authentication":[]},{"HeaderToken":[]}],"components":{"securitySchemes":{"OAuth2 Authentication":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"HeaderToken":{"type":"http","scheme":"bearer","bearerFormat":"Parcellab-API-Token base64(account_id:token)","description":"Send `Authorization: Parcellab-API-Token <encoded-token>`.\n\n`<encoded-token>` = `base64(account_id:token)` as provided in the portal."}},"schemas":{"ReturnConfiguration":{"type":"object","description":"Represents a return configuration set, including courier mappings and returnable periods","properties":{"id":{"type":"integer","readOnly":true},"account":{"type":"integer"},"code":{"type":"string","title":"Configuration Code","description":"Configuration code of the return configuration","maxLength":128},"client":{"type":["integer","null"]},"courier_mappings":{"type":"array","items":{"$ref":"#/components/schemas/ReturnCourierMapping"},"readOnly":true},"returns_order_api":{"type":["integer","null"],"description":"The API to be used to fetch order information"},"returns_rules":{"type":["integer","null"],"description":"Returns reasons to use for this portal"},"returnable_periods":{"type":"array","items":{"$ref":"#/components/schemas/ReturnablePeriod"},"readOnly":true}},"required":["account","code","courier_mappings","id","returnable_periods"]},"ReturnCourierMapping":{"type":"object","description":"Represents a courier mapping configuration","properties":{"courier_api":{"allOf":[{"$ref":"#/components/schemas/ReturnCourierAPI"}],"readOnly":true},"filter":{"type":"object"}},"required":["courier_api"]},"ReturnCourierAPI":{"type":"object","description":"Represents a courier API configuration","properties":{"account":{"type":"integer"},"name":{"type":"string","maxLength":255},"courier_code":{"type":"string","description":"Code used for the translation for the courier in the returns portal.","maxLength":255},"identifier":{"type":"string","description":"Identifier, for instance Warehouse code","maxLength":255},"has_oauth_credential":{"type":"boolean","readOnly":true},"service_levels":{"type":"array","items":{"$ref":"#/components/schemas/ReferenceItem"},"readOnly":true},"service_name":{"type":"string","readOnly":true},"service_config":{"type":"string","readOnly":true}},"required":["account","courier_code","has_oauth_credential","name","service_config","service_levels","service_name"]},"ReferenceItem":{"type":"object","description":"Public reference item (key/name/type) used in lookups and mappings.","properties":{"key":{"type":"string","maxLength":128},"name":{"type":"string","maxLength":200},"type":{"$ref":"#/components/schemas/ReferenceItemEnum"},"updated_at":{"type":"string","format":"date-time","readOnly":true}},"required":["key","name","type","updated_at"]},"ReferenceItemEnum":{"enum":["destination-country-iso3","client","courier","warehouse","courier-service-level","delivery-method","delivery-info-market","payment-method","order-status","claim-reason","return-reject-reason","delivery-timezone","delivery-region","delivery-location","delivery-status","delivery-exception","tracking-tags"],"type":"string","description":"* `destination-country-iso3` - Destination Country ISO3\n* `client` - Client\n* `courier` - Courier\n* `warehouse` - Warehouse\n* `courier-service-level` - Courier Service Level\n* `delivery-method` - Delivery Method\n* `delivery-info-market` - Delivery Info Market\n* `payment-method` - Payment Method\n* `order-status` - Order Status\n* `claim-reason` - Claim Reason\n* `return-reject-reason` - Return Reject Reason\n* `delivery-timezone` - Timezone (Delivery Info)\n* `delivery-region` - Region (Destination)\n* `delivery-location` - Delivery Location\n* `delivery-status` - Delivery Status\n* `delivery-exception` - Delivery Exception\n* `tracking-tags` - Tracking Tags"},"ReturnablePeriod":{"type":"object","description":"Represents a returnable period configuration","properties":{"description":{"type":"string","maxLength":100},"trial_period":{"type":"integer","maximum":2147483647,"minimum":-2147483648,"description":"in days"},"grace_period":{"type":"integer","maximum":2147483647,"minimum":-2147483648,"title":"Grace Period (order date)","description":"Grace period (OrderDate) in days is calculated from the OrderDate in days"},"grace_period_shipping_date":{"type":"integer","maximum":2147483647,"minimum":-2147483648,"title":"Grace Period (shipping date)","description":"Grace period (ShippingDate) in days is calculated from the ShippingDate in days"},"is_warranty_period":{"type":"boolean"},"filter":{"type":"object"}},"required":["description","grace_period","is_warranty_period","trial_period"]},"Error400Response":{"type":"object","properties":{"type":{"type":"string"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/GenericErrorItem"}}},"required":["errors","type"]},"GenericErrorItem":{"type":"object","properties":{"code":{"type":"string"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["code","detail"]},"ErrorResponse403":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ClientErrorEnum"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error403"}}},"required":["errors","type"]},"ClientErrorEnum":{"enum":["client_error"],"type":"string","description":"* `client_error` - Client Error"},"Error403":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode403Enum"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["attr","code","detail"]},"ErrorCode403Enum":{"enum":["permission_denied"],"type":"string","description":"* `permission_denied` - Permission Denied"},"ErrorResponse404":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ClientErrorEnum"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error404"}}},"required":["errors","type"]},"Error404":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode404Enum"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["attr","code","detail"]},"ErrorCode404Enum":{"enum":["not_found"],"type":"string","description":"* `not_found` - Not Found"}}},"paths":{"/v4/returns/returns-configurations/{id}/":{"get":{"operationId":"returns_returns_configurations_retrieve","description":"Return configuration (sets) represent a bundle of configurations, that are available with that configuration code\non an account. The configuration set for instance groups configurations, such as Courier APIs for a specific country\nor language.","summary":"Retrieve Return Configuration","parameters":[{"in":"path","name":"id","schema":{"type":"integer"},"description":"A unique integer value identifying this Returns Portal.","required":true}],"tags":["Return Configuration Set"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnConfiguration"}}},"description":""},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400Response"}}},"description":""},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse403"}}},"description":""},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"description":""}}}}}}
```

## Get Document Templates

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

## List Document Templates

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

```json
{"openapi":"3.1.0","info":{"title":"parcelLab API","version":"v4"},"security":[{"OAuth2 Authentication":[]},{"HeaderToken":[]}],"components":{"securitySchemes":{"OAuth2 Authentication":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"HeaderToken":{"type":"http","scheme":"bearer","bearerFormat":"Parcellab-API-Token base64(account_id:token)","description":"Send `Authorization: Parcellab-API-Token <encoded-token>`.\n\n`<encoded-token>` = `base64(account_id:token)` as provided in the portal."}},"schemas":{"PaginatedReturnDocumentTemplateList":{"type":"object","required":["count","results"],"properties":{"count":{"type":"integer"},"next":{"type":"string","nullable":true,"format":"uri"},"previous":{"type":"string","nullable":true,"format":"uri"},"results":{"type":"array","items":{"$ref":"#/components/schemas/ReturnDocumentTemplate"}}}},"ReturnDocumentTemplate":{"type":"object","description":"Template for generating return documents (labels, slips) exposed via the public API.","properties":{"id":{"type":"integer","readOnly":true},"account":{"type":"integer"},"key":{"type":"string","title":"Technical key","description":"Technical key, must not contain white space","maxLength":255,"pattern":"^[-a-zA-Z0-9_]+$"},"content":{"type":"string"},"client_key":{"type":["string","null"],"readOnly":true},"identifier":{"type":"string","description":"Optional identifier for the template to be used (e.g. language code / local)","maxLength":255}},"required":["account","client_key","id"]},"Error400Response":{"type":"object","properties":{"type":{"type":"string"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/GenericErrorItem"}}},"required":["errors","type"]},"GenericErrorItem":{"type":"object","properties":{"code":{"type":"string"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["code","detail"]},"ErrorResponse403":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ClientErrorEnum"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error403"}}},"required":["errors","type"]},"ClientErrorEnum":{"enum":["client_error"],"type":"string","description":"* `client_error` - Client Error"},"Error403":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode403Enum"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["attr","code","detail"]},"ErrorCode403Enum":{"enum":["permission_denied"],"type":"string","description":"* `permission_denied` - Permission Denied"}}},"paths":{"/v4/returns/document-templates/":{"get":{"operationId":"returns_document_templates_list","description":"Document templates are used to generate return labels, packing slips, and other documents for return registrations.","summary":"List Document Templates","parameters":[{"in":"query","name":"account","schema":{"type":"array","items":{"type":"integer"}},"explode":true,"style":"form"},{"name":"limit","required":false,"in":"query","description":"Number of results to return per page.","schema":{"type":"integer"}},{"name":"offset","required":false,"in":"query","description":"The initial index from which to return the results.","schema":{"type":"integer"}},{"name":"ordering","required":false,"in":"query","description":"Which field to use when ordering the results.","schema":{"type":"string"}}],"tags":["Return Configuration Set"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedReturnDocumentTemplateList"}}},"description":""},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400Response"}}},"description":""},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse403"}}},"description":""}}}}}}
```