Skip to main content
POST
/
invoices
Create an invoice
curl --request POST \
  --url https://api.corebill.io/v1/invoices \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customer_id": "cus_a1b2c3d4e5f6",
  "issue_date": "2025-04-15",
  "due_date": "2025-05-15",
  "currency": "USD",
  "notes": "Thank you for your business",
  "payment_terms": "Net 30",
  "tax_rate": 16,
  "discount_type": "percentage",
  "discount_value": 10,
  "items": [
    {
      "name": "Web Development",
      "description": "Full-stack web application development",
      "quantity": 40,
      "unit": "hour",
      "unit_price": 150
    },
    {
      "name": "UI/UX Design",
      "description": "User interface and experience design",
      "quantity": 20,
      "unit": "hour",
      "unit_price": 120
    }
  ]
}
'
{
  "data": {
    "id": "inv_s9t0u1v2w3x4",
    "invoice_number": "INV-2025-000002",
    "customer_id": "cus_a1b2c3d4e5f6",
    "status": "draft",
    "issue_date": "2025-04-15",
    "due_date": "2025-05-15",
    "subtotal": 8400,
    "discount_type": "percentage",
    "discount_value": 10,
    "discount_amount": 840,
    "subtotal_after_discount": 7560,
    "tax_rate": 16,
    "tax_amount": 1209.6,
    "total": 8769.6,
    "amount_paid": 0,
    "amount_due": 8769.6,
    "currency": "USD",
    "notes": "Thank you for your business",
    "payment_terms": "Net 30",
    "public_token": "1713182400000-k8x2m9p4q7w1",
    "created_at": "2025-04-15T12:00:00.000Z",
    "customer": {
      "id": "cus_a1b2c3d4e5f6",
      "name": "John Doe",
      "contact_email": "[email protected]"
    },
    "items": [
      {
        "id": "di_y5z6a7b8c9d0",
        "item_name": "Web Development",
        "description": "Full-stack web application development",
        "quantity": 40,
        "unit": "hour",
        "unit_price": 150,
        "subtotal": 6000,
        "total": 6000,
        "sort_order": 0
      },
      {
        "id": "di_e1f2g3h4i5j6",
        "item_name": "UI/UX Design",
        "description": "User interface and experience design",
        "quantity": 20,
        "unit": "hour",
        "unit_price": 120,
        "subtotal": 2400,
        "total": 2400,
        "sort_order": 1
      }
    ]
  }
}
Create an invoice for the client for a specified amount. Make sure that the URLs that you provide in the url_success and url_failed fields use the secure HTTPS protocol, use domain names (not IP addresses) and are considered clean by VirusTotal and similar scanners. The end_user_reference parameter is used to group, track and analyse transactions made by a specific customer. To prevent transactions from getting delayed or cancelled, always make sure to include the correct ID. The ID must not contain any personal or identifying customer data. If you do not provide sender data in the request, the invoice will still be created, but your customer will be prompted for their data on the invoice form. If the customer is already registered in your system, include their end_user_reference and the sender_data object for a smoother user experience.

Authorizations

​
Authorization
string
header
required

API key authentication. Generate keys from the Corebill dashboard under the Developers section.

Example: Authorization: Bearer sk_live_abc123def456

Query Parameters

​
company_id
string
required

The company ID to scope the request to

Body

application/json
​
customer_id
string
required

Customer ID to associate with this invoice

Example:

"cus_a1b2c3d4e5f6"

​
issue_date
string<date>

Invoice issue date (defaults to today)

Example:

"2025-04-15"

​
due_date
string<date>

Payment due date (defaults to 30 days from issue_date)

Example:

"2025-05-15"

​
currency
string

Currency code (ISO 4217). Defaults to company currency or USD

Example:

"USD"

​
notes
string

Invoice notes visible to the customer

Example:

"Thank you for your business"

​
payment_terms
string

Payment terms description

Example:

"Net 30"

​
tax_rate
number

Tax rate as a percentage (e.g., 16 for 16%)

Example:

16

​
tax_id
string

Tax identifier or label

Example:

"VAT"

​
discount_type
enum<string>

Type of discount to apply

Available options:
percentage,
fixed
Example:

"percentage"

​
discount_value
number

Discount value (percentage or fixed amount)

Example:

10

​
items
object[]

Line items for the invoice

Response

Invoice created successfully

​
data
object
required

Full invoice object including items and public_token (returned by GET /invoices/{id} and POST /invoices)