API reference / Collectors

Holds

8 operations.

GET/api/v1/holds

List my holds

Signed in

The caller’s holds, newest first, with the book and the store.

SDK: collector.listMyHolds()
Key scopes: holds:read(API keys are coming soon)
Headers: If-None-MatchX-Request-Id

Responses

200The holds.
object
- holdsarray of MyHoldrequired
304Not modified: your copy (the ETag in If-None-Match) is current.

Errors (401, 500)

401unauthorized
unauthorized: Not signed in (no session or token, or an expired one).
500internal
internal: Something went wrong on our side (quote the requestId).

curl

curl 'https://collection.id/api/v1/holds' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN"

TypeScript SDK

await collector.listMyHolds();

POST/api/v1/holds

Ask a store to hold a book

Signed inIdempotent

Ask the store to set copies of a listing aside. The store accepts or declines within 48 hours; an accepted hold keeps the book aside for the store’s hold days.

SDK: collector.requestHold()
Key scopes: holds:write(API keys are coming soon)
Headers: Idempotency-KeyX-Request-Id

Request body (required, application/json)

object

listingIdstring (uuid)required
quantityintegeroptional1–50 · default 1
messagestring or nulloptionalat most 1000 characters

Responses

201The hold request.
object
- holdHoldrequired

Errors (400, 401, 409, 422, 429, 500)

400invalid_request invalid_json invalid_idempotency_key
invalid_request: The query or body doesn’t match the schema (see errors[]).
invalid_json: The body isn’t JSON.
invalid_idempotency_key: The Idempotency-Key isn’t 1–255 visible ASCII characters.
401unauthorized
unauthorized: Not signed in (no session or token, or an expired one).
409idempotency_in_progress listing_unavailable store_unavailable store_closed holds_unavailable too_many_holds invalid_quantity own_store
idempotency_in_progress: The first request with this key is still running.
listing_unavailable: The book isn’t listed, or not enough copies are left.
store_unavailable: The store isn’t taking requests right now.
store_closed: The store has closed.
holds_unavailable: The store isn’t taking holds right now.
too_many_holds: The caller has too many open holds.
invalid_quantity: Hold between 1 and 50 copies, no more than are listed.
own_store: The book is in the caller’s own store.
422idempotency_key_reused
idempotency_key_reused: This key was used for a different request.
429rate_limited
rate_limited: Too many requests; wait the Retry-After seconds.
500internal
internal: Something went wrong on our side (quote the requestId).

curl

curl -X POST 'https://collection.id/api/v1/holds' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d @body.json

TypeScript SDK

await collector.requestHold({ body: { … } });

POST/api/v1/holds/{holdId}/cancel

Cancel a hold

Signed inIdempotent

The buyer cancels, or the store releases a hold. A store releasing an accepted hold records "no sale" and puts the copies back on the shelf.

SDK: collector.cancelHold()
Key scopes: holds:writestore:holds:write(API keys are coming soon)
Headers: Idempotency-KeyX-Request-Id

Parameters

Name	In	Type	About
`holdId`required	path	string (uuid)

Responses

200The closed hold.
object
- holdHoldrequired

Errors (400, 401, 404, 409, 422, 500)

400invalid_idempotency_key
invalid_idempotency_key: The Idempotency-Key isn’t 1–255 visible ASCII characters.
401unauthorized
unauthorized: Not signed in (no session or token, or an expired one).
404not_found
not_found: Nothing at that address.
409idempotency_in_progress invalid_state
idempotency_in_progress: The first request with this key is still running.
invalid_state: The hold isn’t in a state that allows this (already answered, closed…).
422idempotency_key_reused
idempotency_key_reused: This key was used for a different request.
500internal
internal: Something went wrong on our side (quote the requestId).

curl

curl -X POST 'https://collection.id/api/v1/holds/<holdId>/cancel' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"

TypeScript SDK

await collector.cancelHold({ path: { holdId } });

POST/api/v1/holds/{holdId}/complete

Record the sale

Signed inIdempotent

The store closes an accepted hold as sold at the final price. That records the seller fee and asks the buyer to confirm the purchase.

SDK: collector.completeHold()
Key scopes: store:holds:write(API keys are coming soon)
Headers: Idempotency-KeyX-Request-Id

Parameters

Name	In	Type	About
`holdId`required	path	string (uuid)

Request body (required, application/json)

object

finalPriceCentsintegerrequired0–2000000000

Responses

200The sold hold, and the fee it recorded.
object
- holdHoldrequired
- feeobject or nullrequired
  Fields of fee
  fee_centsintegerrequired
  fee_bpsintegerrequired
  currencystringrequired

Errors (400, 401, 403, 404, 409, 422, 500)

400invalid_request invalid_json invalid_idempotency_key
invalid_request: The query or body doesn’t match the schema (see errors[]).
invalid_json: The body isn’t JSON.
invalid_idempotency_key: The Idempotency-Key isn’t 1–255 visible ASCII characters.
401unauthorized
unauthorized: Not signed in (no session or token, or an expired one).
403forbidden
forbidden: The caller’s side can’t do this (only the store answers a request…).
404not_found
not_found: Nothing at that address.
409idempotency_in_progress invalid_state
idempotency_in_progress: The first request with this key is still running.
invalid_state: The hold isn’t in a state that allows this (already answered, closed…).
422idempotency_key_reused
idempotency_key_reused: This key was used for a different request.
500internal
internal: Something went wrong on our side (quote the requestId).

curl

curl -X POST 'https://collection.id/api/v1/holds/<holdId>/complete' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d @body.json

TypeScript SDK

await collector.completeHold({ path: { holdId }, body: { … } });

POST/api/v1/holds/{holdId}/confirm

Confirm the purchase

Signed in

The buyer answers "Did you buy this?" after the store records the sale.

SDK: collector.confirmHoldPurchase()
Key scopes: holds:write(API keys are coming soon)
Headers: X-Request-Id

Parameters

Name	In	Type	About
`holdId`required	path	string (uuid)

Request body (required, application/json)

object

confirmedbooleanrequired

Responses

200The hold with the buyer’s answer.
object
- holdHoldrequired

Errors (400, 401, 403, 404, 409, 500)

400invalid_request invalid_json
invalid_request: The query or body doesn’t match the schema (see errors[]).
invalid_json: The body isn’t JSON.
401unauthorized
unauthorized: Not signed in (no session or token, or an expired one).
403forbidden
forbidden: The caller’s side can’t do this (only the store answers a request…).
404not_found
not_found: Nothing at that address.
409invalid_state
invalid_state: The hold isn’t in a state that allows this (already answered, closed…).
500internal
internal: Something went wrong on our side (quote the requestId).

curl

curl -X POST 'https://collection.id/api/v1/holds/<holdId>/confirm' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN" \
  -H 'Content-Type: application/json' \
  -d @body.json

TypeScript SDK

await collector.confirmHoldPurchase({ path: { holdId }, body: { … } });

GET/api/v1/holds/{holdId}/messages

Read a hold’s messages

Signed in

The thread between the buyer and the store’s staff, oldest first.

SDK: collector.listHoldMessages()
Key scopes: holds:readstore:holds:read(API keys are coming soon)
Headers: If-None-MatchX-Request-Id

Parameters

Name	In	Type	About
`holdId`required	path	string (uuid)

Responses

200The messages.
object
- messagesarray of HoldMessagerequired
304Not modified: your copy (the ETag in If-None-Match) is current.

Errors (401, 404, 500)

401unauthorized
unauthorized: Not signed in (no session or token, or an expired one).
404not_found
not_found: Nothing at that address.
500internal
internal: Something went wrong on our side (quote the requestId).

curl

curl 'https://collection.id/api/v1/holds/<holdId>/messages' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN"

TypeScript SDK

await collector.listHoldMessages({ path: { holdId } });

POST/api/v1/holds/{holdId}/messages

Message about a hold

Signed inIdempotent

The other side gets one notification per unread thread.

SDK: collector.postHoldMessage()
Key scopes: holds:writestore:holds:write(API keys are coming soon)
Headers: Idempotency-KeyX-Request-Id

Parameters

Name	In	Type	About
`holdId`required	path	string (uuid)

Request body (required, application/json)

object

bodystringrequired1–2000 characters

Responses

201The message.
object
- messageHoldMessagerequired

Errors (400, 401, 404, 409, 422, 429, 500)

400invalid_request invalid_json invalid_idempotency_key
invalid_request: The query or body doesn’t match the schema (see errors[]).
invalid_json: The body isn’t JSON.
invalid_idempotency_key: The Idempotency-Key isn’t 1–255 visible ASCII characters.
401unauthorized
unauthorized: Not signed in (no session or token, or an expired one).
404not_found
not_found: Nothing at that address.
409idempotency_in_progress
idempotency_in_progress: The first request with this key is still running.
422idempotency_key_reused
idempotency_key_reused: This key was used for a different request.
429rate_limited
rate_limited: Too many requests; wait the Retry-After seconds.
500internal
internal: Something went wrong on our side (quote the requestId).

curl

curl -X POST 'https://collection.id/api/v1/holds/<holdId>/messages' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d @body.json

TypeScript SDK

await collector.postHoldMessage({ path: { holdId }, body: { … } });

POST/api/v1/holds/{holdId}/respond

Accept or decline a hold request

Signed inIdempotent

The store sets the book aside (accept), or declines with an optional reason.

SDK: collector.respondToHold()
Key scopes: store:holds:write(API keys are coming soon)
Headers: Idempotency-KeyX-Request-Id

Parameters

Name	In	Type	About
`holdId`required	path	string (uuid)

Request body (required, application/json)

object

acceptbooleanrequired
reasonstring or nulloptionalat most 500 characters

Responses

200The hold after the answer.
object
- holdHoldrequired

Errors (400, 401, 403, 404, 409, 422, 500)

400invalid_request invalid_json invalid_idempotency_key
invalid_request: The query or body doesn’t match the schema (see errors[]).
invalid_json: The body isn’t JSON.
invalid_idempotency_key: The Idempotency-Key isn’t 1–255 visible ASCII characters.
401unauthorized
unauthorized: Not signed in (no session or token, or an expired one).
403forbidden
forbidden: The caller’s side can’t do this (only the store answers a request…).
404not_found
not_found: Nothing at that address.
409idempotency_in_progress invalid_state listing_unavailable store_unavailable store_closed
idempotency_in_progress: The first request with this key is still running.
invalid_state: The hold isn’t in a state that allows this (already answered, closed…).
listing_unavailable: The book isn’t listed, or not enough copies are left.
store_unavailable: The store isn’t taking requests right now.
store_closed: The store has closed.
422idempotency_key_reused
idempotency_key_reused: This key was used for a different request.
500internal
internal: Something went wrong on our side (quote the requestId).

curl

curl -X POST 'https://collection.id/api/v1/holds/<holdId>/respond' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d @body.json

TypeScript SDK

await collector.respondToHold({ path: { holdId }, body: { … } });