API v1blend.ie/api/v1

Coffee-as-a-Service
API

Sell coffee, generate brands, and create AI-powered visual assets — all from a single API.

Quick start

curl https://blend.ie/api/v1/catalog/coffees \
  -H "X-Publishable-Key: pk_live_..."

Endpoints

Auth

API Key

Format

JSON

AI Models

Gemini 2.5

Commerce

Browse catalog, build carts, create orders. Everything to sell coffee from your site.

Brand AI

Upload a logo or describe your brand. AI generates identity, colors, fonts, and a live store.

Asset Generation

AI-generated hero images, social banners, textures, product backdrops, and more.

Getting Started

The blend.ie CaaS API lets you browse our coffee catalog, build carts, and create orders from your own website or app. Base URL:

Base URL

https://blend.ie/api/v1/

You get two keys when you sign up as a tenant:

Publishable Key

Client-safe. Read-only catalog access.

pk_live_...

Secret Key

Server-side only. Full access.

sk_live_...

Contact hello@blend.ie to get your API keys.

Authentication

Pass your key in the appropriate header. The API checks X-API-Key first (secret), then X-Publishable-Key (publishable).

Publishable key (client-safe)

Request

curl https://blend.ie/api/v1/catalog/coffees \
  -H "X-Publishable-Key: pk_live_your_key_here"

Secret key (server-side only)

Request

curl -X POST https://blend.ie/api/v1/cart \
  -H "X-API-Key: sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"items": [...]}'

Keys are SHA-256 hashed and compared with timing-safe equality. Expired or deactivated keys return 401 Unauthorized.

Catalog

Browse the coffees available in your tenant catalog. These endpoints accept either key type (publishable or secret).

List coffees

GET/api/v1/catalog/coffees

Query parameters

featuredstring

Set to "true" to return only featured coffees.

sortstring

Sort order: name_asc (default), name_desc, price_asc, price_desc.

limitnumber

Results per page. Default 20, max 100.

offsetnumber

Pagination offset. Default 0.

Example

curl "https://blend.ie/api/v1/catalog/coffees?featured=true&limit=5" \
  -H "X-Publishable-Key: pk_live_your_key_here"

Response

{
  "data": [
    {
      "id": "ethiopia-yirgacheffe",
      "name": "Ethiopia Yirgacheffe",
      "pricePerKg": 32.00,
      "price250g": 8.00,
      "price1kg": 32.00,
      "flavorProfile": ["blueberry", "jasmine", "citrus"],
      "featured": true,
      "notes": ["Bright acidity", "Floral aroma"],
      "process": "Washed",
      "region": "Yirgacheffe",
      "altitude": "1800-2200m",
      "country": "Ethiopia",
      "varietal": "Heirloom",
      "scaScore": 87,
      "recommendedRoast": "Light"
    }
  ],
  "meta": {
    "total": 12,
    "limit": 5,
    "offset": 0,
    "hasMore": true
  }
}

Get coffee by ID

GET/api/v1/catalog/coffees/:id

Returns full details for a single coffee.

Request

curl "https://blend.ie/api/v1/catalog/coffees/ethiopia-yirgacheffe" \
  -H "X-Publishable-Key: pk_live_your_key_here"

Cart

Carts are stateless, encoded as signed JWT tokens. Create a cart, add items, and pass the token to checkout. Write operations require a secret key.

Create a cart

POST/api/v1/cart

Body parameters

itemsCartItem[]required

Array of items (max 50). Each item needs:

coffeeIdstringrequired

Coffee ID from the catalog.

bagSizestringrequired

250g or 1000g.

quantitynumberrequired

Quantity (1-100).

grindstring

Default wholebean. Options: wholebean, filter, espresso, moka, aeropress, french-press.

Request

curl -X POST https://blend.ie/api/v1/cart \
  -H "X-API-Key: sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "coffeeId": "ethiopia-yirgacheffe",
        "bagSize": "250g",
        "quantity": 2,
        "grind": "filter"
      },
      {
        "coffeeId": "colombia-huila",
        "bagSize": "1000g",
        "quantity": 1,
        "grind": "wholebean"
      }
    ]
  }'

Response — 201 Created

{
  "data": {
    "cartToken": "eyJhbGciOiJIUzI1...",
    "items": [
      {
        "coffeeId": "ethiopia-yirgacheffe",
        "name": "Ethiopia Yirgacheffe",
        "bagSize": "250g",
        "grind": "filter",
        "quantity": 2,
        "unitPrice": 8.00,
        "lineTotal": 16.00
      },
      {
        "coffeeId": "colombia-huila",
        "name": "Colombia Huila",
        "bagSize": "1000g",
        "grind": "wholebean",
        "quantity": 1,
        "unitPrice": 28.00,
        "lineTotal": 28.00
      }
    ],
    "itemCount": 3,
    "subtotal": 44.00
  }
}

Retrieve a cart

GET/api/v1/cart?token=...

Pass the cart token as a query parameter to retrieve its contents with current prices.

Request

curl "https://blend.ie/api/v1/cart?token=eyJhbGciOiJIUzI1..." \
  -H "X-Publishable-Key: pk_live_your_key_here"

Add items to a cart

POST/api/v1/cart/items

Merge new items into an existing cart. If an item matches by coffeeId + bagSize + grind, quantities are summed. Requires a secret key.

Request

curl -X POST https://blend.ie/api/v1/cart/items \
  -H "X-API-Key: sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "cartToken": "eyJhbGciOiJIUzI1...",
    "items": [
      {
        "coffeeId": "brazil-santos",
        "bagSize": "250g",
        "quantity": 1,
        "grind": "espresso"
      }
    ]
  }'

Update a cart

PUT/api/v1/cart

Replace the entire cart with a new set of items. Requires a secret key.

Request

curl -X PUT https://blend.ie/api/v1/cart \
  -H "X-API-Key: sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "cartToken": "eyJhbGciOiJIUzI1...",
    "items": [
      {
        "coffeeId": "ethiopia-yirgacheffe",
        "bagSize": "1000g",
        "quantity": 3,
        "grind": "wholebean"
      }
    ]
  }'

Checkout

Create an order from a cart token. Validates the cart, calculates totals, creates a pending order, and fires the order.confirmed webhook. Requires a secret key.

POST/api/v1/checkout

Body parameters

cartTokenstringrequired

The signed cart token from the cart API.

customerobjectrequired

Customer details.

customer.emailstringrequired

Customer email address.

customer.namestring

Full name.

customer.phonestring

Phone number.

customer.typestring

personal (default) or business.

customer.companyNamestring

Company name (business orders).

customer.vatNumberstring

VAT number (business orders).

shippingobjectrequired

Shipping address.

shipping.addressstringrequired

Street address.

shipping.citystring

City.

shipping.statestring

State or county.

shipping.zipstring

Postal / Eircode.

shipping.countrystringrequired

ISO country code (e.g. IE, GB, DE).

shippingCostnumber

Shipping cost in EUR. Default 0.

vatRatenumber

VAT percentage. Default 0.

notesstring

Order notes.

Request

curl -X POST https://blend.ie/api/v1/checkout \
  -H "X-API-Key: sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "cartToken": "eyJhbGciOiJIUzI1...",
    "customer": {
      "email": "orders@example.com",
      "name": "Jane Murphy",
      "phone": "+353891234567"
    },
    "shipping": {
      "address": "12 Main Street",
      "city": "Dublin",
      "zip": "D02 XY45",
      "country": "IE"
    },
    "notes": "Please grind extra fine"
  }'

Response — 201 Created

{
  "data": {
    "checkoutId": "cm1a2b3c4d...",
    "orderNumber": "BL-260312-A1B2C3",
    "status": "pending",
    "summary": {
      "subtotal": 44.00,
      "shippingCost": 0,
      "vatRate": 0,
      "vatAmount": 0,
      "total": 44.00,
      "itemCount": 2
    },
    "items": [...],
    "customer": {
      "email": "orders@example.com",
      "name": "Jane Murphy"
    },
    "shipping": {
      "address": "12 Main Street",
      "city": "Dublin",
      "zip": "D02 XY45",
      "country": "IE"
    },
    "createdAt": "2026-03-12T10:30:00.000Z"
  }
}

Brand Generation

Generate a complete brand identity using Gemini AI. Provide a logo image (base64) or a text description, and the API returns brand colors, fonts, tagline, and optionally creates a live store. No API key required — this is a public onboarding endpoint.

POST/api/v1/brand/generate

Body parameters

logostring

Base64-encoded logo image. Provide this or description (or both).

logoMimeTypestring

MIME type of the logo (e.g. image/png, image/jpeg). Required when logo is provided.

descriptionstring

Text description of your brand (up to 500 chars). Provide this or logo.

answersobject

Optional brand questionnaire:

answers.namestring

Preferred brand name.

answers.vibestring

Brand vibe (e.g. "modern and minimal").

answers.audiencestring

Target audience.

answers.storystring

Brand story or origin.

answers.moodstring

Visual mood (e.g. "warm earth tones").

previewboolean

true = brand identity only. false (default) = create brand + live store.

Preview mode

Request — preview

curl -X POST https://blend.ie/api/v1/brand/generate \
  -H "Content-Type: application/json" \
  -d '{
    "description": "A cozy neighborhood cafe in Galway with rustic vibes",
    "answers": {
      "name": "Claddagh Coffee",
      "vibe": "warm, rustic, welcoming",
      "audience": "locals and tourists",
      "mood": "earth tones with a pop of teal"
    },
    "preview": true
  }'

Response

{
  "preview": true,
  "brand": {
    "brandName": "Claddagh Coffee",
    "tagline": "A taste of home",
    "colors": {
      "primary": "#2A7B6F",
      "secondary": "#D4A574",
      "accent": "#E8C547",
      "background": "#FAF6F1",
      "text": "#2C1810"
    },
    "fonts": {
      "heading": "Playfair Display",
      "body": "Source Sans Pro"
    },
    "personality": "Warm, authentic, community-focused"
  },
  "superPrompt": "A rustic cafe brand with warm earth tones..."
}

Full mode — create brand + live store

Request — full

curl -X POST https://blend.ie/api/v1/brand/generate \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Premium high-grade coffee for fitness enthusiasts",
    "answers": {
      "name": "Peak Roast",
      "vibe": "bold, energetic, clean",
      "audience": "athletes and gym-goers"
    }
  }'

Response — 201 Created

{
  "preview": false,
  "brand": {
    "brandName": "Peak Roast",
    "tagline": "Fuel your summit",
    "colors": { ... },
    "fonts": { ... }
  },
  "storeUrl": "https://blend.ie/store/peak-roast",
  "slug": "peak-roast",
  "tenantId": "cm1x2y3z..."
}

Rate limit: 5 requests per minute per IP. Full mode creates a tenant, generates store pages, and returns a live URL — the entire store is ready in seconds.

Brand Kit

Generate AI-powered visual assets for your brand — hero backgrounds, social banners, card textures, product backdrops, email headers, and more. Uses Gemini 2.5 Flash image generation.

POST/api/brand-kit/generate

Body parameters

targetstringrequired

"blend" for blend.ie assets, or "tenant" for a tenant store.

brandNamestring

Required when target="tenant". The tenant brand name.

colorsobject

Required when target="tenant". Brand color palette:

colors.primarystringrequired

Primary brand color (hex).

colors.secondarystringrequired

Secondary color (hex).

colors.accentstring

Accent color (hex).

colors.backgroundstring

Background color (hex).

colors.textstring

Text color (hex).

Request

curl -X POST https://blend.ie/api/brand-kit/generate \
  -H "Content-Type: application/json" \
  -d '{
    "target": "tenant",
    "brandName": "Claddagh Coffee",
    "colors": {
      "primary": "#2A7B6F",
      "secondary": "#D4A574",
      "accent": "#E8C547",
      "background": "#FAF6F1",
      "text": "#2C1810"
    }
  }'

Response

{
  "success": true,
  "brandName": "Claddagh Coffee",
  "assetCount": 6,
  "assets": [
    { "type": "hero-background", "filename": "hero-bg.png", "path": "/stores/claddagh-coffee/hero-bg.png" },
    { "type": "social-banner", "filename": "social-banner.png", "path": "/stores/claddagh-coffee/social-banner.png" },
    { "type": "card-texture", "filename": "card-texture.png", "path": "/stores/claddagh-coffee/card-texture.png" },
    { "type": "email-header", "filename": "email-header.png", "path": "/stores/claddagh-coffee/email-header.png" },
    { "type": "product-backdrop", "filename": "product-backdrop.png", "path": "/stores/claddagh-coffee/product-backdrop.png" },
    { "type": "logo-cloud", "filename": "logo-cloud.png", "path": "/stores/claddagh-coffee/logo-cloud.png" }
  ]
}

Generated asset types

Asset	blend.ie	Tenant	Description
hero-background	✓	✓	Wide panoramic hero section background
social-banner	✓	✓	Square social media banner (Instagram, etc.)
card-texture	✓	✓	Subtle card background texture
email-header	✓	✓	Wide email marketing header banner
product-backdrop	✓	✓	Product photography background
section-divider	✓	—	Horizontal cloud-wave divider strip
pattern-tile	✓	—	Seamless repeating background pattern
favicon-icon	✓	—	App icon / favicon
logo-cloud	—	✓	Brand icon element with cloud shape

Rate limit: 3 requests per 5 minutes. Each asset is AI-generated and saved to the public directory. Images are served at the paths shown in the response.

Webhooks

Register a webhook endpoint to receive real-time notifications about order lifecycle events. Payloads are signed with HMAC-SHA256 and delivered with up to 3 retry attempts.

Event types

Event	Description
order.confirmed	New order created and payment received
order.roasting	Order has entered the roasting queue
order.shipped	Order dispatched with tracking info
order.delivered	Order marked as delivered
order.cancelled	Order was cancelled
stock.low	A product is running low on stock

Payload format

Webhook delivery

// Delivered via POST to your registered URL
{
  "id": "evt_a1b2c3d4e5f6",
  "type": "order.confirmed",
  "createdAt": "2026-03-12T10:30:00.000Z",
  "data": {
    "orderId": "cm1a2b3c4d...",
    "orderNumber": "BL-260312-A1B2C3",
    "total": 44.00,
    "customerEmail": "orders@example.com",
    "itemCount": 2
  }
}

Verifying signatures

Every webhook includes an X-Blend-Signature header — an HMAC-SHA256 hex digest of the raw body. Always verify before processing.

Node.js verification

const crypto = require("crypto");

function verifyWebhook(body, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature, "hex"),
    Buffer.from(expected, "hex")
  );
}

app.post("/webhooks/blend", (req, res) => {
  const sig = req.headers["x-blend-signature"];
  if (!verifyWebhook(req.rawBody, sig, WEBHOOK_SECRET)) {
    return res.status(401).send("Invalid signature");
  }
  // Process event...
  res.status(200).send("OK");
});

Delivery behaviour

Payloads timeout after 10 seconds.
Failed deliveries are retried up to 3 times (1s, then 2s delay).
Each delivery includes an X-Blend-Event-Id header for idempotency.
Your endpoint must respond with a 2xx status to acknowledge receipt.

Rate Limits

All rate limits are per tenant and use a sliding window. When you hit a limit, the API returns 429 Too Many Requests with a Retry-After header.

Endpoint group	Limit	Window
Catalog (GET /catalog/*)	100 requests	1 minute
Cart (POST/GET/PUT /cart)	60 requests	1 minute
Cart items (POST /cart/items)	60 requests	1 minute
Checkout (POST /checkout)	20 requests	1 minute
Brand Generation (POST /v1/brand/generate)	5 requests	1 minute
Brand Kit (POST /brand-kit/generate)	3 requests	5 minutes

Response headers on every request:

Rate limit headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
Retry-After: 12

Error Responses

All errors follow a consistent format:

Error format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Each item requires a coffeeId string"
  }
}

Status	Code	Meaning
400	VALIDATION_ERROR	Invalid request body or parameters
400	INVALID_TOKEN	Cart token is invalid or expired
400	INVALID_COFFEE	Coffee ID not found in your catalog
400	EMPTY_CART	Cart has no items
401	UNAUTHORIZED	Missing or invalid API key
403	FORBIDDEN	Key type insufficient for endpoint
409	CONFLICT	Store name already taken (brand generation)
429	RATE_LIMITED	Rate limit exceeded
503	SERVICE_UNAVAILABLE	AI service not configured

blend.ie CaaS API v1

Questions? hello@blend.ie

blend.ie

{ "data": [ { "id": "ethiopia-yirgacheffe", "name": "Ethiopia Yirgacheffe", "pricePerKg": 32.00, "price250g": 8.00, "price1kg": 32.00, "flavorProfile": ["blueberry", "jasmine", "citrus"], "featured": true, "notes": ["Bright acidity", "Floral aroma"], "process": "Washed", "region": "Yirgacheffe", "altitude": "1800-2200m", "country": "Ethiopia", "varietal": "Heirloom", "scaScore": 87, "recommendedRoast": "Light" } ], "meta": { "total": 12, "limit": 5, "offset": 0, "hasMore": true } }

curl -X POST https://blend.ie/api/v1/cart \ -H "X-API-Key: sk_live_your_key_here" \ -H "Content-Type: application/json" \ -d '{ "items": [ { "coffeeId": "ethiopia-yirgacheffe", "bagSize": "250g", "quantity": 2, "grind": "filter" }, { "coffeeId": "colombia-huila", "bagSize": "1000g", "quantity": 1, "grind": "wholebean" } ] }'

{ "data": { "cartToken": "eyJhbGciOiJIUzI1...", "items": [ { "coffeeId": "ethiopia-yirgacheffe", "name": "Ethiopia Yirgacheffe", "bagSize": "250g", "grind": "filter", "quantity": 2, "unitPrice": 8.00, "lineTotal": 16.00 }, { "coffeeId": "colombia-huila", "name": "Colombia Huila", "bagSize": "1000g", "grind": "wholebean", "quantity": 1, "unitPrice": 28.00, "lineTotal": 28.00 } ], "itemCount": 3, "subtotal": 44.00 } }

curl -X POST https://blend.ie/api/v1/cart/items \ -H "X-API-Key: sk_live_your_key_here" \ -H "Content-Type: application/json" \ -d '{ "cartToken": "eyJhbGciOiJIUzI1...", "items": [ { "coffeeId": "brazil-santos", "bagSize": "250g", "quantity": 1, "grind": "espresso" } ] }'

curl -X PUT https://blend.ie/api/v1/cart \ -H "X-API-Key: sk_live_your_key_here" \ -H "Content-Type: application/json" \ -d '{ "cartToken": "eyJhbGciOiJIUzI1...", "items": [ { "coffeeId": "ethiopia-yirgacheffe", "bagSize": "1000g", "quantity": 3, "grind": "wholebean" } ] }'

curl -X POST https://blend.ie/api/v1/checkout \ -H "X-API-Key: sk_live_your_key_here" \ -H "Content-Type: application/json" \ -d '{ "cartToken": "eyJhbGciOiJIUzI1...", "customer": { "email": "orders@example.com", "name": "Jane Murphy", "phone": "+353891234567" }, "shipping": { "address": "12 Main Street", "city": "Dublin", "zip": "D02 XY45", "country": "IE" }, "notes": "Please grind extra fine" }'

{ "data": { "checkoutId": "cm1a2b3c4d...", "orderNumber": "BL-260312-A1B2C3", "status": "pending", "summary": { "subtotal": 44.00, "shippingCost": 0, "vatRate": 0, "vatAmount": 0, "total": 44.00, "itemCount": 2 }, "items": [...], "customer": { "email": "orders@example.com", "name": "Jane Murphy" }, "shipping": { "address": "12 Main Street", "city": "Dublin", "zip": "D02 XY45", "country": "IE" }, "createdAt": "2026-03-12T10:30:00.000Z" } }

curl -X POST https://blend.ie/api/v1/brand/generate \ -H "Content-Type: application/json" \ -d '{ "description": "A cozy neighborhood cafe in Galway with rustic vibes", "answers": { "name": "Claddagh Coffee", "vibe": "warm, rustic, welcoming", "audience": "locals and tourists", "mood": "earth tones with a pop of teal" }, "preview": true }'

{ "preview": true, "brand": { "brandName": "Claddagh Coffee", "tagline": "A taste of home", "colors": { "primary": "#2A7B6F", "secondary": "#D4A574", "accent": "#E8C547", "background": "#FAF6F1", "text": "#2C1810" }, "fonts": { "heading": "Playfair Display", "body": "Source Sans Pro" }, "personality": "Warm, authentic, community-focused" }, "superPrompt": "A rustic cafe brand with warm earth tones..." }

curl -X POST https://blend.ie/api/v1/brand/generate \ -H "Content-Type: application/json" \ -d '{ "description": "Premium high-grade coffee for fitness enthusiasts", "answers": { "name": "Peak Roast", "vibe": "bold, energetic, clean", "audience": "athletes and gym-goers" } }'

{ "preview": false, "brand": { "brandName": "Peak Roast", "tagline": "Fuel your summit", "colors": { ... }, "fonts": { ... } }, "storeUrl": "https://blend.ie/store/peak-roast", "slug": "peak-roast", "tenantId": "cm1x2y3z..." }

curl -X POST https://blend.ie/api/brand-kit/generate \ -H "Content-Type: application/json" \ -d '{ "target": "tenant", "brandName": "Claddagh Coffee", "colors": { "primary": "#2A7B6F", "secondary": "#D4A574", "accent": "#E8C547", "background": "#FAF6F1", "text": "#2C1810" } }'

{ "success": true, "brandName": "Claddagh Coffee", "assetCount": 6, "assets": [ { "type": "hero-background", "filename": "hero-bg.png", "path": "/stores/claddagh-coffee/hero-bg.png" }, { "type": "social-banner", "filename": "social-banner.png", "path": "/stores/claddagh-coffee/social-banner.png" }, { "type": "card-texture", "filename": "card-texture.png", "path": "/stores/claddagh-coffee/card-texture.png" }, { "type": "email-header", "filename": "email-header.png", "path": "/stores/claddagh-coffee/email-header.png" }, { "type": "product-backdrop", "filename": "product-backdrop.png", "path": "/stores/claddagh-coffee/product-backdrop.png" }, { "type": "logo-cloud", "filename": "logo-cloud.png", "path": "/stores/claddagh-coffee/logo-cloud.png" } ] }

Asset

blend.ie

Tenant

Description

hero-background

✓

Wide panoramic hero section background

social-banner

✓

Square social media banner (Instagram, etc.)

card-texture

✓

Subtle card background texture

email-header

✓

Wide email marketing header banner

product-backdrop

✓

Product photography background

section-divider

✓

—

Horizontal cloud-wave divider strip

pattern-tile

✓

—

Seamless repeating background pattern

favicon-icon

✓

—

App icon / favicon

logo-cloud

—

✓

Brand icon element with cloud shape

Event

Description

order.confirmed

New order created and payment received

order.roasting

Order has entered the roasting queue

order.shipped

Order dispatched with tracking info

order.delivered

Order marked as delivered

order.cancelled

Order was cancelled

stock.low

A product is running low on stock

// Delivered via POST to your registered URL { "id": "evt_a1b2c3d4e5f6", "type": "order.confirmed", "createdAt": "2026-03-12T10:30:00.000Z", "data": { "orderId": "cm1a2b3c4d...", "orderNumber": "BL-260312-A1B2C3", "total": 44.00, "customerEmail": "orders@example.com", "itemCount": 2 } }

Endpoint group

Limit

Window

Catalog (GET /catalog/*)

100 requests

1 minute

Cart (POST/GET/PUT /cart)

60 requests

1 minute

Cart items (POST /cart/items)

60 requests

1 minute

Checkout (POST /checkout)

20 requests

1 minute

Brand Generation (POST /v1/brand/generate)

5 requests

1 minute

Brand Kit (POST /brand-kit/generate)

3 requests

5 minutes

Status

Code

Meaning

400

VALIDATION_ERROR

Invalid request body or parameters

400

INVALID_TOKEN

Cart token is invalid or expired

400

INVALID_COFFEE

Coffee ID not found in your catalog

400

EMPTY_CART

Cart has no items

401

UNAUTHORIZED

Missing or invalid API key

403

FORBIDDEN

Key type insufficient for endpoint

409

CONFLICT

Store name already taken (brand generation)

429

RATE_LIMITED

Rate limit exceeded

503

SERVICE_UNAVAILABLE

AI service not configured

Coffee-as-a-ServiceAPI

Getting Started

Authentication

Publishable key (client-safe)

Secret key (server-side only)

Catalog

List coffees

Get coffee by ID

Cart

Create a cart

Retrieve a cart

Add items to a cart

Update a cart

Checkout

Brand Generation

Preview mode

Full mode — create brand + live store

Brand Kit

Generated asset types

Webhooks

Event types

Payload format

Verifying signatures

Delivery behaviour

Rate Limits

Error Responses

Coffee-as-a-ServiceAPI

Getting Started

Authentication

Publishable key (client-safe)

Secret key (server-side only)

Catalog

List coffees

Get coffee by ID

Cart

Create a cart

Retrieve a cart

Add items to a cart

Update a cart

Checkout

Brand Generation

Preview mode

Full mode — create brand + live store

Brand Kit

Generated asset types

Webhooks

Event types

Payload format

Verifying signatures

Delivery behaviour

Rate Limits

Error Responses

Coffee-as-a-Service
API

Coffee-as-a-Service
API