API reference / Stores

Stores

4 operations.

POST/api/v1/stores

Create a store

Signed inIdempotent

Open a store with its storefront profile; the caller becomes its owner. Up to 5 stores per collector.

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

Request body (required, application/json)

object

slugstringrequiredat most 80 characters
namestringrequired2–120 characters
taglinestring or nulloptionalat most 640 characters
descriptionstring or nulloptionalat most 8000 characters
websitestring or nulloptionalat most 300 characters
phonestring or nulloptionalat most 160 characters
emailstring or nulloptionalat most 200 characters
address_line1string or nulloptionalat most 800 characters
address_line2string or nulloptionalat most 800 characters
citystring or nulloptionalat most 480 characters
regionstring or nulloptionalat most 480 characters
postal_codestring or nulloptionalat most 80 characters
countrystring or nulloptional
latitudenumber or nulloptional-90–90
longitudenumber or nulloptional-180–180
hoursobjectrequired
Fields of hours
- daysobjectrequired
  Fields of days
  monarray of [string, string]requiredat most 3 items
  tuearray of [string, string]requiredat most 3 items
  wedarray of [string, string]requiredat most 3 items
  thuarray of [string, string]requiredat most 3 items
  friarray of [string, string]requiredat most 3 items
  satarray of [string, string]requiredat most 3 items
  sunarray of [string, string]requiredat most 3 items
- notestring or nulloptionalat most 400 characters
specialtiesarray of stringrequiredat most 16 items
shipsbooleanrequired
accepts_holdsbooleanrequired
hold_daysintegerrequired1–30
logo_pathstring or nulloptionalat most 300 characters
banner_pathstring or nulloptionalat most 300 characters

Responses

201The new store’s id and address.
object
- storeobjectrequired
  Fields of store
  idstring (uuid)required
  slugstringrequired

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

400invalid_request invalid_json invalid_idempotency_key invalid_slug
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_slug: The address isn’t allowed (reserved, too short…).
401unauthorized
unauthorized: Not signed in (no session or token, or an expired one).
409idempotency_in_progress slug_taken store_limit
idempotency_in_progress: The first request with this key is still running.
slug_taken: Another store has that address.
store_limit: The caller already created 5 stores.
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/stores' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d @body.json

TypeScript SDK

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

GET/api/v1/stores/{storeId}

Get a store’s dashboard context

Store member

The store, the caller’s role, billing flags and the counters the dashboard shows. storeId may be the id or the slug.

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

Parameters

Name	In	Type	About
`storeId`required	path	string	The store’s id or slug.1–200 characters

Responses

200The store and the caller’s place in it.
StoreContext
A store, the caller’s role in it and the dashboard’s counters.
- storeStorerequired
- roleenumrequired
  owner (one or more), admin (manages the store), staff (inventory and holds).
  One ofowneradminstaff
- canManagebooleanrequired
  The caller is an owner or admin.
- billingReadybooleanrequired
  A payment method for seller fees is on file.
- billingConfiguredbooleanrequired
  Billing is set up on our side at all.
- feeobjectrequired
  Fields of fee
  bpsintegerrequired
  Seller fee in basis points (100 = 1%).
  minFeeCentsintegerrequired
  maxFeeCentsinteger or nullrequired
  currencystringrequired
  storeOverridebooleanrequired
  This store has its own rate.
- holdsAwaitingintegerrequired
  Hold requests waiting for an answer.
- questionsAwaitingintegerrequired
  Open questions waiting for the store’s answer.
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/stores/<storeId>' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN"

TypeScript SDK

await collector.getStore({ path: { storeId } });

PATCH/api/v1/stores/{storeId}

Update the storefront profile

Store member

Replace the storefront profile: name, contact details, address, hours, specialties and hold settings. Send every field (it isn’t a partial update). Images are uploaded to the store’s folder first.

SDK: collector.updateStore()
Key scopes: store:storefront:write(API keys are coming soon)
Headers: X-Request-Id

Parameters

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

Request body (required, application/json)

object

namestringrequired2–120 characters
taglinestring or nulloptionalat most 640 characters
descriptionstring or nulloptionalat most 8000 characters
websitestring or nulloptionalat most 300 characters
phonestring or nulloptionalat most 160 characters
emailstring or nulloptionalat most 200 characters
address_line1string or nulloptionalat most 800 characters
address_line2string or nulloptionalat most 800 characters
citystring or nulloptionalat most 480 characters
regionstring or nulloptionalat most 480 characters
postal_codestring or nulloptionalat most 80 characters
countrystring or nulloptional
latitudenumber or nulloptional-90–90
longitudenumber or nulloptional-180–180
hoursobjectrequired
Fields of hours
- daysobjectrequired
  Fields of days
  monarray of [string, string]requiredat most 3 items
  tuearray of [string, string]requiredat most 3 items
  wedarray of [string, string]requiredat most 3 items
  thuarray of [string, string]requiredat most 3 items
  friarray of [string, string]requiredat most 3 items
  satarray of [string, string]requiredat most 3 items
  sunarray of [string, string]requiredat most 3 items
- notestring or nulloptionalat most 400 characters
specialtiesarray of stringrequiredat most 16 items
shipsbooleanrequired
accepts_holdsbooleanrequired
hold_daysintegerrequired1–30
logo_pathstring or nulloptionalat most 300 characters
banner_pathstring or nulloptionalat most 300 characters

Responses

200The updated store.
object
- storeStorerequired

Errors (400, 401, 403, 404, 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: Only the store’s owners and admins can do this.
404not_found
not_found: Nothing at that address.
500internal
internal: Something went wrong on our side (quote the requestId).

curl

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

TypeScript SDK

await collector.updateStore({ path: { storeId }, body: { … } });

GET/api/v1/stores/slug

Check a store address

Signed in

Whether a storefront address (collection.id/stores/<slug>) is free to take, and why not.

SDK: collector.checkStoreSlug()
Key scopes: stores:write(API keys are coming soon)
Headers: If-None-MatchX-Request-Id

Parameters

Name	In	Type	About
`slug`optional	query	string	at most 200 characters · default ""

Responses

200Available, or the reason it isn’t.
object
- availablebooleanrequired
- reasonstring or nullrequired
304Not modified: your copy (the ETag in If-None-Match) is current.

Errors (400, 401, 500)

400invalid_request
invalid_request: The query or body doesn’t match the schema (see errors[]).
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/stores/slug' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN"

TypeScript SDK

await collector.checkStoreSlug({ query: { … } });