# API Documentation | RecommerceIQ

> For the complete documentation index, see [llms.txt](/llms.txt). This page is the markdown version of the HTML documentation at /docs.

Integrate daily-updated resale and buyback prices into your platform via the RecommerceIQ REST API. Go live in 1 business day. Covers smartphones, tablets, laptops, and smartwatches across Europe and the US.

## Quick facts

- Time to go live: 1 business day
- Daily price points tracked: 1M+
- Data refresh rate: Daily by default (Buybox monitoring available up to every hour)
- Rate limit: 120 requests/second

## Integration steps

01. **Request access** — Contact us via the demo form. API credentials are provisioned within one business day.
02. **Authenticate** — Pass your API token in the Authorization header. Catalog API V1 uses "Bearer <token>"; Prices API V1 uses the token directly with no prefix. The auth format is shown in each API group below.
03. **Query prices** — Use the Catalog V1 or Prices V1 endpoints for new integrations. Legacy endpoints remain available.
04. **Go live** — Most clients complete integration and go live within 1 business day.

## What the API covers

### Device categories

- Smartphones
- Tablets
- Laptops & PCs
- Smartwatches

### Condition grades — Aesthetic

| Grade | Legend | Definition |
|---|---|---|
| `R` | Brand New | Never been opened. In the original box. |
| `N` | Excellent | Screen, frame, and back look as good as new with no clear signs of use. If applicable, all accessories are present. |
| `A` | Very Good | Screen, frame, or back may have minor traces of use like slight scratches or tiny dents (but never cracks). If applicable, all accessories are present. |
| `B` | Good | Screen, frame, or back have clear signs of use like scratches you can feel with a fingernail or small dents on the edges (but never cracks). If applicable, all accessories are present. |
| `C` | Acceptable | Screen, frame, or back have heavy signs of use like deep scratches you can see immediately or more evident dents on the edges (but never cracks). If applicable, all accessories are present. |
| `D` | Broken | Not fully functional. Screen, frame, or back have physical damage (cracks, pressure marks, screenburn, bent, engravings, pixel discolouration or dead pixels). If applicable, accessories can be missing. |

### Condition grades — Battery

| Grade | Legend | Definition |
|---|---|---|
| `new` | New | 100% battery capacity. No charging cycles. |
| `std` | Standard / used | Following the source website definition. Usually >80% recharge, fewer than 1000 charging cycles. |

### Markets

United States; Germany, France, Italy; Netherlands, Spain; UK, Austria; and more across Europe.

## Current APIs (V1)

## Catalog API (V1)

Use this API if you have shared your product catalog with us. We pre-map your internal SKUs to our database during onboarding, so you can query prices using your own IDs directly — no device-level attribute matching needed on your side.

### GET `/api/v1/catalog/:externalID/prices` — Retrieve price

Retrieve resale and trade-in prices for a catalogue item by your internal ID. Returns aggregate prices by country and competitor, plus individual active listings (add-on).

- Host: `https://dashboard.recommerceiq.com`
- Auth: `Authorization: Bearer YOUR_API_KEY`

**Path params:**
- `externalID` (required) — Your catalogue item internal ID

> If your catalog uses one ID per model (not per grade), append a grade suffix: e.g. YOUR_ID-n for Excellent, YOUR_ID-a for Very Good.

**Request**

```bash
curl --request GET \
  --url https://dashboard.recommerceiq.com/api/v1/catalog/YOUR_ITEM_ID/prices \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

**Response (200 OK)**

Response fields:
- `prices_by_country` — Aggregate pricing data for each market (e.g. DE, FR, UK).
- `prices_by_competitor` — Aggregate pricing data for each competitor and market (e.g. website A in DE, website B in DE).
- `active_listings` — Individual item pricing data per competitor listing (e.g. iPhone 15 Pro 256 GB grade A from website A in DE). Available as an add-on — contact us to enable.
- `suggested_price` — Price suggested after factoring in your pricing strategies set in the RecommerceIQ Dashboard. Can be resale or trade-in depending on your catalog setup.
- `median_market_price` — Aggregate median pricing across all applicable markets, before any pricing strategies. Can be resale or trade-in depending on your catalog setup.

```json
{
  "category": "Smartphone",
  "name": "iPhone XS Max",
  "suggested_price": 300.49,
  "median_market_price": 300.49,
  "currency": "EUR",
  "last_update": "2025-10-08 04:03:48",
  "resell": {
    "prices_by_country": [
      { "currency": "EUR", "country": "de", "min_price": 213.99, "max_price": 329, "average_price": 289, "median_price": 291 }
    ],
    "prices_by_competitor": [
      { "competitor": "Refurbed", "country": "de", "average_price": 269.99, "median_price": 269.99, "min_price": 213.99, "max_price": 307.99, "currency": "EUR" },
      { "competitor": "Back Market", "country": "de", "average_price": 274, "median_price": 274, "min_price": 274, "max_price": 274, "currency": "EUR" }
    ],
    "active_listings": [
      { "competitor": "Refurbed", "country": "de", "name": "Apple iPhone Xs MAX", "price": 256, "currency": "EUR", "url": "https://www.refurbed.de/p/apple-iphone-xs-max/..." }
    ]
  },
  "trade-in": {
    "prices_by_country": [
      { "currency": "EUR", "country": "de", "min_price": 58, "max_price": 75, "average_price": 69.33, "median_price": 75 }
    ],
    "prices_by_competitor": [
      { "vendor_name": "Rebuy", "country": "de", "average_price": 69.33, "median_price": 75, "min_price": 58, "max_price": 75, "currency": "EUR" }
    ],
    "active_listings": [
      { "competitor": "Rebuy", "country": "de", "name": "Apple iPhone Xs MAX", "price": 60, "currency": "EUR" }
    ]
  }
}
```

**Error responses:**

- `401 Unauthorized`

```json
{ "message": "Unauthenticated." }
```


### GET `/api/v1/catalog/:externalID/buybox/:vendorName/:vendorCountry` — Retrieve buybox price

Retrieve the current Buy Box price for a specific vendor and market for a given catalogue item.

- Host: `https://dashboard.recommerceiq.com`
- Auth: `Authorization: Bearer YOUR_API_KEY`

**Path params:**
- `externalID` (required) — Your catalogue item internal ID
- `vendorName` (required) — Vendor name e.g. ebay
- `vendorCountry` (required) — Market country code e.g. de

**Request**

```bash
curl --request GET \
  --url https://dashboard.recommerceiq.com/api/v1/catalog/YOUR_ITEM_ID/buybox/ebay/de \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

**Response (200 OK)**

Response fields:
- `price` — Current Buy Box price for this vendor and market.
- `suggested_price` — Price suggested after applying your pricing strategies set in the RecommerceIQ Dashboard.
- `is_mine` — Whether you currently hold the Buy Box for this vendor and market.

```json
{
  "suggested_price": 123.35,
  "price": 123.45,
  "is_mine": false,
  "seller_name": "Test",
  "url": "https://www.ebay.de/itm/405180570735",
  "created_at": "2025-10-08 17:11:38",
  "currency": "EUR",
  "currency_symbol": "€"
}
```

**Error responses:**

- `401 Unauthorized`

```json
{ "message": "Unauthenticated." }
```


## Prices API (V1)

Use this API if you have not shared a catalog with us. You query prices by passing device attributes directly (brand, model, grade, storage, etc.) and we return matching market prices in real time — no prior SKU mapping required.

### GET `/api/v1/prices/dictionary/:category` — Retrieve category dictionary

Retrieve available brands, models, grades, and specifications for a device category. Use this to build your query parameters for the search endpoints.

- Host: `https://dashboard.recommerceiq.com`
- Auth: `Authorization: YOUR_API_KEY`

**Path params:**
- `category` (required) — smartphone | pc | tablet | smartwatch

**Request**

```bash
curl --request GET \
  --url https://dashboard.recommerceiq.com/api/v1/prices/dictionary/pc \
  --header 'Authorization: YOUR_API_KEY'
```

**Response (200 OK)**

Returns all valid parameter keys for that category. Use these key values (not labels) in your search requests.

```json
{
  "grades": [
    { "label": "Excellent", "key": "N" },
    { "label": "Very Good", "key": "A" },
    { "label": "Good", "key": "B" },
    { "label": "Acceptable", "key": "C" },
    { "label": "Broken", "key": "D" },
    { "label": "New", "key": "R" }
  ],
  "battery": [
    { "key": "new", "label": "New" },
    { "key": "std", "label": "Used" }
  ],
  "brands": [
    {
      "name": "Apple",
      "model": [
        { "label": "MacBook Pro", "key": "MP" },
        { "label": "MacBook Air", "key": "MA" }
      ],
      "display": [
        { "label": "14 inch", "key": "14" },
        { "label": "16 inch", "key": "16" }
      ],
      "processor": [
        { "label": "M3 Max 16-Core", "key": "am3m3x16c" },
        { "label": "M3 Max 14-Core", "key": "am3m3x14c" }
      ],
      "ram": [
        { "label": "36 GB", "key": "36" },
        { "label": "48 GB", "key": "48" }
      ],
      "storage": [
        { "label": "1 TB SSD", "key": "1000SSD" },
        { "label": "2 TB SSD", "key": "2000SSD" }
      ],
      "variant": [
        { "label": "2023", "key": "23" },
        { "label": "2021", "key": "21" }
      ]
    }
  ]
}
```

**Error responses:**

- `401 Unauthorized`

```json
{ "message": "Unauthenticated." }
```


### POST `/api/v1/prices/pc/search` — Search PC prices

Search resale and trade-in prices for a specific PC configuration. Returns prices by country, by competitor, and active listings.

- Host: `https://dashboard.recommerceiq.com`
- Auth: `Authorization: YOUR_API_KEY`

**Body params:**
- `brand` (string, required)
- `grade` (enum, required) — one of: A, B, C, D, N, R
- `battery` (enum, optional) — one of: std, new (default: std)
- `model` (string, required)
- `variant` (string, optional)
- `display` (string, required)
- `processor` (string, required)
- `ram` (string, required)
- `storage` (string, required)

**Request**

```bash
curl --request POST \
  --url https://dashboard.recommerceiq.com/api/v1/prices/pc/search \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "brand": "Apple",
    "grade": "A",
    "battery": "std",
    "model": "MP",
    "display": "15",
    "processor": "i98c2-4",
    "ram": "32",
    "storage": "2000SSD"
  }'
```

**Response (200 OK)**

Same structure as Catalog API prices response. active_listings is available as an add-on — contact us to enable.

```json
{
  "category": "PC",
  "name": "Apple MacBook Pro 2019 - 2 TB SSD - 32 GB RAM - Very Good",
  "last_update": "2025-10-08 04:03:48",
  "resell": {
    "median_market_price": 1477.3,
    "currency": "EUR",
    "prices_by_country": [
      { "currency": "EUR", "country": "de", "min_price": 1328.85, "max_price": 1328.85, "average_price": 1328.85, "median_price": 1328.85 }
    ],
    "prices_by_competitor": [
      { "competitor": "buyZOXS", "country": "de", "average_price": 1328.85, "median_price": 1328.85, "min_price": 1328.85, "max_price": 1328.85, "currency": "EUR" }
    ],
    "active_listings": [
      { "competitor": "buyZOXS", "country": "de", "name": "MacBook Pro 2019 | 2000GB SSD | 32GB | i9 | 15 inch", "price": 1328.85, "currency": "EUR", "url": "https://www.buyzoxs.de/apple-macbook-pro-2019-..." }
    ]
  },
  "trade-in": {
    "median_market_price": 830.18,
    "currency": "EUR",
    "prices_by_country": [
      { "currency": "EUR", "country": "de", "min_price": 363, "max_price": 1269.23, "average_price": 830.18, "median_price": 830.18 }
    ],
    "prices_by_competitor": [
      { "vendor_name": "Rebuy", "country": "de", "average_price": 1269.23, "median_price": 1269.23, "min_price": 1269.23, "max_price": 1269.23, "currency": "EUR" },
      { "vendor_name": "MacOnline", "country": "de", "average_price": 391.13, "median_price": 391.13, "min_price": 363, "max_price": 419.25, "currency": "EUR" }
    ],
    "active_listings": [
      { "competitor": "MacOnline", "country": "de", "name": "MacBook Pro 2019 | 2000GB SSD | 32GB", "price": 363, "currency": "EUR" }
    ]
  }
}
```

**Error responses:**

- `401 Unauthorized`

```json
{ "message": "Unauthenticated." }
```

- `404 Not Found`

```json
{ "message": "Price not found." }
```


### POST `/api/v1/prices/smartphone/search` — Search smartphone prices

Search resale and trade-in prices for a specific smartphone.

- Host: `https://dashboard.recommerceiq.com`
- Auth: `Authorization: YOUR_API_KEY`

**Params:** brand, grade (required), battery (optional, default std), model, storage

> Available upon request — contact us to enable. Parameters and response structure follow /api/v1/prices/pc/search.


### POST `/api/v1/prices/tablet/search` — Search tablet prices

Search resale and trade-in prices for a specific tablet.

- Host: `https://dashboard.recommerceiq.com`
- Auth: `Authorization: YOUR_API_KEY`

**Params:** brand, grade (required), battery (optional, default std), model, storage

> Available upon request — contact us to enable. Parameters and response structure follow /api/v1/prices/pc/search.


### POST `/api/v1/prices/smartwatch/search` — Search smartwatch prices

Search resale and trade-in prices for a specific smartwatch.

- Host: `https://dashboard.recommerceiq.com`
- Auth: `Authorization: YOUR_API_KEY`

**Params:** brand, grade (required), model, storage

> Available upon request — contact us to enable. Parameters and response structure follow /api/v1/prices/pc/search.


## Legacy APIs

These endpoints remain available and are not being deprecated, but new integrations should use the V1 APIs above.

## Buyback API (Legacy)

### GET `/api/buyback/configuration` — Fetch configuration

Fetch global account configuration including available device categories.

- Host: `https://dashboard.recommerceiq.com`
- Auth: `Authorization: Bearer YOUR_API_KEY`

**Request**

```bash
curl --request GET \
  --url https://dashboard.recommerceiq.com/api/buyback/configuration \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

**Response (200 OK)**

```json
{
  "email": "recommerceiq@demo.com",
  "api_url": "https://dashboard.recommerceiq.com",
  "logo_url": "https://dashboard.recommerceiq.com/storage/images/recommerce-iq.svg",
  "favicon_url": "https://dashboard.recommerceiq.com/recommerce-iq.svg",
  "categories": [
    { "name": "Smartphone", "slug": "smartphone" },
    { "name": "PC", "slug": "pc" },
    { "name": "Smartwatch", "slug": "smartwatch" },
    { "name": "Tablet", "slug": "tablet" }
  ]
}
```

**Error responses:**

- `401 Unauthorized`

```json
{ "message": "Unauthenticated." }
```


### GET `/api/buyback/configuration/:slug` — Fetch category configuration

Fetch category-level configuration including brands, models, storage options, grade definitions, and the highest quotable price per model for a specific device category.

- Host: `https://dashboard.recommerceiq.com`
- Auth: `Authorization: Bearer YOUR_API_KEY`

**Path params:**
- `slug` (required) — pc | smartphone | tablet | smartwatch
**Query params:**
- `currency` (optional) — EUR | GBP | CHF | USD. The currency top_price and the root currency report. If omitted: your account's catalog currency, otherwise the only currency your competitors trade in. If your account covers several currencies and none is given, currency and every top_price are null; use top_prices_by_currency.

**Request**

```bash
curl --request GET \
  --url 'https://dashboard.recommerceiq.com/api/buyback/configuration/smartphone?currency=EUR' \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

**Response (200 OK)**

Use the returned model/storage/grade value fields (not key fields) as parameter values in the price request.

Response fields:
- `additional_fields` — The broken-part flags accepted by POST /api/buyback/price for this category.
- `top_price` — The highest price POST /api/buyback/price would quote for that model, across all storages and grades N, A, B and C, with every part working and your pricing strategy applied. Use it for "Up to xxx €" labels (format the label in your own UI). null when there is no market data. Smartphones only; other categories return the root currency but no top_price.
- `top_prices_by_currency` — top_price broken down per currency your account covers, each with currency, currency_symbol and price.
- `series` — Samsung only, optional — the product line a model belongs to: Galaxy S, Galaxy Z or Galaxy A. Not present on other brands' models.

```json
{
  "name": "Smartphone",
  "slug": "smartphone",
  "currency": "EUR",
  "currency_symbol": "€",
  "brands": [
    {
      "name": "Apple",
      "code": "appl",
      "additional_fields": ["biometrics", "cameras", "maximum_battery_capacity", "…"],
      "model": [
        {
          "key": "iPhone 17 Pro",
          "value": "I17Pro",
          "storage": [
            { "key": "256 GB", "value": "256" }
          ],
          "top_price": 879,
          "top_prices_by_currency": [
            { "currency": "EUR", "currency_symbol": "€", "price": 879 }
          ]
        }
      ],
      "grade": [
        { "key": "Excellent", "value": "N" }
      ]
    },
    {
      "name": "Samsung",
      "code": "sams",
      "additional_fields": ["biometrics", "cameras", "maximum_battery_capacity", "…"],
      "model": [
        {
          "key": "Galaxy S25 Ultra",
          "value": "GaS25ul",
          "series": "Galaxy S",
          "storage": [
            { "key": "256 GB", "value": "256" }
          ],
          "top_price": 612,
          "top_prices_by_currency": [
            { "currency": "EUR", "currency_symbol": "€", "price": 612 }
          ]
        }
      ],
      "grade": [
        { "key": "Excellent", "value": "N" }
      ]
    }
  ]
}
```

**Error responses:**

- `401 Unauthorized`

```json
{ "message": "Unauthenticated." }
```

- `404 Not Found`

```json
{ "error": "Category not found" }
```

- `422 Unprocessable Entity`

```json
{ "error": "Invalid currency" }
```


### POST `/api/buyback/price` — Request buyback price

Request a buyback price for a specific device. Supports smartphones, tablets, smartwatches, and PCs. Returns a single price value.

- Host: `https://dashboard.recommerceiq.com`
- Auth: `Authorization: Bearer YOUR_API_KEY`

**Params:** brand, category, model, storage, grade, currency, …broken-part flags

**Broken parts and minimum trade-in**

Each part below can be sent as an optional boolean, e.g. "flashlight": false. true means working or included; false means broken or missing; omitted counts as true. Accepted values are true / false / 1 / 0 / "1" / "0". Any other value, including the string "false", returns a 422. Flags that don't belong to the requested category are ignored. The same list is returned per category in additional_fields by Fetch category configuration.

- **smartphone:** `biometrics`, `cameras`, `maximum_battery_capacity`, `charger_included`, `fingerprint_scanner`, `startup`, `charging`, `sound_playback`, `flashlight`, `buttons`, `vibration_motor`, `original_box_included`
- **tablet:** `maximum_battery_capacity`, `charger_included`, `original_box_included`
- **smartwatch:** `maximum_battery_capacity`, `charger_included`, `original_box_included`, `original_bracelet_in_excellent_condition`
- **pc:** `maximum_battery_capacity`, `charger_included`, `power_supply_included`, `original_box_included`, `original_keyboard_included`, `original_mouse_included`

Each false flag lowers the quote by the amount set in your dashboard (Buyback strategy → Broken parts). A quote below your minimum trade-in value is raised to it. If any part is broken and the quote falls below your zero-out threshold, the price is 0. Grade D ignores flags, because the Broken grade is already priced as broken.

**Currency**

currency (EUR, GBP, CHF, USD) chooses the currency of the returned price. It is optional when your account trades in a single currency or has a catalog currency set. It is required when your account covers several currencies and none is set: without it the request returns a 422 that lists available_currencies.

**Aesthetic grade:**
- `R` — Brand New: Never been opened. In the original box.
- `N` — Excellent: Screen, frame, and back look as good as new with no clear signs of use. If applicable, all accessories are present.
- `A` — Very Good: Screen, frame, or back may have minor traces of use like slight scratches or tiny dents (but never cracks). If applicable, all accessories are present.
- `B` — Good: Screen, frame, or back have clear signs of use like scratches you can feel with a fingernail or small dents on the edges (but never cracks). If applicable, all accessories are present.
- `C` — Acceptable: Screen, frame, or back have heavy signs of use like deep scratches you can see immediately or more evident dents on the edges (but never cracks). If applicable, all accessories are present.
- `D` — Broken: Not fully functional. Screen, frame, or back have physical damage (cracks, pressure marks, screenburn, bent, engravings, pixel discolouration or dead pixels). If applicable, accessories can be missing.

**Request**

```bash
curl --request POST \
  --url https://dashboard.recommerceiq.com/api/buyback/price \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "brand": "appl",
    "category": "smartphone",
    "model": "i17pro",
    "storage": 256,
    "grade": "C",
    "currency": "EUR",
    "flashlight": false,
    "maximum_battery_capacity": false
  }'
```

**Request body — Tablet**

```json
{
  "brand": "appl",
  "category": "tablet",
  "model": "iPA13_9-7",
  "network": "wifi",
  "storage": 16,
  "grade": "C",
  "currency": "EUR",
  "charger_included": true,
  "original_box_included": true,
  "maximum_battery_capacity": true
}
```

**Request body — Smartwatch**

```json
{
  "brand": "appl",
  "category": "smartwatch",
  "model": "WSE2cell40",
  "case_material": "Al",
  "grade": "C",
  "currency": "EUR",
  "maximum_battery_capacity": true,
  "charger_included": true,
  "original_box_included": true,
  "original_bracelet_in_excellent_condition": true
}
```

**Request body — PC (desktop and laptop)**

```json
{
  "brand": "appl",
  "category": "pc",
  "model": "MA20",
  "storage": 256,
  "hd": "SSD",
  "ram": 8,
  "processor": "i32c1-1",
  "display": 13,
  "grade": "N",
  "currency": "EUR",
  "maximum_battery_capacity": false,
  "charger_included": false,
  "original_box_included": true,
  "original_keyboard_included": true,
  "original_mouse_included": true
}
```

**Response (200 OK)**

```json
{ "price": 760 }
```

**Error responses:**

- `401 Unauthorized`

```json
{ "message": "Unauthenticated." }
```

- `404 Not Found`

```json
{ "message": "Price not found." }
```

- `422 Unprocessable Entity`

```json
{
  "message": "The selected category is invalid.",
  "errors": { "category": ["The selected category is invalid."] }
}
```


## Resell API (Legacy)

### POST `/api/resell/price` — Request resale price

Request a resale price for a specific smartphone. Returns a single price value. Tablets, smartwatches, and PCs are not yet supported on this endpoint.

- Host: `https://dashboard.recommerceiq.com`
- Auth: `Authorization: Bearer YOUR_API_KEY`

**Params:** brand, category — smartphone only, name, grade

**Aesthetic grade:**
- `R` — Brand New: Never been opened. In the original box.
- `N` — Excellent: Screen, frame, and back look as good as new with no clear signs of use. If applicable, all accessories are present.
- `A` — Very Good: Screen, frame, or back may have minor traces of use like slight scratches or tiny dents (but never cracks). If applicable, all accessories are present.
- `B` — Good: Screen, frame, or back have clear signs of use like scratches you can feel with a fingernail or small dents on the edges (but never cracks). If applicable, all accessories are present.
- `C` — Acceptable: Screen, frame, or back have heavy signs of use like deep scratches you can see immediately or more evident dents on the edges (but never cracks). If applicable, all accessories are present.
- `D` — Broken: Not fully functional. Screen, frame, or back have physical damage (cracks, pressure marks, screenburn, bent, engravings, pixel discolouration or dead pixels). If applicable, accessories can be missing.

**Request**

```bash
curl --request POST \
  --url https://dashboard.recommerceiq.com/api/resell/price \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "brand": "appl",
    "category": "smartphone",
    "name": "IPhone XS Max 512GB Space Grey",
    "grade": "C"
  }'
```

**Response (200 OK)**

```json
{ "price": 760 }
```

**Error responses:**

- `401 Unauthorized`

```json
{ "message": "Unauthenticated." }
```

- `404 Not Found`

```json
{ "message": "Price not found." }
```

- `422 Unprocessable Entity`

```json
{
  "message": "The selected category is invalid.",
  "errors": { "category": ["The selected category is invalid."] }
}
```


### POST `/api/resell/price/history` — Request price history

Request historical resale prices for a smartphone by vendor, with daily min, max, average, and median prices. Tablets, smartwatches, and PCs are not yet supported.

- Host: `https://dashboard.recommerceiq.com`
- Auth: `Authorization: Bearer YOUR_API_KEY`

**Params:** brand, category — smartphone only, grade, name, battery (optional, default std)

**Aesthetic grade:**
- `R` — Brand New: Never been opened. In the original box.
- `N` — Excellent: Screen, frame, and back look as good as new with no clear signs of use. If applicable, all accessories are present.
- `A` — Very Good: Screen, frame, or back may have minor traces of use like slight scratches or tiny dents (but never cracks). If applicable, all accessories are present.
- `B` — Good: Screen, frame, or back have clear signs of use like scratches you can feel with a fingernail or small dents on the edges (but never cracks). If applicable, all accessories are present.
- `C` — Acceptable: Screen, frame, or back have heavy signs of use like deep scratches you can see immediately or more evident dents on the edges (but never cracks). If applicable, all accessories are present.
- `D` — Broken: Not fully functional. Screen, frame, or back have physical damage (cracks, pressure marks, screenburn, bent, engravings, pixel discolouration or dead pixels). If applicable, accessories can be missing.

**Battery:**
- `new` — New: 100% battery capacity. No charging cycles.
- `std` — Standard / used: Following the source website definition. Usually >80% recharge, fewer than 1000 charging cycles.

**Request**

```bash
curl --request POST \
  --url https://dashboard.recommerceiq.com/api/resell/price/history \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "brand": "appl",
    "category": "smartphone",
    "grade": "B",
    "name": "IPhone 12 256GB Space Grey",
    "battery": "new"
  }'
```

**Response (200 OK)**

```json
[
  {
    "vendor": "Swappie",
    "prices": [
      { "date": "2024-04-06", "min_price": 169, "max_price": 169, "average_price": 169, "median_price": 169 },
      { "date": "2024-04-07", "min_price": 169, "max_price": 169, "average_price": 169, "median_price": 169 },
      { "date": "2024-04-08", "min_price": 169, "max_price": 169, "average_price": 169, "median_price": 169 }
    ]
  }
]
```

**Error responses:**

- `401 Unauthorized`

```json
{ "message": "Unauthenticated." }
```

- `404 Not Found`

```json
{ "message": "Price not found." }
```

- `422 Unprocessable Entity`

```json
{
  "message": "The selected category is invalid.",
  "errors": { "category": ["The selected category is invalid."] }
}
```


## Catalog API (Legacy)

### GET `/api/catalog/:externalId/prices/buyback` — Fetch catalog trade-in prices

Fetch trade-in prices for a catalogue item by your feed ID, returned by country and grade.

- Host: `https://dashboard.recommerceiq.com`
- Auth: `Authorization: Bearer YOUR_API_KEY`

**Path params:**
- `externalId` (required) — Your catalogue item ID as listed in the feed

**Request**

```bash
curl --request GET \
  --url https://dashboard.recommerceiq.com/api/catalog/YOUR_ITEM_ID/prices/buyback \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

**Response (200 OK)**

```json
[
  {
    "country": "de",
    "prices": [
      { "grade": "A", "price": 449, "currency": "EUR" },
      { "grade": "B", "price": 419, "currency": "EUR" }
    ]
  },
  {
    "country": "fr",
    "prices": [
      { "grade": "A", "price": 409, "currency": "EUR" },
      { "grade": "B", "price": 409, "currency": "EUR" }
    ]
  }
]
```

**Error responses:**

- `401 Unauthorized`

```json
{ "message": "Unauthenticated." }
```

- `404 Not Found`

```json
{ "message": "Catalog item not found." }
```


## FAQ

### Which trade-in appraisal APIs are available for online marketplaces?

RecommerceIQ offers two. The Buyback API (`POST /api/buyback/price`) returns a trade-in offer for a device: you send brand, category, model, storage and a condition grade, and get back a price based on live market data with your own buyback strategy applied. Optional broken-part flags lower the offer for devices that are not fully working. The Prices API (V1) returns market resale and trade-in prices for the same attributes, by country and by competitor. Grades come from one defined scale: R (Brand New), N (Excellent), A (Very Good), B (Good), C (Acceptable) and D (Broken), with written definitions for each grade. The API does not inspect or grade devices; your own grading process or diagnostics tool sets the grade, and the API prices it.

---

Request API access: https://www.recommerceiq.com/register
Full documentation (Notion): https://www.notion.so/RecommerceIQ-API-documentation-886bc2eb6c584ef2b5f0b1c2d0e2f8ff
Canonical HTML page: https://www.recommerceiq.com/docs