Skip to main content

Returns Warehouse

The ReturnsWarehouse API lets you retrieve, create, update, or delete warehouse addresses where customers can return parcel shipment items. You can also retrieve, create, update, or delete one or more carriers associated with each return warehouse address.

Please note that you must first remove all carriers associated with a returns warehouse address before you delete it, and you cannot delete the last remaining address.

Returns Warehouse Types​

When adding a return warehouse address, you can choose from different warehouse types:

  • NATIONAL
    Used for return warehouse addresses located within Germany.

  • INTERNATIONAL_CONSOLIDATION_HUB
    Used when the carrier supports consolidation functionality for the partner.

  • INTERNATIONAL
    Used for return warehouse addresses outside of Germany. Supported countries include: Austria, Netherlands, France, Spain, Poland, Denmark, Italy, and Czechia.

Carriers​

When linking a carrier to a warehouse, consider the supported returnWarehouseType values for each carrier:

  • Hermes
    Supports only the NATIONAL return warehouse type.

  • DHL
    Supports all three return warehouse types: NATIONAL, INTERNATIONAL, and INTERNATIONAL_CONSOLIDATION_HUB.

  • GLS
    Supports only the NATIONAL return warehouse type.

Common Use Cases​

Create a return warehouse address​

Create a return warehouse, which will later be used to generate a return label or QR code, as applicable.

POST /v2/returns-warehouse/addresses

This endpoint can create returns warehouse address for any returnWarehouseType and returns returnAddressId in response, which can be further used to fetch address details and to associate carriers.

Update a return warehouse address​

Update the returns warehouse address using returnAddressId

PUT /v2/returns-warehouse/addresses/{returnAddressId}

Once the address is created, it can be used to update most fields, except for returnWarehouseType and country.

Fetch a return warehouse address​

Fetch a specific returns warehouse address details using this endpoint. You can identify the address using returnAddressId.

GET /v2/returns-warehouse/addresses/{returnAddressId}

Fetch all the returns warehouse addresses​

Fetch all the return warehouse addresses created by you using below endpoint. This endpoint supports pagination, allowing you to specify how many return warehouses to include in each response.

GET /v2/returns-warehouse/addresses

Delete a returns warehouse address​

Delete a returns warehouse address using returnAddressId.

DELETE /v2/returns-warehouse/addresses/{returnAddressId}

If partner wants to delete any returns warehouse address, they can use above endpoint by passing returnAddressId.

Create a carrier for a return warehouse address​

Create a return carrier for a specific warehouse, via which customer can return items.

POST /v2/returns-warehouse/addresses/{returnAddressId}/carriers

This endpoint can be used to add carrier to the returns warehouse address using returnAddressId of a warehouse address. This endpoint will return returnAddressCarrierId in response that can be used to fetch/update/delete the carrier.

Update a carrier for a return warehouse address​

Update the carrier associated to returns warehouse address using returnAddressId and returnAddressCarrierId.

PUT /v2/returns-warehouse/addresses/{returnAddressId}/carriers/{returnAddressCarrierId}

Fetch a carrier for a return warehouse address​

Fetch a specific carrier associated to a returns warehouse address using this endpoint. You can identify the carrier using returnAddressId and returnAddressCarrierId..

GET /v2/returns-warehouse/addresses/{returnAddressId}/carriers/{returnAddressCarrierId}

Fetch all carriers for a returns warehouse addresses​

Fetch all the carriers associated to a return warehouse addresses. This endpoint supports pagination, allowing you to specify how many return carriers to include in each response.

GET /v2/returns-warehouse/addresses/{returnAddressId}/carriers

Delete carrier for a returns warehouse address​

Delete a carrier associated to returns warehouse address using returnAddressId and returnAddressCarrierId.

DELETE /v2/returns-warehouse/addresses/{returnAddressId}/carriers/{returnAddressCarrierId}

The last carrier associated to a standard warehouse cannot be deleted.

Example​

A typical sequence dealing with our interfaces would be:

1. You create an address for your warehouse.
2. You then associate a carrier to the address created above.
3. You can add more carriers to the address created above.
4. You can add multiple warehouse address and there corresponding carriers, if you need to handle returns from multiple warehouses.
5. You can fetch the details of the addresses created and then update the warehouse address for a specific warehouse.
6. You can delete a warehouse address if you no more need it.
7. You can fetch all carriers for a given address and then specify a specific carrier id while shipping.

Pagination​

Pagination is managed using the following parameters:

  • limit: This sets the maximum number of return warehouses returned in each response. The default limit is 20.
  • next: This is a cursor that indicates the next return warehouse to be queried.

Glossary​

  • returnWarehouseType - This field will specify the type of warehouse addresses i.e. if its NATIONAL, INTERNATIONAL or INTERNATIONAL_CONSOLIDATION_HUB as explained in Returns Warehouse Types section.
  • returnAddressId - The id of the returns address in uuid4 format used to uniquely identify a return warehouse address.
  • returnAddressCarrierId - The id of the return carrier in uuid4 format, which is linked with a returns warehouse address.
  • country - The name of the country in which the return warehouse is located.

ON THIS PAGE