raiseInvoice()

ItemisedTransactionDetail raiseInvoice(string usn, NewInvoiceRequest newInvoiceRequest)

This method raises a invoice against an account or subscription.

Parameters

usn: Format: string; Purpose: Specifies the USN of the account or subscription against which the invoice is raised.
newInvoiceRequest: Format: NewInvoiceRequest XML; Purpose: Defines a NewInvoiceRequest XML document that specifies the details of the invoice.

Example: A NewInvoiceRequest XML document

This example shows a NewInvoiceRequest XML document.

A NewInvoiceRequest document contains the following elements:

<effectiveDate>

(Optional) Specifies the invoice's transaction date.

<dueDate>

(Optional) Specifies the invoice’s due date.

<ChargeRequest>

Specifies the details of the charge to include on the invoice. Multiple ChargeRequest elements can be specified for an invoice.

<USN>: Specifies the USN of the account or subscription that the charge is to be made against.
<itemCode>: Specifies the item code of the item,(or category of item, that is to be billed.
<description>: (Optional) Specifies a free-form text description of the item.
<quantity>: (Optional) Specifies a volume measurement of the items that are being billed in this line item.
<count>: (Optional) Specifies the number of instances that this line item is billed. For example, multiple purchases of the same item. If omitted, 1 is the default.
<startDate>: Specifies the starting date of the charge period.
<endDate>: Specifies the ending date of the charge period. If the charge is for a once-off item, then set endDate the same as startDate.
<amount>: (Optional) Specifies the charge amount, excluding tax.
<chargeGST>: (Optional) true if GST is to be charged for this item; otherwise false otherwise. If omitted, false is the default.
<gst>: (Optional). Specifies the amount of GST chargeable.
<chargeId>: (Optional). Specifies the unique UUID identifier for this charge. This identifier can be used to correlate this charge in other systems and can also be used as reference if this charge is to be later retracted.; Note: The client is responsible for ensuring that this UUID identifier is unique and has never been used for a previous charge.
<retractChargeId>: (Optional) Specifies the chargeId of a previous charge that is to be retracted at the same time that this charge is lodged.
<discount>: (Optional) Specifies if a discount applies for this line item.
<purchaseOrderNumber>: (Optional) Specifies a customer-supplied purchase order number associated with this line item.
<overrideCostCentre>: (Optional) Specifies a cost centre is to be associated with this line item. By default the account or subscription's default cost centre, if any, will be used.
<Object>: (Optional, unless the item description has one or more mandatory custom fields) Specifies custom fields for this invoice line item if any have been defined for the item description referred to by <itemCode>.
<location>: (Optional) Specifies the point-of-sale location for the transaction. The key="..." attribute should contain the Office ID numeric key listed next to the office location's entry under Office Locations in the Smile Configuration menu.

<InvoiceOperation>

(Optional) By default or when the value is Close, the invoice will be closed. When the value is LeaveOpen, the invoice will stay open.

<suppressAutoPayment>

true or false

(Optional) If there are bank details associated with the account or subscription and no auto payments should be scheduled, suppressAutoPayment should be set to true.

<NewInvoiceRequest xmlns="http://xml.inomial.com/smile/2.xsd">
  <dueDate>2015-02-14T00:00:00+11:00</dueDate>
  <ChargeRequest>
    <USN>1000000008</USN>
    <itemCode>cst</itemCode>
    <startDate>2015-01-01T00:00:00+11:00</startDate>
    <endDate>2015-01-01T00:00:00+11:00</endDate>
    <amount>50</amount>
    <chargeGst>true</chargeGst>
    <overrideCostCentre key="568">IT department</overrideCostCentre>
  </ChargeRequest>
  <ChargeRequest>
    <USN>1000000008</USN>
    <itemCode>adsl</itemCode>
    <startDate>2015-01-01T00:00:00+11:00</startDate>
    <endDate>2015-02-22T00:00:00+11:00</endDate>
    <chargeGst>false</chargeGst>
    <Object>
      <String name="colour">Chartreuse</String>
    </Object>
    <location key="12"/>
  </ChargeRequest>
  <InvoiceOperation>Close</InvoiceOperation>
  <suppressAutoPayment>false</suppressAutoPayment> 
</NewInvoiceRequest>

Results

This method returns an ItemisedTransactionDetails XML document containing details of the invoice.

Smile emits the TransactionClosed message if a closed invoice is produced. A closed invoice is produced when the <InvoiceOperation> element value is Close or not present.

The value of the <effectiveCostCentre> element will either reflect the <overrideCostCentre> if one is defined in the NewInvoiceRequest XML document for a <transactionItem>, or the default account or subscription cost centre is used instead. If the account or subscription lacks a default cost centre, then the <effectiveCostCentre> element will be omitted for these transaction items entirely.

Example: A returned ItemisedTransactionDetail XML document

This example shows an ItemisedTransactionDetail XML document.

<ItemisedTransactionDetail xmlns="http://xml.inomial.com/smile/2.xsd" xmlns="http://ws.inomial.com/smile.2">
  <version>2.0</version>
  <transactionType>Invoice</transactionType>
  <company>1</company>
  <usn>1000000008</usn>
  <transactionNumber>21441027</transactionNumber>
  <currency>AUD</currency>
  <amount>154.00</amount>
  <accountType>1</accountType>
  <gstAmount>5.00</gstAmount>
  <entryTimestamp>2015-01-19T09:54:39.027+11:00</entryTimestamp>
  <salesReportCategory>invoice</salesReportCategory>
  <formattedAmount currency="AUD" formatted="$154.00">154.00</formattedAmount>
  <formattedGstAmount currency="AUD" formatted="$5.00">5.00</formattedGstAmount>           
  <unallocatedAmount>154.00</unallocatedAmount>
  <enteredByUsn>2142421276</enteredByUsn>
  <logTimestamp>2015-01-19T09:54:39.033+11:00</logTimestamp>
  <formattedUnallocatedAmount currency="AUD" formatted="$154.00">154.00</formattedUnallocatedAmount>     
  <transactionDate>2015-01-19+11:00</transactionDate>
  <dueDate>2015-02-14+11:00</dueDate>
  <openDate>2015-01-19+11:00</openDate>
  <closeDate>2015-01-19+11:00</closeDate>
  <quoteNumber>21441027</quoteNumber>
  <createdByUsn>2142421276</createdByUsn>
  <discount>0.00</discount>
  <transactionSource>Manual</transactionSource>
  <transactionItem>
    <usn>1000000008</usn>
    <lineNumber>0</lineNumber>
    <itemCode>cst</itemCode>
    <chargeFrom>2015-01-01+11:00</chargeFrom>
    <chargeTo>2015-01-01+11:00</chargeTo>
    <description>Consultation Fee</description>
    <quantity>1.000</quantity>
    <currency>AUD</currency>
    <amount>50.00</amount>
    <isGst>false</isGst>
    <chargeGst>true</chargeGst>
    <discount>0.00</discount>
    <count>0</count>
    <gstAmount>5.000000</gstAmount>
    <salesReportCategory>invoice</salesReportCategory>
    <effectiveCostCentre key="568">IT department</effectiveCostCentre>
  </transactionItem>
  <transactionItem>
    <usn>1000000008</usn>
    <lineNumber>1</lineNumber>
    <itemCode>adsl</itemCode>
    <chargeFrom>2015-01-01+11:00</chargeFrom>
    <chargeTo>2015-02-22+11:00</chargeTo>
    <description>ADSL2 Modem</description>
    <quantity>1.000</quantity>
    <displayRate>$108.90</displayRate>
    <currency>AUD</currency>
    <amount>99.00</amount>
    <isGst>false</isGst>
    <chargeGst>false</chargeGst>
    <discount>0.00</discount>
    <count>0</count>
    <gstAmount>0.000000</gstAmount>
    <salesReportCategory>hardware</salesReportCategory>
    <Object formId="646" objectId="3435" displayName="ADSL2 Modem (Chartreuse)">
      <String name="colour">Chartreuse</String>
    </Object>
    <location key="12">Greenfields store</location>
  </transactionItem>
  <transactionItem>
    <usn>1000000008</usn>
    <lineNumber>2</lineNumber>
    <itemCode>gst</itemCode>
    <chargeFrom>2015-01-19+11:00</chargeFrom>
    <chargeTo>2015-01-19+11:00</chargeTo>
    <description>Includes 10% GST</description>
    <quantity>1.000</quantity>
    <currency>AUD</currency>
    <amount>5.00</amount>
    <isGst>true</isGst>
    <chargeGst>false</chargeGst>
    <discount>0.00</discount>
    <count>0</count>
    <gstAmount>0.000000</gstAmount>
    <salesReportCategory>gst</salesReportCategory>
  </transactionItem>
</ItemisedTransactionDetail>

Faults

NoSuchItemException

This fault is returned when the account or subscription does not exist or the USN, itemcode , GSTIds, discountIds or retractChargeIds in the ChargeRequest cannot be found.

InvalidRequestException

This fault is returned when the USN or new invoice request are missing, the USN in ChargeRequest does not belong to the account or subscription, or the request is invalid for another reason.

Java client syntax

java -cp build/smilewsv2-client.jar [options]
 com.inomial.smile.client.v2.examples.RaiseInvoice usn filename

usn: Purpose: Specifies the USN of the account or subscription against which the invoice is raised.
filename: Purpose: Defines the filename of the NewInvoiceRequest XML document.

Note: For more information about the Java client and the options it accepts, see Java client syntax.