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 credit notes to invoices
Allows you to delete draft credit notes
Allows you to void approved credit notes
Allows you to attach files to credit notes

To refund credit notes use the payments endpoint

GET CreditNotes

The following elements are returned in the CreditNotes response

Type See Credit Note Types
Contact See Contacts
Date The date the credit note is issued YYYY-MM-DD. If the Date element is not specified then it will default to the current date based on the timezone setting of the organisation
Status See Credit Note Status Codes
LineAmountTypes See Invoice Line Amount Types
LineItems See Invoice Line Items
SubTotal The subtotal of the credit note excluding taxes
TotalTax The total tax on the credit note
Total The total of the Credit Note(subtotal + total tax)
UpdatedDateUTC UTC timestamp of last update to the credit note
CurrencyCode Currency used for the Credit Note
FullyPaidOnDate Date when credit note was fully paid(UTC format)
CreditNoteID Xero generated unique identifier
CreditNoteNumber ACCRECCREDIT - Unique alpha numeric code identifying credit note.
ACCPAYCREDIT - Non-unique alpha numeric code identifying credit note. This value will also display as Reference in the UI.
Reference ACCRECCREDIT only - additional reference number
SentToContact boolean to indicate if a credit note has been sent to a contact via the Xero app (currently read only)
CurrencyRate The currency rate for a multicurrency invoice. If no rate is specified, the XE.com day rate is used
RemainingCredit The remaining credit balance on the Credit Note
Allocations See Allocations
BrandingThemeID See BrandingThemes
HasAttachments boolean to indicate if a credit note has an attachment

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 credit notes 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)

Example response for GET CreditNotes

GET https://api.xero.com/api.xro/2.0/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>

Example response for retrieving an individual CreditNote

GET https://api.xero.com/api.xro/2.0/CreditNotes/7df8949c-b71f-40c0-bbcf-39f2f450f286
 <CreditNotes>
  <CreditNote>
    <Contact>
      <ContactID>d0cd2c4f-18a0-4f7c-a32a-2db00f29d298</ContactID>
      <ContactStatus>ACTIVE</ContactStatus>
      <Name>PC Complete</Name>
      ....
    </Contact>
    <Date>2016-10-18T00:00:00</Date>
    <DueDate>2016-10-18T00:00:00</DueDate>
    <Status>PAID</Status>
    <LineAmountTypes>Exclusive</LineAmountTypes>
    <LineItems>
      <LineItem>
        <Description>Internal DVD drive couldn't be supplied, backorder (Oliver laptop)</Description>
        <UnitAmount>199.00</UnitAmount>
        <TaxType>INPUT</TaxType>
        <TaxAmount>19.90</TaxAmount>
        <LineAmount>199.00</LineAmount>
        <AccountCode>453</AccountCode>
        <Tracking>
          <TrackingCategory>
            <Name>Region</Name>
            <Option>North</Option>
            <TrackingCategoryID>093af706-c2aa-4d97-a4ce-2d205a017eac</TrackingCategoryID>
            <TrackingOptionID>3f05cdf9-246b-46a2-bf6f-441da1b09b89</TrackingOptionID>
          </TrackingCategory>
        </Tracking>
        <Quantity>1.0000</Quantity>
      </LineItem>
    </LineItems>
    <SubTotal>199.00</SubTotal>
    <TotalTax>19.90</TotalTax>
    <Total>218.90</Total>
    <UpdatedDateUTC>2008-09-16T09:40:09.467</UpdatedDateUTC>
    <CurrencyCode>AUD</CurrencyCode>
    <FullyPaidOnDate>2016-10-23T00:00:00</FullyPaidOnDate>
    <Type>ACCPAYCREDIT</Type>
    <RemainingCredit>0.00</RemainingCredit>
    <Allocations>
      <Allocation>
        <AppliedAmount>218.90</AppliedAmount>
        <Date>2016-10-23T00:00:00</Date>
        <Invoice>
          <InvoiceID>673dd7cc-beb7-4697-83d4-0c47cb400cc2</InvoiceID>
        </Invoice>
      </Allocation>
    </Allocations>
    <HasAttachments>false</HasAttachments>
    <CreditNoteID>7df8949c-b71f-40c0-bbcf-39f2f450f286</CreditNoteID>
    <CreditNoteNumber>03391</CreditNoteNumber>
  </CreditNote>
</CreditNotes>

POST CreditNotes

Use this method to create or update a credit note.

Type See Credit Note Types
Contact See Contacts
Date The date the credit note is issued YYYY-MM-DD. If the Date element is not specified then it will default to the current date based on the timezone setting of the organisation
Status See Credit Note Status Codes
LineAmountTypes See Invoice Line Amount Types
LineItems See Invoice Line Items
CurrencyCode Currency used for the Credit Note
CreditNoteNumber ACCRECCREDIT - Unique alpha numeric code identifying credit note (when missing will auto-generate from your Organisation Invoice Settings)
ACCPAYCREDIT - non-unique alpha numeric code identifying credit note. This value will also display as Reference in the UI.
Reference ACCRECCREDIT only - additional reference number
SentToContact boolean to indicate if a credit note has been sent to a contact via the Xero app (currently read only)
CurrencyRate The currency rate for a multicurrency invoice. If no rate is specified, the XE.com day rate is used
BrandingThemeID See BrandingThemes

SummarizeErrors

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

Example of minimum elements required to add a new draft credit note with no line items

POST https://api.xero.com/api.xro/2.0/CreditNotes
<CreditNote>
  <Type>ACCPAYCREDIT</Type>
  <Contact>
    <ContactID>eaa28f49-6028-4b6e-bb12-d8f6278073fc</ContactID>
  </Contact>
</CreditNote>

Example of a draft credit note with enough detail to be approved once it’s been created.

POST https://api.xero.com/api.xro/2.0/CreditNotes
<CreditNote>
  <Type>ACCPAYCREDIT</Type>
  <Contact>
    <ContactID>eaa28f49-6028-4b6e-bb12-d8f6278073fc</ContactID>
  </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

POST https://api.xero.com/api.xro/2.0/CreditNotes
<CreditNote>
  <Type>ACCPAYCREDIT</Type>
  <Status>AUTHORISED</Status>
  <Contact>
    <ContactID>eaa28f49-6028-4b6e-bb12-d8f6278073fc</ContactID>
  </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>

Uploading an Attachment

You can upload up to 10 attachments(each up to 3mb in size) per credit note, once the credit note has been created in Xero. To do this you'll need to know the ID of the credit note which you'll use to construct the URL when POST/PUTing a byte stream containing the attachment file. See the Attachments page for more details.

Example request to upload an attachment

POST https://api.xero.com/api.xro/2.0/CreditNotes/f0ec0d8c-6fce-4330-bb3b-8306278c6fd8/Attachments/image.png
Headers:
Authorization: OAuth...
Content Type: image/png
Content-Length: 10293

Body:
{RAW-IMAGE-CONTENT}

PUT CreditNotes

The PUT method can be used to create CreditNotes or allocate CreditNotes to outstanding Invoices.

The elements required to allocate a credit note to an invoice

Invoice the invoice the credit note is being allocated against
AppliedAmount the amount being applied to the invoice
Date the date the credit note is applied YYYY-MM-DD (read-only). This will be the latter of the invoice date and the credit note date.

Credit notes must have a Status of "AUTHORISED" to be available for allocation.



You cannot create and allocate a credit note in a single call. The create and allocation must be done in two separate calls



Note : Currently applying 'Allocations' cannot be tested through the API Previewer.

An example request to allocate $60.50 from an ACCREC credit note to an outstanding ACCREC invoice for the same contact. Note the Request URL needs to specify the credit note that you are allocating

PUT https://api.xero.com/api.xro/2.0/CreditNotes/7df8949c-b71f-40c0-bbcf-39f2f450f286/Allocations
 <Allocations>
  <Allocation>
    <AppliedAmount>60.50</AppliedAmount>
    <Invoice>
      <InvoiceID>f5832195-5cd3-4660-ad3f-b73d9c64f263</InvoiceID>
    </Invoice>
  </Allocation>
</Allocations>