Migrating from 3.1 to 4.0 Simple
Important information to update from 3.1 to 4.0s of the API.
Please make sure you have migrated to 3.1 first before migrating to 4.0s 3.1 Migration Guide
4.0 Simple (4.0s) is a presentation of the same /api/v4/ API documented under 4.0, written for integrations that address records by their own identifiers. It is not a separate version of the API: there is no /api/v4s/ URL, and a request built from these pages is an ordinary 4.0 request. What differs is the presentation — these pages identify records by externalId and keep the flat customer structure, which makes the move from 3.1 smaller in scope than the full 4.0. externalId is an accepted identifier rather than a required one, and 4.0 accepts it too: every 4.0 endpoint takes _id, globalRecordId or externalId.
Breaking Changes
- Update requests to .../api/v4/... instead of .../api/v3.1/... .
- Money is now sent and returned as an integer number of cents. In 3.1 the same fields took decimal dollars, so 45.99 in 3.1 becomes 4599 in 4.0s.
- This applies to money fields generally — invoice totals, taxes, discounts, line item unit prices and totals, payment amounts, allocations, item unit prices, and every other amount you send or receive — not to a single field.
- This is a silent change: the same payload is accepted at both versions with no error, and means a hundred-fold different amount. Both directions are easy to hit.
- Sending unchanged 3.1 values to 4.0s undercharges a hundred-fold: a 45.99 that meant $45.99 is read as cents and charges about $0.46.
- Reading a 4.0s response as dollars overcharges a hundred-fold: a returned 4599 is $45.99 in cents, but read as dollars it becomes $4599.00.
- POST{base_url}/api/v4/site/{site_id}/invoice/addUpdate
- POST{base_url}/api/v4/site/{site_id}/item/addUpdate
- The notification_options field has been removed from the Customer.
- 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
- The attachments field (a plain list of URLs) has been replaced by the attachmentRefs object, which organises attachments into internal , external , and sourcePdf 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