Lumen Documentation

Create an invoice with optional line items and tax details. When status is set to issued, a customer-facing invoice number is generated and a PDF is queued for generation.

Authorization

bearerAuth

AuthorizationBearer <token>

Use your secret API key as the bearer token

In: header

Request Body

application/json

customerId*string

Match^cus_[A-Za-z0-9]{22}$

subscriptionId?string|null

status*string

Value in"draft" | "issued"

currency*string

issueDate?string|null

Formatdate-time

dueDate?string|null

Formatdate-time

subtotalCents?integer|null

taxAmountCents?integer|null

totalAmountCents?integer|null

If omitted, calculated as subtotal + tax.

effectiveTaxRate?string|null

taxJurisdiction?string|null

taxCalculationMethod?string|null

Value in"auto" | "manual" | "exempt"

manualTaxDescription?string|null

Free-form description stored when taxCalculationMethod is manual.

notes?string|null

lineItems?

Response Body

`application/json`

curl -X POST "https://api.getlumen.dev/v1/invoices" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cus_Lo4xGg1Yk9pB2eWv3sNt",
    "status": "draft",
    "currency": "USD",
    "taxCalculationMethod": "manual",
    "effectiveTaxRate": "0.0875",
    "taxAmountCents": 1130,
    "manualTaxDescription": "NYC sales tax",
    "lineItems": [
      {
        "description": "Pro plan",
        "quantity": 1,
        "unitAmountCents": 12900,
        "type": "fixed"
      }
    ]
  }'

curl -X POST "https://api.getlumen.dev/v1/invoices" \  -H "Content-Type: application/json" \  -d '{    "customerId": "cus_Lo4xGg1Yk9pB2eWv3sNt",    "status": "draft",    "currency": "USD",    "taxCalculationMethod": "manual",    "effectiveTaxRate": "0.0875",    "taxAmountCents": 1130,    "manualTaxDescription": "NYC sales tax",    "lineItems": [      {        "description": "Pro plan",        "quantity": 1,        "unitAmountCents": 12900,        "type": "fixed"      }    ]  }'

{
  "id": "inv_c9MBd7QfJH5s2r4aLvXK",
  "customerInvoiceNumber": "LO4XGG-001",
  "customerId": "string",
  "subscriptionId": "string",
  "status": "draft",
  "totalAmountCents": 0,
  "subtotalCents": 0,
  "taxAmountCents": 0,
  "effectiveTaxRate": "0.0875",
  "taxJurisdiction": "string",
  "taxCalculationMethod": "auto",
  "currency": "USD",
  "dueDate": "2019-08-24T14:15:22Z",
  "issueDate": "2019-08-24T14:15:22Z",
  "paidDate": "2019-08-24T14:15:22Z",
  "billingPeriodStart": "2019-08-24T14:15:22Z",
  "billingPeriodEnd": "2019-08-24T14:15:22Z",
  "pdfUrl": "http://example.com",
  "hasPdf": true,
  "taxLineItemDescriptions": [
    "string"
  ],
  "notes": "string",
  "documentType": "standard",
  "originalInvoiceId": "string",
  "cancellationOrCreditReason": "string",
  "lineItems": [
    {
      "id": "string",
      "type": "string",
      "componentId": "string",
      "metricId": "string",
      "description": "string",
      "quantity": 0,
      "unitAmountCents": 0,
      "subtotalCents": 0,
      "taxMetadata": {},
      "billingPeriodStart": "2019-08-24T14:15:22Z",
      "billingPeriodEnd": "2019-08-24T14:15:22Z",
      "usagePeriodStart": "2019-08-24T14:15:22Z",
      "usagePeriodEnd": "2019-08-24T14:15:22Z",
      "prorationType": "string",
      "prorationPeriodStart": "2019-08-24T14:15:22Z",
      "prorationPeriodEnd": "2019-08-24T14:15:22Z",
      "discountCode": "string",
      "discountType": "string",
      "discountPercent": 0,
      "discountAppliedToComponents": [
        "string"
      ]
    }
  ],
  "adjustmentInvoices": [
    {
      "id": "string",
      "customerInvoiceNumber": "string",
      "documentType": "string",
      "totalAmountCents": 0,
      "currency": "string",
      "issueDate": "2019-08-24T14:15:22Z",
      "hasPdf": true
    }
  ],
  "paymentId": "string",
  "createdAt": "2019-08-24T14:15:22Z"
}

{
  "error": "Failed to create invoice"
}

Create Invoice

Authorization

Request Body

Response Body

201application/json

500application/json

`application/json`

`application/json`