General

You need an access token to be able to communicate with our API. The token has to be submitted on every call in the request header/gRPC metadata using method Plain.

{ 
	"Authorization": "Plain xxxxxxx-xxxx-xxxx-be5d-80a446a3d0dd"
}

You can request your access token here supplier.refurbed.com

Unused API token will expire after 2 months. In case you are affected, please request a new API token from us.

Please use a meaningful user-agent in your API requests. We suggest a format like “seller/integrator name - <default by the used request library>”, e.g.: ”refurbed - GuzzleHttp/7”

🚀 Getting Started

In this documentation, we will focus on setting up the HTTP version of our API. It is also possible to use the gRPC framework if you are familiar with it and your programming language supports it.​

To make your first API calls we suggest using a REST Client like Postman or Insomnia.

For Postman, you can download the files to import both the collection and the production and sandbox environments below. This will give you the possibility to comfortably test and develop your API connector. Our API uses only POST method.

You can find the Postman API configuration documents for Collection, Sandbox Environment and the Product environment in the attachments of this article. 

Collection

Sandbox Environment

Product Environment

For Insomnia, you can find a guide below on how to set up an environment where you can test and develop your API connector.

1) Install Insomnnia on your device and open it.

2) Install the following Insomnia Plugin: Global Headers. Go to Preferences → Plugins → enter insomnia-plugin-global-headers and hit “Install Plugin”.

3) In your workspace click on the (➕) sign top right and choose Import. Download the following file and import it. It will also create the environments prod and sandbox for you.

Insomnia API configuration

4) Open the newly imported collection, find the ⚙ icon in the top of the left panel next to the environment. Click to manage your environments. For prod please add your prod API token after Plain. For sandbox please replace <merchantname> with the sandbox name, that you receive from the integrations team. Close the the environments settings.

5) To do your first request expand Currency Service in the left panel and select Gets a single supported currency. In the JSON tab change the content to the following:

{
	"code": "EUR"
}

6) Press Send and check the Response to the right. You should see Status: 200 OK and in the response the current exchange rates from EUR to other currencies.

🎉 Congratulations 🎉 You have successfully set up Insomnia to call the refurbed API.

You can test other endpoints too (be aware of the environment, if you manipulate data 😉) and you may need to adapt the payload. Refer to the OpenAPI/Swagger.

🚧 API Rate Limits

To keep our systems stable, the API implements rate limiting. The default rate limit is 10 requests per second. Please write a sensible implementation, group updates, and use batch operations where available.

You can check the state of your rate limits using the following response headers:

• X-RateLimit-Limit: The number of requests allowed during the 1-second window.
• X-RateLimit-Remaining: The number of requests remaining in the 1-second window before encountering a 429 error.
• X-RateLimit-Reset: when the time window will reset as a unix timestamp.

❌ Error Handling

If you are having trouble with authentication please check the status code and response. Here are some typical Authentication problems.

{
  "code": 16,
  "message": "unauthenticated",
  "details": []
}

{
  "code": 16,
  "message": "malformed authorization header: fxxxxxxx-xxxx-xxxx-be5d-80a446a3d0dd",
  "details": []
}