Roastery API
- Endpoints
- 17
- Groups
- 5
- Models
- 15
The Roastery API runs a specialty coffee business: the bean catalog, roast schedules, orders and subscriptions.
| Environment | Base URL | Data |
|---|---|---|
| Production | https://api.roastery.dev/v2 | Live |
| Sandbox | https://{region}.sandbox.roastery.dev/v2 | Reset nightly |
Every request needs a bearer token. Lists are paginated with page and per_page; responses carry the totals in meta.
Sandbox orders are never shipped, so try anything there.
Beans
Green and roasted coffee in the catalog.
List beans
/beansoperationId: beans_list
RequiresbearerAuth
Returns the catalog, newest first. Filter by origin, process or availability.
Query parameters
ISO 3166-1 alpha-2 country code of the farm.
Only beans that can be ordered now.
Responses
Add a bean
/beansoperationId: beans_create
RequiresbearerAuth
Request body
requiredResponses
Country code
Get a bean
/beans/{bean_id}operationId: beans_show
RequiresbearerAuth
Path parameters
Responses
Country code
Remove a bean
/beans/{bean_id}operationId: beans_delete
RequiresbearerAuth
Path parameters
Responses
Update a bean
/beans/{bean_id}operationId: beans_update
RequiresbearerAuth
Path parameters
Request body
Responses
Country code
Upload a bag photo
/beans/{bean_id}/photooperationId: beans_photo
RequiresbearerAuth
Path parameters
Request body
requiredResponses
Roasts
Roast batches and their profiles.
List roast batches
/roastsoperationId: roasts_list
RequiresbearerAuth
Query parameters
Responses
Schedule a roast
/roastsoperationId: roasts_schedule
RequiresbearerAuth
Request body
requiredResponses
Links
- roast_id
- $response.body#/id
Get a roast batch
/roasts/{roast_id}operationId: roasts_show
RequiresbearerAuth
Path parameters
Responses
Orders
Orders from the web shop and wholesale customers.
List orders
/ordersoperationId: orders_list
RequiresbearerAuth
Query parameters
Responses
Place an order
/ordersoperationId: orders_create
RequiresbearerAuth
Places an order and charges it. Send an Idempotency-Key so a retried request never charges twice.
Header parameters
Request body
requiredResponses
Get an order
/orders/{order_id}operationId: orders_show
RequiresbearerAuth
Path parameters
Responses
Cancel an order
/orders/{order_id}/canceloperationId: orders_cancel
RequiresbearerAuth
Only orders that have not shipped yet can be cancelled; the charge is refunded.
Path parameters
Responses
Subscriptions
Recurring deliveries.
List subscriptions
/subscriptionsoperationId: subscriptions_list
RequiresbearerAuth
Responses
Start a subscription
/subscriptionsoperationId: subscriptions_create
RequiresbearerAuth
Request body
requiredResponses
Pause a subscription
/subscriptions/{subscription_id}/pauseoperationId: subscriptions_pause
RequiresbearerAuth
Path parameters
Request body
Responses
Customers
Get a customer
/customers/{customer_id}operationId: customers_show
RequiresbearerAuth
Path parameters
Responses
Webhooks
Requests this API sends to your endpoint.
Order shipped
order.shippedoperationId: webhook_order_shipped
RequiresbearerAuth
Sent when a parcel leaves the roastery, with its tracking number.
Request body
Responses
Models
Process
RoastLevel
Bean
Country code
BeanInput
Roast
OrderStatus
OrderInput
CardPayment
InvoicePayment
Order
Subscription
Customer
Money
Minor units (cents)