# Store API

> HTTP API for the two API-key surfaces of this store: a CUSTOMER surface for
> browsing the catalogue and placing orders, and a COLLABORATOR surface for
> fulfilling product orders. Authentication is an `X-Api-Key` header. The API
> is server-to-server: it sends no CORS headers, so a browser on another
> origin cannot call it.

## Full reference

- [Complete API reference](https://rollroyce.store/docs/api/llms-full.txt): every endpoint, parameter, response and error code as Markdown
- [Human-readable docs](https://rollroyce.store/docs/api): the same reference with a live request console

## Customer surface

- [GET /api/v1/client/catalog/categories](https://rollroyce.store/docs/api#client.catalog.categories): The public category tree, paginated.
- [GET /api/v1/client/catalog/groups](https://rollroyce.store/docs/api#client.catalog.groups): Listing groups, filterable and sortable. This is the catalogue.
- [GET /api/v1/client/catalog/groups/:id](https://rollroyce.store/docs/api#client.catalog.group): One listing group, with its live sellable stock count.
- [GET /api/v1/client/catalog/groups/:id/products](https://rollroyce.store/docs/api#client.catalog.products): The individual products inside one product-type group.
- [POST /api/v1/client/orders/quote](https://rollroyce.store/docs/api#client.orders.quote): Price a basket without creating anything. Nothing is reserved and nothing is charged.
- [POST /api/v1/client/orders](https://rollroyce.store/docs/api#client.orders.create): Creates the order and debits the wallet. This one spends real money.
- [GET /api/v1/client/orders](https://rollroyce.store/docs/api#client.orders.list): Order history for the account the key acts as.
- [GET /api/v1/client/orders/:code](https://rollroyce.store/docs/api#client.orders.show): One order by its public code. Metadata only — no credentials.
- [GET /api/v1/client/orders/:code/credentials](https://rollroyce.store/docs/api#client.orders.credentials): The decrypted accounts of your own completed account-type order.
- [GET /api/v1/client/orders/:code/export](https://rollroyce.store/docs/api#client.orders.export): The whole order in one streamed response: a text file, one account per line, or NDJSON.
- [GET /api/v1/client/me/balance](https://rollroyce.store/docs/api#client.me.balance): The wallet balance and the discount rate the account is currently getting.

## Collaborator surface

- [GET /api/v1/collab/product-orders/queue](https://rollroyce.store/docs/api#collab.productOrders.queue): Unclaimed product orders waiting for a collaborator.
- [GET /api/v1/collab/product-orders](https://rollroyce.store/docs/api#collab.productOrders.mine): Orders this collaborator has claimed, in any state.
- [GET /api/v1/collab/product-orders/:id](https://rollroyce.store/docs/api#collab.productOrders.show): One order in full, including the buyer's answers to the group's questions.
- [POST /api/v1/collab/product-orders/:id/claim](https://rollroyce.store/docs/api#collab.productOrders.claim): Take an order out of the queue. Once claimed it is yours to finish.
- [POST /api/v1/collab/product-orders/:id/complete](https://rollroyce.store/docs/api#collab.productOrders.complete): Report the work done. Starts the payout clock.
- [POST /api/v1/collab/product-orders/:id/cancel](https://rollroyce.store/docs/api#collab.productOrders.cancel): Give up an order you are holding. The buyer is refunded in full.
- [GET /api/v1/collab/payouts](https://rollroyce.store/docs/api#collab.payouts.list): Payouts already released to you. Money still in escrow is on your product orders, not here.
- [GET /api/v1/collab/complaints](https://rollroyce.store/docs/api#collab.complaints.list): Complaint items filed against your sales — the ones waiting on you and the ones already answered.
- [GET /api/v1/collab/complaints/:id](https://rollroyce.store/docs/api#collab.complaints.show): One item of yours. Somebody else's item is a 404, never a 403.
- [POST /api/v1/collab/complaints/:id/refund](https://rollroyce.store/docs/api#collab.complaints.refund): Close the item in the buyer's favour. If the money had already been paid out to you, it is clawed back.
- [POST /api/v1/collab/complaints/:id/fix](https://rollroyce.store/docs/api#collab.complaints.fix): Replace the disputed account's credentials in place, or re-send a product order's result. The buyer then has a window to confirm.
- [POST /api/v1/collab/stock](https://rollroyce.store/docs/api#collab.stock.create): File account credentials into a group's pool, in your own name. Up to 5,000 rows per call.
- [GET /api/v1/collab/stock](https://rollroyce.store/docs/api#collab.stock.list): A page of your own inventory — ready, reserved and sold rows. No credential is ever in this list.
- [PUT /api/v1/collab/stock/:id](https://rollroyce.store/docs/api#collab.stock.update): Change the login on one of your own `ready` rows. No price field — what you are paid per row is the administrator's figure, not yours to set.
- [DELETE /api/v1/collab/stock/:id](https://rollroyce.store/docs/api#collab.stock.destroy): Remove one of your own `ready` rows for good. A row that is reserved or already sold refuses — there is nothing left to un-sell.

## Getting a key

- [GET /api/v1/account/api-keys](https://rollroyce.store/docs/api#session.apiKeys.list): Every key on your account. The secret is never among them.
- [POST /api/v1/account/api-keys](https://rollroyce.store/docs/api#session.apiKeys.create): The only way a key is ever created — and the only time its secret is shown.
- [DELETE /api/v1/account/api-keys/:id](https://rollroyce.store/docs/api#session.apiKeys.revoke): Kills the key on the next request. Orders it placed are kept.