​
Welcome to the Roastify API

The Roastify API enables you to build, customize, and automate coffee product creation, order fulfillment, and more. Designed for seamless integration with e-commerce platforms, creator tools, and custom applications, the API provides robust endpoints for managing products, artwork, orders, and fulfillment.

​
Core Concepts

RESTful JSON API

All endpoints use standard HTTP methods and return JSON responses.

Authentication

Authenticate every request with your API key using the x-api-key header.

All requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail. The base URL for all API requests is:

https://api.roastify.app

Roastify uses a versioning scheme to indicate which version of the API is being used. The current version is v1. The version is specified in the URL path, e.g. /v1/….

https://api.roastify.app/v1/…

Requests are rate limited to 100 requests per minute. Exceeding this returns a 429 error.

Authenticate every request with your API key using the x-api-key header. More documentation on this can be found here.

​
Test vs Live Environments

Roastify provides separate environments for development and production:

Test Environment

  • For development and testing
  • Simulated transactions (no real charges)
  • Use your Test API Key
  • Recommended for integration and QA

Live Environment

  • For production use
  • Real transactions and charges
  • Use your Live API Key
  • Switch only after testing is complete

You can generate and manage both Test and Live API keys in the Developers section of your dashboard. Always verify which environment your key is for before making requests.

​
Quick Start Example

Make your first authenticated request to the API:

fetch('https://api.roastify.app/v1/orders', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Idempotency-Key': 'YOUR_IDEMPOTENCY_KEY', // only used for POST requests
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ items: [...], toAddress: {...} })
})
  • All requests must use HTTPS.
  • Replace YOUR_API_KEY with your actual key.
  • Replace YOUR_IDEMPOTENCY_KEY with a unique identifier for the request. This is only used for POST requests. Learn more about Idempotency.
  • See Authentication for details.

​
Error Handling

Roastify uses standard HTTP status codes:

  • 2xx: Success
  • 4xx: Client error (e.g., invalid input, authentication failure)
  • 5xx: Server error (rare)

Error responses include a JSON body with message and code fields.

​
Pagination

Requests that return multiple items will be paginated to 20 items by default. The API uses cursor-based pagination which gives users the flexibility to specify a pageSize parameter to control the number of items per page. Additionally, users can provide a cursor parameter to retrieve results starting from a specific point in the dataset.

​
pagination
object

​
Currency

All monetary values are represented in the currency’s smallest unit (cents). For example, 2400 represents $24.00 in USD. This is to avoid any unwanted rounding errors when dealing with currency. We express this as an integer to avoid floating point precision issues.

At the moment, Roastify only accepts USD

​
Next Steps

For a full list of endpoints and guides, explore the sidebar or search above.