Your First Invoice

This guide walks through the complete invoice workflow: creating a contact, issuing an invoice, and recording payment.

Prerequisites

• SpeyBooks account with API key (Quick Start)
• A customer to invoice

Step 1: Create a contact

Before creating an invoice, you need a contact (customer):

curl -X POST https://api.speybooks.com/v1/contacts \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corporation",
    "email": "accounts@acme.com",
    "type": "customer",
    "address": {
      "line1": "123 Business Park",
      "city": "London",
      "postal_code": "EC1A 1BB",
      "country": "GB"
    }
  }'

Response:

{
  "id": "cont_8x9s0a",
  "name": "Acme Corporation",
  "email": "accounts@acme.com",
  "type": "customer",
  "address": {
    "line1": "123 Business Park",
    "city": "London",
    "postal_code": "EC1A 1BB",
    "country": "GB"
  },
  "created_at": "2026-01-31T10:00:00Z"
}

Save the id — you'll need it for the invoice.

Step 2: Create an invoice

Now create an invoice for that contact:

curl -X POST https://api.speybooks.com/v1/invoices \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": "cont_8x9s0a",
    "currency": "GBP",
    "items": [
      {
        "description": "Software Development - January 2026",
        "quantity": 10,
        "unit_price": 50000,
        "vat_rate": "standard"
      },
      {
        "description": "Code Review",
        "quantity": 2,
        "unit_price": 25000,
        "vat_rate": "standard"
      }
    ],
    "notes": "Payment due within 30 days",
    "due_days": 30
  }'

Response:

{
  "id": "inv_7k2m9p",
  "number": "INV-0001",
  "status": "draft",
  "contact_id": "cont_8x9s0a",
  "items": [
    {
      "description": "Software Development - January 2026",
      "quantity": 10,
      "unit_price": 50000,
      "vat_rate": "standard",
      "vat_amount": 100000,
      "line_total": 600000
    },
    {
      "description": "Code Review",
      "quantity": 2,
      "unit_price": 25000,
      "vat_rate": "standard",
      "vat_amount": 10000,
      "line_total": 60000
    }
  ],
  "subtotal": 550000,
  "vat_amount": 110000,
  "total": 660000,
  "currency": "GBP",
  "issue_date": "2026-01-31",
  "due_date": "2026-03-02",
  "notes": "Payment due within 30 days",
  "created_at": "2026-01-31T10:05:00Z"
}

Understanding the amounts

Field	Value	Meaning
subtotal	550000	£5,500.00 (before VAT)
vat_amount	110000	£1,100.00 (20% VAT)
total	660000	£6,600.00 (inc. VAT)

VAT rates

• standard — 20%
• reduced — 5%
• zero — 0%
• exempt — No VAT applicable

Step 3: Send the invoice

Mark the invoice as sent and optionally email it to the customer:

curl -X POST https://api.speybooks.com/v1/invoices/inv_7k2m9p/send \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "send_email": true
  }'

Response:

{
  "id": "inv_7k2m9p",
  "status": "sent",
  "sent_at": "2026-01-31T10:10:00Z"
}

The invoice status changes from draft to sent.

Step 4: Download PDF

Generate a PDF for your records or manual sending:

curl https://api.speybooks.com/v1/invoices/inv_7k2m9p/pdf \
  -H "Authorization: Bearer sk_live_your_api_key" \
  --output invoice-0001.pdf

Step 5: Record payment

When the customer pays:

curl -X POST https://api.speybooks.com/v1/invoices/inv_7k2m9p/payments \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 660000,
    "date": "2026-02-15",
    "method": "bank_transfer",
    "reference": "BACS-123456"
  }'

Response:

{
  "id": "pay_abc123",
  "invoice_id": "inv_7k2m9p",
  "amount": 660000,
  "date": "2026-02-15",
  "method": "bank_transfer",
  "reference": "BACS-123456",
  "created_at": "2026-02-15T14:00:00Z"
}

The invoice status automatically changes to paid when fully settled.

Invoice lifecycle

draft → sent → paid
         ↓
       overdue (automatic after due_date)

Status	Description
draft	Not yet sent to customer
sent	Sent, awaiting payment
overdue	Past due date, unpaid
paid	Fully paid
void	Cancelled

Next steps

• Invoices API Reference — Full endpoint documentation
• VAT Returns — Submit MTD VAT returns
• Bank Reconciliation — Match payments to invoices