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

Bash
 1curl -X POST "https://api.corebill.io/v1/invoices?company_id=com_abc123" \
 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

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:

texttext
 1subtotal = SUM(quantity * unit_price)
 2discount_amount = subtotal * (discount_value / 100)    // if percentage
 3subtotal_after_discount = subtotal - discount_amount
 4tax_amount = subtotal_after_discount * (tax_rate / 100)
 5total = subtotal_after_discount + tax_amount
 6amount_due = total - amount_paid

Amounts

All monetary amounts are in the major unit of the currency. $75 is represented as 75, not 7500.

Send an Invoice

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

Record a Payment

Bash
 1curl -X POST "https://api.corebill.io/v1/invoices/inv_abc123/record_payment?company_id=com_abc123" \
 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

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

Refund an Invoice

Bash
 1curl -X POST "https://api.corebill.io/v1/invoices/inv_abc123/refund?company_id=com_abc123" \
 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.

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

Filtering

Bash
 1# By status
 2curl "https://api.corebill.io/v1/invoices?company_id=com_abc123&status=overdue" \
 3  -H "Authorization: Bearer sk_live_your_api_key"
 4
 5# By customer
 6curl "https://api.corebill.io/v1/invoices?company_id=com_abc123&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?company_id=com_abc123&status=sent&customer_id=cus_abc123&limit=10" \
11  -H "Authorization: Bearer sk_live_your_api_key"
CustomersQuotes