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 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

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>
  <DueDate>2009-03-29</DueDate>
  <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>
  <DueDate>2009-03-29</DueDate>
  <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

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 – http://developer.xero.com/api-overview/http-get/

Example response for GET CreditNotes

<CreditNotes>
  <CreditNote>
    <Reference />
    <Type>ACCPAY</Type>
    <Contact>
      <ContactID>aaf1960f-63b4-4640-9100-b151f27dd5ed</ContactID>
      <ContactStatus>ACTIVE</ContactStatus>
      <Name>Victor Power</Name>
      <Addresses>
        <Address>
          <AddressType>POBOX</AddressType>
        </Address>
        <Address>
          <AddressType>STREET</AddressType>
 	</Address>
      </Addresses>
      <Phones>
        <Phone>
          <PhoneType>DEFAULT</PhoneType>
        </Phone>
        <Phone>
 	  <PhoneType>MOBILE</PhoneType>
        </Phone>
        <Phone>
          <PhoneType>DDI</PhoneType>
 	</Phone>
        <Phone>
          <PhoneType>FAX</PhoneType>
        </Phone>
      </Phones>
      <UpdatedDateUTC>2009-05-29T00:41:12.113</UpdatedDateUTC>
      <ContactGroups />
      <IsSupplier>true</IsSupplier>
      <IsCustomer>false</IsCustomer>
    </Contact>
    <Date>2009-03-29T00:00:00</Date>
    <DueDate>2009-04-14T00:00:00</DueDate>
    <Status>PAID</Status>
    <LineAmountTypes>Exclusive</LineAmountTypes>
    <LineItems>
      <LineItem>
        <Description>Power for Nov-Dec</Description>
 	<Quantity>1.0000</Quantity>
 	<UnitAmount>263.00</UnitAmount>
 	<TaxType>INPUT</TaxType>
 	<TaxAmount>32.88</TaxAmount>
        <LineAmount>263.00</LineAmount>
 	<AccountCode>445</AccountCode>
 	<Tracking />
      </LineItem>
    </LineItems>
    <SubTotal>263.00</SubTotal>
    <TotalTax>32.88</TotalTax>
    <Total>295.88</Total>
    <UpdatedDateUTC>2009-05-29T00:41:12.193</UpdatedDateUTC>
    <CurrencyCode>NZD</CurrencyCode>
    <FullyPaidOnDate>2009-04-19T00:00:00</FullyPaidOnDate>
    <CreditNoteID>db4dd737-a948-4f8d-9b47-88b3b67bb83a</CreditNoteID>
    <CreditNoteNumber>00712165</CreditNoteNumber>
  </CreditNote>
</CreditNotes>

Developer

Credit Notes