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.

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.