ℹ This page describes the suggested and currently most effective way to create listings/offers on refurbed. Listing requests created this way will be treated with higher priority than via email.

All services and operations concerning the offers must be called with CatalogService or OfferService in the URL followed by the command/operation.

E.g.: https://api.refurbed.com/refb.merchant.v1.OfferService/BatchCreateOffers

or

https://api.refurbed.com/refb.merchant.v1.CatalogService/GetCatalogTemplates

All calls must be done using POST method.

Our Next Gen Listing workflow allows you to send us your to be listed product and offer data in one action in contrary to our previous workflow, where listing and offer creation were two separate steps, and only offer creation was available in the Seller API.
This new workflow is a more commonly used template based workflow as it is used by many platforms and provides more convenience and scaleability to you.

Get Templates (GetCatalogTemplates)

⚠ Currently available category templates: Laptops, Desktops, Tablets, Audio, E-Bikes, Smartwatches, Accessories, Cameras, Consoles, Monitors, Printers, Smartphones and TVs. More will be added soon.

This method exposes our category templates. Provide category_type (ELECTRONICS, SPORTS or KIDS) and lang_code (DE, EN) in the request payload to retrieve all category templates for a certain category type at once. You can also specify a specific category_id to only receive the template of a certain category. On the root of the response object you will find category_id, category_name, child_templates and version. While category_id and category_name specify what their names imply child_templates will expose if there are more specific templates available for sub categories; version is incremented every time we do an update on a template.

The constraints section holds the template definitions as a list of objects, whereas each product attribute is represented by one object:

Example response:

{
  "templates": [
    {
      "constraints": [
        {
          "attribute_key": "operating_system",
          "attribute_name": "Operating System",
          "presence": "REQUIRED",
          "known_values": ["Windows 11 Home", "Windows 11 Professional"],
          "value_type": "STRING",
          "description": "iOS/Android/Windows"
        },
        {
          "attribute_key": "ram_size",
          "attribute_name": "RAM Size",
          "presence": "REQUIRED",
          "known_values": [],
          "value_type": "STRING",
          "description": "With units e.g. 4 GB",
          "unit": "GB"
        },
        [ ... ]
      ],
      "category_id": "6",
      "category_name": "Tablets",
      "childTemplates": [
        {
          "constraints": [
            {
              "attributeKey": "case_material",
              "attributeName": "Gehäusematerial",
              "presence": "OPTIONAL",
              "knownValues": [
                "Glas",
                "Plastic",
                "Metal"
              ],
              "valueType": "STRING",
              "description": ""
            },
            {
              "attributeKey": "case_colour",
              "attributeName": "Case colour",
              "presence": "OPTIONAL",
              "knownValues": [
                "Blue",
                "Red",
                "Green"
              ],
              "valueType": "STRING",
              "description": ""
            }
          ],
          "categoryId": "36",
          "categoryName": "Microsoft Tablets",
          "version": "1"
        }
      ],
      "version": "1"
    }
  ]
}

Create Listings/Offers (BatchCreateOffers)

ℹ The new workflow was implemented into the existing BatchCreateOffers method to allow an easier adoption of your already existing implementation. It is fully backwards compatible and it is still possible to simply create offers as described Offers . The new listing workflow cannot be used with the single action route (CreateOffer) as this is not the preferred and suggested method to create Listings/Offers due to performance reasons.

To create a new listing and offer we expect you to send us your product data in accordance with our outlined templates for respective category as well as offer related data like stock, price information, grading etc.

We will explain the product data part first and then the offer data part, which you might already be familiar with, if you used it before, in this case you can skip the second part.

Submitting a Listing Request

Our BatchCreateOffers method is designed to be able to take offer and product data for up to 50 items. In the request payload you need to provide a list of listing requests whereas every object can include an instance_descriptor section:

ℹ specification, instance_id, gtin and mpn are one_of fields of the same group, meaning you need to provide either of these in your request.

It is possible to submit key, val objects in the specification, that are outside the constraints as defined per template. They may help us identify and create a product more easily, however they will not have any influence on matching.

The above data concludes the product data part of your listing request, the complete your request you need to provide offer data:

Example request

{
  "offers": [
    {
      "instance_descriptor": {
        "lang_code": "EN",
        "instance_name": "BeatsX black",
        "category_id": "85",
        "specification": [
          {
            "key": "brand",
            "val": "Beats"
          },
          {
            "key": "colour",
            "val": "black"
          },
          {
            "key": "connection_type",
            "val": "Bluetooth"
          },
          {
            "key": "connectors",
            "val": "USB-C"
          },
          {
            "key": "connectivity",
            "val": "Bluetooth"
          },
          {
            "key": "headphone_type",
            "val": "Overear"
          },
          {
            "key": "no_template_key",
            "val": "random information"
          }
        ],
        "hints": {
          "mpn": "MTH52ZM/A"
        }
      },
      "sku": "Beats_x_bl_A",
      "reference_price": "200",
      "reference_currency_code": "EUR",
      "stock": 0,
      "grading": "A",
      "shipping_profile_id": "2341",
      "warranty": "M12",
      "taxation": "GROSS",
      "create_market_prices": [
        {
          "market_code": "fr",
          "currency_code": "EUR",
          "price": "82.00",
          "min_price": "72.00"
        }
      ],
      "battery_condition": null
    }
  ]
}

Prices can be defined in any of the supported currencies returned by the CurrencyService/ListCurrencies endpoint. Shipping costs have to be set within your shipping profiles.

The reference prices are the default prices used for all markets if you don’t specify any market offers. They are automatically converted into the respective market's currency if it doesn't match the offer price's currency and we have a localized site for it. The reference_price is only a reference and may be increased by refurbed due to dynamic pricing according to the merchant guide.

If you set a reference_min_price this price will be taken into consideration when calculating the BuyBox and your price could be lowered until your reference_min_price if that would make you win the BuyBox.

When creating an offer you can already create_market_prices by adding the market_code, price, currency_code, and optionally also a market-specific min_price per country if you want to set different prices in the countries you are selling in. Refer to the market offers article for more detail.

💡Learn more: Minimum Price Feature - How does it work and what are the main benefits?

If your account has been granted permission to sell devices with new battery, you will be able to create such offers directly by providing the battery_condition field in the payload. Creating offers with this attribute is only possible for certain product categories, your account manager can tell you which are eligible. Omitting the field will result in the value UNSPECIFIED. Offers with value UNSPECIFIED are treated like offers with the value OPTIMAL. So you would only need to create offers with value NEW to sell devices with new batteries.

You can use identifier matching (GTIN or MPN) like you would do with creating regular offers.

Resolution of your Listing Request

Once you sent your Listing Requests, they will immediately show up in the seller interface, if matching was possible as a valid offer with state OK and assigned instance_id. If not matchable or non-existing product the Listing Request will apper with state SUBMITTED waiting in a queue for the initial matching. If it cannot be matched automatically by our system, the state will transist to PENDING_REVIEW and awaiting manual action from refurbed’s team.

Once in review, refurbed can either resolve your request, which will create the offer and set state to OK, or reject your request due to various reasons, e.g.: device is not CE compliant, device is too old, not enough/unclear product data was provided. Refurbed will expose the Listing Request states in ListOffers as well as provide a rejection category and message (additional free text):

While some rejection reasons mark the end for you Listing Request, missing requirements or unclear data problems can be resolved by resubmitting your listing request with the same offer data, but corrected data in the specifications. This will retrigger the resolution process.

Flow Chart