Developer Reference

ReceiptIQ API

Integrate receipt extraction and search into your own product.

Base URLhttps://api.receiptiq.ai/v1Auth via Authorization: Bearer <token> header

Authentication

All API requests (except registration and login) require a bearer token in the Authorization header. Obtain a token by logging in or registering.

Step 1 — Get a token
POST https://api.receiptiq.ai/v1/api/auth/login
Content-Type: application/json

{
  "email": "you@example.com",
  "password": "yourpassword"
}

// Response:
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
Step 2 — Authenticate every request
GET https://api.receiptiq.ai/v1/api/receipts
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

Endpoints

POST/api/auth/register

Create a new user account and receive an authentication token.

Request
{
  "email": "user@example.com",
  "password": "secret123",
  "name": "Jane Smith"       // optional
}
Response
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
POST/api/auth/login

Authenticate with email and password to receive a bearer token.

Request
{
  "email": "user@example.com",
  "password": "secret123"
}
Response
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
GET/api/receipts

List all receipts for the authenticated user, sorted by upload date descending.

Request
// No request body. Pass Authorization header:
// Authorization: Bearer <token>
Response
[
  {
    "id": "rcpt_abc123",
    "vendor": "Staples",
    "total": 42.99,
    "currency": "USD",
    "date": "2026-03-15",
    "status": "done",
    "created_at": "2026-03-15T14:22:00Z"
  },
  ...
]
POST/api/receipts/upload

Upload a receipt image or PDF. Accepts multipart/form-data with a "file" field. Returns the created receipt object immediately with status "processing".

Request
// multipart/form-data
// Field: file  (image/jpeg, image/png, application/pdf)
Response
{
  "id": "rcpt_xyz789",
  "status": "processing",
  "vendor": null,
  "total": null,
  "currency": null,
  "date": null,
  "created_at": "2026-04-05T09:11:00Z"
}
GET/api/receipts/:id

Retrieve a single receipt with full extracted data including line items.

Request
// No request body.
// Replace :id with the receipt ID, e.g. /api/receipts/rcpt_abc123
Response
{
  "id": "rcpt_abc123",
  "vendor": "Staples",
  "total": 42.99,
  "currency": "USD",
  "date": "2026-03-15",
  "status": "done",
  "line_items": [
    { "description": "A4 Paper (500 sheets)", "quantity": 2, "unit_price": 14.99, "total": 29.98 },
    { "description": "Ballpoint Pens (12pk)",  "quantity": 1, "unit_price": 13.01, "total": 13.01 }
  ],
  "created_at": "2026-03-15T14:22:00Z"
}
GET/api/receipts/:id/export/csv

Download the receipt and its line items as a CSV file. Returns a file attachment.

Request
// No request body. Replace :id with the receipt ID.
Response
// Response: Content-Type: text/csv
// Content-Disposition: attachment; filename="receipt_abc123.csv"
id,vendor,total,currency,date,description,quantity,unit_price,line_total
rcpt_abc123,Staples,42.99,USD,2026-03-15,A4 Paper (500 sheets),2,14.99,29.98
rcpt_abc123,Staples,42.99,USD,2026-03-15,Ballpoint Pens (12pk),1,13.01,13.01
POST/api/receipts/:id/retry

Re-run AI extraction on a receipt that failed or returned incomplete data.

Request
// No request body. Replace :id with the receipt ID.
Response
{
  "id": "rcpt_abc123",
  "status": "processing",
  "vendor": null,
  "total": null,
  "created_at": "2026-03-15T14:22:00Z"
}
POST/api/search

Semantic and keyword search across all uploaded receipts. Supports natural language queries.

Request
{
  "query": "coffee shop January"
}
Response
{
  "query": "coffee shop January",
  "results": [
    {
      "id": "rcpt_def456",
      "vendor": "Blue Bottle Coffee",
      "total": 8.50,
      "date": "2026-01-12",
      "score": 0.94
    },
    ...
  ]
}
GET/api/billing/status

Get the current billing status, plan, and upload quota for the authenticated user.

Request
// No request body.
Response
{
  "plan": "starter",
  "uploads_used": 47,
  "limit": 200,
  "has_subscription": true
}
POST/api/billing/create-checkout

Create a Stripe Checkout session for upgrading to a paid plan. Redirect the user to the returned URL.

Request
{
  "plan": "starter"  // "starter" | "pro"
}
Response
{
  "url": "https://checkout.stripe.com/pay/cs_test_..."
}
POST/api/billing/create-portal

Create a Stripe Customer Portal session for managing subscription, payment method, or cancellation.

Request
// No request body.
Response
{
  "url": "https://billing.stripe.com/session/..."
}

Webhooks

ReceiptIQ uses Stripe webhooks to keep billing in sync. Stripe sends signed POST requests to /api/billing/webhook. The endpoint verifies the Stripe signature before processing.

checkout.session.completed

Fired when a user completes a Stripe Checkout session. ReceiptIQ activates the subscription and increments the upload limit.

customer.subscription.updated

Fired when a subscription is modified — e.g. plan change, renewal, or payment failure. ReceiptIQ updates the plan and limit accordingly.

customer.subscription.deleted

Fired when a subscription is cancelled. ReceiptIQ downgrades the account to the Free plan at the end of the billing period.

Rate Limits

Rate limits are enforced per user account. When exceeded, the API returns a 429 Too Many Requests response with a Retry-After header.

Free
10 requests / minute
Starter
60 requests / minute
Pro
120 requests / minute