Credit Notes
| URL | https://api.xero.com/api.xro/2.0/CreditNotes |
| Methods Supported | POST, PUT, GET |
| Description | Allows you to retrieve any credit notes Allows you to add or update draft credit notes Allows you to add approved credit notes Allows you to allocate part or full amounts of credit notes to outstanding invoices Allows you to delete draft credit notes Allows you to void approved credit notes |
Credit Notes are almost identical to Invoices, with the exception of the naming of a few key elements.
Elements for credit notes
| Reference | An optional field to store a reference |
| Type | See Credit Note Types |
| Contact | See Contacts |
| Date | The date the credit note is created |
| Status | See Invoice Status Codes |
| LineAmountTypes | See invoice line amount types |
| LineItems | See invoice line items |
| SubTotal | The subtotal of the credit note excluding taxes |
| Total Tax | The total tax on the credit note |
| Total | The total of the Credit Note(subtotal + total tax) |
| UpdatedDateUTC | UTC timestamp of last update to contact |
| CurrencyCode | Currency used for the Credit Note |
| FullyPaidOnDate | Date when credit note was fully paid(UTC format) |
| CreditNoteID | Xero generated unique identifier |
| CreditNoteNumber | The user friendly unique identifier for a credit note e.g. CN 1001 |
| SentToContact | boolean to indicate if a credit note has been sent to a contact via the Xero app |
Current limitations
At the moment it is not possible to refund a credit note via the API.
To add your support for this feature and to be kept up to date on feature development, please vote in our request forum.
POST CreditNotes
Use this method to create or update a standalone credit note with either a DRAFT, SUBMITTED or AUTHORISED status by specifying the Status element in your request.
Example of minimum elements required to add a new draft credit note to ABC Limited with no line items
<CreditNote>
<Type>ACCPAYCREDIT</Type>
<Contact>
<Name>ABC Limited</Name>
</Contact>
</CreditNote>
Example of a draft credit note with enough detail to be approved once it’s been created.
<CreditNote>
<Type>ACCPAYCREDIT</Type>
<Contact>
<Name>Apple Computers Ltd</Name>
</Contact>
<Date>2009-03-29</Date>
<LineAmountTypes>Exclusive</LineAmountTypes>
<LineItems>
<LineItem>
<Description>MacBook - White</Description>
<Quantity>1.0000</Quantity>
<UnitAmount>1995.00</UnitAmount>
<AccountCode>720</AccountCode>
<Tracking />
</LineItem>
</LineItems>
</CreditNote>
Example of a creating an approved credit note
<CreditNote>
<Type>ACCPAYCREDIT</Type>
<Status>AUTHORISED</Status>
<Contact>
<Name>Apple Computers Ltd</Name>
</Contact>
<Date>2009-03-29</Date>
<LineAmountTypes>Exclusive</LineAmountTypes>
<LineItems>
<LineItem>
<Description>MacBook - White</Description>
<Quantity>1.0000</Quantity>
<UnitAmount>1995.00</UnitAmount>
<AccountCode>720</AccountCode>
<Tracking />
</LineItem>
</LineItems>
</CreditNote>
If you are entering many credit notes in a single API call then we recommend you utilise our new response format that shows validation errors for each invoice. The new response messages for validating bulk API calls would mean a breaking change so to utilise this functionality you’ll need to append ?SummarizeErrors=false to the end of your API calls e.g. POST /api.xro/2.0/CreditNotes?SummarizeErrors=false
The PUT method is similar to the POST CreditNotes method, however you can only create new credit notes with this method (i.e. no edits).
You can also allocate part or full amounts of credit notes to outstanding invoices.
Elements for Allocations
| Invoice | the invoice the credit note is being allocated against |
| AppliedAmount | the amount being applied to the invoice |
Below is an example of allocating $60.50 from an ACCREC credit note to an outstanding ACCREC invoice for the same contact. Note the URL needs to specify the credit note that you are allocating e.g. PUT CreditNotes/b356e488-2678-4be4-ad4b-d294df2d48d6/Allocations
<Allocations>
<Allocation>
<AppliedAmount>60.50</AppliedAmount>
<Invoice>
<InvoiceID>f5832195-5cd3-4660-ad3f-b73d9c64f263</InvoiceID>
</Invoice>
</Allocation>
</Allocations>
Optional parameters for GET CreditNotes
| Record filter | You can specify an individual record by appending the value to the endpoint, i.e. GET https://…/CreditNotes/{identifier} |
| CreditNoteID – The Xero identifier for a Credit Note e.g. 297c2dc5-cc47-4afd-8ec8-74990b8761e9 |
|
| CreditNoteNumber – Identifier for Credit Note CN-8743802 |
|
| Modified After | The ModifiedAfter filter is actually an HTTP header: ‘If-Modified-Since‘. A UTC timestamp (yyyy-mm-ddThh:mm:ss) . Only contacts created or modified since this timestamp will be returned e.g. 2009-11-12T00:00:00 |
| Where | Filter by an any element (see Filters) |
| order | Order by any element returned (see Order By) |
By default GET CreditNotes responses are formatted as XML. You can also retrieve responses in JSON format. Individual credit notes (e.g. CreditNotes/97c2dc5-cc47-4afd-8ec8-74990b8761e9) can also be returned as PDF’s see our HTTP GET documentation
Example response for GET CreditNotes
<CreditNotes>
<CreditNotes>
<CreditNote>
<Contact>
<ContactID>c6c7b870-bb4d-489a-921e-2f0ee4192ff9</ContactID>
<Name>Test Apply Credit Note</Name>
</Contact>
<Date>2012-08-30T00:00:00</Date>
<Status>PAID</Status>
<LineAmountTypes>Inclusive</LineAmountTypes>
<SubTotal>86.96</SubTotal>
<TotalTax>13.04</TotalTax>
<Total>100.00</Total>
<UpdatedDateUTC>2012-08-29T23:43:01.097</UpdatedDateUTC>
<CurrencyCode>NZD</CurrencyCode>
<FullyPaidOnDate>2012-08-30T00:00:00</FullyPaidOnDate>
<Type>ACCRECCREDIT</Type>
<CreditNoteID>aea95d78-ea48-456b-9b08-6bc012600072</CreditNoteID>
<CreditNoteNumber>CN-0002</CreditNoteNumber>
<CurrencyRate>1.000000</CurrencyRate>
<RemainingCredit>0.00</RemainingCredit>
<Allocations>
<Allocation>
<AppliedAmount>100.00</AppliedAmount>
<Date>2012-08-30T00:00:00</Date>
<Invoice>
<InvoiceID>87cfa39f-136c-4df9-a70d-bb80d8ddb975</InvoiceID>
<InvoiceNumber>INV-0001</InvoiceNumber>
</Invoice>
</Allocation>
</Allocations>
</CreditNote>
</CreditNotes>