CorebillCorebill
Start for free
Integrations

Node.js SDK

Typed client for the Corebill API with automatic pagination, safe retries and webhook verification.

Installation

Bash
 1npm install @corebill/sdk
TypeScript
 1import { Corebill } from '@corebill/sdk'
 2
 3const corebill = new Corebill({ apiKey: process.env.COREBILL_API_KEY! })
 4
 5const invoice = await corebill.invoices.create({
 6  customer_id: 'cus_abc123',
 7  line_items: [{ item_name: 'Consulting', quantity: 10, unit_price: 200 }],
 8})
 9await corebill.invoices.send(invoice.id)

Works with ESM and CommonJS (require('@corebill/sdk')) on Node.js 18 or newer. Each API key belongs to one company; corebill.account.retrieve() tells you which.

Resources

PropertyMethods
customerslist, listAutoPaginate, create, retrieve, update, del
quoteslist, listAutoPaginate, create, retrieve, update, del, send, approve, reject, convertToInvoice
invoiceslist, listAutoPaginate, create, retrieve, update, del, send, recordPayment, refund, cancel, markUncollectible
itemslist, listAutoPaginate, create, retrieve, update, del
expenseslist, listAutoPaginate, create, retrieve, update, del
vendors / expenseCategorieslist, create (vendors)
projectslist, create, retrieve, update, del, timeSummary, plus projects.tasks and projects.timeEntries
companieslist, retrieve
accountretrieve (company, organization and permission of the key)
eventslist, retrieve, plus the event types and test events
webhooksconstructEvent, generateTestHeader

Optional modules have their own resources, available while the module is on (otherwise the API answers 403 module_disabled, thrown as CorebillPermissionError):

PropertyModuleGuide
products, productCategories, productBrandsProductsProducts
warehouses, stock (with stock.movements, stock.reasons, stock.adjustments, stock.transfers)InventoryInventory
purchaseOrders, billsPurchasesPurchases
cashRegisters, cashSessions, cashMovementsCashCash
posSalesPoint of salePoint of Sale
workOrdersWork ordersWork Orders

Pagination

TypeScript
 1for await (const customer of corebill.customers.listAutoPaginate({ status: 'active' })) {
 2  console.log(customer.name)
 3}

Retries and Idempotency

Network errors, timeouts, 429 and 5xx responses are retried (2 times by default, honoring Retry-After). Every POST carries an Idempotency-Key, generated automatically, so a retry never creates a duplicate. Pass { idempotencyKey } as the last argument to dedupe across processes.

Verifying Webhooks

TypeScript
 1import express from 'express'
 2import { webhooks } from '@corebill/sdk'
 3
 4app.post('/webhooks/corebill', express.raw({ type: 'application/json' }), (req, res) => {
 5  try {
 6    const event = webhooks.constructEvent(req.body, req.get('Corebill-Signature'), process.env.COREBILL_WEBHOOK_SECRET!)
 7    // event.event === 'invoice.paid' ...
 8    res.sendStatus(200)
 9  } catch {
10    res.sendStatus(400)
11  }
12})

Errors

API errors throw typed classes: CorebillAuthenticationError, CorebillPermissionError, CorebillInvalidRequestError (with param), CorebillNotFoundError, CorebillRateLimitError and CorebillConnectionError. All extend CorebillAPIError with status, type and code.

MCP ServerCLI