Home‎ > ‎Developer's Guide‎ > ‎REST Web Service API‎ > ‎

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.
Defaults used if the query string parameters are missing:
   statusValue = ignored if not defined
   offset=0
   max=50


GET /rest/customers? format=xml&offset=[n]&max=[m]&status=[statusValue]

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>


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 XL 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 XL 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 XL 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]



Comments