Changelog: API Unification of Customer Invoices Resources

Overview

We fully unified the invoice-related resources : draft invoices, customer invoices, and credit notes into a single comprehensive "customer invoices" resource.

What's Changing

Resource Unification

Customer Invoices endpoints (under customer_invoices:all and customer_invoices:readonlyscopes), are now fully compatible for draft invoices and credit notes (invoice with negative amounts).

Key Benefits

• Simplified API Navigation: Access all customer invoices types through a consistent set of endpoints
• Improved Resource Tracking: Follow a customer invoice through its entire lifecycle without switching between different endpoints
• Enhanced Attribute Consistency: Uniform representation of shared attributes across all customer invoices types

Resource representation

The Customer Invoices resource response includes these new fields:

• draft (boolean): Indicates if an invoice is in draft state. If false, it is considered as finalized or imported.
• credited_invoice: References the invoice which is credited when the record is a credit note.

The status attribute now includes two additional values:

• draft: For draft invoices
• credit_note: For credit notes

⚠︎ A draft credit_note will have a credit_note status.
⚠︎ If the credit note has been linked to a credited invoice it will have a cancelled status.

What is new in the Customer Invoices endpoints ?

- List customer invoices

New filters are available draft and credit_note to be able to filter resources.
To ensure backward compatibility during the transition period, no draft or credit notes will be rendered by default. More details in the Deprecations section below.

- Create a credit notes

The endpoint "Create a customer invoice" now supports the creation of draft or credit notes (using negative amounts).

A new boolean draftattribute is available to set the invoice as draft. By default, the invoice will be considered as finalized if not specified.

A credited invoice can also be linked using the credited_invoice_id attribute.

Of course, it is now possible to create draft credit_note.

- Import a credit notes (Same for Update imported credit note)

The endpoint "Import a customer invoice" now supports the creation of invoice or credit notes (using negative amounts).

A credited invoice can be linked using the credited_invoice_id attribute.

- Update an imported credit notes

The endpoint "Update an imported customer invoice" now supports the update of imported invoice or credit notes.

A credited invoice can be linked using the credited_invoice_id attribute.

- Turn the draft invoice into a finalized invoice.

Since it is now possible to create draft credit_note, it is also possible to finalize them using the already existing endpoint.

- Update a customer invoice

The Update a draft invoice and Update a finalized invoice endpoints are now deprecated and will be replaced by a single update endpoint that works for both draft and finalized customer invoices.

- Customer invoices summary :

The table below summarizes all customer invoices availability depending on the state of your invoice :

Deprecations

- Draft Invoices and Credit Notes endpoints

All endpoints listed in the Draft invoices and Credit Notes sections are now deprecated.

the oauth scopesdraft_invoices:all, draft_invoices:readonly, credit_notes:all, credit_notes:readonly are also deprecated.

- List customer invoices default filter :

To ensure backward compatibility during the transition period:

• ⚠︎Until may 14th 2025 : By default, the endpoint returns only finalized customer invoices (excluding credit notes and draft).
• ⚠︎From may 15th 2025 By default, the endpoint will return all invoices (customer invoices and credit notes, draft and not draft).

New filters draft and credit_note are available to be able to filter draft invoices or credit notes.

During the deprecation period, if you need to retrieve both customer invoices and credit notes , you will need to make separate requests using the appropriate filters:

# Filter to get all drafts
[{"field": "draft", "operator": "eq", "value": "true"}]

# Filter to get all "non draft" invoices
[{"field": "draft", "operator": "eq", "value": "false"}]

# Filter to get all credit notes
[{"field": "credit_note", "operator": "eq", "value": "true"}]

# Filter to get all customer invoices (excluding credit notes)
[{"field": "credit_note", "operator": "eq", "value": "false"}]

# Filter to get all draft customer invoices (excluding credit notes)
[{"field": "draft", "operator": "eq", "value": "true"}, {"field": "credit_note", "operator": "eq", "value": "true"}]

- Update a finalized customer invoice endpoint

This endpoint is deprecated in favor of the newly added Update a customer invoice. This new endpoint will allow you to update draft, finalized credit_notes and customer invoices.

Timeline

The deprecation period will end May 15th 2025.

Action Required

Look at the Deprecations section and migrate your implementation regarding incoming changes.

Questions?

If you have any questions about these changes or need assistance transitioning to the new unified resource model, please don't hesitate to contact our support team.