4 Customer API

The related collection of entities associated with the "Customer": 

• Customer - the main entity that represents the account being invoiced. This may represent either an individual or an organization

• billingContact - this child entity of the customer represents the specific contact (individual) that will receive the invoice. The "Bill To" fields on the invoice will reflect this value if not overridden at the invoice level. This entity is required when creating a Customer entity. Note that the billingContact is an instance of the CustomerContact class.

• salesContact - this child entity of the customer is optional and represents the default "Ship To" details. As before, an invoice may override the "Ship To" fields for that specific invoice. Note that the salesContact is an instance of the CustomerContact class.

• CustomerFinancials - this entity represents provides a snapshot of the customer's current financial standing with fields such as current balance, last payment, etc.

  • PaymentMethodDTO - this is a generic Data Transfer Object that contains a specific payment method embedded inside. This is used when you wish to automatically charge the customer on the invoice due date by having the customer's payment information on file. Examples of the specific payment method include creditCardPaymentMethod and achPaymentMethod.

4.1 Retrieve Customer

Note: eBill will NEVER return any of the *PaymentMethod objects or sensitive fields like passwords for security reasons (you may replace the current values however).

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

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

4.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.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.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>Acme Co</name> 

  <status>Active</status>

  <extCustomerRef>bj444</extCustomerRef>   <crmCustomerId>xyz12345</crmCustomerId> 

  <erpCustomerId>abc9876</erpCustomerId> 

  <isBusinessAccount>true</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@acme.com</emailPrimary>

    <workPhone>555 555 1234</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>

4.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.6. Delete a Customer

It returns the confirmation status

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

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

4.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. 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.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]

4.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>