Skip to main content
Calling POST /api/invoices creates an invoice record, generates a PDF, provisions a USDC deposit address on Base, and — by default — emails the invoice to your vendor immediately. The response includes everything you need to track payment: a hosted invoice URL, a PDF download link, and an optional webhook secret if you provided a webhook_url.

​
Request

cURL
curl -X POST https://pay.kibble.sh/api/invoices \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_email": "you@example.com",
    "merchant_name": "Acme SaaS",
    "merchant_address": "123 Main St, SF",
    "vendor_email": "vendor@example.com",
    "vendor_name": "Vendor Co",
    "vendor_address": "456 Oak Ave, NY",
    "line_items": [
      {
        "description": "Consulting",
        "quantity": 10,
        "unit_price": "150.00"
      }
    ],
    "issue_date": "2026-04-28",
    "due_date": "2026-05-28",
    "notes": "Net 30",
    "wallet_type": "privy",
    "webhook_url": "https://example.com/webhooks/kibble",
    "send_now": true
  }'

​
Request fields

​
merchant_email
string
required
Your email address as the billing merchant. Appears in the invoice record.
​
merchant_name
string
required
Your business name. Written to the invoice at creation time and never updated — see immutable fields.
​
merchant_address
string
required
Your business address. Printed on the generated PDF invoice.
​
vendor_email
string
required
The email address where Kibble sends the invoice. This is your customer or the party you are billing.
​
vendor_name
string
required
The vendor’s display name, shown on the invoice PDF and hosted page.
​
vendor_address
string
The vendor’s mailing address. Optional; included on the PDF if provided.
​
line_items
object[]
required
One to 30 line items that make up the invoice total. Each item is an object with the following fields:
​
due_date
string
required
The payment due date in YYYY-MM-DD format. Used to compute the overdue flag on the invoice.
​
issue_date
string
default:"today"
The invoice issue date in YYYY-MM-DD format. Defaults to today’s date if omitted.
​
notes
string
Optional free-text notes printed at the bottom of the invoice, such as payment terms ("Net 30").
​
wallet_type
string
required
How Kibble provisions the USDC deposit address. Use "privy" for a Kibble-managed wallet or "byo" to supply your own wallet address.
​
wallet_address
string
Your USDC wallet address on Base. Required when wallet_type is "byo".
​
webhook_url
string
A URL that Kibble calls with a signed POST request when the invoice is paid, partially paid, or overpaid. See webhooks.
​
send_now
boolean
default:"true"
When true, Kibble emails the vendor immediately after the invoice is created. Set to false to create a draft invoice without sending the email.

​
Response

A successful request returns HTTP 201 with the following body: 
{
  "invoice_id": "a1b2c3d4-...",
  "invoice_number": "INV-0001",
  "slug": "abc12345",
  "invoice_url": "https://pay.kibble.sh/i/abc12345",
  "pdf_url": "https://pay.kibble.sh/api/invoices/a1b2c3d4-.../pdf",
  "deposit_address": "0x1234...",
  "total_amount": "1500.00",
  "sent_at": null,
  "webhook_secret": "abc..."
}
​
invoice_id
string
required
The UUID for this invoice. Use it in all subsequent API calls.
​
invoice_number
string
required
A human-readable invoice number (e.g., INV-0001). Written once at creation and never changed.
​
slug
string
required
Short identifier used in the hosted invoice URL.
​
invoice_url
string
required
The URL of the hosted invoice page at https://pay.kibble.sh/i/{slug}. Share this with your vendor or embed it in your own UI.
​
pdf_url
string
required
Direct URL to download the invoice PDF. See download the PDF below.
​
deposit_address
string
required
The USDC wallet address on Base where the vendor sends payment.
​
total_amount
string
required
The sum of all line items, in USDC (e.g., "1500.00").
​
sent_at
string
ISO 8601 timestamp of when the vendor email was sent. null if the invoice is still a draft.
​
webhook_secret
string
The HMAC secret used to verify incoming webhook payloads. Only present when webhook_url was provided. Store this value securely — it is not returned again.

​
Create a draft without sending

Set send_now: false to create the invoice without emailing the vendor. The invoice will have status draft until you send it.
cURL
# Include all required fields (merchant_email, merchant_name, vendor_email, etc.)
# and set send_now to false:
curl -X POST https://pay.kibble.sh/api/invoices \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_email": "you@example.com",
    "merchant_name": "Acme SaaS",
    "merchant_address": "123 Main St, SF",
    "vendor_email": "vendor@example.com",
    "vendor_name": "Vendor Co",
    "line_items": [{ "description": "Consulting", "quantity": 1, "unit_price": "500.00" }],
    "due_date": "2026-05-28",
    "wallet_type": "privy",
    "send_now": false
  }'
When you are ready to send, call the send endpoint:
cURL
curl -X POST https://pay.kibble.sh/api/invoices/{id}/send
POST /api/invoices/{id}/send is not idempotent — each call sends a new email to the vendor. Use it deliberately.

​
Download the PDF

The invoice PDF is generated server-side and available immediately after creation.
cURL
curl -o invoice.pdf https://pay.kibble.sh/api/invoices/{id}/pdf
You can also get the URL from the pdf_url field in the create response.