# Decent Espresso product API

Read-only product data for Decent Espresso machines, accessories and spare parts: names, prices in USD, EUR, GBP, CAD, AUD and HKD, availability, descriptions, specifications, photos and related products. It can also price a cart for a country and give the link that fills it. Free to use; please credit (see below).

- **JSON version of this page:** <https://zh-hant.decentespresso.com/api/index.json> (Markdown: <https://zh-hant.decentespresso.com/api/?format=md>)
- **OpenAPI description:** <https://zh-hant.decentespresso.com/api/openapi.json>
- **Site description for AI agents:** <https://zh-hant.decentespresso.com/llms.txt>

## Endpoints

All responses are JSON (`application/json; charset=utf-8`), allow cross-origin requests, and include a `license` block.

| Endpoint | Returns | Example |
|---|---|---|
| `GET /api/products?q=&category=&page=&all=&offset=&limit=` | product summaries, at most 100 per page, with `next` | <https://zh-hant.decentespresso.com/api/products?category=tampers> |
| `GET /api/products/{sku}` | one product in full, with related products | <https://zh-hant.decentespresso.com/api/products/DE-304TAMPERV61ALUH-75830> |
| `GET /api/categories` | the shop's categories, with product counts | <https://zh-hant.decentespresso.com/api/categories> |
| `GET /api/cart/quote?s=&country=&currency=&shipping=` | the price of a cart delivered to a country, and its checkout link | <https://zh-hant.decentespresso.com/api/cart/quote?s=75830+2&country=DE> |

Filters for `/api/products`: `q` (text search in name, SKU, page and materials, at least 2 characters), `category` (an id from `/api/categories`), `page` (a product page, e.g. `tamper`), `all=1` (include spare parts not shown in the shop), `offset`, `limit`.

A product summary gives `sku`, `cart_number`, `name`, `price` (per currency), `availability` (in_stock, pre_order, coming_soon, out_of_stock or discontinued), `categories`, `web_url`, `api_url` and `image`. A full product adds `details` (description, features, materials, weight and shipping weight in grams, dimensions in cm, voltage, model, battery, expected ship date, free shipping, photos, `cart_url`) and `related`: `variants`, `full_price_version`, `discounted_versions`, `can_replace`, `included_parts_you_can_swap`, `alternatives_that_replace_this`, `contains` (a kit's parts, with quantities) and `part_of` (the kits a part belongs to).

Names and descriptions are in the language of the host: use de., fr., es., kr., zh-hans. or zh-hant.decentespresso.com for translations.

## Buying for a person: account, address, payment

An agent can take a person all the way to paying, with the same steps they would take on the website. The person confirms their email and pays on Stripe's page; the agent never handles card details. Steps 2-7 use the customer API, documented in full at <https://zh-hant.decentespresso.com/support/api/#shopping>.

1. **Price the cart.** Find products here, then `GET /api/cart/quote?s=75830+2&country=US` prices a cart (`NUMBER+QUANTITY` pairs, using each product's `cart_number`): line prices, quantity discount (10% from 5 accessories up to 30% from 80), shipping, import tax for machines, `total_estimate` and `can_checkout`. One espresso machine is checked out alone, accessories separately (`separate_orders`). Options: `currency=`, `shipping=expedited`.
2. **Start an account.** `POST /support/api/account/start {"email": "..."}` emails the person a confirmation link and returns a `signup_id`. Nothing is created until they click it.
3. **Wait for the click.** `GET /support/api/account/status?signup_id=...` until `"status": "confirmed"`.
4. **Create the account, or log in.** `POST /support/api/account/create {"signup_id", "name", "password"}` returns a `token`. If `"account_exists": true`, use `POST /support/api/login {"email", "password"}` instead. Send `Authorization: Bearer <token>` from then on.
5. **Add the address.** `POST /support/api/addresses` with `full_name`, `phone`, `address_line_1`, `city`, `country` (and `state` in the US), plus an optional `billing` address.
6. **Check out.** `POST /support/api/checkout {"s": "75830+2"}` saves the order on the person's account and returns a `payment_url`, plus `payment_options` (Stripe: card and local methods; PayPal). **Give the person a link to pay.**
7. **Follow it.** `GET /support/api/orders/{order_id}` gives the order in full: status (`awaiting_payment`, `awaiting_review`, `paid`), items, address, charges, and each parcel with its courier, tracking number and link and delivery status. `GET /support/api/orders` lists all paid orders and `GET /support/api/carts` all unpaid carts. `POST /support/api/orders/{order_id}/pay` gives fresh payment links (add `"amount"` to pay part now); `GET /support/api/orders/{order_id}/wire` gives bank transfer details.

The same token works for the rest of the customer area, documented at <https://zh-hant.decentespresso.com/support/api/#customer>: change an order's address or notes, stop it, re-order, email a receipt, account settings and password reset, the person's machines and warranty, payment history, messages to Decent support, and nearby Decent ambassadors. The guide is public: no account is needed to read it.

Without an account, `https://zh-hant.decentespresso.com/c?s=NUMBER+QUANTITY+...` opens the website cart already filled in, for the person to check out themselves.

## MCP server

This data, and buying, as tools for AI assistants over the Model Context Protocol: https://zh-hant.decentespresso.com/mcp (Streamable HTTP). Product, quote and docs tools need no login; addresses and checkout need the person's login: OAuth for MCP clients (or https://zh-hant.decentespresso.com/mcp/account, which asks for it as soon as you connect), else the `login` tool's token sent as `Authorization: Bearer <token>`. Agents with a Stripe Shared Payment Token can pay an order themselves with `pay_order` (MPP). Claude Code: `claude mcp add --transport http decent https://zh-hant.decentespresso.com/mcp`. Open https://zh-hant.decentespresso.com/mcp in a browser for the tool list.

## Owners: support MCP server

The customer area as an MCP server: https://zh-hant.decentespresso.com/support/mcp (login required when connecting): the owner's machines and every shot their Decent app uploaded (list, filter, compare curves, profile changes, export), orders and tracking, payments, and messages with Decent support. It wraps https://zh-hant.decentespresso.com/support/api/.

## Cocktails

Decent Cocktails has its own API and MCP server: cocktail recipes in grams from The PDT Cocktail Book and Death & Co, ingredients and search at https://zh-hant.decentespresso.com/cocktails/api/ (guide, OpenAPI, no account), and the MCP server https://zh-hant.decentespresso.com/cocktails/mcp, which with a free account also keeps Your Bar ("what can I make?") and a Wishlist (https://zh-hant.decentespresso.com/cocktails/mcp/account to sign in when connecting).

## Limits

- 120 requests per minute per IP address; over that you get HTTP 429 with `Retry-After`.
- Availability is approximate and quotes are estimates: the cart page shows the final total, including any coupon, before payment.
- Responses may be cached for 10 minutes; cart quotes are not cached.
- Customer data is never served under `/api/`.

## Licence and credit

- **Decent Espresso's own product text, photos and data** are licensed under [Creative Commons Attribution 4.0](https://creativecommons.org/licenses/by/4.0/) (CC BY 4.0).
- Trademarks and logos (Decent, DE1, Bengle) and third-party content are not covered. Details: <https://zh-hant.decentespresso.com/license>
- **How to credit:** name "Decent Espresso" with a link to the product's `web_url`.
