CorebillCorebill
Start for free
Core Resources

Invoices

Create, manage, and track invoices through the API.

Overview

Invoices are the core billing documents in Corebill. They support line items, taxes, discounts, and payment tracking. Invoice numbers are auto-generated using your company's configured prefix.

Create an Invoice

 1curl -X POST "https://api.corebill.io/v1/invoices" \
 2  -H "Authorization: Bearer sk_live_your_api_key" \
 3  -H "Content-Type: application/json" \
 4  -d '{
 5    "customer_id": "cus_abc123",
 6    "due_date": "2026-07-15",
 7    "tax_rate": 16,
 8    "discount_type": "percentage",
 9    "discount_value": 10,
10    "payment_terms": "Net 30",
11    "notes": "Thank you for your business",
12    "line_items": [
13      {
14        "item_name": "Web Development",
15        "description": "Frontend implementation - React",
16        "quantity": 40,
17        "unit": "hour",
18        "unit_price": 75
19      }
20    ]
21  }'

Invoice Numbers

Numbers are generated automatically: {PREFIX}-{YEAR}-{COUNTER}

Example: INV-2026-000001

The prefix is configurable per company (default: INV).

A company can have several series (Settings > Prefixes). The number is assigned when the invoice is issued, with the default series or the one in series_id. List them with GET /v1/document-series?type=invoice and send series_id when creating the invoice.

Buyer

For a sale to a generic customer (walk-in), send buyer with the name and document of whoever buys: { "name": "Maria Lopez", "tax_id": "45578923", "tax_id_type": "1" }. No customer is created; the PDF and the official document use the buyer. tax_id_type uses the same codes as the customer identity document type (0, 1, 4, 6, 7). The invoice returns it in buyer.

Statuses

StatusDescription
draftInitial state, fully editable
sentSent to the customer
viewedCustomer has viewed the invoice
in_reviewUnder review
partialPartially paid
paidFully paid
overduePast due date, unpaid
cancelledCancelled
refundedFully or partially refunded

Calculations

Totals are calculated automatically when creating an invoice with items:

Output
 1// every amount is rounded to 2 decimals (major unit)
 2line.subtotal = quantity * unit_price
 3line.total    = line.subtotal - line discount          // no tax at line level
 4subtotal = SUM(line.total)
 5discount_amount = subtotal * (discount_value / 100)    // if percentage (fixed: discount_value, capped at subtotal)
 6subtotal_after_discount = subtotal - discount_amount
 7tax_amount = subtotal_after_discount * (tax_rate / 100)
 8total = subtotal_after_discount + tax_amount
 9amount_due = max(0, total - amount_paid)

Amounts

All monetary amounts are in the major unit of the currency with 2 decimals (major unit, 2 decimals). $1,234.56 is represented as 1234.56, never as cents (123456).

Send an Invoice

 1curl -X POST "https://api.corebill.io/v1/invoices/inv_abc123/send" \
 2  -H "Authorization: Bearer sk_live_your_api_key"

Record a Payment

 1curl -X POST "https://api.corebill.io/v1/invoices/inv_abc123/record_payment" \
 2  -H "Authorization: Bearer sk_live_your_api_key" \
 3  -H "Content-Type: application/json" \
 4  -d '{
 5    "amount": 2000,
 6    "payment_method": "bank_transfer",
 7    "transaction_id": "TXN-12345"
 8  }'

The invoice status transitions automatically: partial when partially paid, paid when fully paid.

Cancel an Invoice

 1curl -X POST "https://api.corebill.io/v1/invoices/inv_abc123/cancel" \
 2  -H "Authorization: Bearer sk_live_your_api_key" \
 3  -H "Content-Type: application/json" \
 4  -d '{ "cancellation_reason": "Duplicate invoice" }'

Refund an Invoice

 1curl -X POST "https://api.corebill.io/v1/invoices/inv_abc123/refund" \
 2  -H "Authorization: Bearer sk_live_your_api_key" \
 3  -H "Content-Type: application/json" \
 4  -d '{
 5    "amount": 1500,
 6    "reason": "Partial refund",
 7    "payment_method": "bank_transfer"
 8  }'

If amount is omitted, the full paid amount is refunded.

Editing Restrictions

  • Draft invoices: All fields can be updated
  • Non-draft invoices: Only notes, payment_terms, and status can be updated

Deleting Invoices

Invoices with status paid cannot be deleted. You must cancel them first.

 1curl -X DELETE "https://api.corebill.io/v1/invoices/inv_abc123" \
 2  -H "Authorization: Bearer sk_live_your_api_key"

Filtering

 1# By status
 2curl "https://api.corebill.io/v1/invoices?status=overdue" \
 3  -H "Authorization: Bearer sk_live_your_api_key"
 4
 5# By customer
 6curl "https://api.corebill.io/v1/invoices?customer_id=cus_abc123" \
 7  -H "Authorization: Bearer sk_live_your_api_key"
 8
 9# Combined with pagination
10curl "https://api.corebill.io/v1/invoices?status=sent&customer_id=cus_abc123&limit=10" \
11  -H "Authorization: Bearer sk_live_your_api_key"
CustomersCredit and Collection