API Docs 3.1API Docs 4.0 SimpleAPI Docs 4.0

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/... .
Money Values
  • 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.0.
  • 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.0 undercharges a hundred-fold: a 45.99 that meant $45.99 is read as cents and charges about $0.46.
  • Reading a 4.0 response as dollars overcharges a hundred-fold: a returned 4599 is $45.99 in cents, but read as dollars it becomes $4599.00.
  • One exception: the amount field on the refund endpoint was already an integer number of cents in 3.1 and is unchanged in 4.0.
    • Affecting
    • POST
      {base_url}/api/v4/site/{site_id}/invoice/addUpdate
    • POST
      {base_url}/api/v4/site/{site_id}/payment/addUpdate
    • POST
      {base_url}/api/v4/site/{site_id}/item/addUpdate
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 primaryContact 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 billTo object.
  • The shipping_address field has been replaced by the soldTo 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 .
    • Affecting
    • POST
      {base_url}/api/v4/site/{site_id}/item/addUpdate
Attachments
  • 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.
    • Affecting
    • 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
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 billToCustomer field allows billing a different (e.g. parent) customer instead of the primary customer on the invoice.