API reference

Invoices

Create invoices and credit notes, issue and email them, download PDFs.

Invoices and credit notes share one resource. A new invoice is a draft: change it as often as you like, then issue it (status: "open") or send it, which issues it first.

Only drafts can be edited or deleted. After that, only the status changes: paid, uncollectible or void.
Customers and items are copied onto the invoice. Pass a contact_id or catalog_id and Zulu copies their details, so later edits to the customer or item never change an invoice you've sent.
Totals and VAT are worked out for you on every save. You can't set them.
To correct an issued invoice, create a credit note with type: "credit_note" and credit_note_for_id. Once it's issued, it's taken off the invoice's amount_due; credited shows how much has been credited.

List invoices, or get one by id

GET/v1/invoice

query searches name and number. Filters: status, type, contact_id (the customer it was billed to), credit_note_for_id (an invoice's credit notes) and overdue (open and past its due date, Irish time).

Needs the invoice:read permission

Query parameters

idinvoice id
invoice_
querytext
Up to 200 characters
limitnumber
1–50, default 20
afterinvoice id
invoice_
beforeinvoice id
invoice_
status"draft" or "open" or "paid" or "uncollectible" or "void"
type"invoice" or "credit_note"
A credit note corrects an issued invoice; its amounts are positive
contact_idcustomer id
contact_
credit_note_for_idinvoice id
invoice_
overdue"true"
Only invoices that are open and past their due date

Request

curl https://api.zulu.ie/v1/invoice \
  -H "Authorization: Bearer $ZULU_API_KEY" \
  -H "Zulu-Business-Id: $ZULU_BUSINESS_ID"

Example response200

Response · 200

{
  "data": [
    {
      "id": "invoice_9f8e7d6c-5b4a-4c3d-2e1f-0a9b8c7d6e5f",
      "created_at": "2026-10-27T09:30:00.000Z",
      "updated_at": "2026-10-27T09:30:00.000Z",
      "type": "invoice",
      "credit_note_for_id": "invoice_9f8e7d6c-5b4a-4c3d-2e1f-0a9b8c7d6e5f",
      "status": "draft",
      "issued_at": "2026-10-27T09:30:00.000Z",
      "paid_at": "2026-10-27T09:30:00.000Z",
      "sent_at": "2026-10-27T09:30:00.000Z",
      "name": "Main",
      "number": "INV-0042",
      "date": "2026-10-27",
      "due_date": "2026-10-27",
      "currency": "EUR",
      "notes": "Thank you for your business.",
      "custom_fields": [
        {
          "name": "Main",
          "value": "…"
        }
      ],
      "hide": [
        "notes"
      ],
      "sender": {
        "source_id": "contact_8a3e2c1d-4b5f-4e6a-9c7d-1e2f3a4b5c6d",
        "first_name": "Aoife",
        "last_name": "Murphy",
        "company_name": "Globex Ireland Ltd",
        "vat_number": "IE9876543W",
        "email": {
          "source_id": "email_3f2b8c1e-7a6d-4e5f-9b0a-1c2d3e4f5a6b",
          "name": "Main",
          "email": "accounts@globex.ie",
          "first_name": "Aoife",
          "last_name": "Murphy"
        },
        "phone": {
          "source_id": "phone_3f2b8c1e-7a6d-4e5f-9b0a-1c2d3e4f5a6b",
          "name": "Main",
          "phone": "+353 1 234 5678"
        },
        "address": {
          "source_id": "address_3f2b8c1e-7a6d-4e5f-9b0a-1c2d3e4f5a6b",
          "name": "Main",
          "address_1": "Unit 4, Docklands Innovation Park",
          "address_2": null,
          "city": "Dublin 1",
          "county": "Dublin",
          "eircode": "D01 X2Y3",
          "country": "Ireland"
        }
      },
      "bill_to": {
        "source_id": "contact_8a3e2c1d-4b5f-4e6a-9c7d-1e2f3a4b5c6d",
        "first_name": "Aoife",
        "last_name": "Murphy",
        "company_name": "Globex Ireland Ltd",
        "vat_number": "IE9876543W",
        "email": {
          "source_id": "email_3f2b8c1e-7a6d-4e5f-9b0a-1c2d3e4f5a6b",
          "name": "Main",
          "email": "accounts@globex.ie",
          "first_name": "Aoife",
          "last_name": "Murphy"
        },
        "phone": {
          "source_id": "phone_3f2b8c1e-7a6d-4e5f-9b0a-1c2d3e4f5a6b",
          "name": "Main",
          "phone": "+353 1 234 5678"
        },
        "address": {
          "source_id": "address_3f2b8c1e-7a6d-4e5f-9b0a-1c2d3e4f5a6b",
          "name": "Main",
          "address_1": "Unit 4, Docklands Innovation Park",
          "address_2": null,
          "city": "Dublin 1",
          "county": "Dublin",
          "eircode": "D01 X2Y3",
          "country": "Ireland"
        }
      },
      "ship_to": {
        "source_id": "contact_8a3e2c1d-4b5f-4e6a-9c7d-1e2f3a4b5c6d",
        "first_name": "Aoife",
        "last_name": "Murphy",
        "company_name": "Globex Ireland Ltd",
        "vat_number": "IE9876543W",
        "email": {
          "source_id": "email_3f2b8c1e-7a6d-4e5f-9b0a-1c2d3e4f5a6b",
          "name": "Main",
          "email": "accounts@globex.ie",
          "first_name": "Aoife",
          "last_name": "Murphy"
        },
        "phone": {
          "source_id": "phone_3f2b8c1e-7a6d-4e5f-9b0a-1c2d3e4f5a6b",
          "name": "Main",
          "phone": "+353 1 234 5678"
        },
        "address": {
          "source_id": "address_3f2b8c1e-7a6d-4e5f-9b0a-1c2d3e4f5a6b",
          "name": "Main",
          "address_1": "Unit 4, Docklands Innovation Park",
          "address_2": null,
          "city": "Dublin 1",
          "county": "Dublin",
          "eircode": "D01 X2Y3",
          "country": "Ireland"
        }
      },
      "items": [
        {
          "source_id": "catalog_5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a",
          "name": "Main",
          "category": "product",
          "description": null,
          "quantity": "1",
          "unit_price": "120.00",
          "vat": {
            "source_id": "vat_1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
            "name": "Main",
            "code": "S",
            "rate": "0.23"
          },
          "net": "120.00",
          "vat_amount": "27.60"
        }
      ],
      "bank_details": {
        "source_id": "bank_details_3f2b8c1e-7a6d-4e5f-9b0a-1c2d3e4f5a6b",
        "name": "Main",
        "bic": "AIBKIE2D",
        "iban": "IE29AIBK93115212345678",
        "account_number": null,
        "sort_code": null
      },
      "vat_breakdown": [
        {
          "name": "Main",
          "code": "S",
          "rate": "0.23",
          "net": "120.00",
          "vat": "27.60"
        }
      ],
      "subtotal": "120.00",
      "vat_total": "27.60",
      "total": "147.60",
      "credited": "120.00",
      "amount_due": "120.00"
    }
  ],
  "has_more": false
}

Create an invoice

POST/v1/invoice

Starts as draft unless status is open. The sender defaults to the business. A credit note (type: credit_note) needs credit_note_for_id and defaults to that invoice's content. Totals are calculated from items.

Needs the invoice:write permission

Body

type"invoice" or "credit_note"
A credit note corrects an issued invoice; its amounts are positive
credit_note_for_idinvoice id
nametextrequired
Up to 200 characters
numbertextrequired
Up to 50 characters
status"draft" or "open"
datedate
YYYY-MM-DD
due_datedate
YYYY-MM-DD
currencycurrency code
ISO 4217, e.g. EUR
notestext
Up to 5,000 characters
custom_fieldslist of objects
2 fields inside
- nametextrequired
  The label, e.g. "Order No."
- valuetextrequired
  Can be empty, to show a blank to fill in
hidelist of text
Fields to leave off the PDF. The sender's VAT number can't be hidden on an issued invoice that charges VAT.
senderobject
8 fields inside
- contact_idcustomer id
- first_nametext
  Up to 200 characters
- last_nametext
  Up to 200 characters
- company_nametext
  Up to 200 characters
- vat_numbertext
  Up to 30 characters
- emailobject
  5 fields inside
  - email_idemail id
  - nametext
    Up to 200 characters
  - emailemail
    Up to 254 characters
  - first_nametext
    Up to 200 characters
  - last_nametext
    Up to 200 characters
- phoneobject
  3 fields inside
  - phone_idphone id
  - nametext
    Up to 200 characters
  - phonetext
    Up to 50 characters
- addressobject
  8 fields inside
  - address_idaddress id
  - nametext
    Up to 200 characters
  - address_1text
    Up to 200 characters
  - address_2text
    Up to 200 characters
  - citytext
    Up to 200 characters
  - countytext
    Up to 200 characters
  - eircodetext
    Up to 200 characters
  - countrytext
    Up to 200 characters
bill_toobject
8 fields inside
- contact_idcustomer id
- first_nametext
  Up to 200 characters
- last_nametext
  Up to 200 characters
- company_nametext
  Up to 200 characters
- vat_numbertext
  Up to 30 characters
- emailobject
  5 fields inside
  - email_idemail id
  - nametext
    Up to 200 characters
  - emailemail
    Up to 254 characters
  - first_nametext
    Up to 200 characters
  - last_nametext
    Up to 200 characters
- phoneobject
  3 fields inside
  - phone_idphone id
  - nametext
    Up to 200 characters
  - phonetext
    Up to 50 characters
- addressobject
  8 fields inside
  - address_idaddress id
  - nametext
    Up to 200 characters
  - address_1text
    Up to 200 characters
  - address_2text
    Up to 200 characters
  - citytext
    Up to 200 characters
  - countytext
    Up to 200 characters
  - eircodetext
    Up to 200 characters
  - countrytext
    Up to 200 characters
ship_toobject
8 fields inside
- contact_idcustomer id
- first_nametext
  Up to 200 characters
- last_nametext
  Up to 200 characters
- company_nametext
  Up to 200 characters
- vat_numbertext
  Up to 30 characters
- emailobject
  5 fields inside
  - email_idemail id
  - nametext
    Up to 200 characters
  - emailemail
    Up to 254 characters
  - first_nametext
    Up to 200 characters
  - last_nametext
    Up to 200 characters
- phoneobject
  3 fields inside
  - phone_idphone id
  - nametext
    Up to 200 characters
  - phonetext
    Up to 50 characters
- addressobject
  8 fields inside
  - address_idaddress id
  - nametext
    Up to 200 characters
  - address_1text
    Up to 200 characters
  - address_2text
    Up to 200 characters
  - citytext
    Up to 200 characters
  - countytext
    Up to 200 characters
  - eircodetext
    Up to 200 characters
  - countrytext
    Up to 200 characters
itemslist of objects
7 fields inside
- catalog_iditem id
- quantityquantityrequired
  Decimal string, up to 4 places, e.g. "1.5"
- nametext
  Up to 200 characters
- category"product" or "service"
- descriptiontext
  Up to 2,000 characters
- unit_pricemoney
  Decimal string, up to 2 places, e.g. "12.50"
- vatobject
  4 fields inside
  - vat_idVAT rate id
  - nametext
    Up to 200 characters
  - codetext
    Up to 20 characters
  - raterate
    Decimal string between 0 and 1, up to 4 places, e.g. "0.135" for 13.5%
bank_detailsobject
6 fields inside
- bank_details_idbank account id
- nametext
  Up to 200 characters
- bictext
  Up to 11 characters
- ibantext
  Up to 34 characters
- account_numbertext
  Up to 30 characters
- sort_codetext
  Up to 20 characters

Request

curl -X POST https://api.zulu.ie/v1/invoice \
  -H "Authorization: Bearer $ZULU_API_KEY" \
  -H "Zulu-Business-Id: $ZULU_BUSINESS_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Shelving for the Docklands office",
    "number": "INV-0042",
    "date": "2026-10-27",
    "due_date": "2026-11-10",
    "bill_to": {
      "contact_id": "contact_8a3e2c1d-4b5f-4e6a-9c7d-1e2f3a4b5c6d"
    },
    "items": [
      {
        "catalog_id": "catalog_5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a",
        "quantity": "2"
      },
      {
        "name": "Installation",
        "category": "service",
        "quantity": "1",
        "unit_price": "320.00",
        "vat": {
          "vat_id": "vat_1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
        }
      }
    ],
    "notes": "Thank you for your business."
  }'

Example response201

Response · 201

{
  "id": "invoice_9f8e7d6c-5b4a-4c3d-2e1f-0a9b8c7d6e5f",
  "created_at": "2026-10-27T09:30:00.000Z",
  "updated_at": "2026-10-27T09:30:00.000Z",
  "type": "invoice",
  "credit_note_for_id": "invoice_9f8e7d6c-5b4a-4c3d-2e1f-0a9b8c7d6e5f",
  "status": "draft",
  "issued_at": "2026-10-27T09:30:00.000Z",
  "paid_at": "2026-10-27T09:30:00.000Z",
  "sent_at": "2026-10-27T09:30:00.000Z",
  "name": "Main",
  "number": "INV-0042",
  "date": "2026-10-27",
  "due_date": "2026-10-27",
  "currency": "EUR",
  "notes": "Thank you for your business.",
  "custom_fields": [
    {
      "name": "Main",
      "value": "…"
    }
  ],
  "hide": [
    "notes"
  ],
  "sender": {
    "source_id": "contact_8a3e2c1d-4b5f-4e6a-9c7d-1e2f3a4b5c6d",
    "first_name": "Aoife",
    "last_name": "Murphy",
    "company_name": "Globex Ireland Ltd",
    "vat_number": "IE9876543W",
    "email": {
      "source_id": "email_3f2b8c1e-7a6d-4e5f-9b0a-1c2d3e4f5a6b",
      "name": "Main",
      "email": "accounts@globex.ie",
      "first_name": "Aoife",
      "last_name": "Murphy"
    },
    "phone": {
      "source_id": "phone_3f2b8c1e-7a6d-4e5f-9b0a-1c2d3e4f5a6b",
      "name": "Main",
      "phone": "+353 1 234 5678"
    },
    "address": {
      "source_id": "address_3f2b8c1e-7a6d-4e5f-9b0a-1c2d3e4f5a6b",
      "name": "Main",
      "address_1": "Unit 4, Docklands Innovation Park",
      "address_2": null,
      "city": "Dublin 1",
      "county": "Dublin",
      "eircode": "D01 X2Y3",
      "country": "Ireland"
    }
  },
  "bill_to": {
    "source_id": "contact_8a3e2c1d-4b5f-4e6a-9c7d-1e2f3a4b5c6d",
    "first_name": "Aoife",
    "last_name": "Murphy",
    "company_name": "Globex Ireland Ltd",
    "vat_number": "IE9876543W",
    "email": {
      "source_id": "email_3f2b8c1e-7a6d-4e5f-9b0a-1c2d3e4f5a6b",
      "name": "Main",
      "email": "accounts@globex.ie",
      "first_name": "Aoife",
      "last_name": "Murphy"
    },
    "phone": {
      "source_id": "phone_3f2b8c1e-7a6d-4e5f-9b0a-1c2d3e4f5a6b",
      "name": "Main",
      "phone": "+353 1 234 5678"
    },
    "address": {
      "source_id": "address_3f2b8c1e-7a6d-4e5f-9b0a-1c2d3e4f5a6b",
      "name": "Main",
      "address_1": "Unit 4, Docklands Innovation Park",
      "address_2": null,
      "city": "Dublin 1",
      "county": "Dublin",
      "eircode": "D01 X2Y3",
      "country": "Ireland"
    }
  },
  "ship_to": {
    "source_id": "contact_8a3e2c1d-4b5f-4e6a-9c7d-1e2f3a4b5c6d",
    "first_name": "Aoife",
    "last_name": "Murphy",
    "company_name": "Globex Ireland Ltd",
    "vat_number": "IE9876543W",
    "email": {
      "source_id": "email_3f2b8c1e-7a6d-4e5f-9b0a-1c2d3e4f5a6b",
      "name": "Main",
      "email": "accounts@globex.ie",
      "first_name": "Aoife",
      "last_name": "Murphy"
    },
    "phone": {
      "source_id": "phone_3f2b8c1e-7a6d-4e5f-9b0a-1c2d3e4f5a6b",
      "name": "Main",
      "phone": "+353 1 234 5678"
    },
    "address": {
      "source_id": "address_3f2b8c1e-7a6d-4e5f-9b0a-1c2d3e4f5a6b",
      "name": "Main",
      "address_1": "Unit 4, Docklands Innovation Park",
      "address_2": null,
      "city": "Dublin 1",
      "county": "Dublin",
      "eircode": "D01 X2Y3",
      "country": "Ireland"
    }
  },
  "items": [
    {
      "source_id": "catalog_5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a",
      "name": "Main",
      "category": "product",
      "description": null,
      "quantity": "1",
      "unit_price": "120.00",
      "vat": {
        "source_id": "vat_1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "name": "Main",
        "code": "S",
        "rate": "0.23"
      },
      "net": "120.00",
      "vat_amount": "27.60"
    }
  ],
  "bank_details": {
    "source_id": "bank_details_3f2b8c1e-7a6d-4e5f-9b0a-1c2d3e4f5a6b",
    "name": "Main",
    "bic": "AIBKIE2D",
    "iban": "IE29AIBK93115212345678",
    "account_number": null,
    "sort_code": null
  },
  "vat_breakdown": [
    {
      "name": "Main",
      "code": "S",
      "rate": "0.23",
      "net": "120.00",
      "vat": "27.60"
    }
  ],
  "subtotal": "120.00",
  "vat_total": "27.60",
  "total": "147.60",
  "credited": "120.00",
  "amount_due": "120.00"
}

Update an invoice

PATCH/v1/invoice

Only drafts can be edited. Issuing (draft → open) needs a sender and customer with names and addresses, at least one item, and the sender's VAT number if items charge VAT; the date defaults to today. Invoices: open → paid, uncollectible or void; uncollectible → paid or void. Credit notes: open → paid or void.

Needs the invoice:write permission

Body

idinvoice idrequired
status"draft" or "open" or "paid" or "uncollectible" or "void"
nametext
Up to 200 characters
numbertext
Up to 50 characters
datedate
YYYY-MM-DD
due_datedate
YYYY-MM-DD
currencycurrency code
ISO 4217, e.g. EUR
notestext
Up to 5,000 characters
custom_fieldslist of objects
2 fields inside
- nametextrequired
  The label, e.g. "Order No."
- valuetextrequired
  Can be empty, to show a blank to fill in
hidelist of text
Fields to leave off the PDF. The sender's VAT number can't be hidden on an issued invoice that charges VAT.
senderobject
8 fields inside
- contact_idcustomer id
- first_nametext
  Up to 200 characters
- last_nametext
  Up to 200 characters
- company_nametext
  Up to 200 characters
- vat_numbertext
  Up to 30 characters
- emailobject
  5 fields inside
  - email_idemail id
  - nametext
    Up to 200 characters
  - emailemail
    Up to 254 characters
  - first_nametext
    Up to 200 characters
  - last_nametext
    Up to 200 characters
- phoneobject
  3 fields inside
  - phone_idphone id
  - nametext
    Up to 200 characters
  - phonetext
    Up to 50 characters
- addressobject
  8 fields inside
  - address_idaddress id
  - nametext
    Up to 200 characters
  - address_1text
    Up to 200 characters
  - address_2text
    Up to 200 characters
  - citytext
    Up to 200 characters
  - countytext
    Up to 200 characters
  - eircodetext
    Up to 200 characters
  - countrytext
    Up to 200 characters
bill_toobject
8 fields inside
- contact_idcustomer id
- first_nametext
  Up to 200 characters
- last_nametext
  Up to 200 characters
- company_nametext
  Up to 200 characters
- vat_numbertext
  Up to 30 characters
- emailobject
  5 fields inside
  - email_idemail id
  - nametext
    Up to 200 characters
  - emailemail
    Up to 254 characters
  - first_nametext
    Up to 200 characters
  - last_nametext
    Up to 200 characters
- phoneobject
  3 fields inside
  - phone_idphone id
  - nametext
    Up to 200 characters
  - phonetext
    Up to 50 characters
- addressobject
  8 fields inside
  - address_idaddress id
  - nametext
    Up to 200 characters
  - address_1text
    Up to 200 characters
  - address_2text
    Up to 200 characters
  - citytext
    Up to 200 characters
  - countytext
    Up to 200 characters
  - eircodetext
    Up to 200 characters
  - countrytext
    Up to 200 characters
ship_toobject
8 fields inside
- contact_idcustomer id
- first_nametext
  Up to 200 characters
- last_nametext
  Up to 200 characters
- company_nametext
  Up to 200 characters
- vat_numbertext
  Up to 30 characters
- emailobject
  5 fields inside
  - email_idemail id
  - nametext
    Up to 200 characters
  - emailemail
    Up to 254 characters
  - first_nametext
    Up to 200 characters
  - last_nametext
    Up to 200 characters
- phoneobject
  3 fields inside
  - phone_idphone id
  - nametext
    Up to 200 characters
  - phonetext
    Up to 50 characters
- addressobject
  8 fields inside
  - address_idaddress id
  - nametext
    Up to 200 characters
  - address_1text
    Up to 200 characters
  - address_2text
    Up to 200 characters
  - citytext
    Up to 200 characters
  - countytext
    Up to 200 characters
  - eircodetext
    Up to 200 characters
  - countrytext
    Up to 200 characters
itemslist of objects
7 fields inside
- catalog_iditem id
- quantityquantityrequired
  Decimal string, up to 4 places, e.g. "1.5"
- nametext
  Up to 200 characters
- category"product" or "service"
- descriptiontext
  Up to 2,000 characters
- unit_pricemoney
  Decimal string, up to 2 places, e.g. "12.50"
- vatobject
  4 fields inside
  - vat_idVAT rate id
  - nametext
    Up to 200 characters
  - codetext
    Up to 20 characters
  - raterate
    Decimal string between 0 and 1, up to 4 places, e.g. "0.135" for 13.5%
bank_detailsobject
6 fields inside
- bank_details_idbank account id
- nametext
  Up to 200 characters
- bictext
  Up to 11 characters
- ibantext
  Up to 34 characters
- account_numbertext
  Up to 30 characters
- sort_codetext
  Up to 20 characters

Request

curl -X PATCH https://api.zulu.ie/v1/invoice \
  -H "Authorization: Bearer $ZULU_API_KEY" \
  -H "Zulu-Business-Id: $ZULU_BUSINESS_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "invoice_9f8e7d6c-5b4a-4c3d-2e1f-0a9b8c7d6e5f",
    "status": "paid"
  }'

Example response200

Response · 200

{
  "id": "invoice_9f8e7d6c-5b4a-4c3d-2e1f-0a9b8c7d6e5f",
  "created_at": "2026-10-27T09:30:00.000Z",
  "updated_at": "2026-10-27T09:30:00.000Z",
  "type": "invoice",
  "credit_note_for_id": "invoice_9f8e7d6c-5b4a-4c3d-2e1f-0a9b8c7d6e5f",
  "status": "draft",
  "issued_at": "2026-10-27T09:30:00.000Z",
  "paid_at": "2026-10-27T09:30:00.000Z",
  "sent_at": "2026-10-27T09:30:00.000Z",
  "name": "Main",
  "number": "INV-0042",
  "date": "2026-10-27",
  "due_date": "2026-10-27",
  "currency": "EUR",
  "notes": "Thank you for your business.",
  "custom_fields": [
    {
      "name": "Main",
      "value": "…"
    }
  ],
  "hide": [
    "notes"
  ],
  "sender": {
    "source_id": "contact_8a3e2c1d-4b5f-4e6a-9c7d-1e2f3a4b5c6d",
    "first_name": "Aoife",
    "last_name": "Murphy",
    "company_name": "Globex Ireland Ltd",
    "vat_number": "IE9876543W",
    "email": {
      "source_id": "email_3f2b8c1e-7a6d-4e5f-9b0a-1c2d3e4f5a6b",
      "name": "Main",
      "email": "accounts@globex.ie",
      "first_name": "Aoife",
      "last_name": "Murphy"
    },
    "phone": {
      "source_id": "phone_3f2b8c1e-7a6d-4e5f-9b0a-1c2d3e4f5a6b",
      "name": "Main",
      "phone": "+353 1 234 5678"
    },
    "address": {
      "source_id": "address_3f2b8c1e-7a6d-4e5f-9b0a-1c2d3e4f5a6b",
      "name": "Main",
      "address_1": "Unit 4, Docklands Innovation Park",
      "address_2": null,
      "city": "Dublin 1",
      "county": "Dublin",
      "eircode": "D01 X2Y3",
      "country": "Ireland"
    }
  },
  "bill_to": {
    "source_id": "contact_8a3e2c1d-4b5f-4e6a-9c7d-1e2f3a4b5c6d",
    "first_name": "Aoife",
    "last_name": "Murphy",
    "company_name": "Globex Ireland Ltd",
    "vat_number": "IE9876543W",
    "email": {
      "source_id": "email_3f2b8c1e-7a6d-4e5f-9b0a-1c2d3e4f5a6b",
      "name": "Main",
      "email": "accounts@globex.ie",
      "first_name": "Aoife",
      "last_name": "Murphy"
    },
    "phone": {
      "source_id": "phone_3f2b8c1e-7a6d-4e5f-9b0a-1c2d3e4f5a6b",
      "name": "Main",
      "phone": "+353 1 234 5678"
    },
    "address": {
      "source_id": "address_3f2b8c1e-7a6d-4e5f-9b0a-1c2d3e4f5a6b",
      "name": "Main",
      "address_1": "Unit 4, Docklands Innovation Park",
      "address_2": null,
      "city": "Dublin 1",
      "county": "Dublin",
      "eircode": "D01 X2Y3",
      "country": "Ireland"
    }
  },
  "ship_to": {
    "source_id": "contact_8a3e2c1d-4b5f-4e6a-9c7d-1e2f3a4b5c6d",
    "first_name": "Aoife",
    "last_name": "Murphy",
    "company_name": "Globex Ireland Ltd",
    "vat_number": "IE9876543W",
    "email": {
      "source_id": "email_3f2b8c1e-7a6d-4e5f-9b0a-1c2d3e4f5a6b",
      "name": "Main",
      "email": "accounts@globex.ie",
      "first_name": "Aoife",
      "last_name": "Murphy"
    },
    "phone": {
      "source_id": "phone_3f2b8c1e-7a6d-4e5f-9b0a-1c2d3e4f5a6b",
      "name": "Main",
      "phone": "+353 1 234 5678"
    },
    "address": {
      "source_id": "address_3f2b8c1e-7a6d-4e5f-9b0a-1c2d3e4f5a6b",
      "name": "Main",
      "address_1": "Unit 4, Docklands Innovation Park",
      "address_2": null,
      "city": "Dublin 1",
      "county": "Dublin",
      "eircode": "D01 X2Y3",
      "country": "Ireland"
    }
  },
  "items": [
    {
      "source_id": "catalog_5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a",
      "name": "Main",
      "category": "product",
      "description": null,
      "quantity": "1",
      "unit_price": "120.00",
      "vat": {
        "source_id": "vat_1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "name": "Main",
        "code": "S",
        "rate": "0.23"
      },
      "net": "120.00",
      "vat_amount": "27.60"
    }
  ],
  "bank_details": {
    "source_id": "bank_details_3f2b8c1e-7a6d-4e5f-9b0a-1c2d3e4f5a6b",
    "name": "Main",
    "bic": "AIBKIE2D",
    "iban": "IE29AIBK93115212345678",
    "account_number": null,
    "sort_code": null
  },
  "vat_breakdown": [
    {
      "name": "Main",
      "code": "S",
      "rate": "0.23",
      "net": "120.00",
      "vat": "27.60"
    }
  ],
  "subtotal": "120.00",
  "vat_total": "27.60",
  "total": "147.60",
  "credited": "120.00",
  "amount_due": "120.00"
}

Delete an invoice

DELETE/v1/invoice

Only drafts can be deleted; void an issued invoice or correct it with a credit note.

Needs the invoice:delete permission

Body

idinvoice idrequired

Request

curl -X DELETE https://api.zulu.ie/v1/invoice \
  -H "Authorization: Bearer $ZULU_API_KEY" \
  -H "Zulu-Business-Id: $ZULU_BUSINESS_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "invoice_9f8e7d6c-5b4a-4c3d-2e1f-0a9b8c7d6e5f"
  }'

Returns 204 with no body.

Suggest the next invoice or credit note number

GET/v1/invoice/next-number

Adds one to the business's latest number of that type, keeping its format (INV-0041 → INV-0042), and skips numbers already used. Starts at INV-0001 or CN-0001.

Needs the invoice:write permission

Query parameters

type"invoice" or "credit_note"
A credit note corrects an issued invoice; its amounts are positive

Request

curl https://api.zulu.ie/v1/invoice/next-number \
  -H "Authorization: Bearer $ZULU_API_KEY" \
  -H "Zulu-Business-Id: $ZULU_BUSINESS_ID"

Example response200

Response · 200

{
  "number": "INV-0042"
}

Download an invoice or credit note as a PDF

GET/v1/invoice/pdf

Drafts and void invoices are clearly labelled. The VAT number and bank details are shown at the bottom.

Needs the invoice:read permission

Query parameters

idinvoice idrequired
invoice_

Request

curl "https://api.zulu.ie/v1/invoice/pdf?id=invoice_9f8e7d6c-5b4a-4c3d-2e1f-0a9b8c7d6e5f" \
  -H "Authorization: Bearer $ZULU_API_KEY" \
  -H "Zulu-Business-Id: $ZULU_BUSINESS_ID" \
  -o invoice.pdf

Returns the file itself (a PDF), not JSON.

List when invoices were emailed, and to whom

GET/v1/invoice/send

invoice_id lists one invoice's sends, and status filters, e.g. scheduled. Newest first.

Needs the invoice:read permission

Query parameters

idinvoice send id
invoice_send_
querytext
Up to 200 characters
limitnumber
1–50, default 20
afterinvoice send id
invoice_send_
beforeinvoice send id
invoice_send_
invoice_idinvoice id
invoice_
status"pending" or "scheduled" or "sent" or "delivered" or "bounced" or "complained" or "failed" or "cancelled"
See docs/api.md, "Sending"

Request

curl https://api.zulu.ie/v1/invoice/send \
  -H "Authorization: Bearer $ZULU_API_KEY" \
  -H "Zulu-Business-Id: $ZULU_BUSINESS_ID"

Example response200

Response · 200

{
  "data": [
    {
      "id": "invoice_send_3f2b8c1e-7a6d-4e5f-9b0a-1c2d3e4f5a6b",
      "created_at": "2026-10-27T09:30:00.000Z",
      "updated_at": "2026-10-27T09:30:00.000Z",
      "invoice_id": "invoice_9f8e7d6c-5b4a-4c3d-2e1f-0a9b8c7d6e5f",
      "status": "pending",
      "scheduled_at": "2026-10-27T09:30:00.000Z",
      "sent_by_user_id": "user_3f2b8c1e-7a6d-4e5f-9b0a-1c2d3e4f5a6b",
      "sent_by_api_key_id": "api_key_3f2b8c1e-7a6d-4e5f-9b0a-1c2d3e4f5a6b",
      "to": [
        "…"
      ],
      "cc": [
        "…"
      ],
      "bcc": [
        "…"
      ],
      "message": "Here's your invoice. Thanks again!"
    }
  ],
  "has_more": false
}

Email an invoice or credit note with its PDF, now or later

POST/v1/invoice/send

Sends to the customer's email on bill_to unless to is given; cc and bcc are optional. With scheduled_at, it goes out then instead (up to 30 days ahead). A draft is issued first; scheduled drafts without a date are dated the day they go out. Needs a verified email. Every send is recorded.

Needs the invoice:write permission

Body

idinvoice idrequired
tolist of email
Defaults to the customer's email on bill_to
cclist of email
e.g. the ship-to contact
bcclist of email
e.g. your own records
messagetext
A note shown in the email
greeting"hi" | "hello" | "dear"
How the email opens: "Hi Hank," (hi, the default), "Hello Hank," or "Dear Hank,"
wordingtext
The main sentence: standard (the default), minimal, friendly, formal, or reminder (for an invoice that is due or overdue; credit notes use standard)
sign_offtext
How the email ends, before the business name: thank_you (the default), thanks, many_thanks, kind_regards, best_regards or regards
scheduled_attimestamp
Send later: from a minute to 30 days ahead

Request

curl -X POST https://api.zulu.ie/v1/invoice/send \
  -H "Authorization: Bearer $ZULU_API_KEY" \
  -H "Zulu-Business-Id: $ZULU_BUSINESS_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "invoice_9f8e7d6c-5b4a-4c3d-2e1f-0a9b8c7d6e5f",
    "cc": [
      "office@globex.ie"
    ],
    "message": "Here's your invoice for the shelving. Thanks again!"
  }'

Example response200

Response · 200

{
  "invoice": {
    "id": "invoice_9f8e7d6c-5b4a-4c3d-2e1f-0a9b8c7d6e5f",
    "created_at": "2026-10-27T09:30:00.000Z",
    "updated_at": "2026-10-27T09:30:00.000Z",
    "type": "invoice",
    "credit_note_for_id": "invoice_9f8e7d6c-5b4a-4c3d-2e1f-0a9b8c7d6e5f",
    "status": "draft",
    "issued_at": "2026-10-27T09:30:00.000Z",
    "paid_at": "2026-10-27T09:30:00.000Z",
    "sent_at": "2026-10-27T09:30:00.000Z",
    "name": "Main",
    "number": "INV-0042",
    "date": "2026-10-27",
    "due_date": "2026-10-27",
    "currency": "EUR",
    "notes": "Thank you for your business.",
    "custom_fields": [
      {
        "name": "Main",
        "value": "…"
      }
    ],
    "hide": [
      "notes"
    ],
    "sender": {
      "source_id": "contact_8a3e2c1d-4b5f-4e6a-9c7d-1e2f3a4b5c6d",
      "first_name": "Aoife",
      "last_name": "Murphy",
      "company_name": "Globex Ireland Ltd",
      "vat_number": "IE9876543W",
      "email": {
        "source_id": "email_3f2b8c1e-7a6d-4e5f-9b0a-1c2d3e4f5a6b",
        "name": "Main",
        "email": "accounts@globex.ie",
        "first_name": "Aoife",
        "last_name": "Murphy"
      },
      "phone": {
        "source_id": "phone_3f2b8c1e-7a6d-4e5f-9b0a-1c2d3e4f5a6b",
        "name": "Main",
        "phone": "+353 1 234 5678"
      },
      "address": {
        "source_id": "address_3f2b8c1e-7a6d-4e5f-9b0a-1c2d3e4f5a6b",
        "name": "Main",
        "address_1": "Unit 4, Docklands Innovation Park",
        "address_2": null,
        "city": "Dublin 1",
        "county": "Dublin",
        "eircode": "D01 X2Y3",
        "country": "Ireland"
      }
    },
    "bill_to": {
      "source_id": "contact_8a3e2c1d-4b5f-4e6a-9c7d-1e2f3a4b5c6d",
      "first_name": "Aoife",
      "last_name": "Murphy",
      "company_name": "Globex Ireland Ltd",
      "vat_number": "IE9876543W",
      "email": {
        "source_id": "email_3f2b8c1e-7a6d-4e5f-9b0a-1c2d3e4f5a6b",
        "name": "Main",
        "email": "accounts@globex.ie",
        "first_name": "Aoife",
        "last_name": "Murphy"
      },
      "phone": {
        "source_id": "phone_3f2b8c1e-7a6d-4e5f-9b0a-1c2d3e4f5a6b",
        "name": "Main",
        "phone": "+353 1 234 5678"
      },
      "address": {
        "source_id": "address_3f2b8c1e-7a6d-4e5f-9b0a-1c2d3e4f5a6b",
        "name": "Main",
        "address_1": "Unit 4, Docklands Innovation Park",
        "address_2": null,
        "city": "Dublin 1",
        "county": "Dublin",
        "eircode": "D01 X2Y3",
        "country": "Ireland"
      }
    },
    "ship_to": {
      "source_id": "contact_8a3e2c1d-4b5f-4e6a-9c7d-1e2f3a4b5c6d",
      "first_name": "Aoife",
      "last_name": "Murphy",
      "company_name": "Globex Ireland Ltd",
      "vat_number": "IE9876543W",
      "email": {
        "source_id": "email_3f2b8c1e-7a6d-4e5f-9b0a-1c2d3e4f5a6b",
        "name": "Main",
        "email": "accounts@globex.ie",
        "first_name": "Aoife",
        "last_name": "Murphy"
      },
      "phone": {
        "source_id": "phone_3f2b8c1e-7a6d-4e5f-9b0a-1c2d3e4f5a6b",
        "name": "Main",
        "phone": "+353 1 234 5678"
      },
      "address": {
        "source_id": "address_3f2b8c1e-7a6d-4e5f-9b0a-1c2d3e4f5a6b",
        "name": "Main",
        "address_1": "Unit 4, Docklands Innovation Park",
        "address_2": null,
        "city": "Dublin 1",
        "county": "Dublin",
        "eircode": "D01 X2Y3",
        "country": "Ireland"
      }
    },
    "items": [
      {
        "source_id": "catalog_5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a",
        "name": "Main",
        "category": "product",
        "description": null,
        "quantity": "1",
        "unit_price": "120.00",
        "vat": {
          "source_id": "vat_1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
          "name": "Main",
          "code": "S",
          "rate": "0.23"
        },
        "net": "120.00",
        "vat_amount": "27.60"
      }
    ],
    "bank_details": {
      "source_id": "bank_details_3f2b8c1e-7a6d-4e5f-9b0a-1c2d3e4f5a6b",
      "name": "Main",
      "bic": "AIBKIE2D",
      "iban": "IE29AIBK93115212345678",
      "account_number": null,
      "sort_code": null
    },
    "vat_breakdown": [
      {
        "name": "Main",
        "code": "S",
        "rate": "0.23",
        "net": "120.00",
        "vat": "27.60"
      }
    ],
    "subtotal": "120.00",
    "vat_total": "27.60",
    "total": "147.60",
    "credited": "120.00",
    "amount_due": "120.00"
  },
  "send": {
    "id": "invoice_send_3f2b8c1e-7a6d-4e5f-9b0a-1c2d3e4f5a6b",
    "created_at": "2026-10-27T09:30:00.000Z",
    "updated_at": "2026-10-27T09:30:00.000Z",
    "invoice_id": "invoice_9f8e7d6c-5b4a-4c3d-2e1f-0a9b8c7d6e5f",
    "status": "pending",
    "scheduled_at": "2026-10-27T09:30:00.000Z",
    "sent_by_user_id": "user_3f2b8c1e-7a6d-4e5f-9b0a-1c2d3e4f5a6b",
    "sent_by_api_key_id": "api_key_3f2b8c1e-7a6d-4e5f-9b0a-1c2d3e4f5a6b",
    "to": [
      "…"
    ],
    "cc": [
      "…"
    ],
    "bcc": [
      "…"
    ],
    "message": "Here's your invoice. Thanks again!"
  }
}

Cancel a scheduled send

POST/v1/invoice/send/cancel

Only while it is still scheduled. Fails with 409 if it has already gone out. The invoice stays issued.

Needs the invoice:write permission

Body

idinvoice send idrequired

Request

curl -X POST https://api.zulu.ie/v1/invoice/send/cancel \
  -H "Authorization: Bearer $ZULU_API_KEY" \
  -H "Zulu-Business-Id: $ZULU_BUSINESS_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "invoice_send_3f2b8c1e-7a6d-4e5f-9b0a-1c2d3e4f5a6b"
  }'

Example response200

Response · 200

{
  "id": "invoice_send_3f2b8c1e-7a6d-4e5f-9b0a-1c2d3e4f5a6b",
  "created_at": "2026-10-27T09:30:00.000Z",
  "updated_at": "2026-10-27T09:30:00.000Z",
  "invoice_id": "invoice_9f8e7d6c-5b4a-4c3d-2e1f-0a9b8c7d6e5f",
  "status": "pending",
  "scheduled_at": "2026-10-27T09:30:00.000Z",
  "sent_by_user_id": "user_3f2b8c1e-7a6d-4e5f-9b0a-1c2d3e4f5a6b",
  "sent_by_api_key_id": "api_key_3f2b8c1e-7a6d-4e5f-9b0a-1c2d3e4f5a6b",
  "to": [
    "…"
  ],
  "cc": [
    "…"
  ],
  "bcc": [
    "…"
  ],
  "message": "Here's your invoice. Thanks again!"
}

Change when a scheduled send goes out

POST/v1/invoice/send/reschedule

Only while it is still scheduled. The invoice keeps its date. Fails with 409 if it has already gone out.

Needs the invoice:write permission

Body

idinvoice send idrequired
scheduled_attimestamprequired
From a minute to 30 days ahead

Request

curl -X POST https://api.zulu.ie/v1/invoice/send/reschedule \
  -H "Authorization: Bearer $ZULU_API_KEY" \
  -H "Zulu-Business-Id: $ZULU_BUSINESS_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "invoice_send_3f2b8c1e-7a6d-4e5f-9b0a-1c2d3e4f5a6b",
    "scheduled_at": "2026-10-27T09:30:00.000Z"
  }'

Example response200

Response · 200

{
  "id": "invoice_send_3f2b8c1e-7a6d-4e5f-9b0a-1c2d3e4f5a6b",
  "created_at": "2026-10-27T09:30:00.000Z",
  "updated_at": "2026-10-27T09:30:00.000Z",
  "invoice_id": "invoice_9f8e7d6c-5b4a-4c3d-2e1f-0a9b8c7d6e5f",
  "status": "pending",
  "scheduled_at": "2026-10-27T09:30:00.000Z",
  "sent_by_user_id": "user_3f2b8c1e-7a6d-4e5f-9b0a-1c2d3e4f5a6b",
  "sent_by_api_key_id": "api_key_3f2b8c1e-7a6d-4e5f-9b0a-1c2d3e4f5a6b",
  "to": [
    "…"
  ],
  "cc": [
    "…"
  ],
  "bcc": [
    "…"
  ],
  "message": "Here's your invoice. Thanks again!"
}

Totals for an overview: outstanding, overdue, paid and issued

GET/v1/invoice/summary

Invoices only, per currency. Each amount is the invoice total less its issued credit notes. Outstanding: open with something left to pay. Overdue: outstanding and past its due date (Irish time). Paid and issued this month and last month (for comparisons): by calendar month in Ireland; issued leaves out void invoices.

Needs the invoice:read permission

Request

curl https://api.zulu.ie/v1/invoice/summary \
  -H "Authorization: Bearer $ZULU_API_KEY" \
  -H "Zulu-Business-Id: $ZULU_BUSINESS_ID"

Example response200

Response · 200

{
  "as_of": "2026-10-27",
  "currencies": [
    {
      "currency": "EUR",
      "outstanding": {
        "count": 1,
        "amount": "147.60"
      },
      "overdue": {
        "count": 1,
        "amount": "147.60"
      },
      "paid_this_month": {
        "count": 1,
        "amount": "147.60"
      },
      "paid_last_month": {
        "count": 1,
        "amount": "147.60"
      },
      "issued_this_month": {
        "count": 1,
        "amount": "147.60"
      },
      "issued_last_month": {
        "count": 1,
        "amount": "147.60"
      }
    }
  ]
}

PreviousBasics NextCustomers