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).

Statuses

Status	Description
`draft`	Initial state, fully editable
`sent`	Sent to the customer
`viewed`	Customer has viewed the invoice
`in_review`	Under review
`partial`	Partially paid
`paid`	Fully paid
`overdue`	Past due date, unpaid
`cancelled`	Cancelled
`refunded`	Fully 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"

Customers Quotes