Client Billing Settings

Database Constraint

There can only be one client-billing-settings record for a Client ID. Trying to create more than one record will result in an error. For now it’s a 500 status code + “Access Denied” message.

In the future it will be better caught and a validation error message returned.

Basic Record

Here’s a sample post to create a client-billing-settings record where the Client ID of 687 is already known:

[POST] /client-billing-settings

{
 "client": 687, 
 "distributeByEmail": false, 
 "distributeByFax": false, 
 "distributeByMail": false, 
 "distributionNote": "", 
 "emailList": [], 
 "faxNumber": "", 
 "flagForReview": false, 
 "invoiceAttentionOf": "", 
 "invoicePermanentMemo": "", 
 "taxClass": null, 
 "taxExempt": false, 
 "taxExemptCode": "", 
 "useMainAddress": true
}

You can provide additional information to feed into relation lists of emailList and billingAddress:

{
   "useMainAddress": true,
   "distributeByMail": false,
   "distributeByEmail": false,
   "emailList": ["email1@domain.com,email2@domain.com"],
   "distributeByFax": false,
   "faxNumber": "",
   "taxClass": null,
   "taxExempt": false,
   "taxExemptCode": "",
   "distributionNote": "",
   "invoicePermanentMemo": "",
   "invoiceAttentionOf": "",
   "flagForReview": false,
   "billingAddress" : {
       "addressLine1" : "123 Main Street",
       "addressLine2": "",
       "city" : "Montréal",
       "country": "CA",
       "state": "QC",
       "postalCode": "H2W 2R2"
   }
}

When a billingAddress is provided, and Address record will also be created and become a relation list for the client-billing-settings record. It will be visible in the response as a key:value pair like:
 

"billingAddress" : 1626,
 

All the information from relation lists can be retrieved using “include” parameters:

[GET] /client-billing-settings/38?include=billingAddress

{
       "useMainAddress": false,
       "distributeByMail": false,
       "distributeByEmail": false,
       "emailList": [
           "email1@domain.com",
           "email2@domain.com"
       ],
       "distributeByFax": false,
       "faxNumber": "",
       "client": 687,
       "taxClass": null,
       "paymentTerm": "",
       "taxExempt": false,
       "taxExemptCode": "",
       "distributionNote": "",
       "invoicePermanentMemo": "",
       "invoiceAttentionOf": "",
       "flagForReview": false,
       "id": 38,
       "billingAddress": {
           "addressLine1": "123 Main Street",
           "addressLine2": "",
           "city": "Montréal",
           "country": "CA",
           "state": "QC",
           "postalCode": "H2W 2R2",
           "latitude": null,
           "longitude": null,
           "id": 1626
       }
   }

Notice how the comma separated single-string of email addresses has become an array of separate strings.
 

"emailList": ["email1@domain.com,email2@domain.com"],
vs
"emailList": [ "email1@domain.com", "email2@domain.com" ],
 

When patching the list of emails, you must continue to use the comma separated values format.
 

emailList

The emailList is an array of email addresses that can be entered via the web application as well in the client site’s billing settings:

WARNING: billingAddress vs "useMainAddress": true,

When a Client Billing Setting is receiving an address for the first time, an address record will be created in the database and its primary key for that record included as the billingAddress value in API responses. This is how the address can be included as a relation list.

When PATCHing an address, it’s important to take note of what true|false valuethe useMainAddress key has. When useMainAddress field is set to TRUE, there will be a NEW address record created, and a new ID number will be assigned. If you PATCH over and over with useMainAddress set to true, a new address and new ID number will be generated each time.

If you’d like to simply update a billingAddress without generating any new records or ID numbers, make sure to have "useMainAddress": false in your payload.

This is what happens when you don’t:

BEFORE

{
       "useMainAddress": false,
       "billingAddress": 1626,
       "distributeByMail": false,
       "distributeByEmail": false,
       "emailList": [
           "email1@domain.com",
           "email2@domain.com"
       ],
       "distributeByFax": false,
       "faxNumber": "",
       "client": 687,
       "taxClass": null,
       "paymentTerm": "",
       "taxExempt": false,
       "taxExemptCode": "",
       "distributionNote": "",
       "invoicePermanentMemo": "",
       "invoiceAttentionOf": "",
       "flagForReview": false,
       "id": 38
   }

[PATCH] /client-billing-settings/38

{
   "useMainAddress": true,
   "billingAddress" : {
       "addressLine1" : "123 Main Street",
       "addressLine2": "",
       "city" : "Montréal",
       "country": "CA",
       "state": "QC",
       "postalCode": "H2W 2R2"
   }
}

Result :

{
       "useMainAddress": false,
 ==>   "billingAddress": 1627,         <== a new ID
       "distributeByMail": false,
       "distributeByEmail": false,
       "emailList": [
           "email1@domain.com",
           "email2@domain.com"
       ],
       "distributeByFax": false,
       "faxNumber": "",
       "client": 687,
       "taxClass": null,
       "paymentTerm": "",
       "taxExempt": false,
       "taxExemptCode": "",
       "distributionNote": "",
       "invoicePermanentMemo": "",
       "invoiceAttentionOf": "",
       "flagForReview": false,
       "id": 38
   }