4.3 Invoice API
4.3.1. Retrieve Invoice:
Returns this object graph: Invoice, InvoiceLineItem, InvoiceLineItemCharge
GET /rest/invoice/[id]?format={xml| pdf| html}
GET /rest/invoice?format= {xml| pdf| html}&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>
4.3.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)
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/invoices?format=xml&offset=[n]&max=[m]&status=[status]&customerId=[id]
GET /rest/invoices?format=xml&offset=[n]&max=[m]&status=[status]&extCustomerRef=[customerNumber]&createStartTime=[YYYYMMDDHHmm]&createEndTime=[YYYYMMDDHHmm]&updateStartTime=[YYYYMMDDHHmm]&updateEndTime=[YYYYMMDDHHmm]
Sample Output:
<list>
<invoice id="1">
...
</invoice>
<invoice id="2">
...
</invoice>
</list>
4.3.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&cancelOrders=true&rollbackBillingPeriod=true
DELETE
/rest/invoice?invoiceNumber[value]&suspendOrders=true&cancelOrders=true&rollbackBillingPeriod=true
Notes:
The invoice status must be Outstanding
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.
rest/invoice?invoiceNumber=1120&suspendOrders=false&cancelOrders=false&rollbackBillingPeriod=false
radio button 1 which signifies cancel the current invoice and don't make any change to underlying orders (the NextBillDate for the order line items will not change)
rest/invoice?invoiceNumber=1120&suspendOrders=false&cancelOrders=false&rollbackBillingPeriod=true
radio button 2 which signifies cancel the current invoice and change the underlying order(s) so that the NextBillDate is rolled back.
rest/invoice?invoiceNumber=1120&suspendOrders=false&cancelOrders=true
radio button 3 which signifies cancel the invoice and also cancel the orders as well. There will be no more invoices generated from these order(s).
Response XML
<status>
<success>true</success>
<message>Invoice 1120 has been cancelled.</message>
</status>
4.3.4. Create Invoice:
Here we can have either customerRef or customerId in the url parameter
POST - /rest/invoices?extCustomerRef=12345
- /rest/invoices?customerId=123
Sample Payload
<invoice>
<dueDate>2022-4-25</dueDate>
<isAutoPay>true</isAutoPay>
<invoiceLineItems>
<invoiceLineItem>
<enterpriseSubscription>STANDARD-PRICE-BOOK</enterpriseSubscription>
<invoiceLineItemCharges>
<invoiceLineItemCharge>
<priceCode>ASSES-3MO</priceCode>
<position>1</position>
<invoiceText>3 month subscription for Assessments-Copy</invoiceText>
<isPercent>false</isPercent>
<unitPrice>29.99</unitPrice>
<quantity>1</quantity>
<amount>29.99</amount>
</invoiceLineItemCharge>
<invoiceLineItemCharge>
<priceCode>GC1020</priceCode>
<position>2</position>
<invoiceText>GenWatt Diesel 10kW</invoiceText>
<isPercent>false</isPercent>
<unitPrice>5000</unitPrice>
<quantity>1</quantity>
<amount>5000</amount>
</invoiceLineItemCharge>
</invoiceLineItemCharges>
</invoiceLineItem>
<invoiceLineItem>
<enterpriseSubscription>ASSES-3MO</enterpriseSubscription>
<invoiceLineItemCharges/>
</invoiceLineItem>
<invoiceLineItem>
<enterpriseSubscription>GC1020</enterpriseSubscription>
<invoiceLineItemCharges/>
</invoiceLineItem>
</invoiceLineItems>
<notes/>
</invoice>