refurbished supplier API

General

This is the Refurbished store API. With this API you can add products, get orders and create shipments. Below here are alle the available endpoints.

Getting Started: Selling on Our Platform

To begin selling on our platform, you need to upload your product inventory to our system. This can be done using the offer/create endpoint. Ensure that your product data is complete and accurate to avoid issues during listing.

Step 1: Push Your Listings

Once you have successfully added your product listings via the offer/create endpoint, they will be visible to customers on our platform.

Step 2: Manage Orders

When a customer places an order, you need to process it promptly. To retrieve all open orders, use the offer/list endpoint. These open orders represent purchases made by customers and require your immediate attention.

  • Acknowledge or Decline Orders:
    Use the order/acknowledge or order/decline endpoint to either confirm or reject an order. Once processed, the order will no longer appear in the results from the offer/list endpoint.

Step 3: Ship the Order

After acknowledging an order and preparing it for shipment, you must provide tracking and serial information. This ensures transparency and a smooth delivery process.
To submit this information, call the order/shipment endpoint and include the following details:

  • Tracking and tracing link
  • Product serial numbers (if applicable)

Authentication

Before you start, make sure you have a token. You cannot connect with us without a token. The API uses bearer authentication.

Authorization: Bearer <token>

Base URL

The base URL for the API is https://connect.refurbished.nl/api/v3/ .

Testing

We recommend that you test your application on our test environment first. The test environment has an unique token.

The base URL for the test enviroment is https://connecttest.refurbished.nl/api/v3/ .

Api client example

$token = 'klu3mAyKtvQNLPyv8TQ8kEeQMVBVcFjl';//your token here

$client = new GuzzleHttp\Client([
    'base_uri'      => 'https://connect.refurbished.nl/api/v3/',
    'http_errors'   => false,
    'headers'       => [
        'Authorization' => 'Bearer ' . $token,
        'Accept'        => 'application/json'
    ]
]);

$options = array(
	'body' => json_encode(
		[
           [
                'product_title'     => 'Iphone X 32gb space gray',
                'grade'	            => 'a',
                'price'             => 700.00,
                'margin'            => 0,
                'stock'             => 20
           ]
        ]
    )
);

$response = $client->request('POST', 'offer/stock', $options);

print_r(json_decode($response->getBody()->getContents()));

Postman

You can view the online postman files on: https://www.postman.com/satellite-geoscientist-21379561/live/collection/xdu1dcp/refurbished?action=share&creator=26349042
Here you can also download the example postman files.

Rate limiting

All endpoints have a rate limiting off 50 calls per minute.

GET offer/list?{page}

Getting a list of all products with the option to add a page number as parameter

Request parameters:

Name Optional Description
Page Yes Page number

Request:

offer/list?page=1

Response:

{
    "status": "success",
    "result": [
         {
            "offer_guid": "bcaa0359-ddb8-4e68-b778-8517ed534e7a",
            "offer_id": 532924,
            "product_id": 1,
            "condition": "new",
            "grade": "",
            "product_title": "Lightning kabel",
            "price": 150,
            "retail_price": 150,
            "margin": true,
            "stock": -1,
            "ean": ""
        }
    ]
}

GET offer/find/{product_id}

Find product by its product_id.

Name Type Description
product_id int

Request:

offer/find/{product_id}

Response:

{
    "status": "success",
    "result": {
        "offer_guid": "bcaa0359-ddb8-4e68-b778-8517ed534e7a",
        "offer_id": 532924,
        "product_id": 1,
        "condition": "new",
        "grade": "",
        "product_title": "Lightning kabel",
        "price": 150,
        "retail_price": 150,
        "margin": true,
        "stock": -1,
        "ean": ""
    }
}

POST offer/create

Push your stock and product information to Refurbished.

Request parameters:

Name Type Description Required
offer_guid string Offer identifier
offer_id int Unique offer id
product_id int Product identifier
product_title string Product title
condition string refurbished/new
grade string Add the grade of the product here. See grades description for more information.
price float Sale price on platform
margin boolean True if the product has been bought without VAT
stock int Amount of stock available
ean int EAN number

When a product is already created, the only required field is product_id.

Request:

[
    {
        "product_id": "",
        "product_title": "iPhone X wit 64GB",
        "condition": "refurbished",
        "grade": "q",
        "price": 110.00,
        "margin": "1",
        "stock": 10
    },
    {
        "product_id": 1,
        "product_title": "Lightning kabel",
        "condition": "new",
        "price": 150.00,
        "margin": true,
        "stock": -1
    }
]

Response:

{
    "status": "success",
    "result": [
        {
            "status": "failed",
            "product": {
                "product_id": "",
                "condition": "refurbished",
                "grade": "q",
                "product_title": "iPhone X wit 64GB",
                "price": 110,
                "reatail_price": 150,
                "margin": "1",
                "stock": 10,
                "ean": ""
            },
            "errors": [
                "Grade is incorrect. Should be A, B or C",
                "Field product_id is required",
                "Field margin should be a boolean"
            ]
        },
        {
            "status": "created",
            "product": {
                "offer_guid": "bcaa0359-ddb8-4e68-b778-8517ed534e7a",
                "offer_id": 532924,
                "product_id": 1,
                "condition": "new",
                "product_title": "Lightning kabel",
                "grade": "",
                "price": 150,
                "reatail_price": 150,
                "margin": true,
                "stock": -1,
                "ean": ""
            }
        }
    ]
}

DELETE offer/delete/{guid}

Delete a product by guid.

Name Type Description
guid string

Request:

offer/delete/{guid}

Response:

{
    "status": "success",
    "result": {
      "product_id": 1
    }
}

GET order/list?{page}

Getting a list of all unacknowledged orders with the option to add a page number as parameter

Request parameters:

Name Optional Description
Page Yes Page number

Request:

order/list?page=1

Response:

{
    "status": "success",
    "result": [
        {
            "order_number": "ORD82065455",
            "order_guid": "bcaa0359-ddb8-4e68-b778-8517ed534e7a",
            "created_at": "2020-08-16 12:44:18",
            "customer": {
                "customer_guid": "bcaa0359-ddb8-4e68-b778-8517ed534e7a",
                "company_name" : "Refurbished.nl BV",
                "vat_number": "NL855918998B01",
                "gender": "M",
                "first_name": "Jan",
                "last_name": "De Vries",
                "address": "Dijnselburgerlaan 7",
                "zip": "3705 LP",
                "city": "Zeist",
                "country": "NL",
                "phone": "0031853033799",
                "email": "klantenservice@refurbished.nl"
            },
            "products": [
                {
                    "order_product_guid": "bcaa0359-ddb8-4e68-b778-8517ed534e7a",
                    "product_guid": "bcaa0359-ddb8-4e68-b778-8517ed534e7a",
                    "product_id": "12112",
                    "offer_id": "32158",
                    "status": "open",
                    "quantity": "1",
                    "retail_price": "297.00",
                    "price": "330.00",
                    "fee": "30.00",
                    "tax": "0.00",
                    "taxrate": 0,
                    "tracking_url": ""
                }
            ]
        }
    ]
}

GET order/find/{order_number}

Retrieve an order by its order number.

Name Type Description
order_number String Page number

Request:

order/find/{order_number}

Response:

{
    "status": "success",
    "result": {
      "order_number": "ORD82065455",
      "order_guid": "bcaa0359-ddb8-4e68-b778-8517ed534e7a",
      "created_at": "2020-08-16 12:44:18",
      "customer": {
        "customer_guid": "bcaa0359-ddb8-4e68-b778-8517ed534e7a",
        "company_name" : "Refurbished.nl BV",
        "vat_number": "NL855918998B01",
        "gender": "M",
        "first_name": "Jan",
        "last_name": "De Vries",
        "address": "Dijnselburgerlaan 7",
        "zip": "3705 LP",
        "city": "Zeist",
        "country": "NL",
        "phone": "0031853033799",
        "email": "klantenservice@refurbished.nl"
      },
      "products": [
        {
          "order_product_guid": "bcaa0359-ddb8-4e68-b778-8517ed534e7a",
          "product_guid": "bcaa0359-ddb8-4e68-b778-8517ed534e7a",
          "product_id": "12112",
          "offer_id": "32158",
          "status": "acknowledged",
          "quantity": "1",
          "retail_price": "297.00",
          "price": "330.00",
          "fee": "30.00",
          "tax": "0.00",
          "taxrate": 0,
          "tracking_url": ""
        }
    }

POST order/acknowledge/{guid}

Name Type Description
guid string GUID of the order product

Giving confirmation of the order

Request:

order/acknowledge/{guid}

{
    "order_id": "test123
}

Response:


{

  "status": "success",
  "result": {
    "order_guid": "328bb4b6-079c-4155-980f-f2fe0a98a7a9",
    "order_number": "ORD304834",
    "external_id": "o-1234"
  }
}

POST order/decline/{guid}

Name Type Description
guid string GUID of the order product

Declining an error in case the product is not in stock(anymore).

Request:

order/decline/{guid}

{
    "reason": "My reason for declining the order
}

Response:


{

  "status": "success",
  "result": {
    "order_product_guid": "328bb4b6-079c-4155-980f-f2fe0a98a7a9",
    "order_number": "ORD304834"
  }
}

POST order/shipment/{guid}

Getting a shipment with the guid you got from the offer/create earlier

Request parameters:

Name Type Description
GUID string GUID of the order product
serials array Should be an imei for phones, for all the other products serial.

Request:

order/shipment/{guid}

{
    "tracking_url": "https://postnl.nl/tracktrace/?B=3SNOCV7483762&P=2640&D=BE&T=C&L=NL",
    "serials": [
        "FHLXh463KDH9",
        "DMPWQDD2JF8J"
    ]
}

Response:

{
    "status": "success",
    "result": {
        "order_guid": "328bb4b6-079c-4155-980f-f2fe0a98a7a9",
        "order_number": "ORD304834",
        "tracking_url": "https://postnl.nl/tracktrace/?B=3SNOCV7483762&P=2640&D=BE&T=C&L=NL",
        "serials": [
            "FHLXh463KDH9",
            "DMPWQDD2JF8J"
        ]
    }
}

POST order/refund/{guid}

Getting a refund with the guid you got from the order/list earlier

Request parameters:

Name Type Description
GUID string GUID of the order product
quantity int Item amount to be refunded
reason_id int See refund reasons

Request:

order/refund/{guid}

{
    "reason_id": 1,
    "quantity": 1
}

Response:

{
    "status": "success",
    "result": {
        "order_product_guid": "328bb4b6-079c-4155-980f-f2fe0a98a7a9",
        "order_number": "ORD304834"
    }
}

Variables

Country codes

This API uses the ISO 3166-1 standard for country codes. For more information about the ISO standard visit the following url: http://en.wikipedia.org/wiki/ISO_3166-1


Gender

Code Gender
M Male
F Female

Grades

For a more information about the grades on Refurbished go to :https://www.refurbished.store/customer-service/product-conditions

Value Description
P Premium (not allowed for all suppliers)
A As good as new
B Light usage
C Visible signs of use

Statuses

Value Description
open Order is placed by the customer, but not yet approved/declined by the supplier
acknowledged Order is acknowledged by the supplier with external ID
shipped Order has been shipped. Track&Trace and serials have been sent
declined Order is declined by the supplier

Reasons

ID Description
1 Cancellation before delivery
2 Out of stock
3 Revocation
4 Warranty

Statuscodes

Code Type
200 Success
400 Bad Request
401 Unauthorized
429 Too Many Requests