5. Invoice API

The related collection of entities associated with the "Invoice": 
  • Invoice - the main entity that represents a billable charge against a particular Customer.
  • InvoiceLineItem - these entities represent the individual line items on the invoice. Every invoice should have at least one of these entities.
  • InvoicePayment - this collection of associated objects indicate which payment(s) have been applied to which invoices and represent an many-to-many mapping between Invoice and Payment. When creating or updating the Invoice object, do not send the InvoicePayment object, it must be sent with the Payment entity instead.




Invoice Fields

Field Name

Data Type

Required

(C = Conditional)

Notes

Invoice Number

String (10)

Y

The unique invoice number as assigned by the source system.

CRM Invoice ID

String (25)

N

This is the internal ID of the Invoice  in the CRM system.

ERP Invoice ID

String (25)

N

This is the internal ID of the invoice  in the ERP system.

Customer Account Number

String (50)

C

The unique customer account that is displayed on invoice. Any one of the 3 customer identifiers must be provided

CRM Customer ID

String (25)

C

This is the internal ID of the customer in the CRM system. Any one of the 3 customer identifiers must be provided

ERP Customer ID

String (25)

C

This is the internal ID of the customer in the ERP system. Any one of the 3 customer identifiers must be provided

Invoice Custom Options

String (100)

N

Used for customization, leave blank unless instructed otherwise

Currency Code

String(3)

N

Currency code, default to “USD” if not provided

Status

Enum

Y

Valid values are:

 

'Outstanding' - Unpaid or partially paid

 

'Paid' - Full payment has been received

 

'Cancelled' - The invoice was cancelled after it was issued

 

'Draft' - Do not use, for system use only. Indicates

 

'Error' - Do not use, for system use only

 

Invoice Date

Date

Y

Date the invoice was generated.

Due Date

Date

Y

Date after which the invoice is considered overdue if full payment is not received. The customer status will change on if invoices are overdue.

Billing Start Date

Date

N

The start of the Billing Period

Billing End Date

Date

N

The end of the Billing period

Current Amount Due

Money

Y

This field represents the sum of all the Invoice Line Items.

Payments And Adjustments

Money

Y

Previous payments made to the invoice or credits applied

Previous Balance

Money

N

Do not use without contacting customer support. The practice of carrying forward balances from previous invoices is not recommended. Set to 0.00

Outstanding Balance

Money

Y

Net amount owned on this invoice. MUST be equal to

previousBalance + currentAmountDue - paymentsAndAdjustments

Invoice Mode

Enum

N

“Invoice” (default) or “Statement”.

Purchase Order Number

String(50)

N

PO Number if any

Shipping Carrier

String(50)

N

 

Tracking Number

String(50)

N

 

Billing Period

Enum

N

Text to display for the Billing frequency. Must be one of   

            'Daily',

                'Weekly',

                'BiWeekly',   // 14 days, aka fortnightly

                'Monthly',

                'Quarterly',

                'BiAnnual',  // every 6 months

                'Yearly',

                '5-Yearly',

                '10-Yearly',

                '20-Yearly',

                '25-Yearly']

 

 (see also Billing Start/End Dates)

Notes

250

N

Specific notes that are to be printed on the bottom of the invoice for the customer to view

 

Bill To Name

String (100)

N

If the Bill To fields are specified, then this billing address will be used on the invoice instead of the Customer’s default billing address.

Bill To Street

String (100)

N

Bill To Suite/Dept

String (100)

N

Bill To City

String (50)

N

Bill To State / Province

String (50)

N

Bill To Zip / Postal Code

String (50)

N

Bill To Country

 

 

Ship To Name

String (100)

N

If the Ship To fields are specified, then this shipping address will be used on the invoice instead of the Customer’s default shipping address. The shipping address may be blank for an invoice.

Ship To Street

String (100)

N

Ship To Suite/Dept

String (100)

N

Ship To City

String (50)

N

Ship To State / Province

String (50)

N

Ship To Zip / Postal Code

String (50)

N

Ship To Country

String (50)

N

Custom Field1

String (100)

N

Please contact support for custom fields.

Custom Field2

String (100)

N

Custom Field3

String (100)

N

Custom Field4

String (100)

N

Custom Field5

String (100)

N

Custom Field6

String (100)

N

Custom Field7

String (100)

N

Custom Field8

String (100)

N

Custom Field9

String (100)

N

Custom Field10

String (1,000)

N

Note that the 10th field is extra long and is stored encrypted.


InvoiceLineItem Fields

Field Name

Data Type

Required

(C = Conditional)

Notes





Invoice Number

String (10)

Y

The unique invoice number as assigned by the source system. Any one of the 3 invoice identifiers must be provided

CRM Invoice ID

String (25)

N

This is the internal ID of the Invoice  in the CRM system. Any one of the 3 invoice identifiers must be provided

ERP Invoice ID

String (25)

N

This is the internal ID of the invoice  in the ERP system. Any one of the 3 invoice identifiers must be provided

Item Custom Options

String (100)

N

Used for customization, leave blank unless instructed otherwise

Position

Number

Y

The sequence in which the invoice line item must be displayed. See also Parent Position

Item Type

Enum

Y

Must be one of these:

 

"LineItem" - A chargable line item with an amount

 

"ItemCharge" - N/A for eBill (BluBilling product specific field)

 

"SubTotal" - The item is a sub-total

 

"BlankLine" - Display a blank line after the previous item

 

"Note" - Display the text, but there is no amount associated with this line item

 

Charge Type

Enum

Y

Must be one of these:

 

"ItemAmount" - Regular Item

 

"TaxAmount" - Identifies this amount as a tax change

 

"Discount" - This is amount as a discount charge.

 

"SubTotal" - Use this value when the “Item Type” field is a “Sub Total”

 

"Note" - Use this value when the “Item Type” field is a “Note”

Unit Price

Money

C

The per-unit price. Required if “Qty” is specified.

Qty

Number

C

The quantity associated with the line item. Required if “Unit Price” is specified.

Amount

Money

Y

The amount to display. Use “0.00” if the “Item Type” is “BlankLine” or “Note”. May be negative for discounts and taxes.

Tax Amount

Money

N

The taxable amount for this line item

Unit Of Measure

String(10)

N

Use when you want the Qty column to indicate specific units, e.g., “Ibs”

Invoice Text

String (100)

Y

The primary text for the invoice line item. If ItemType is “BlankLine” send a single space character

Item Code

String(10)

N

Use if this line item is associated with a product /SKU code

CRM Item ID

String (25)

N

This is the internal ID of the Item/SKU in the CRM system.

ERP Item ID

String (25)

N

This is the internal ID of the Item/SKU in the ERP system.

Parent Position

Number

N

This field is used to control upto 3 levels of hierarchy when the items are displayed on the invoice. Child Items are indented on the invoice to convey that this is a breakup of the parent item. For example, to display this format for the invoice line items:

 

1. Shipping & Handling_______ $ 100

2.        Freight _______________$  25

3.        Packing Materials ______$  75

 

Then set the Parent Position of both item #2 and item #3 to “1” (which corresponds to the value of the “Position” field of item #1)

Custom Field1

String (100)

N

Please contact support for custom fields.

Custom Field2

String (100)

N

Custom Field3

String (100)

N

Custom Field4

String (100)

N

Custom Field5

String (100)

N

Custom Field6

String (100)

N

Custom Field7

String (100)

N

Custom Field8

String (100)

N

Custom Field9

String (100)

N

Custom Field10

String (1,000)

N

Note that the 10th field is extra long and is stored encrypted.






5.1. Retrieve Invoice:

Returns this object graph: Invoice, InvoiceLineItem, InvoicePayment



GET /rest/invoice/[id]?format={xml| pdf}
GET /rest/invoice?format= {xml| pdf}&invoiceNumber=[value]

<invoice id="2">
  <delegatedInvoice id="5" />
  <invoiceDate>2010-02-01</invoiceDate>
  <billingEndDate>2009-12-31</billingEndDate>
  <customer id="13" />
  <currency id="USD" />
  <paymentsAndAdjustments>0.00</paymentsAndAdjustments>
  <billingPeriod>Monthly</billingPeriod>
  <outstandingBalance>838.00</outstandingBalance>
  <dueDate>2010-03-03</dueDate>
  <currentAmountDue>838.00</currentAmountDue>
  <ordersIncluded>
    <subscriptionOrder id="9" />
    <subscriptionOrder id="10" />
  </ordersIncluded>
  <status>CarriedOver</status>
  <totalDue>838.00</totalDue>
  <lastUpdated>2010-08-06</lastUpdated>
  <invoiceNumber>1002</invoiceNumber>
  <billingStartDate>2009-10-31</billingStartDate>
  <invoiceLineItems>
    <invoiceLineItem id="2">
      <position>1</position>
      <invoiceText>Monthly subscription - Anti Virus and Spam Bundle</invoiceText>
      <billingEndDate>2009-12-31</billingEndDate>
      <billingStartDate>2009-10-31</billingStartDate>
      <invoiceLineItemCharges>
        <invoiceLineItemCharge id="3">
          <accountingCode>MO-AV-SP-2008</accountingCode>
          <position>1</position>
          <contractCharge id="3" />
          <isPercent>false</isPercent>
          <billingEndDate>2009-11-30</billingEndDate>
          <chargeDate />
          <unitPrice>100.00</unitPrice>
          <amount>100.00</amount>
          <orderLineItem id="13" />
          <quantity>1.00</quantity>
          <unitOfMeasure />
          <invoiceText>Setup fee</invoiceText>
          <pricingTier id="7" />
          <billingStartDate>2009-10-31</billingStartDate>
          <currencySymbol>lt;/currencySymbol>
          <isUsageChargeSubTotal>false</isUsageChargeSubTotal>
       </invoiceLineItemCharge>
       <invoiceLineItemCharge id="4">
       ... 
       ...
       </invoiceLineItemCharge>
     </invoiceLineItemCharges>
     <lineAmountTotal>419.00</lineAmountTotal>
     <orderNumber>1010</orderNumber>
     <subscriptionOrder id="10" />
     <contractCode>B-Mo-AV-SP</contractCode>
   </invoiceLineItem>
 </invoiceLineItems>
 <dateCreated>2010-08-06</dateCreated>
 <invoicePayments />
 <notes />
 <previousBalance>0.00</previousBalance>
</invoice>


5.2. Retrieve Invoice List

Returns a paged list of Invoices. The invoices are sorted in descending order by dueDate. Either the internal CustomerId or the Customer Account Number (extCustomerRef) may be used to query for a single customer's invoices.
Defaults used if the query string parameters are missing:    offset=0
   max=50
   status = ignored if not defined
   customerId = ignored if not defined (i.e, returns a list of all customers)
   extCustomerRef = ignored if not defined (i.e, returns a list of all customers)


GET /rest/invoices?format=xml&offset=[n]&max=[m]&status=[status]&customerId=[id]

GET /rest/invoices?format=xml&offset=[n]&max=[m]&status=[status]&extCustomerRef=[customerNumber] 

Sample Output:

<list>
  <invoice id="1">
  ...
  </invoice>
  <invoice id="2">
  ...
  </invoice>
</list>

5.3 Cancel Invoice

While an Invoice cannot be deleted (for financial audit reasons), you may cancel an invoice that is in the "outstanding" status. This changes the status of the Invoice to Cancelled and reverses the invoice amount from the Customer's account balance. The REST calls for cancelling an invoice use the HTTP DELETE operation:




DELETE /rest/invoice/[id]?suspendOrders=true
DELETE /rest/invoice?invoiceNumber=[value]&suspendOrders=true


Notes:
  1. The invoice status must be Outstanding
  2. If the suspendOrders parameter is set to true, then all Active Orders that are associated with the Invoice will be suspended. It defaults to false if not provided.
Comments