Offers

Use these endpoints to fetch published (second-hand) offers and to mark shipments as received. The list endpoint includes your service fee in the returned price; the detail endpoint returns the raw offer price.

The public offer model

This is the public offer object as returned by the API. Note: in the list endpoint, price includes the service fee and a separate serviceFee property is present. In detail, serviceFee is absent and price is the raw offer price.

Properties

Name
id
Type
integer
Description
Internal identifier of the offer.
Name
ean
Type
string
Description
EAN of the offered book.
Name
price
Type
number
Description
Offer price. In GET /v1/offers?eans= this is the price including service fee; in GET /v1/offers/:id it is the raw offer price.
Name
serviceFee
Type
number?
Description
Service fee (only present in the list endpoint).
Name
condition
Type
enum
Description
Book condition: excellent | good | acceptable.
Name
remarks
Type
string?
Description
Optional seller remarks.

GET/marketplace/v1/offers?eans=...

List offers by EANs

Retrieve all published offers for one or more EANs. The result contains the total price (offer price + service fee) and a separate serviceFee field.

Required query parameters

Name
eans
Type
string
Description
Comma-separated list of EANs. Example: 9789462126510,9789024570476.

Notes

Only offers with status published are returned.
In this response, price already includes the service fee (currently €1.99), and serviceFee is provided separately.

Request

GET

/marketplace/v1/offers?eans=9789462126510,9789024570476

curl -G https://api.example.com/marketplace/v1/offers \
  -H "Authorization: Bearer {token}" \
  --data-urlencode "eans=9789462126510,9789024570476"

Response

[
  {
    "id": 123,
    "ean": "9789462126510",
    "price": 12.99,       // offer 11.00 + serviceFee 1.99
    "serviceFee": 1.99,
    "condition": "good",
    "remarks": "Minor wear"
  },
  {
    "id": 456,
    "ean": "9789024570476",
    "price": 8.49,        // offer 6.50 + serviceFee 1.99
    "serviceFee": 1.99,
    "condition": "excellent",
    "remarks": null
  }
]

Validation error · 400

{ "error": "Please provide EANs to get" }

GET/marketplace/v1/offers/:id

Retrieve an offer

Fetch a single offer by its id. This response returns the raw offer price (without service fee).

Path parameters

Name
id
Type
integer
Description
Offer identifier.

Request

GET

/marketplace/v1/offers/123

curl https://api.example.com/marketplace/v1/offers/123 \
  -H "Authorization: Bearer {token}"

Response

{
  "id": 123,
  "ean": "9789462126510",
  "price": 11.00,          // raw offer price (no service fee)
  "condition": "good",
  "remarks": "Minor wear"
}

Not found · 404

{ "error": "Not found" }

POST/marketplace/v1/offers/received

Mark offers as received

Mark one or more offers as received. Each offer is set to status received. If all items of a related order are received, the order status is updated to delivered and a downstream job (Snelstart) is queued.

Body

Name
offerIds
Type
integer[]
Description
List of offer IDs that were received.

Behavior

Processed atomically per request via a database transaction.
Sets the order to delivered if no non-received items remain.
Publishes a snelstart: fulfilment-delivered job with the order id.

Request

POST

/marketplace/v1/offers/received

curl -X POST https://api.example.com/marketplace/v1/offers/received \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{ "offerIds": [123, 456, 789] }'

Response

{ "success": true }

Server error · 500

{ "error": "Something went wrong while updating the sales line." }

Authentication

All endpoints require a valid Bearer token in the header: Authorization: Bearer <token>.