Credit Notes


Overview

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

To refund credit notes use the payments endpoint

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
BrandingThemeID See BrandingThemes

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


PUT CreditNotes

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>

GET CreditNotes

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>