Search
K

Hot Dog Stand API

A pragmatic REST API for running a fleet of delightful hot dog stands: menus, orders, payments, inventory, loyalty, and webhooks.

Base URL

  • Production: https://api.franks.io/v1
  • Sandbox: https://sandbox.api.franks.io/v1

All requests use HTTPS. JSON only.

Versioning

  • URI based versioning. Example: /v1/orders
  • Backward compatible changes include new optional fields and new endpoints.

Authentication

  • Header: Authorization: Bearer <api_key>
  • Keys are scoped to an organization. Rotate keys regularly.
  • 401 means the key is missing or invalid. 403 means the key is valid but lacks scope.

OAuth 2.0 (optional)

  • Grant types: Client Credentials, Authorization Code with PKCE
  • Scopes: orders:read, orders:write, menu:read, menu:write, payments:write, inventory:write, loyalty:write

Idempotency

  • Header: Idempotency-Key: <uuid> for POST, PUT, PATCH that modify state.
  • The server returns the same result for the same key within 24 hours.

Rate Limits

  • Default: 120 requests per minute per API key.
  • Response headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Pagination

  • Cursor based.
  • Query params: limit (1..200), cursor.
  • Response fields: next_cursor, previous_cursor.

Errors

{
  "error": {
    "type": "validation_error",
    "message": "Quantity must be positive",
    "code": "QTY_POSITIVE",
    "docs_url": "https://api.franks.io/docs/errors#QTY_POSITIVE",
    "param": "items[0].quantity"
  }
}
  • Common types: validation_error, authentication_error, authorization_error, rate_limit_error, conflict_error, not_found.

Resources

1) Stands

Represents a physical cart or kiosk.

Object

{
  "id": "std_9xXk8",
  "name": "Union Square Cart",
  "status": "open",
  "timezone": "America/New_York",
  "address": {
    "line1": "14th St and Broadway",
    "city": "New York",
    "region": "NY",
    "postal_code": "10003",
    "country": "US"
  },
  "hours": [
    {"day": "mon", "open": "10:00", "close": "18:00"}
  ],
  "created_at": "2025-02-18T15:23:11Z",
  "updated_at": "2025-07-01T11:02:45Z"
}

List stands

GET /stands?status=open&limit=50&cursor=...

Retrieve a stand

GET /stands/{stand_id}

Update a stand

PATCH /stands/{stand_id}
Content-Type: application/json

Body example:

{"status":"closed"}

2) Menu Items

Individual products that can be ordered.

Object

{
  "id": "mi_classic_dog",
  "stand_id": "std_9xXk8",
  "name": "Classic Dog",
  "description": "Beef hot dog in a toasted bun",
  "price": 450,
  "currenc