Migrating from 3.1 to 4.0
Important information to update from 3.1 to 4.0 of the API.
Please make sure you have migrated to 3.1 first before migrating to 4.0 3.1 Migration Guide
Breaking Changes
POST
{base_url}/api/v4/
- Update requests to .../api/v4/... instead of .../api/v3.1/... .
POST
{base_url}/api/v4/site/{site_id}/customer/addUpdate
- Root-level contact fields ( first_name , last_name , email , mobile_phone ) must now be provided inside a primary_contact object, or as entries in the contacts array.
- The notification_options field has been removed. Notification preferences are now managed at the contact level.
POST
{base_url}/api/v4/site/{site_id}/invoice/addUpdate
- The fields bill_email , bill_email_cc , bill_email_bcc , and billing_address have been replaced by the bill_to object.
- The shipping_address field has been replaced by the sold_to object.
Products → Items
- The Products endpoint has been renamed to Items. Update requests to site/{site_id}/item/addUpdate instead of site/{site_id}/product/addUpdate .
- POST{base_url}/api/v4/site/{site_id}/item/addUpdate
Affecting
Attachments
- The attachments field (a plain list of URLs) has been replaced by the attachment_refs object, which organises attachments into internal , external , and source_pdf sub-fields.
- POST{base_url}/api/v4/site/{site_id}/invoice/addUpdate
- POST{base_url}/api/v4/site/{site_id}/customer/addUpdate
- POST{base_url}/api/v4/site/{site_id}/subscription/addUpdate
Affecting
Record Identification
- Records are now identified and updated by _id instead of external_id .
New in 4.0
POST
{base_url}/api/v4/site/{site_id}/contact/addUpdate
- Contacts are now first-class records. Use the Contact endpoints to create, retrieve, and manage contacts independently from customers.
POST
{base_url}/api/v4/site/{site_id}/invoice/addUpdate
- A new bill_to_customer field allows billing a different (e.g. parent) customer instead of the primary customer on the invoice.