API reference / Stores
9 operations.
/api/v1/stores/{storeId}/import/commitInsert the confirmed rows of a previewed CSV (up to 500 per request). Rows that fail are reported by line; the rest are listed.
collector.commitInventoryImport()store:inventory:write(API keys are coming soon)Idempotency-KeyX-Request-Id| Name | In | Type | About |
|---|---|---|---|
storeIdrequired | path | string (uuid) |
object
rowsarray of objectrequired1–500 itemslineintegerrequiredat least 1issueIdstring (uuid)requirededitionIdstring (uuid) or nullrequiredfieldsobjectrequiredpriceCentsinteger or nullrequiredquantityintegerrequired0–100000gradenumber or nullrequired0.5–10gradingCompanyenum or nullrequiredOne ofcgccbcspsapgxegshgaother
certNumberstring or nullrequiredat most 80 characterslabelTypestring or nullrequiredat most 40 characterspageQualityenum or nullrequiredOne ofwhiteoff_white_to_whiteoff_whitecream_to_off_whitecreamlight_tantanbrittle
isSignedbooleanrequiredsignaturesarray of stringrequiredat most 12 itemsconditionNotesstring or nullrequiredat most 2000 charactersskustring or nullrequiredat most 80 charactersshelfLocationstring or nullrequiredat most 120 charactersstatusenumrequiredOne ofactivehidden
object
createdintegerrequiredfailedarray of objectrequiredlineintegerrequiredmessagestringrequiredinvalid_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.
unauthorized: Not signed in (no session or token, or an expired one).
not_found: Nothing at that address.
idempotency_in_progress: The first request with this key is still running.
store_inactive: The store is closed or suspended, so its books can’t be listed for sale.
idempotency_key_reused: This key was used for a different request.
internal: Something went wrong on our side (quote the requestId).
curl -X POST 'https://collection.id/api/v1/stores/<storeId>/import/commit' \
-H "Authorization: Bearer $COLLECTOR_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d @body.jsonawait collector.commitInventoryImport({ path: { storeId }, body: { … } });/api/v1/stores/{storeId}/import/previewParse an inventory CSV (up to 2 MB) and match every row against the catalog. Nothing is saved: commit the rows you confirm with import/commit.
collector.previewInventoryImport()store:inventory:write(API keys are coming soon)X-Request-Id| Name | In | Type | About |
|---|---|---|---|
storeIdrequired | path | string (uuid) |
object
csvstringrequired1–2000000 charactersAn inventory CSV, parsed and matched against the catalog. Nothing is saved.
rowsarray of objectrequiredlineintegerrequiredThe CSV line (the header is line 1).
inputobjectrequiredtitlestring or nullrequirednumberstring or nullrequiredyearinteger or nullrequiredpublisherstring or nullrequiredvariantstring or nullrequiredfieldsobjectrequiredpriceCentsinteger or nullrequiredquantityintegerrequiredgradenumber or nullrequiredgradingCompanyenum or nullrequiredOne ofcgccbcspsapgxegshgaother
certNumberstring or nullrequiredlabelTypestring or nullrequiredpageQualityenum or nullrequiredOne ofwhiteoff_white_to_whiteoff_whitecream_to_off_whitecreamlight_tantanbrittle
isSignedbooleanrequiredsignaturesarray of stringrequiredconditionNotesstring or nullrequiredskustring or nullrequiredshelfLocationstring or nullrequiredstatusenumrequiredOne ofactivehidden
errorsarray of stringrequiredwarningsarray of stringrequiredmatchobjectrequiredstatusenumrequiredOne ofmatchedambiguousnot_foundinvalid
chosenKeystring or nullrequirededitionIdstring (uuid) or nullrequiredcolumnsarray of objectrequiredheaderstringrequiredfieldenum or nullrequiredOne oftitlenumberyearpublishervariantgradegradingCompanycertNumberlabelTypepageQualitysignedpricequantityskushelfLocationnotesstatus
totalRowsintegerrequiredtruncatedbooleanrequiredOnly the first rows were read.
invalid_request: The query or body doesn’t match the schema (see errors[]).
invalid_json: The body isn’t JSON.
unauthorized: Not signed in (no session or token, or an expired one).
not_found: Nothing at that address.
csv_columns: The CSV lacks the columns needed (title, number, price…).
internal: Something went wrong on our side (quote the requestId).
curl -X POST 'https://collection.id/api/v1/stores/<storeId>/import/preview' \
-H "Authorization: Bearer $COLLECTOR_TOKEN" \
-H 'Content-Type: application/json' \
-d @body.jsonawait collector.previewInventoryImport({ path: { storeId }, body: { … } });/api/v1/stores/{storeId}/listingsOne page of the inventory, every status, with staff-only fields (SKU, shelf location). Pages with limit and offset; count is the total.
collector.listStoreListings()store:inventory:read(API keys are coming soon)If-None-MatchX-Request-Id| Name | In | Type | About |
|---|---|---|---|
storeIdrequired | path | string (uuid) | |
statusoptional | query | enum | One of active, hidden, sold_out, archived, all |
qoptional | query | string | A title and number, or a SKU, cert number or shelf.at most 200 characters |
sortoptional | query | enum | One of updated, price_desc, price_asc, quantity |
limitoptional | query | integer | 1–200 |
offsetoptional | query | integer | 0–1000000 |
idsoptional | query | string | Comma-separated listing ids (up to 200): just these.at most 7400 characters |
object
countintegerrequiredinvalid_request: The query or body doesn’t match the schema (see errors[]).
unauthorized: Not signed in (no session or token, or an expired one).
not_found: Nothing at that address.
internal: Something went wrong on our side (quote the requestId).
curl 'https://collection.id/api/v1/stores/<storeId>/listings' \
-H "Authorization: Bearer $COLLECTOR_TOKEN"await collector.listStoreListings({ path: { storeId }, query: { … } });/api/v1/stores/{storeId}/listingsAdd a copy to the inventory: issueId, or a candidate from catalog search (a provider-only book is imported first), with its condition, price and stock.
collector.createStoreListing()store:inventory:write(API keys are coming soon)Idempotency-KeyX-Request-Id| Name | In | Type | About |
|---|---|---|---|
storeIdrequired | path | string (uuid) |
object
editionIdstring (uuid) or nulloptionalquantityintegerrequired0–100000priceCentsintegerrequired1–2000000000currencystringoptionalgradenumber or nullrequired0.5–10gradingCompanyenum or nullrequiredOne ofcgccbcspsapgxegshgaother
certNumberstring or nulloptionalat most 320 characterslabelTypestring or nulloptionalat most 160 characterspageQualityenum or nullrequiredOne ofwhiteoff_white_to_whiteoff_whitecream_to_off_whitecreamlight_tantanbrittle
isSignedbooleanrequiredsignaturesarray of stringrequiredat most 12 itemsconditionNotesstring or nulloptionalat most 4000 charactersphotoPathsarray of stringrequiredat most 12 itemsskustring or nulloptionalat most 320 charactersshelfLocationstring or nulloptionalat most 480 charactersstatusenumrequiredOne ofactivehidden
issueIdstring (uuid) or nulloptionalcandidateobject or nulloptionalissueIdstring (uuid) or nullrequirededitionIdstring (uuid) or nullrequiredproviderobject or nullrequiredproviderenumrequiredOne ofmetrongcdcataloggd
issueIdstringrequired1–262 charactersvariantIdstring or nulloptionalat most 200 charactersobject
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.
invalid_listing: The listing’s fields don’t add up (a cert number without a grader…); detail says which.
unauthorized: Not signed in (no session or token, or an expired one).
not_found: Nothing at that address.
idempotency_in_progress: The first request with this key is still running.
store_inactive: The store is closed or suspended, so its books can’t be listed for sale.
not_in_catalog: The picked book isn’t in our catalog yet; search again.
idempotency_key_reused: This key was used for a different request.
internal: Something went wrong on our side (quote the requestId).
curl -X POST 'https://collection.id/api/v1/stores/<storeId>/listings' \
-H "Authorization: Bearer $COLLECTOR_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d @body.jsonawait collector.createStoreListing({ path: { storeId }, body: { … } });/api/v1/stores/{storeId}/listings/{listingId}One listing with its staff-only fields and, when a moderator hid it, why.
collector.getStoreListing()store:inventory:read(API keys are coming soon)If-None-MatchX-Request-Id| Name | In | Type | About |
|---|---|---|---|
storeIdrequired | path | string (uuid) | |
listingIdrequired | path | string (uuid) |
object
unauthorized: Not signed in (no session or token, or an expired one).
not_found: Nothing at that address.
internal: Something went wrong on our side (quote the requestId).
curl 'https://collection.id/api/v1/stores/<storeId>/listings/<listingId>' \
-H "Authorization: Bearer $COLLECTOR_TOKEN"await collector.getStoreListing({ path: { storeId, listingId } });/api/v1/stores/{storeId}/listings/{listingId}Only a listing without hold or question history; archive the others.
collector.deleteStoreListing()store:inventory:write(API keys are coming soon)X-Request-Id| Name | In | Type | About |
|---|---|---|---|
storeIdrequired | path | string (uuid) | |
listingIdrequired | path | string (uuid) |
object
ok"true"requiredunauthorized: Not signed in (no session or token, or an expired one).
not_found: Nothing at that address.
has_holds: It has hold history: archive it instead.
has_questions: Collectors asked about it: archive it instead.
internal: Something went wrong on our side (quote the requestId).
curl -X DELETE 'https://collection.id/api/v1/stores/<storeId>/listings/<listingId>' \
-H "Authorization: Bearer $COLLECTOR_TOKEN"await collector.deleteStoreListing({ path: { storeId, listingId } });/api/v1/stores/{storeId}/listings/{listingId}Change any of its fields (send only what changes). Removed photos are deleted.
collector.updateStoreListing()store:inventory:write(API keys are coming soon)X-Request-Id| Name | In | Type | About |
|---|---|---|---|
storeIdrequired | path | string (uuid) | |
listingIdrequired | path | string (uuid) |
object
editionIdstring (uuid) or nulloptionalquantityintegeroptional0–100000priceCentsintegeroptional1–2000000000currencystringoptionalgradenumber or nulloptional0.5–10gradingCompanyenum or nulloptionalOne ofcgccbcspsapgxegshgaother
certNumberstring or nulloptionalat most 320 characterslabelTypestring or nulloptionalat most 160 characterspageQualityenum or nulloptionalOne ofwhiteoff_white_to_whiteoff_whitecream_to_off_whitecreamlight_tantanbrittle
isSignedbooleanoptionalsignaturesarray of stringoptionalat most 12 itemsconditionNotesstring or nulloptionalat most 4000 charactersphotoPathsarray of stringoptionalat most 12 itemsskustring or nulloptionalat most 320 charactersshelfLocationstring or nulloptionalat most 480 charactersstatusenumoptionalOne ofactivehidden
object
invalid_request: The query or body doesn’t match the schema (see errors[]).
invalid_json: The body isn’t JSON.
invalid_listing: The listing’s fields don’t add up (a cert number without a grader…); detail says which.
unauthorized: Not signed in (no session or token, or an expired one).
not_found: Nothing at that address.
moderation_hidden: A moderator hid this listing after a report, so it can’t go back on sale.
store_inactive: The store is closed or suspended, so its books can’t be listed for sale.
internal: Something went wrong on our side (quote the requestId).
curl -X PATCH 'https://collection.id/api/v1/stores/<storeId>/listings/<listingId>' \
-H "Authorization: Bearer $COLLECTOR_TOKEN" \
-H 'Content-Type: application/json' \
-d @body.jsonawait collector.updateStoreListing({ path: { storeId, listingId }, body: { … } });/api/v1/stores/{storeId}/listings/bulkList, hide or archive up to 500 listings at once. Listings a moderator hid stay hidden; moderationHidden counts them.
collector.setStoreListingsStatus()store:inventory:write(API keys are coming soon)Idempotency-KeyX-Request-Id| Name | In | Type | About |
|---|---|---|---|
storeIdrequired | path | string (uuid) |
object
idsarray of string (uuid)required1–500 itemsstatusenumrequiredOne ofactivehiddenarchived
object
updatedintegerrequiredmoderationHiddenintegerrequiredinvalid_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.
unauthorized: Not signed in (no session or token, or an expired one).
not_found: Nothing at that address.
idempotency_in_progress: The first request with this key is still running.
store_inactive: The store is closed or suspended, so its books can’t be listed for sale.
idempotency_key_reused: This key was used for a different request.
internal: Something went wrong on our side (quote the requestId).
curl -X POST 'https://collection.id/api/v1/stores/<storeId>/listings/bulk' \
-H "Authorization: Bearer $COLLECTOR_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d @body.jsonawait collector.setStoreListingsStatus({ path: { storeId }, body: { … } });/api/v1/stores/catalog-searchCatalog search for adding inventory (store staff only). q finds issues, and series when no issue number was typed; seriesId lists every issue of a series. Fewer than 2 characters answers no results.
collector.searchStoreCatalog()store:inventory:read(API keys are coming soon)If-None-MatchX-Request-Id| Name | In | Type | About |
|---|---|---|---|
qoptional | query | string | e.g. "amazing spider-man 300" (first 120 characters).at most 500 characters |
seriesIdoptional | query | string (uuid) | List every issue of this series instead. |
storeIdoptional | query | string (uuid) | Search as staff of this store (default: staff of any store). |
seriesarray of objectrequiredSeries hits when no issue number was typed.
seriesIdstring (uuid)requiredtitlestringrequiredstartYearinteger or nullrequiredpublisherstring or nullrequiredissueCountinteger or nullrequiredcoverUrlstring (uri) or nullrequiredsourceenumrequiredcatalog: our catalog and the providers; local: our catalog only.
One ofcataloglocal
invalid_request: The query or body doesn’t match the schema (see errors[]).
unauthorized: Not signed in (no session or token, or an expired one).
not_found: The caller isn’t on a store’s team, or no such series.
internal: Something went wrong on our side (quote the requestId).
curl 'https://collection.id/api/v1/stores/catalog-search' \
-H "Authorization: Bearer $COLLECTOR_TOKEN"await collector.searchStoreCatalog({ query: { … } });