Key Concepts

Products

A product contains only general data of a device like e.g. dimensions or weight. Every product is related to a category. A product can have multiple variants (instances). Every product has its own unique internal id, the product_id. The product_id is currently only relevant for bid creation (Buyback). All products are created by refurbed’s Listing Team.

Instances

An instance is a variant of a product. The instance holds all specific variant data e.g. attributes like color or storage size, but also images and identifiers like MPN or GTINs. Every instance has its own unique internal id, the instance_id. All existing instances (product variants) can be found in our product catalogue. All instances are created by refurbed’s Listing Team.

Offers

An offer holds all relevant selling data, like prices, stock, currency, grade, etc. The main offer identifier is the SKU which the seller assigns. The SKU is related to an instance’s instance_id.

Create Products and its variants

Products that do not exist yet in our product catalogue can be requested by using our listing template and sending the product data to the Listing team.

💡 Providing additional identifiers like GTIN and/or MPN is beneficial for easier offer creation later.

Create Offers

Offers can be created by providing the specific selling data, like prices, stock, currency, grade, etc. as well as your SKU as a main reference. To create an offer this data must be related to an instance in our product catalogue, this can be done by referring to our instance_id or, if available, a GTIN or MPN.

Read (`GetInstance` / `BatchGetInstances`)

All services and operations concerning instances must be called with InstanceService in the URL followed by the command/operation.

https://api.refurbed.com/refb.merchant.v1.InstanceService/GetInstance

All calls must be done using POST method.

To find instances in our product catalouge you can utilitize the InstanceService endpoints. By requesting a gtin or mpn our API will return the instance_id and name. This way you can check if a product and/or its identifier is already existing in our product catalogue. We encourage you to send us identifiers like GTIN or MPN already in your listing request to improve the offer creation.

Request payload example GTIN:

**POST** <https://api.refurbed.com/refb.merchant.v1.InstanceService/GetInstance>

{
	"gtin": "0195949036248"
}

If you have a sandbox you can use the following GTIN to test: 0888462562034, 0190198746542

Request payload example MPN:

**POST** <https://api.refurbed.com/refb.merchant.v1.InstanceService/GetInstance>

{
	"mpn": "900 274 273"
}

Response example:

{
  "instance": {
    "id": "2731",
    "name": "AEG LX7-2-ÖKO Vacuum cleaner | black"
  }
}

Since MPN's can be various strings, it can happen that two or more MPN in our system become ambiguous, when they stand alone. We will handle ambiguous MPN's in the API response.

If an MPN exists for more than one instance we will return the following message:
specified MPN matches multiple instances, cannot be used to identify an instance

In such cases, you can only try to send the GTIN to get an instance match/create the offer with the identifier.