raiseAdjustment()

TransactionDetail raiseAdjustment(string usn, int adjustmentType, 
 dateTime effective, decimal amount, decimal gst, string comment, 
 AllocationRequest allocationRequest)

This method raises a credit or debit note against a given account. A credit note decreases the account balance, that is, decreases the amount a debtor owes; a debit note increases the account balance, that is, increases the amount a debtor owes. You can use adjustments to raise balancing transactions that correct mistakes or compensate customers.

The value of the credit or debit note is added to the account balance, and the adjustment transaction is entered in the account history and appears on invoices, statements and sales reports.

Before you use this method, define the limits of the adjustments that can be raised in Smile.

Parameters

usn: Format: string; Purpose: Specifies the USN of the account to raise the adjustment against.
adjustmentType: Format: integer; Purpose: Specifies the adjustment type. You predefine the adjustment type in Smile when you define the adjustment limits. This parameter may affect sales report categories and helps you track and report on the number of adjustments that are raised.
effective: Format: dateTime; Purpose: Specifies the date and time to raise the adjustment, for example, 2011-05-20T14:55:00+11:00. This date must be later than the debtor close date.
amount: Format: decimal (two decimal places); Purpose: Specifies the value, in dollars and cents and including GST, of the adjusting transaction. The adjustment amount cannot be zero. If you use the nil attribute to make this field null, Smile uses the amount predefined in the adjustment type.; Note: A negative amount raises a credit note (decreases an account balance), a positive amount raises a debit note (increases the account balance).
gst: Format: decimal (two decimal places); Purpose: Specifies the GST to adjust. This parameter must have the same sign as amount. If the amount is nil, Smile uses the amount predefined in the adjustment type.
comment: Format: string; Purpose: (Optional) Explains the reason for the adjustment. Smile stores the comment with the transaction record.
allocationRequest: Format: AllocationRequest XML; Purpose: (Optional) Defines an AllocationRequest XML document that contains the transaction number to raise the adjustment against, such as an invoice or a receipt, and the amount to adjust.; You can also use auto-allocation instead of providing transaction number(s).

Example: Raise a debit note against an undercharged transaction

This example raises a debit note of $170.00 to correct transaction number 21447701. The debit note increases the account balance of the corresponding account, that is, increases the amount the debtor owes.

<AllocationRequest xmlns="http://xml.inomial.com/smile/2.xsd">
  <AllocateTo>
    <TransactionNumber>21447701</TransactionNumber>
    <AllocateAmount>170.00</AllocateAmount>
  </AllocateTo>
</AllocationRequest>

Example: Request an auto-allocated payment

This example will cause Smile to automatically allocate the adjustment to any unallocated credits or debits on the account.

<AllocationRequest xmlns="http://xml.inomial.com/smile/2.xsd">
  <AutoAllocate>true</AutoAllocate>
</AllocationRequest>

Results

This method returns a TransactionDetail XML document that contains information about the adjustment transaction. Smile also emits the TransactionClosed message when the adjustment transaction is closed.

Example: A returned TransactionDetail XML document

This example shows a returned TransactionDetail XML document for a $10 adjustment with $1 GST.

Note the following points about the structure of the TransactionDetail XML document:

If the transaction is a credit note, debit note, surcharge or surcharge reversal, the <salesReportCategory> element is nested in the <TransactionDetail> element.
If the transaction is itemised, the <salesReportCategory> element is nested in the <transactionItem> element.

Because this example shows a TransactionDetail XML document for a credit note, the <salesReportCategory> element appears in the <TransactionDetail> element. However, because a credit note is not an itemised transaction, the <transactionItem> element does not appear.

<TransactionDetail xmlns="http://xml.inomial.com/smile/2.xsd">
  <version>2.0</version>
  <transactionType>CreditNote</transactionType>             
  <company>1</company>              
  <usn>1240001823</usn>
  <transactionNumber>28139823</transactionNumber>             
  <currency>AUD</currency>
  <amount>10.00</amount>             
  <accountType>12</accountType>
  <gstAmount>1.00</gstAmount>             
  <entryTimestamp>2011-05-20T11:55:00+11:00</entryTimestamp>
  <salesReportCategory>credit</salesReportCategory>
  <formattedAmount currency="AUD" formatted="$10.00">10.00</formattedAmount>
  <formattedGstAmount currency="AUD" formatted="$1.00">1.00</formattedGstAmount>
  <unallocatedAmount>10.00</unallocatedAmount>             
  <enteredByUsn>1240000182</enteredByUsn>
  <logTimestamp>2011-05-20T11:57:00+11:00</logTimestamp>
  <glCode>C20122</glCode>
  <formattedUnallocatedAmount currency="AUD" formatted="$10.00">10.00</formattedUnallocatedAmount>
</TransactionDetail>

Faults

AccountTransactionException

This fault is returned when the caller does not have permission to raise an adjustment against the account, a USN is not provided or the GST is incorrectly entered.

NoSuchItemException

This fault is returned when the account does not exist or the adjustment type is not defined.

IllegalArgumentException

This fault is returned if the specified USN is not an account, or if a value for a parameter does not conform to the predefined adjustment type.

Java client syntax

java -cp build/smilewsv2-client.jar [options] com.inomial.smile.client.v2.examples.RaiseAdjustment usn adjustmentType 
 effective amount gst [comment] [filename]

usn: Purpose: Specifies the USN of the account to raise the adjustment against.
adjustmentType: Purpose: Specifies the adjustment type.
effective: Purpose: Specifies the date and time to raise the adjustment, for example, 2011-05-20T14:55:00+11:00.
amount: Purpose: Specifies the value, in dollars and cents and including GST, of the adjusting transaction. A negative amount raises a credit note, a positive amount raises a debit note.
gst: Purpose: Specifies the GST to adjust. This parameter must have the same sign as amount.
comment: Purpose: (Optional) Explains the reason for the adjustment.
filename: Purpose: (Optional) Defines the filename of the AllocationRequest XML document.

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