Skip to content

Implementing an Ecomm Bridge

Get Purchases Endpoint

The purchases endpoint is used to retrieve order and item information to facilitate a return.

This is a JSON-RPC style endpoint where each request is a POST. We will send an order number and email address in the request body, your implementation should use this information to search for purchases accordingly.

Additionally we send a maxAgeDays field which specifies the date range of purchases to be returned (starting at the fulfillment date). This typically provides a buffer beyond the return period so it possible to inform a consumer that an order was found but that it is now ineligible for return since the return deadline has passed. The request can also specify, via the includeOtherOrders field, that purchases for all orders from that consumer should be searched for. This is relevant if this Returnista configuration option is on, or the consumer has entered the Returns Portal via a "magic link".

The response sent by the Ecomm Bridge must adhere to the Returnista Ecomm Bridge schema by mapping the structure of your orders, products and consumer data. Each item in the response should be its own Purchase row, where a “Purchase” is a line item within an order. The Purchase’s quantity of units is determined by the number of items in the “units” array field. For example, an order line item for a White T-Shirt with a quantity of three, should map to one purchase with three units. Each unit contains fields such as the paidAmount (for that unit), the returnability status and fullfillment date.

In most cases Returnista will manage if a purchase unit is returnable or not. For example, if it has already been returned via Returnista, it is in an excluded category (managed by Returnista) or it is past the end of the Return period. However, the Ecomm Bridge implementation can force the returnability to false for each unit of a purchase.

Other points to consider:

  • Ecomm Bridges are by default synchronous; the HTTP request is kept open while waiting for the response. In some integration platforms there may be a constraint where the communication flow cannot be synchronous where, once the Ecomm Bridge has found and mapped orders, it cannot respond to the original HTTP request. In this scenario, an asynchronous flow is possible. Please discuss with us if this is relevant.
  • A Purchase will typically have one payent method, but it is possible to specify multiple payment methods for a single purchase. Such as a payment split between a card and gift voucher.
  • Your fulfillment process might also play a role in this process, especially when purchases are fulfilled separately. Think of the impact this might have on the return flow to make sure purchases can only be returned when they have been received by your consumers.