Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.dolfinai.co/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks through the end-to-end flow of sending an invoice via the Dolfin API. You’ll create a customer, create a product, create an invoice, and send it.

​
Prerequisites

  • A Dolfin API key
  • An organisation already provisioned (see Client Integration)
  • A valid session token or API key for authentication
All requests below require the x-dolfin-api-key and x-dolfin-organisation-id headers. See Authentication for details.

​
Overview

1

Create a customer

Add the customer who will receive the invoice.
2

Create a product

Define the product or service you’re billing for.
3

Create an invoice

Build a draft invoice with line items referencing the customer and product.
4

Send the invoice

Mark the invoice as sent and deliver it to the customer.

​
Step 1: Create a Customer

curl -X POST https://api.dolfinai.co/customers \
  -H "x-dolfin-api-key: dol_live_abc123" \
  -H "x-dolfin-organisation-id: 9a658587-fe02-402e-b1ac-bfaf53274ef8" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Riverside Construction Ltd",
    "email": "accounts@riverside.co.uk",
    "addressLine1": "45 Thames Street",
    "city": "London",
    "postalCode": "SE1 2AQ",
    "country": "GB"
  }'
Response: 
{
  "id": "c3456789-abcd-ef01-2345-6789abcdef01",
  "organisationId": "9a658587-fe02-402e-b1ac-bfaf53274ef8",
  "name": "Riverside Construction Ltd",
  "email": "accounts@riverside.co.uk",
  "addressLine1": "45 Thames Street",
  "city": "London",
  "postalCode": "SE1 2AQ",
  "country": "GB",
  "createdAt": "2025-01-20T09:00:00Z",
  "updatedAt": "2025-01-20T09:00:00Z"
}
Save the customer id - you’ll need it when creating the invoice.

​
Step 2: Create a Product

curl -X POST https://api.dolfinai.co/products \
  -H "x-dolfin-api-key: dol_live_abc123" \
  -H "x-dolfin-organisation-id: 9a658587-fe02-402e-b1ac-bfaf53274ef8" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Emergency Boiler Repair",
    "description": "Callout and repair for domestic boiler systems",
    "unitPrice": 150.00,
    "currency": "GBP",
    "type": "Service"
  }'
Response: 
{
  "id": "d4567890-abcd-ef01-2345-6789abcdef01",
  "organisationId": "9a658587-fe02-402e-b1ac-bfaf53274ef8",
  "name": "Emergency Boiler Repair",
  "description": "Callout and repair for domestic boiler systems",
  "unitPrice": 150.00,
  "currency": "GBP",
  "type": "Service",
  "createdAt": "2025-01-20T09:01:00Z",
  "updatedAt": "2025-01-20T09:01:00Z"
}
Save the product id - you’ll reference it in the invoice line items. The type field accepts Product or Service.

​
Step 3: Create an Invoice

Create a draft invoice that ties together the customer and product. The lineItems array references the product by its id. 
curl -X POST https://api.dolfinai.co/invoices \
  -H "x-dolfin-api-key: dol_live_abc123" \
  -H "x-dolfin-organisation-id: 9a658587-fe02-402e-b1ac-bfaf53274ef8" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "c3456789-abcd-ef01-2345-6789abcdef01",
    "currency": "GBP",
    "dueDate": "2025-02-20T00:00:00Z",
    "memo": "Boiler repair at 12 Oak Lane - January 2025",
    "lineItems": [
      {
        "productId": "d4567890-abcd-ef01-2345-6789abcdef01",
        "quantity": 2
      }
    ]
  }'
Response: 
{
  "id": "e5678901-abcd-ef01-2345-6789abcdef01",
  "organisationId": "9a658587-fe02-402e-b1ac-bfaf53274ef8",
  "customerId": "c3456789-abcd-ef01-2345-6789abcdef01",
  "documentNumber": "INV-0001",
  "currency": "GBP",
  "issueDate": "2025-01-20T09:02:00Z",
  "dueDate": "2025-02-20T00:00:00Z",
  "status": "Draft",
  "subTotal": 300.00,
  "taxAmount": 0,
  "totalAmount": 300.00,
  "memo": "Boiler repair at 12 Oak Lane - January 2025",
  "lineItems": [
    {
      "productId": "d4567890-abcd-ef01-2345-6789abcdef01",
      "quantity": 2
    }
  ],
  "createdAt": "2025-01-20T09:02:00Z",
  "updatedAt": "2025-01-20T09:02:00Z"
}
The invoice is created in Draft status. You can add a taxRateId to each line item if you need to apply tax.

​
Step 4: Send the Invoice

Send the draft invoice to the customer. This marks it as sent and delivers it, this will also set the issue date of the invoice. 
curl -X POST https://api.dolfinai.co/invoices/e5678901-abcd-ef01-2345-6789abcdef01/send \
  -H "x-dolfin-api-key: dol_live_abc123" \
  -H "x-dolfin-organisation-id: 9a658587-fe02-402e-b1ac-bfaf53274ef8"
Response: 
{
  "id": "e5678901-abcd-ef01-2345-6789abcdef01",
  "organisationId": "9a658587-fe02-402e-b1ac-bfaf53274ef8",
  "customerId": "c3456789-abcd-ef01-2345-6789abcdef01",
  "documentNumber": "INV-0001",
  "currency": "GBP",
  "issueDate": "2025-01-20T09:02:00Z",
  "dueDate": "2025-02-20T00:00:00Z",
  "status": "Sent",
  "subTotal": 300.00,
  "taxAmount": 0,
  "totalAmount": 300.00,
  "memo": "Boiler repair at 12 Oak Lane - January 2025",
  "createdAt": "2025-01-20T09:02:00Z",
  "updatedAt": "2025-01-20T09:03:00Z"
}
The invoice status changes from Draft to Sent.

​
Summary

StepEndpointWhat it does
1POST /customersCreate the customer to bill
2POST /productsDefine the product or service
3POST /invoicesCreate a draft invoice with line items
4POST /invoices/{id}/sendSend the invoice to the customer

​
Next Steps

API Reference

Explore the full API reference for all endpoints.

Client Integration

Set up organisation provisioning and user authentication.