Skip to content

API Guide

Introduction

The Returnista API is a REST API that provides CRUD operations on the Returnista domain. It has predictable resource-oriented URLs, returns JSON responses, and uses standard HTTP response codes, methods, and authentication.

Responses typically come in two formats:

  • Single Resource Response: When requesting a single resource, that resource will be at the immediate root of the response body. For example, a request to GET a single Return Request:
/api/v0/account/0190bb7f-4be4-7c65-8bb6-5d1dd951ac1f/return-requests/0190bb7f-900b-7214-bb49-220adf9aafca

will return a response body like this:

{
  "id": "0190b659-66a8-7d41-aed2-9a03705bed30",
  "purchaseId": "15584720257367",
  "purchaseOrderNumber": "#1004800",
  "returnOrderId": "0190b659-66a8-7d41-aed2-9a02b27b6b9d",
  "returnReasonId": "018f0f94-486b-7e21-80a3-e218001ace29",
  "returnReasonComment": "",
  "requestedResolution": "Refund"
}
  • List of Resources Response: When requesting a list of resources, they will be wrapped in a data property along with other meta properties for helping with pagination. For example, a GET request to get multiple Return Requests:
/api/v0/account/0190bb7f-4be4-7c65-8bb6-5d1dd951ac1f/return-requests

will return a response body like this:

{
  "data": [
    {
      "id": "0190b659-66a8-7d41-aed2-9a03705bed30",
      "purchaseId": "15584720257367",
      "purchaseOrderNumber": "#1004800",
      "returnOrderId": "0190b659-66a8-7d41-aed2-9a02b27b6b9d",
      "returnReasonId": "018f0f94-486b-7e21-80a3-e218001ace29",
      "returnReasonComment": "",
      "requestedResolution": "Refund"
    }
  ],
  "limit": 10,
  "page": 1,
  "nextPage": 2,
  "hasMore": true
}

Authentication

To ensure secure access to our REST API, we use Bearer Token authentication. This method requires clients to include an access token in the Authorization header of their HTTP requests. Here’s how to authenticate your requests:

curl -X GET https://core.returnista.com/api/v0/return-requests \
  -H "Authorization: Bearer your_access_token"

Obtaining an Access Token / API Key

Temporary, expiring access tokens can be obtained for users via the /auth/user endpoint.

Non-expiring account-scoped API Keys can be used as access tokens and are provided when creating a "Service User".

Expanding Responses

Many resources allow you to request additional information as an expanded response by using the expand request parameter. You can expand responses in two ways:

  1. Inline Expansion: In many cases, an object contains the ID of a related object in its response properties. For example, a ReturnOrder might have an associated consumerId. You can expand such objects inline using the expand request parameter. The expandable label in the documentation indicates ID fields that you can expand into objects.

  2. Additional Fields: Some fields aren’t included in the responses by default, such as the shipments and returnRequests fields on a ReturnOrder resource. You can request these fields as an expanded response by using the expand request parameter.

Example:

curl -X GET https://core.returnista.com/api/v0/account/0190bb7f-4be4-7c65-8bb6-5d1dd951ac1f/return-orders \
  -H "Authorization: Bearer your_access_token" \
  --data-urlencode expand=consumer --data-urlencode expand=shipments

Filtering

List responses can be refined by providing a filter query parameter with a filter clause. For example:

curl -X GET https://core.returnista.com/api/v0/account/0190bb7f-4be4-7c65-8bb6-5d1dd951ac1f/return-requests \
  -H "Authorization: Bearer your_access_token" \
  --data-urlencode filter="purchaseOrderNumber:#1004800"

This will fetch all Return Requests from an account with the order number "#1004800".

Only certain fields can be used for filtering. These are marked as filterable in the documentation.

Pagination

You can paginate through list responses using the page and limit query parameters.

  • The limit parameter defines how many results are within a page.
  • The page parameter is a cursor for pagination across multiple pages of results. Don’t include this parameter on the first call. Use the nextPage value returned in a previous response to request subsequent results.