Returns API integration (Recommended)

When your eCommerce order management system receives a return event, your system should call the Usizy API to confirm the return event as an HTTP POST to the following URL: https://usizy.com/api/v2/event/return

Essential variables

The following variables should be included in your script:

api_key

In order to authenticate, you should include your api key in the “Authorization” HTTP header, prepended with the string “Api-Key “.

For example:

Authorization: Api-Key 401f7ac837da42b97f

order_id

The order identifier must be identical to the one provided during the purchase confirmation.

product_ids

Each product identifier must be the same as the one provided during the purchase confirmation. This variable may contain a single value or multiple ones, depending on the content of the initial order.

variation_ids

Each variation id must be unique for its corresponding specific item. It is recommended to use the SKU. If more than one product is returned within a single order, you must include a list of variations, for each product returned within that specific order.

date Date or date time of return event, format ISO 8601 (“2017-09-12” or “2017-09-12T15:48:02Z”).

reason The reason for returning the product is essential to understand what type of returns are impacting your Ecommerce. Usizy reduces returns due to size error.

We recommend including the following reasons:

  • return due to size (“size”)
  • other reasons ("other”)

fit

Confirms if the size being returned is too small (“small”) or too big (“large”). This field can be left blank if no information is available. The number of fits must be equal to the number of products. If more than one value are included, they must be comma-separated.

ecomm_size

Size originally ordered during purchase. This field is useful when multiple returns are requested for the same product within a single order. The number of sizes included must match the number of products returned. If more than one product is returned, the values must be comma-separated.

Optional variables

size_changed

In case of a product exchange for a different size, the new size may be included in this field to improve machine learning. The number of size_changed must be equal to the number of products. If more than one value is included, they must be comma-separated.

return_cost

Total return shipping cost.

currency

Currency used for return-cost. ISO 4217 alpha codes

OpenAPI documentation

An OpenAPI spec with a developer-oriented documentation is available through the following link.

API returns integration script example

You may review an example of a typical script here:

API returns integration script example

API returns integration validation

If you need help validating your integration with us, please provide the confirmation code received from your browser console, after initiating a call to our API.

You can view some validation code examples here: Validation code examples