Invoices

Outcome: Create, finalize, render, and deliver an invoice.
Prerequisites: An entity and API key; customer and item data can be inline.
You'll use: Entity key, or account key plus entity_id.

Create

Use the standard Create Invoice API for normal invoice creation. It calculates totals and taxes from your line items and applies the regular document lifecycle. The /custom endpoint is only for imports or integrations that must preserve externally calculated totals exactly.

Minimal invoice with inline customer and one line item:

Create minimaltypescript

// title: Minimal invoice
const _invoice = await sdk.invoices.create({
  customer: { name: "Acme Corp" },
  items: [{ name: "Service", quantity: 1, price: 100 }],
});

Or reference saved data:

Create with refstypescript

// title: Invoice with saved references
const _invoice = await sdk.invoices.create({
  customer_id: "cus_abc123",
  items: [
    { item_id: "itm_xyz789", quantity: 5 },
    { name: "Custom service", quantity: 1, price: 250 },
  ],
});

If your rollout needs gross-discount consumer pricing instead of the default B2B flow, see Calculation Modes.

Categorized service-period invoices

For subscriptions, memberships, hosting, retainers, and other service-period billing, categorize the revenue on the line item and add line-level revenue recognition:

curl -X POST "https://eu.spaceinvoices.com/invoices" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-entity-id: YOUR_ENTITY_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "name": "Nebula Propulsion Labs"
    },
    "date_service": "2026-07-01",
    "date_service_to": "2026-07-31",
    "items": [
      {
        "name": "Monthly platform subscription",
        "quantity": 1,
        "unit": "month",
        "price": 99,
        "taxes": [{ "classification": "standard" }],
        "financial_category_id": "fcat_subscription",
        "revenue_recognition": {
          "method": "service_period_daily",
          "date_from": "2026-07-01",
          "date_to": "2026-07-31"
        }
      }
    ]
  }'

Use financial_category_id directly on each line when the category is known while creating the invoice. Use category_assignments when assigning categories by request item index, for example when the item payload is generated separately.

Finalize

Finalize a draft to assign its invoice number. A finalized document can still be updated with version history until it is fiscalized or voided:

Finalizetypescript

// title: Finalize invoice
// Finalize assigns a document number. Fiscalization, when enabled, is a separate lifecycle concern.
const _finalized = await sdk.documents.finalizeDocument(invoice.id);

Or pass draft: false when creating to finalize immediately.

Download PDF

Render pdftypescript

// title: Render PDF
const pdf = await sdk.invoices.renderPdf(invoice.id);

// Save to file
fs.writeFileSync("invoice.pdf", pdf);

// Or send as response
res.setHeader("Content-Type", "application/pdf");
res.send(pdf);

Send by Email

Send emailtypescript

// title: Send invoice
await sdk.email.sendEmail({
  document_id: invoice.id,
  to: invoice.customer.email,
  subject: "Your invoice #{document_number}",
  body_text: "Thank you for your business!",
});

Uses the entity’s default email template. See Email API for custom subject/body.