> API Documentation

Complete API reference for JSONBill - create PDF invoices and settlement statements from JSON data

Overview

JSONBill is a super lightweight JSON-based billing system. It provides a RESTful API for creating PDF invoices and settlement statements from JSON data.

Related: x402 Payments

Authentication

All API endpoints require authentication via the Authorization header:

Authorization: Bearer <token>

The <token> can be either a JWT token or an API key. The system automatically detects the token type.

Credits

Each PDF generation costs 1 Quaily credit. When using API key authentication, your credit balance is checked before task creation. Ensure you have sufficient credits in your account.

x402 Payments (v2)

JSONBill supports x402 v2 for pay-per-request onchain payments. Supported network/asset: Base (eip155:8453) USDC.

When paying with x402, you do not need the Authorization header. Detailed guide: x402 Payments.

Flow:

Call POST /tasks/docs without PAYMENT-SIGNATURE.
Receive 402 Payment Required with a PAYMENT-REQUIRED header (base64 PaymentRequired JSON).
Sign the payment using an x402 client and retry with PAYMENT-SIGNATURE.

Retry example (headers only):

Content-Type: application/json
PAYMENT-SIGNATURE: <base64 payment payload>

API Endpoints

Create Document Task

Endpoint: POST /tasks/docs

Description: Create a new PDF invoice or settlement statement generation task from JSON data.

Request Headers:

Content-Type: application/json
Authorization: Bearer <token>

Request Body Example:

{
  "type": "invoice",
  "lang": "en",
  "theme": "classic",
  "params": {
    "id": "20260102-INC-1",
    "date": "2026-01-02T09:30:01.001Z",
    "currency": "USD",
    "company_name": "Example Inc.",
    "company_address": "No.102, Roodwood St., Pasadena, CA, 98812",
    "company_email": "john@example.com",
    "tax_number": "123456789Z",
    "bill_to_company": "Hello Inc.",
    "bill_to_address": "2F House, AZ Church St, George, 119802",
    "doc": {
      "title": "Invoice",
      "description": "Consulting services for Dec 2025"
    },
    "summary": {
      "period_start": "2025-12-01T00:00:00.000Z",
      "period_end": "2026-01-01T00:00:00.000Z",
      "title": "Consulting Service",
      "currency": "USD",
      "total_include_tax": 10000,
      "tax_rate": 0.08,
      "total_include_tax_quote_amount": 1500000,
      "total_include_tax_quote_symbol": "JPY"
    },
    "detail_items": [
      {
        "date": "2025-12-15T00:00:00.000Z",
        "title": "Project Alpha - Phase 1",
        "desc": "Initial development and setup",
        "currency": "USD",
        "total_include_tax": 5000,
        "total_include_tax_quote_amount": 750000,
        "total_include_tax_quote_symbol": "JPY"
      },
      {
        "date": "2025-12-28T00:00:00.000Z",
        "title": "Project Alpha - Phase 2",
        "desc": "Testing and deployment",
        "url": "https://example.com/project-alpha",
        "total_include_tax": 5000
      }
    ],
    "payment": {
      "instruction": {
        "receive_account_bank": "Bank of George",
        "receive_account_branch": "Roodwood St. Branch",
        "receive_account_number": "12345-113",
        "receive_deposit_type": "Checking",
        "receive_account_name": "Example Inc"
      }
    }
  }
}

Request Parameters:

Parameter	Type	Required	Description
`type`	string	No	Document type: `invoice` or `settlementstatement`. Default: `invoice`
`lang`	string	No	Language code (`en`, `ja`, `zh_cn`, `zh_tw`). Default: `en`
`theme`	string	No	Document theme. Default: `classic`
`params`	object	Yes	Document data (see Document Data Format)

Settlement statement notes:

Use recipient_company / recipient_address instead of bill_to_company / bill_to_address.
payment.instruction is ignored; only payment.result is rendered.

Available Themes:

Theme	Description
`classic`	Traditional invoice layout, matches the baseline output
`modern`	Dashboard style with two-column layout for bill-to and summary sections
`compact`	Denser version of modern, reduced whitespace, more one-page friendly
`spotlight`	Big total/payment amount upfront, then details - good for quick scanning
`ledger`	Accounting style with details first, totals and summary at the end
`split`	Details first, then two-column footer with payment and summary side by side

Preview the PDF output for each theme: Theme Samples.

Response:

{
  "data": {
    "id": 1,
    "trace_id": "f4730554-791c-463b-9a27-aeacdfb02cf2",
    "status": 0,
    "created_at": "2026-01-02T09:30:01.001Z",
    "updated_at": "2026-01-02T09:30:01.001Z"
  },
  "ts": 1767766187
}

Task Status Codes:

0: Init (task created)
1: Scheduled
2: Running
3: Completed
4: Error

Query Task Status

Endpoint: GET /tasks/{traceID}

Description: Check the status of a document generation task.

Response:

{
  "data": {
    "id": 1,
    "trace_id": "f4730554-791c-463b-9a27-aeacdfb02cf2",
    "status": 3,
    "created_at": "2026-01-02T09:30:01.001Z",
    "updated_at": "2026-01-02T09:30:05.001Z"
  },
  "ts": 1767766191
}

Download PDF

Endpoint: GET /tasks/{traceID}.pdf

Description: Download the generated PDF document. Only available when task status is 3 (Completed).

Response: PDF file

Note: The PDF file will be removed from the server after 1 hour.

Check Credit Balance

Endpoint: GET /proxy/credits/balance

Description: Check your current credit balance.

Response:

{
  "data": {
    "user_id": 123,
    "balance_credit": "10.00",
    "status": 1
  },
  "ts": 1767766187
}

Document Data Format

Basic Document Fields

Field	Type	Required	Description
`id`	string	No	Document ID/number
`date`	string	No	Document date (ISO 8601 format)
`currency`	string	No	Currency code (e.g., `USD`, `EUR`, `JPY`, `CNY`). Supports any currency code.
`company_name`	string	Yes	Your company name
`company_address`	string	No	Your company address
`company_email`	string	No	Your company email
`tax_number`	string	No	Tax registration number
`bill_to_company`	string	No	Client company name (invoice only)
`bill_to_address`	string	No	Client address (invoice only)
`recipient_company`	string	No	Recipient company name (settlement statement)
`recipient_address`	string	No	Recipient address (settlement statement)
`doc`	object	No	Document info (see Document Fields)

Document Fields

The doc object controls the document title and description shown on the document:

Field	Type	Required	Description
`title`	string	No	Document title
`description`	string	No	Document description

Summary Fields

The summary object contains the document totals and period information:

Field	Type	Required	Description
`title`	string	No	Summary title/description
`period_start`	string	No	Billing period start date (ISO 8601)
`period_end`	string	No	Billing period end date (ISO 8601)
`currency`	string	No	Currency code for this summary (defaults to top-level `currency`)
`total_exclude_tax`	number	No	Total amount excluding tax
`total_include_tax`	number	No	Total amount including tax
`tax`	number	No	Tax amount
`tax_rate`	number	No	Tax rate (e.g., `0.08` for 8%)
`total_include_tax_quote_amount`	number	No	Equivalent amount in quote currency
`total_include_tax_quote_symbol`	string	No	Quote currency symbol (e.g., `JPY`)

Notes:

total_exclude_tax and total_include_tax are mutually exclusive.
When using total_exclude_tax, provide either tax or tax_rate.

Quote Currency Example:

When invoicing in USD but your client prefers to see the amount in their local currency:

"summary": {
  "total_include_tax": 10000,
  "total_include_tax_quote_amount": 1500000,
  "total_include_tax_quote_symbol": "JPY"
}

This displays an implied exchange rate of 1 USD = 150 JPY on the document.

Excluding Tax Example:

"summary": {
  "total_exclude_tax": 9259.26,
  "tax": 740.74
}

Detail Items

The detail_items array contains line items for the document:

Field	Type	Required	Description
`date`	string	No	Item date (ISO 8601)
`title`	string	No	Item title
`desc`	string	No	Item description
`url`	string	No	Related URL
`currency`	string	No	Currency code for this item (defaults to top-level `currency`)
`total_exclude_tax`	number	No	Item amount excluding tax
`total_include_tax`	number	No	Item amount including tax
`total_include_tax_quote_amount`	number	No	Equivalent amount in quote currency (item-level)
`total_include_tax_quote_symbol`	string	No	Quote currency symbol (item-level)
`tax`	number	No	Item tax amount

Notes:

total_exclude_tax and total_include_tax are mutually exclusive.
When using total_exclude_tax, you can provide tax.

Example:

"detail_items": [
  {
    "date": "2025-12-15T00:00:00.000Z",
    "title": "Consulting - Week 1",
    "desc": "Strategy planning and analysis",
    "total_exclude_tax": 2500,
    "tax": 200
  },
  {
    "date": "2025-12-22T00:00:00.000Z",
    "title": "Consulting - Week 2",
    "desc": "Implementation support",
    "url": "https://example.com/report",
    "total_exclude_tax": 2500,
    "tax": 200
  }
]

Payment Methods

The payment object has two optional sections:

instruction: how your client should pay.
result: payment outcome (optional).

Both sections support a disabled flag to hide them on the document.

Bank Transfer (Instruction)

"payment": {
  "instruction": {
    "receive_account_bank": "Bank of George",
    "receive_account_branch": "Roodwood St. Branch",
    "receive_account_number": "12345-113",
    "receive_deposit_type": "Checking",
    "receive_account_name": "Example Inc"
  }
}

SWIFT Transfer (Instruction)

"payment": {
  "instruction": {
    "receive_account_swift": "BOFAUS3N",
    "receive_account_number": "123456789",
    "receive_account_name": "Example Inc.",
    "receive_account_bank": "Bank of America",
    "receive_account_branch": "Charlotte, NC"
  }
}

Cryptocurrency (Instruction)

"payment": {
  "instruction": {
    "receive_crypto_network": "ETH Mainnet",
    "receive_crypto_address": "0x1234567890abcdef1234567890abcdef12345678",
    "receive_crypto_currency": "USDC",
    "receive_crypto_memo": ""
  }
}

Field	Description
`instruction.receive_crypto_network`	Blockchain network (e.g., ETH Mainnet, Polygon, Solana)
`instruction.receive_crypto_address`	Wallet address to receive payment
`instruction.receive_crypto_currency`	Cryptocurrency symbol (e.g., USDC, USDT, ETH)
`instruction.receive_crypto_memo`	Optional memo or destination tag (for networks like XRP, XLM)

Payment Result (Optional)

"payment": {
  "result": {
    "payment_method": "Bank transfer",
    "amount_paid": 5200,
    "currency": "USD",
    "paid_date": "2026-01-27",
    "tx_id": "TXN-12345"
  }
}

Field	Description
`result.payment_method`	Method used to pay (free text)
`result.amount_paid`	Amount actually paid
`result.currency`	Currency for the paid amount
`result.paid_date`	Payment date (ISO string)
`result.tx_id`	Transaction or reference ID

Table of Contents

Overview

Authentication

Credits

x402 Payments (v2)

API Endpoints

Create Document Task

Query Task Status

Download PDF

Check Credit Balance

Document Data Format

Basic Document Fields

Document Fields

Summary Fields

Detail Items

Payment Methods

Bank Transfer (Instruction)

SWIFT Transfer (Instruction)

Cryptocurrency (Instruction)

Payment Result (Optional)