Partner API · version 2

Coffee data for the shops that pour it.

Wholesale partners and their point-of-sale or ordering tools can use the Maple Roast Partner API to read our current coffees, check roast dates and place repeat orders without picking up the phone.

All endpoints operational · last checked 26 Oct 2026

Getting started

The API speaks JSON over HTTPS. Every request is made against the base URL below and authenticated with a partner key sent as a bearer token. Keys are issued to approved wholesale accounts by our team; there is no self-service sign-up.

Base URL   https://api.mapleroast.com/v2
Auth       Authorization: Bearer <partner-key>
Format     application/json; charset=utf-8
Time       ISO 8601, America/New_York

A first request to check that your key works:

curl https://api.mapleroast.com/v2/coffees \
  -H "Authorization: Bearer $MAPLE_KEY"

Endpoints

GET/coffees

Lists coffees currently on offer, with origin, process, roast level and available bag sizes. Seasonal lots appear here two weeks before their first roast.

GET/coffees/{slug}

One coffee in detail, including tasting notes and recommended brew ratios.

{
  "slug": "house-maple",
  "name": "House Maple",
  "origin": "Brazil & Guatemala blend",
  "roast": "medium",
  "notes": ["toasted pecan", "maple", "milk chocolate"],
  "sizes_g": [340, 1000, 5000],
  "next_roast": "2026-10-27"
}

GET/roast-calendar

Roast, rest and dispatch dates for the next four weeks. Optional coffee filter by slug.

POST/orders

Places a wholesale order for the next available roast day. Send an Idempotency-Key header so that retries never create a second order.

POST /v2/orders
Idempotency-Key: 7d1c2e9a-cafe-4b1e-9a3f-2f0b7c5d1e11

{
  "account": "MR-0142",
  "lines": [
    { "coffee": "house-maple", "size_g": 5000, "qty": 2 },
    { "coffee": "orchard-lane", "size_g": 1000, "qty": 3 }
  ]
}

GET/orders/{id}

Order status: received, scheduled, roasted, packed or shipped, with a tracking reference once dispatched.

GET/invoices

Invoices for your account, newest first, with totals in USD and settlement status.

Rate limits

120 requests per minute per key. Responses include X-RateLimit-Remaining; when it reaches zero you will receive 429 with a Retry-After header.

Errors

Errors return a JSON body with code and message. Common codes: 401 invalid_key, 404 not_found, 409 order_locked after Sunday cut-off.

Changelog

2026-09-02 — added next_roast to coffees.
2026-05-14 — v2 released; v1 retired on 2026-08-31.

Support

Questions about keys or integrations: partners@mapleroast.com. We reply within two working days.