v2.4.0OpenAPI 3.1.0

Roastery API

Endpoints
17
Groups
5
Models
15

The Roastery API runs a specialty coffee business: the bean catalog, roast schedules, orders and subscriptions.

EnvironmentBase URLData
Productionhttps://api.roastery.dev/v2Live
Sandboxhttps://{region}.sandbox.roastery.dev/v2Reset 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

get/beans

operationId: beans_list

RequiresbearerAuth

Returns the catalog, newest first. Filter by origin, process or availability.

Query parameters

pageinteger
≥ 1
Default: 1
per_pageinteger
≥ 1≤ 100
Default: 20
originstring

ISO 3166-1 alpha-2 country code of the farm.

pattern: ^[A-Z]{2}$
Example: "ET"
processstring
Values:"washed""natural""honey""anaerobic"
Example: "washed"
in_stockboolean

Only beans that can be ordered now.

Responses

array<Bean>required
PageMetarequired

Add a bean

post/beans

operationId: beans_create

RequiresbearerAuth

Request body

required
namestringrequired
min length 2
Example: "Guji Hambela"
originstringrequired
pattern: ^[A-Z]{2}$
Example: "ET"
processstringrequired
Values:"washed""natural""honey""anaerobic"
Example: "washed"
notesarray<string>
max items 5
Example: ["jasmine","bergamot"]
Moneyrequired

Responses

idstringrequired
Example: "bean_eth_guji"
namestringrequired
Example: "Guji Hambela"
originstringrequired

Country code

Example: "ET"
regionstring
Example: "Oromia"
altitude_minteger
Example: 2100
processstringrequired
Values:"washed""natural""honey""anaerobic"
Example: "washed"
notesarray<string>
Example: ["jasmine","bergamot","peach"]
Moneyrequired
in_stockboolean
Example: true
created_atstring<date-time>
Example: "2026-09-12T08:00:00Z"

Get a bean

get/beans/{bean_id}

operationId: beans_show

RequiresbearerAuth

Path parameters

bean_idstringrequired
Example: "bean_eth_guji"

Responses

idstringrequired
Example: "bean_eth_guji"
namestringrequired
Example: "Guji Hambela"
originstringrequired

Country code

Example: "ET"
regionstring
Example: "Oromia"
altitude_minteger
Example: 2100
processstringrequired
Values:"washed""natural""honey""anaerobic"
Example: "washed"
notesarray<string>
Example: ["jasmine","bergamot","peach"]
Moneyrequired
in_stockboolean
Example: true
created_atstring<date-time>
Example: "2026-09-12T08:00:00Z"

Remove a bean

delete/beans/{bean_id}

operationId: beans_delete

RequiresbearerAuth

Path parameters

bean_idstringrequired
Example: "bean_eth_guji"

Responses

Update a bean

patch/beans/{bean_id}

operationId: beans_update

RequiresbearerAuth

Path parameters

bean_idstringrequired
Example: "bean_eth_guji"

Request body

namestringrequired
min length 2
Example: "Guji Hambela"
originstringrequired
pattern: ^[A-Z]{2}$
Example: "ET"
processstringrequired
Values:"washed""natural""honey""anaerobic"
Example: "washed"
notesarray<string>
max items 5
Example: ["jasmine","bergamot"]
Moneyrequired

Responses

idstringrequired
Example: "bean_eth_guji"
namestringrequired
Example: "Guji Hambela"
originstringrequired

Country code

Example: "ET"
regionstring
Example: "Oromia"
altitude_minteger
Example: 2100
processstringrequired
Values:"washed""natural""honey""anaerobic"
Example: "washed"
notesarray<string>
Example: ["jasmine","bergamot","peach"]
Moneyrequired
in_stockboolean
Example: true
created_atstring<date-time>
Example: "2026-09-12T08:00:00Z"

Upload a bag photo

put/beans/{bean_id}/photo

operationId: beans_photo

RequiresbearerAuth

Path parameters

bean_idstringrequired
Example: "bean_eth_guji"

Request body

required
photostring<binary>required
altstring
Example: "Ethiopia Guji"

Responses

urlstring<uri>
Example: "https://cdn.roastery.dev/beans/eth-guji.png"

Roasts

Roast batches and their profiles.

List roast batches

get/roasts

operationId: roasts_list

RequiresbearerAuth

Query parameters

pageinteger
≥ 1
Default: 1
datestring<date>
Example: "2026-10-02"

Responses

array<Roast>

Schedule a roast

post/roasts

operationId: roasts_schedule

RequiresbearerAuth

Request body

required
bean_idstringrequired
Example: "bean_eth_guji"
profilestringrequired
Values:"light""medium""espresso"
Example: "light"
kilogramsnumberrequired
≥ 1≤ 60
Example: 12.5
roast_atstring<date-time>required
Example: "2026-10-03T07:30:00Z"

Responses

idstring
Example: "roast_7Hq2"
bean_idstring
Example: "bean_eth_guji"
profilestring
Values:"light""medium""espresso"
Example: "light"
kilogramsnumber
Example: 12.5
statusstring
Values:"scheduled""roasting""cooling""done"
Example: "scheduled"
roast_atstring<date-time>
Example: "2026-10-03T07:30:00Z"

Links

roast_id
$response.body#/id

Get a roast batch

get/roasts/{roast_id}

operationId: roasts_show

RequiresbearerAuth

Path parameters

roast_idstringrequired
Example: "roast_7Hq2"

Responses

idstring
Example: "roast_7Hq2"
bean_idstring
Example: "bean_eth_guji"
profilestring
Values:"light""medium""espresso"
Example: "light"
kilogramsnumber
Example: 12.5
statusstring
Values:"scheduled""roasting""cooling""done"
Example: "scheduled"
roast_atstring<date-time>
Example: "2026-10-03T07:30:00Z"

Orders

Orders from the web shop and wholesale customers.

List orders

get/orders

operationId: orders_list

RequiresbearerAuth

Query parameters

pageinteger
≥ 1
Default: 1
statusstring
Values:"pending""paid""shipped""cancelled"
Example: "paid"

Responses

array<Order>

Place an order

post/orders

operationId: orders_create

RequiresbearerAuth

Places an order and charges it. Send an Idempotency-Key so a retried request never charges twice.

Header parameters

Idempotency-Keystring<uuid>required
Example: "6f1c7a3e-2b9d-4c55-9a51-0e8f2d6b7c10"

Request body

required
customer_idstringrequired
Example: "cus_41aX"
array<object>required
min items 1
oneOfrequired
notestring
max length 280
Example: "Leave it with the neighbour."

Responses

customer_idstringrequired
Example: "cus_41aX"
array<object>required
min items 1
oneOfrequired
notestring
max length 280
Example: "Leave it with the neighbour."
idstring
Example: "ord_2Wd8"
statusstring
Values:"pending""paid""shipped""cancelled"
Example: "paid"
Money
created_atstring<date-time>
Example: "2026-10-02T09:14:00Z"

Get an order

get/orders/{order_id}

operationId: orders_show

RequiresbearerAuth

Path parameters

order_idstringrequired
Example: "ord_2Wd8"

Responses

customer_idstringrequired
Example: "cus_41aX"
array<object>required
min items 1
oneOfrequired
notestring
max length 280
Example: "Leave it with the neighbour."
idstring
Example: "ord_2Wd8"
statusstring
Values:"pending""paid""shipped""cancelled"
Example: "paid"
Money
created_atstring<date-time>
Example: "2026-10-02T09:14:00Z"

Cancel an order

post/orders/{order_id}/cancel

operationId: orders_cancel

RequiresbearerAuth

Only orders that have not shipped yet can be cancelled; the charge is refunded.

Path parameters

order_idstringrequired
Example: "ord_2Wd8"

Responses

customer_idstringrequired
Example: "cus_41aX"
array<object>required
min items 1
oneOfrequired
notestring
max length 280
Example: "Leave it with the neighbour."
idstring
Example: "ord_2Wd8"
statusstring
Values:"pending""paid""shipped""cancelled"
Example: "paid"
Money
created_atstring<date-time>
Example: "2026-10-02T09:14:00Z"

Subscriptions

Recurring deliveries.

List subscriptions

get/subscriptions

operationId: subscriptions_list

RequiresbearerAuth

Responses

array<Subscription>

Start a subscription

post/subscriptions

operationId: subscriptions_create

RequiresbearerAuth

Request body

required
customer_idstringrequired
Example: "cus_41aX"
bean_idstringrequired
Example: "bean_eth_guji"
gramsinteger
Values:2505001000
Default: 250
everystringrequired
Values:"week""two_weeks""month"
Example: "two_weeks"

Responses

idstring
Example: "sub_9Kp3"
customer_idstring
Example: "cus_41aX"
bean_idstring
Example: "bean_eth_guji"
gramsinteger
Example: 250
everystring
Example: "two_weeks"
statusstring
Values:"active""paused""cancelled"
Example: "active"
next_deliverystring<date>
Example: "2026-10-16"

Pause a subscription

post/subscriptions/{subscription_id}/pause

operationId: subscriptions_pause

RequiresbearerAuth

Path parameters

subscription_idstringrequired
Example: "sub_9Kp3"

Request body

untilstring<date>
Example: "2026-11-01"

Responses

idstring
Example: "sub_9Kp3"
customer_idstring
Example: "cus_41aX"
bean_idstring
Example: "bean_eth_guji"
gramsinteger
Example: 250
everystring
Example: "two_weeks"
statusstring
Values:"active""paused""cancelled"
Example: "active"
next_deliverystring<date>
Example: "2026-10-16"

Customers

Get a customer

get/customers/{customer_id}

operationId: customers_show

RequiresbearerAuth

Path parameters

customer_idstringrequired
Example: "cus_41aX"

Responses

idstring
Example: "cus_41aX"
namestring
Example: "Ada Yılmaz"
emailstring<email>
wholesaleboolean
Example: false

Webhooks

Requests this API sends to your endpoint.

Order shipped

postorder.shipped

operationId: webhook_order_shipped

RequiresbearerAuth

Sent when a parcel leaves the roastery, with its tracking number.

Request body

eventstring
Order
tracking_urlstring<uri>
Example: "https://track.example/RX4419"

Responses

Models

Process

string
Values:"washed""natural""honey""anaerobic"
Example: "washed"

RoastLevel

string
Values:"light""medium""espresso"
Example: "light"

Bean

idstringrequired
Example: "bean_eth_guji"
namestringrequired
Example: "Guji Hambela"
originstringrequired

Country code

Example: "ET"
regionstring
Example: "Oromia"
altitude_minteger
Example: 2100
processstringrequired
Values:"washed""natural""honey""anaerobic"
Example: "washed"
notesarray<string>
Example: ["jasmine","bergamot","peach"]
Moneyrequired
in_stockboolean
Example: true
created_atstring<date-time>
Example: "2026-09-12T08:00:00Z"

BeanInput

namestringrequired
min length 2
Example: "Guji Hambela"
originstringrequired
pattern: ^[A-Z]{2}$
Example: "ET"
processstringrequired
Values:"washed""natural""honey""anaerobic"
Example: "washed"
notesarray<string>
max items 5
Example: ["jasmine","bergamot"]
Moneyrequired

Roast

idstring
Example: "roast_7Hq2"
bean_idstring
Example: "bean_eth_guji"
profilestring
Values:"light""medium""espresso"
Example: "light"
kilogramsnumber
Example: 12.5
statusstring
Values:"scheduled""roasting""cooling""done"
Example: "scheduled"
roast_atstring<date-time>
Example: "2026-10-03T07:30:00Z"

OrderStatus

string
Values:"pending""paid""shipped""cancelled"
Example: "paid"

OrderInput

customer_idstringrequired
Example: "cus_41aX"
array<object>required
min items 1
oneOfrequired
notestring
max length 280
Example: "Leave it with the neighbour."

CardPayment

methodstringrequired
tokenstringrequired
Example: "tok_visa_4242"

InvoicePayment

methodstringrequired
tax_idstringrequired
Example: "TR1234567890"
due_daysinteger
Values:1430
Default: 30

Order

customer_idstringrequired
Example: "cus_41aX"
array<object>required
min items 1
oneOfrequired
notestring
max length 280
Example: "Leave it with the neighbour."
idstring
Example: "ord_2Wd8"
statusstring
Values:"pending""paid""shipped""cancelled"
Example: "paid"
Money
created_atstring<date-time>
Example: "2026-10-02T09:14:00Z"

Subscription

idstring
Example: "sub_9Kp3"
customer_idstring
Example: "cus_41aX"
bean_idstring
Example: "bean_eth_guji"
gramsinteger
Example: 250
everystring
Example: "two_weeks"
statusstring
Values:"active""paused""cancelled"
Example: "active"
next_deliverystring<date>
Example: "2026-10-16"

Customer

idstring
Example: "cus_41aX"
namestring
Example: "Ada Yılmaz"
emailstring<email>
wholesaleboolean
Example: false

Money

amountintegerrequired

Minor units (cents)

Example: 1850
currencystringrequired
Values:"EUR""USD""TRY"
Example: "EUR"

PageMeta

pageinteger
Example: 1
per_pageinteger
Example: 20
totalinteger
Example: 42

Error

titlestringrequired
Example: "Validation failed"
errorsobject
Example: {"origin":["Must be a two-letter country code."]}