POST /api/invoices — Create and Send a USDC Invoice

Generate a USDC invoice with line items and a PDF. Kibble provisions a deposit address, emails the vendor, and fires a signed webhook when payment arrives.

Call POST /api/invoices to create a USDC invoice. Kibble generates a line-item breakdown, calculates the total, renders a PDF, provisions a unique deposit address on Base, and — by default — emails the vendor a link to the hosted invoice page at https://pay.kibble.sh/i/{slug}. Optionally, you can suppress the email with send_now: false and trigger it later using POST /api/invoices/{id}/send.

Request

POST https://pay.kibble.sh/api/invoices
Content-Type: application/json

Body parameters

Merchant

merchant_email · string · required

Your email address as the billing merchant. Kibble uses this to identify your account and provision your managed wallet when wallet_type is "privy".

merchant_name · string · required

Your business name as it appears on the invoice.

merchant_address · string · required

Your business address as it appears on the invoice. This value is captured at creation time and cannot be changed after the invoice is created.

Vendor

vendor_email · string · required

The vendor’s email address. Kibble sends the invoice to this address (unless send_now is false).

vendor_name · string · required

The vendor’s name as it appears on the invoice.

vendor_address · string

The vendor’s address. Optional — displayed on the invoice if provided.

Line items

line_items · object[] · required

An array of between 1 and 30 line items. Each item contributes to the invoice total.

Show line item properties

description · string · required

A human-readable description of the product or service (e.g. "Consulting — April").

quantity · number · required

A positive number representing how many units are being billed.

unit_price · string · required

The USDC price per unit, as a positive decimal string (e.g. "150.00"). Kibble multiplies this by quantity to calculate line_total.

Dates

issue_date · string

The invoice issue date in YYYY-MM-DD format. Defaults to today if omitted.

due_date · string · required

The payment due date in YYYY-MM-DD format. Kibble uses this to compute the overdue field.

Wallet

wallet_type · string · required

How Kibble resolves your receiving wallet. Use "privy" for a Kibble-managed wallet or "byo" to supply your own address.

wallet_address · string

Required when wallet_type is "byo". Must be a valid EVM address in checksum format.

Options

notes · string

Optional free-text notes displayed at the bottom of the invoice (e.g. "Net 30").

webhook_url · string

A publicly reachable URL that Kibble will POST to when the invoice reaches paid, partial, or excess status. The request is signed with an HMAC secret — see Webhooks for verification details.

send_now · boolean · default: "true"

Set to false to create the invoice without emailing the vendor. Use POST /api/invoices/{id}/send to send the email when you are ready.

Example request

cURL

curl --request POST \
  --url https://pay.kibble.sh/api/invoices \
  --header 'Content-Type: application/json' \
  --data '{
    "merchant_email": "[e-mail]",
    "merchant_name": "Acme SaaS",
    "merchant_address": "123 Main St, San Francisco, CA 94105",
    "vendor_email": "[e-mail]",
    "vendor_name": "Vendor Co",
    "vendor_address": "456 Market Ave, New York, NY 10001",
    "line_items": [
      {
        "description": "Consulting — April",
        "quantity": 10,
        "unit_price": "150.00"
      }
    ],
    "due_date": "2026-05-28",
    "notes": "Net 30",
    "wallet_type": "privy",
    "webhook_url": "https://your-app.com/webhooks/kibble",
    "send_now": true
  }'

Response

A successful request returns 201 Created with the following fields.

invoice_id · string · required

The UUID for this invoice. Use it in all subsequent API calls that reference this invoice.

invoice_number · string · required

A human-readable invoice identifier (e.g. "INV-0001"). Increments automatically for each new invoice.

slug · string · required

The short identifier used in the hosted invoice URL.

invoice_url · string · required

The hosted invoice page URL. Send this to your vendor so they can review the invoice and pay.

pdf_url · string · required

The URL to download the invoice as a PDF. See Download invoice PDF.

deposit_address · string · required

The on-chain USDC deposit address on Base where the vendor should send payment.

total_amount · string · required

The sum of all line item totals, in USDC (e.g. "1500.00").

sent_at · string

ISO 8601 timestamp of when the vendor email was sent. null if send_now was false.

webhook_secret · string

The HMAC secret used to sign webhook requests. Only present when you provided a webhook_url. Store this securely — you need it to verify incoming webhook signatures.

Example response

201

{
  "invoice_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "invoice_number": "INV-0001",
  "slug": "abc12345",
  "invoice_url": "https://pay.kibble.sh/i/abc12345",
  "pdf_url": "https://pay.kibble.sh/api/invoices/a1b2c3d4-e5f6-7890-abcd-ef1234567890/pdf",
  "deposit_address": "0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B",
  "total_amount": "1500.00",
  "sent_at": "2026-04-28T12:00:00Z",
  "webhook_secret": "whs_abc123..."
}

webhook_secret is returned only once, at creation time. If you lose it, you will need to create a new invoice with a fresh webhook_url to get a new secret.

Errors

Status	Cause
400	One or more fields failed validation. The response body contains field-level error details.
500	Kibble could not provision your wallet or save the invoice to the database.