Creating Returns from a Sale

Git RepositoryEdit on Github
Last update: 2 years ago by luigi mangaReading time: 2 min

Marketplaces may feel the need to create customized return flows.

Alongside raising returns in the Onport admin or customer portal, you can also raise and manage returns using the Onport API. Sale returns will automatically be split by in-house / dropship. When this happens, multiple sale-return objects will be created, linked back to the parent sale by the saleId attribute.

Each sale return will also have a unique reference. It will inherit the parent sale reference, then add a numerical suffix. For example, if two sale return objects were generated for a parent sale, it will generate the references 1001-01, 1001-02.

Look up the Sale objects

It's likely you'll want to look the sale up by either the externalId (this is the system ID of the order in the sales channel, such as the Shopify system Id). Or, you may want to lookup by the reference field. This can be accomplished by making the following cURL request:

curl --request GET \
--url '' \
--header 'Authorization: Bearer {{token}}'

The response will return an array containing Sale object. You will need to collect the id.

The Sales Order Id is also available from Onport's UI via the following URL: or programmatically through the Sales collection GET /api/sales.json.

Look up the Sale Items to Return

Each Sales Order contains a number of Sale Items. If you wish to return the order partially, you may want to collect the respective Sale Item ids.

The following API call retrieves a list of Sale Items by Sales Order id.

curl --request GET \
--url '' \
--header 'Authorization: Bearer {{token}}'

Generate the Return

The easiest way to generate the sale return object is to use the cancel.json endpoint. This will automatically return an array of sale return objects. One for any in-house items and one per dropship provider you are returning items for.

You can optionally pass in an array of sale-item ids to return. Or, just leave this black to return the whole sale. Setting skipQuantities will prevent the values from being pre-populated, setting the items to be returned / cancelled as 0 on the sale return items created for the sale return. After looking up theid` values from the JSON response, it is possible to prepare the API request to partially or cancel/return

curl --request POST \
--url '' \
--header "Authorization: Bearer {{token}}" \
--header 'Content-Type: application/json' \
--data '{"setQuantities":false,"ids":[id,id,id]}'
๐Ÿ”ƒ Reseller โ€” Previous
Creating a Reseller Customer
Next โ€” ๐Ÿ”ƒ Returns
Changing the Status of a Return