4.1 Customer API

4.1. Retrieve Customer and all details:

Returns this object graph: Customer, billingContact, salesContact, CustomerFinancials. Note: NEVER return any of the *PaymentMethod data, they can replace the current values, but we never allow them to retrieve the data back.

GET /rest/customer/[id]?format=xml

GET /rest/customer? format=xml&extCustomerRef=[code] 

4.1.2. Retrieve CustomerContact:

Returns either the billingContact or SalesContact

GET /rest/customer/[id]/salesContact?format=xml

GET /rest/customer/salesContact?format=xml&extCustomerRef=[code]

GET /rest/customer/[id]/billingContact? format=xml

GET /rest/customer/billingContact?format=xml&extCustomerRef=[code] 

4.1.3. Retrieve multiple Customers:

Returns a list of matching customers

GET /rest/customers?format=xml&search=[searchTerm] 

Returns a paged list of customers. All params are optional and may be combined
Defaults used if the query string parameters are missing:

• • • • statusValue = ignored if not defined

      • offset=0

      • max=50

      • createStartTime and createEndTime are optional params and can be used to retrieve a list of records created between the specified date range. Note that if createStartTime is specified and createEndTime is not specified, then createEndTime defaults to the current date/time

      • updateStartTime and updateEndTime are optional params and can be used to retrieve a list of records updated between the specified date range. Note that if updateStartTime is specified and updateEndTime is not specified, then updateEndTime defaults to the current date/time

GET /rest/customers? format=xml&offset=[n]&max=[m]&status=[statusValue]&createStartTime=[YYYYMMDDHHmm]&createEndTime=[YYYYMMDDHHmm]&updateStartTime=[YYYYMMDDHHmm]&updateEndTime=[YYYYMMDDHHmm] 

4.1.4. Create a new Customer:

The XML that is POSTED should contain the Customer object, the billingContact (required) and optionally the salesContact. It returns the full XML (same response as the "GET customer/[id]?format=xml"

POST /rest/customers?format=xml 

Sample POST payload:

<customer>

  <name>Bill Joseph</name>

  <status>Active</status>

  <extCustomerRef>bj444</extCustomerRef>

  <locale>en_US</locale>

  <isBusinessAccount>false</isBusinessAccount>

  <paymentTermsValue>30</paymentTermsValue>

  <paymentTermsUnits>Days</paymentTermsUnits>

  <currency id="USD"/>

  <billingContact>

    <username>bill0004</username>

    <passwd>Sachxwe001</passwd>

    <firstName>Bill</firstName>

    <lastName>Joseph</lastName>

    <emailPrimary> Bill@bmontgomery.com</emailPrimary>

    <workPhone>324 555 879</workPhone>

    <address>

      <street1>43 Main Av</street1>

      <city>Chicago</city>

      <state>IL</state>

      <zip>12345</zip>

      <country>United States</country>

      <countryCode>usa</countryCode>

    </address>

  </billingContact>

</customer> 

If the tax configuration is enabled, then we are validating the address by using the Avalara API. If the customer creation and address validation is OK. Then its response will be the customer data in XML form and status code will be 200 OK. And if only customer creation is successfully done, and address is not valid then the status code will be 201 and response has given below.

Same condition will be apply for updating a existing customer .

      <status>

    <success>True</success>

      <customer>

        <id>341</id>

        <extCustomerRef>cus1001</extCustomerRef>   

      </customer>

      <errors>

   <error>An exact street name match could not be found and phonetically matching the street name resulted in either no matches or matches to more than one street name</error>

   </errors>   

     </status> 

4.1.5. Update an existing Customer:

The XML that is POSTED could contain only the Customer object, or it could optionally include the billingContact and the salesContact. It returns the full XML (same response as the "GET customer/[id]? format=xml"

PUT /rest/customer/[id]?format=xml

PUT /rest/customer? format=xml&extCustomerRef=[code] 

The following calls permit an existing Customer Contact to be updated. The returned XML is the same as the corresponding GET call

PUT /rest/customer/[id]/salesContact?format=xml

PUT /rest/customer/ [id]/billingContact?format=xml

PUT /rest/customer/salesContact?format=xml&extCustomerRef=[code]

PUT /rest/customer/billingContact?format=xml&extCustomerRef=[code] 

4.1.6. Delete a Customer:

It returns the confirmation status

DELETE /rest/customer/[id]?format=xml

DELETE /rest/customer? format=xml&extCustomerRef=[code] 

4.1.7. Add or Replace an autopay method:

The XML that is POSTED should contain one paymentMethodDTO. Inside the we could have either an or a . This maps to the customerService.savePaymentMethod.

Returns success or error XML. Note that PaymentMethods such as credit cards and ACH cannot be queried / retrieved for security reasons, they can only be created or updated. Inside the we could have one of creditCardPaymentMethod, achPaymentMethod, tokenPaymentMethod, checkPaymentMethod, or cashPaymentMethod. If the autopayPreference field is the same, then the previous autopay method will be replaced by the current one. Note that each customer can have up to 3 payment methods on file as indicated by the <autopayPreference> value which can range from 1 to 3. The system will process payment using the 1st preferred payment method, and try the 2nd preferred payment method only if the 1st one declines, etc.

If the "validate=true" is passed in with the querystring params, then the credit card is validated via a call to the configured payment gateway (note: this requires that your payment gateway permits $0 transactions, please check beforehand on approvals required and transaction charges)

PUT /rest/customer/[id]/autopay?format=xml&validate=true

PUT /rest/customer/autopay?format=xml&extCustomerRef=[code]&validate=true

Sample POST:

<autopay>

  <paymentMethodDTO type="CreditCard">

    <creditCardPaymentMethod>

      <autopayPreference>1</autopayPreference>

      <cardNumber>4111111111111111</cardNumber>

      <expiry>2010-12-31</expiry>

      <cardType>Visa</cardType>

      <cardholderName>John Villanova</cardholderName>

      <cvv>1234</cvv>

      <billingAddress>

        <street1>9872 Central St</street1>

        <city>Anytown</city>

        <state>AK</state>

        <zip>11001</zip>

        <country>USA</country>

      </billingAddress>

    </creditCardPaymentMethod>

  </paymentMethodDTO>

</autopay>

To get all payment autoPay methods of a customer use GET request to following endpoint.
GET /rest/customer/[customerId]/autopay

4.1.8. Other operations on a Customer

 The [actionName] may be one of the following:

  [suspend] - suspend a customer's billing activity.
  [activate] - activate a new customer or a suspended customer.

POST /rest/customer/[id]?format=xml&actionName=[command]

POST /rest/customer?format=xml&extCustomerRef= [code]&actionName=[command]

Create a new Customer with an Order: DEPRECATED

This call is used to first create a Customer and then an Order. It is an atomic operation. The XML that is POSTED should contain the Customer object, the billingContact (required) and optionally the salesContact. In addition, a collection of one or more Orders will be created. It returns the full XML that contains the Customer and Order collection

POST /rest/customers? format=xml&actionName=addCustomerAndOrder

The request payload:

<addCustomerAndOrder>

 <customer>

    ...

 </customer>

 <subscriptionOrders>

  <subscriptionOrder>

   ... <!-- first order -->

  <subscriptionOrder>

  <subscriptionOrder>

   ... <!-- second order (Optional) -->

  <subscriptionOrder>

 <subscriptionOrders>

</addCustomerAndOrder>

and the response:

<addCustomerAndOrderResponse>

 <customer id="123">

 <subscriptionOrder id="xyz">

</addCustomerAndOrderResponse>

4.1.9 Customer Transitions

Customers can transition between various states depending on whether their accounts are current or overdue ("ageing" or "dunning"). The actual transitions may be configured by logging into BluBilling and accessing the "System >> Overdue Notifications" menu. The following states are available:

        'Active',

        'Overdue1',

        'Overdue2',

        'Overdue3',

        'Suspended1',

        'Suspended2',

        'Suspended3',

        'InActive1',

        'InActive2',

As an example, you may choose to set the customer status to 'Overdue1" when they are 15 days behind their payment, then change the status to 'Overdue2' at 30 days, and finally to 'Suspended1' at 60 days. So the customer status will change at 15, 30, and 60 days so that you may take appropriate steps on your side such as disabling users, etc.

If you wish to receive a callback notification to your website/application via a HTTP POST, then select the events of interest to you under the "System >> Website Callbacks". On this screen, you can register your URL (https recommended) as well as the events of interest (such as Customer transitions, payment failed, payment success, etc.) The data sent in the HTTP POST is the same XML data that is retrieved in a REST query (see below).

On the other hand, you may wish to query for the customer transitions within a date range:

GET /rest/customers/transitions?format=xml

GET /rest/customers/transitions?format=xml&startDate=[date1]&endDate=[date2]
GET /rest/customers/transitions?format=xml&endDate=[date]&daysAgo=30

Note: The endDate defaults to today if not specified, startDate defaults to 30 days prior to the endDate

Dates must be specified as YYYY-MM-DD (example "2010-12-31" for Dec 12, 2010).

<list>

  <customerTransition id="1">

    <dateTransitioned>2010-11-01</dateTransitioned>

    <previousStatus>Active</previousStatus>

    <newStatus>Overdue1</newStatus>

    <customer id="316">

      <extCustomerRef>JRICH</extCustomerRef>

      ...

    </customer>

  </customerTransition>

  <customerTransition id="2">

    <dateTransitioned>2010-11-01</dateTransitioned>

    <previousStatus>Overdue1</previousStatus>

    <newStatus>Suspended1</newStatus>

    <customer id="832">

      <extCustomerRef>AGEORGE</extCustomerRef>

      ...

    </customer>

  </customerTransition>

</list>

4.1.10 Create a Payment Plan

A payment plan is specific to a customer and is intended to allow them to pay off their outstanding balance in installments. This outstanding balance could due to a single invoice or from multiple invoices. 

While a payment plan is active for a customer, the system will not attempt to automatically pay the entire invoice(s) balance, rather, it will process the lesser of the installment amount or the outstanding customer balance instead. You can override this behavior by setting the <chargeOnlyIfBalanceOwed> element to false in which case the system will process the installment amount on the scheduled date regardless of the customer balance.

To create a new payment plan:

POST /rest/customers/paymentPlan?format=xml&id=[customerId]

POST /rest/customers/paymentPlan?format=xml&extCustomerRef=[extCustomerRef]

The XML payload for the above operation:

<paymentPlan>

   <chargeAmount>199.00</chargeAmount> <!-- this is the periodic installment amount -->

   <startDate>2016-11-01</startDate> <!-- the date on which to process the 1st installment -->

   <totalNumberOfInstallments>4</totalNumberOfInstallments> <!-- the number of installments -->

   <!-- the periodic interval at which the installments are to be charged -->

   <frequencyValue>1</frequencyValue>

   <frequencyUnits>Months</frequencyUnits> <!-- options are Days | Weeks | Months | Quarters | Years -->

</paymentPlan>

4.1.11 Retrieve a Payment Plan

To retrieve a new payment plan:

GET /rest/customers/[customerId]/paymentPlan?format=xml

GET /rest/customers/paymentPlan?format=xml&extCustomerRef=[extCustomerRef]

The sample XML payload below shows the case where 1 installment has already been charged and 3 installments are remaining.

<paymentPlan id="123">

   <chargeOnlyIfBalanceOwed>true</chargeOnlyIfBalanceOwed> 

   <chargeAmount>199.00</chargeAmount>

   <startDate>2016-11-01</startDate>

   <nextPaymentDate>2016-12-01</nextPaymentDate>

   <totalNumberOfInstallments>4</totalNumberOfInstallments>

   <remainingInstallments>3</remainingInstallments>

   <frequencyValue>1</frequencyValue>

   <frequencyUnits>Months</frequencyUnits>

   <isEnabled>true</isEnabled>

</paymentPlan>

4.1.12 Update a Payment Plan

The recommended way to update a payment plan is to first do a GET operation, change the values and then perform a POST operation

To create a new payment plan:

PUT /rest/customers/paymentPlan?format=xml&id=[customerId]

PUT /rest/customers/paymentPlan?format=xml&extCustomerRef=[extCustomerRef]

The XML payload for the PUT operation is the same as the GET operation in 4.1.11 above

4.1.13 Delete a Payment Plan

Deleting a payment plan is a shortcut to setting the <isEnabled> element to false and does not require a XML payload

DELETE /rest/customers/paymentPlan?format=xml&id=[customerId]

DELETE /rest/customers/paymentPlan?format=xml&extCustomerRef=[extCustomerRef]

4.1.14 Email Notification to a Customer

This API call will result in the appropriate email notification being sent to the customer. The notifications are managed under the [System >> Notifications >> Customer Notifications] menu and the selected notification type must be enabled for this API to send out the notification.

POST /rest/customers/notification

The XML payload for the above operation:

<sendEmail>

    <eventType>EVENTNAME</eventType>

    <!-- either the objectId or the objectNumber must be specified -->

    <objectId><objectId>

    <objectRef>INV1001</objectRef>

    <!-- the customer number or Id can be optionally sent to validate that the object is associated with this customer -->

    <customerRef>CUS1001</customerRef>

    <customerId>CUS1001</customerId>

</sendEmail>

eventType -  it will have one of the three values for now,  newInvoice, newOrder and paymentReceived. 

                 -  case sensitive and mandatory.
objectId , objectRef - any one of the field should be present with a valid value.

customerId , customerRef - any one of the field must be present with a valid value.

The XML response for the above operation:

<response>

    <success>true</success>

    <message>Mail Send successfully</message>

</response>

success - will have either true or false,

message - corresponding message received from the system