Draft invoices are customer invoices that have been created but not yet validated in Pennylane. They are commonly used during invoice preparation and review workflows before final posting.

Filtering draft invoices helps you retrieve the right drafts efficiently — for example to display pending drafts, sync them with an external billing system, or locate a specific draft by reference.

This guide shows how to filter draft invoices using the filters[] parameter on the GET /customer_invoices endpoint.

📘

Reminder: Filters use a JSON array passed as the filters query parameter. See Filter API Data for the general filtering syntax and operators.

How Filtering Works

Draft invoices are retrieved by filtering customer invoices on their status:

[
  { "field": "status", "operator": "eq", "value": "draft" }
]]

Example request:

GET /customer_invoices?filters=[{"field":"status","operator":"eq","value":"draft"}]

You can combine multiple filters to narrow down results further.

Common Use Cases

Filtering draft invoices is typically used to:

• List invoices pending validation
• Retrieve a specific draft invoice by reference
• Sync draft invoices between Pennylane and an external system
• Support internal review or approval workflows

Examples

Retrieve draft invoices

GET /customer_invoices?filters=[
  {"field":"status","operator":"eq","value":"draft"}
]

Retrieve a specific draft invoice by invoice number

GET /customer_invoices?filters=[
  {"field":"status","operator":"eq","value":"draft"},
  {"field":"invoice_number","operator":"eq","value":"TEST"}
]

Available Fields and Operators

✍️

Note: Draft invoices are identified using status = "draft" on the customer invoices endpoint.

Tips & Troubleshooting

• Filtering by invoice_number uses exact matching (not partial search).
• Always URL-encode the filters[] parameter to avoid 400 Bad Request errors.
• This endpoint returns cursor-based pagination (has_more, next_cursor). Use the cursor parameters supported by the API when iterating over large datasets.
• If you want to retrieve validated invoices, adjust the status filter accordingly or remove it.