Billing API

Overview

The following provides information when using the API for the creation of Billing Records including the following:

• Object API names
• Required fields for inserting a record
• Posting and Unposting Global Classes
• Posting and Unposting via REST API

Billings

A billing object is a common integration point for the Accounting Seed Financial Suite. Please note the following:

1. The billing is a single object that handles both sales invoices and credit memos. The net total of the Billing_Line__c.Total__c field on the billing line determines if the Billing is an Invoice or Credit Memo. This is represented in a Roll-Up Summary called Total__c on the Billing object. If Total__c is a positive number then the Type__c is automatically determined to be "Invoice" on the Billing. If Total__c is a negative number, then Type__c is automatically determined to be a "Credit Memo."
2. There is a limit of 500 Billing Lines to a single Billing.

The following fields are required on the Billing Object: AcctSeed__Billing__c

Field Name	API Name	Type
Customer	AcctSeed__Customer__c	Lookup (Customer)

The following fields are required on the Billing Line object: AcctSeed__Billing_Line__c

Field Name	API Name	Type
Billing	AcctSeed__Billing__c	Master-Detail (Billing)
Units	AcctSeed__Hours_Units__c	Number (12,6)
Rate	AcctSeed__Rate__c	Currency (12,6)

Posting or Unposting via Apex Code

The following provides information when using the API for posting or unposting a Billing via Apex Code.

There is a global class in the Accounting Seed Financial Suite managed package called BillingPostService. This class can be called through Apex Code external to the Accounting Seed Financial Suite package to post or unpost a set of billing records. Please note the following:

• This class contains two static global methods. One of the static methods is related to posting billing records and is called postBillings. The other static method is related to unposting billing records and is called unpostBillings.
• You cannot call either the post or unpost methods with a set of billing records where the aggregate line count is more than 1,000 billing lines. If you need to post or unpost more than 1,000 billing lines, you will need to call the class static method from a class which supports batch apex.
• Each method returns a list of post result records, which will indicate if the billing was posted or unposted successfully. If the record was not posted or unposted successfully, an error status code is provided documenting the reason the record was not posted or unposted.

Supported Error Status Codes for the BillingPostService class

Billing Post Method

• NO_LINES – The billing records do not have any associated billing lines and cannot be posted.
• LINE_COUNT_LIMIT_EXCEEDED – Attempted to post a set of billing records where the aggregate number of billing lines exceeded 1,000.
• STATUS_NOT_APPROVED – The billing posting status is not approved.
• ALREADY_POSTED – Record you are attempting to post is already posted.
• NO_CONTROL_AR_ACCOUNT_DEFINED – No AR GL Control Account is defined on the accounting settings tab.
• NO_BILLING_LINES – No billing lines are associated with the billing.
• CLOSED_ACCOUNTING_PERIOD – The accounting period associated with the billing is closed.
• SYSTEM_EXCEPTION – Internal exception.

Billing Unpost Method

• LINE_COUNT_LIMIT_EXCEEDED – Attempted to unpost a set of billing records where the aggregate number of billing lines exceeded 1,000.
• BILLING_CASH_RECEIPTS_EXIST – Billing cash receipts exist associated with the billing. You must delete all billing cash receipts before you can unpost.
• BILLING_CREDIT_MEMOS_EXIST – Billing credit memos exist which are associated with this billing. You must delete all billing credit memos before you can unpost.
• CLOSED_ACCOUNTING_PERIOD – The accounting period associated with the billing is closed.
• SYSTEM_EXCEPTION – Internal exception.

Example using the BillingPostService class to post and unpost a set of billing records

The following example posts and unposts a set of billing records:

// Create billing records to post and unpost
List<AcctSeed__Billing__c> billings = new List <AcctSeed__Billing__c> ();
billings.add(
  new AcctSeed__Billing__c(
    AcctSeed__Customer__c = [Select Id From Account Limit 1].Id
  )
);

billings.add(
  new AcctSeed__Billing__c(
    AcctSeed__Customer__c = [Select Id From Account Limit 1].Id
  )
);

insert billings;

// Create billing line records to post and unpost:
List <AcctSeed__Billing_Line__c> bLines = new List <AcctSeed__Billing_Line__c> ();

for (AcctSeed__Billing__c bill : billings) {
  AcctSeed__Billing_Line__c objBillingLine = new AcctSeed__Billing_Line__c();
  objBillingLine.AcctSeed__Billing__c = bill.id;
  objBillingLine.AcctSeed__Rate__c = 25;
  objBillingLine.AcctSeed__Hours_Units__c = 1;
  bLines.add(objBillingLine);

  objBillingLine = new AcctSeed__Billing_Line__c();
  objBillingLine.AcctSeed__Billing__c = bill.id;
  objBillingLine.AcctSeed__Rate__c = 25;
  objBillingLine.AcctSeed__Hours_Units__c = 2;
  bLines.add(objBillingLine);
}

insert bLines;

// Call the post billings service
AcctSeed.PostResult[] postResults = AcctSeed.BillingPostService.postBillings(billings);

// Loop through post results
for (AcctSeed.PostResult theResult : postResults) {
  if (theResult.isSuccess) {
    System.debug('Successfully posted billing: ' + theResult.id);
  }
  else {
    System.debug('Error posting billing ' + theResult.id);
    for (AcctSeed.PostResult.PostErrorResult errorResult: theResult.errors) {
      System.debug('Error status code ' + errorResult.statusCode);
      System.debug('Error message ' + errorResult.message);
    }
  }
}

// Call the unpost billings service
AcctSeed.PostResult[] unpostResults = AcctSeed.BillingPostService.unpostBillings(billings);

// Loop through unpost results
for (AcctSeed.PostResult theResult : unpostResults) {
  if (theResult.isSuccess) {
    System.debug('Successfully unposted billing: ' + theResult.id);
  }
  else {
    System.debug('Error unposting billing ' + theResult.id);
    for (AcctSeed.PostResult.PostErrorResult errorResult: theResult.errors) {
      System.debug('Error status code ' + errorResult.statusCode);
      System.debug('Error message ' + errorResult.message);
    }
  }
}

Posting or Unposting a Billing via the REST Webservice

Below is the URI you can leverage to post and unpost billings utilizing the REST webservice. The same set of error codes associated with the Apex Code BillingPostService class can be returned for both posting and unposting via the REST webservice.

Billing Post Method

• Use the HTTP PUT method to invoke the REST webservice.
• Same set of error status codes as invoking postBillings method in BillingPostService class via Apex Code. In addition the following error code can be returned:
  • INVALID_BILLING_ID – An invalid billing ID has been provided.

URI

<SERVER>/services/apexrest/AcctSeed/v1.0/billing/post/<BILLING_ID>

Example

https://<MY_DOMAIN>.my.salesforce.com/services/apexrest/AcctSeed/v1.0/billing/post/<BILLING_ID>

Billing Unpost Method

• Use the HTTP DELETE method to invoke the REST webservice.
• Same set of error status codes as invoking unpostBillings method in BillingPostService class via Apex Code. In addition the following error code can be returned:
  • INVALID_BILLING_ID – An invalid billing ID has been provided.

URI

<SERVER>/services/apexrest/AcctSeed/v1.0/billing/post/<BILLING_ID>

Example

https://<MY_DOMAIN>.my.salesforce.com/services/apexrest/AcctSeed/v1.0/billing/post/<BILLING_ID>

See also the Billing Test Class.