Changelog
Back to All
improved

V2 - Upcoming Merge for Finalized / Draft Customer Invoices and Credit Notes

March 26th, 2025 by Integrations Squad

Changelog: API Unification of Customer Invoices Resources

Overview

Following user feedback, we're planning an upcoming enhancement to our API that will simplify how you interact with invoice-related resources. In the coming weeks, until the end of April, we'll be unifying draft invoices, finalized invoices, and credit notes into a single comprehensive "customer invoices" resource.

The upcoming changes are non-breaking and are designed to improve your development experience while maintaining full backward compatibility with existing integrations.

What's Changing

Resource Unification

We're merging three separate resources:

  • Draft invoices
  • Finalized invoices
  • Credit notes

into a single, unified "customer invoices" resource that handles all customer invoices types through their lifecycle, from draft to finalized to credit note. The resources will be now accessible using the existing customer_invoices:all and customer_invoices:readonlyscopes.

draft_invoices:all, draft_invoices:readonly, credit_notes:all, credit_notes:readonly will be deprecated.

Resource representation

The Customer Invoices resource response includes these new fields:

  • draft (boolean): Indicates if an invoice is in draft state (true) or finalized (false)
  • credited_invoice_id: References the credited invoice when the record is a credit note

The status attribute now includes two additional values:

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

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

Timeline

These improvements will be rolled out gradually over the coming weeks, with full implementation expected by the end of April.
The deprecation period will end May 15th 2025. To ensure a smooth transition, the deprecated endpoints will be hidden from the documentation by the end of April 2025 to prevent new integrations using these endpoints

What This Means For You

No Breaking Changes

All existing endpoints will continue to function as they do today. Your current integrations will work without modification.

Gradual Deprecation

While we'll begin deprecating the endpoints in the Draft Invoices and Credit Notes categories, they will remain functional during the transition period.

What To Expect

  1. Documentation Updates: Our API documentation will be progressively updated to reflect the new unified resource model
  2. Deprecation Notice: Clear notices when older endpoints are scheduled for eventual removal

Action Required

No immediate action is required. Your existing integrations will continue to function as expected.

We recommend:

  • Reviewing the updated documentation as it becomes available
  • Planning to migrate to the new unified endpoints for future development
  • Testing your integrations with the new endpoints when they become available

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.