CreditNotes

Used to query, insert, and update credit notes for a Xero organization. Credit notes are used to adjust invoices, typically in cases of overpayment, returns, or errors.

Table Specific Information

The CreditNotes table allows you to SELECT, INSERT, UPDATE, and DELETE credit note line items for a Xero organization. The Id column is generated by the connector; the value of this field combines the index of the line item with the unique, Xero-generated CreditNoteId.

Optimized Filters and High Volume Thresholds

The Xero API defines a list of optimized filters for certain tables and views. If any query filter not included in this list is applied to any such table or view, and the number of records available in that table or view exceeds a certain value (what Xero calls a "high volume threshold"), the Xero API will block the query.

To avoid the rejection of your queries by the Xero API, if the the number of records in your table or view exceed the high volume threshold, make sure to use filters from the list of optimized filters.

Note that the high volume threshold, as well as the exact list of optimized filters, is subject to change as Xero updates its API.

The Xero API does not list a high volume threshold for the CreditNotes table. The Xero API lists the following optimized filters for this table:

Optimized columns (when used in WHERE clauses):
- Status
- Date
- Reference
- Contact.ContactID
- Contact.Name
- Contact.ContactNumber
- Type
Optimized ORDER BY columns:
- CreditNoteID
- UpdatedDateUTC
- Date

SELECT

The Xero API allows extensive filtering and ordering. You can define WHERE and ORDER BY clauses in a query to filter and order the results using any non-line-item column.

Note: The Xero API does not support filtering on line items or journal lines.

INSERT

To insert a single row, set the required fields. A new table object is created as a single entry. To insert a new credit note, the Contact_Name field is required. For a credit note to be approved, the following fields must be defined in addition to at least one line item: Contact_Name, Date, and LineAmountTypes.

In addition to inserting a single row, line item tables offer two additional ways to insert into a table.

You can also insert a new object with multiple line items using XML aggregates. The elements supported here are the same as the LineItem columns without the "LineItem_" prefix, except when assigning tracking categories. Please refer to the Xero documentation of the CreditNotes API for more details.
```
INSERT INTO CreditNotes (Type, Contact_Name, LineItemAggregate) VALUES (
  'ACCPAYCREDIT',
  'John Doe',
  '<LineItem>
	<Description>LineItemDesc1</Description>
	<Quantity>1</Quantity>
  </LineItem>
  <LineItem>
	<Description>LineItemDesc2</Description>
	<Quantity>2</Quantity>
  </LineItem>'
)
```
You can insert a new line item on an existing object by specifying the Xero-generated identifier of the existing record. For example, to add a line item to an existing credit note:
```
INSERT INTO CreditNotes (CreditNoteId, LineItem_Description, LineItem_Quantity) VALUES ('XXXXX-XXXXX-XXXXX-XXXXX', 'New Line Item Desc', 1)
```

Note: Inserting into existing records will count as two operations against the Xero API. One is required to retrieve the existing record, and another to update the record with new data.

UPDATE

You can update any field that is not read-only.

Note: UPDATE operations will count as two operations against the Xero API. One is required to retrieve the existing record, and another to update the record with new data.

DELETE

The Xero API has limited support for deleting any object. In order to delete objects, you must update their Status to an appropriate value.

Applicable values for this field may be state-dependent. For example, invoices can only have their status set to DELETED when the invoice status is currently DRAFT or SUBMITTED.

Columns


Name	Type	ReadOnly	Description
Id [KEY]	String	True	A unique identifier for the credit note allocation line item. This combines the allocation index with the ID of the credit note, ensuring each allocation is uniquely identifiable within the system.
CreditNoteId	String	False	The unique identifier of the credit note. This links the allocation to the specific credit note, making it possible to track which credit note is being applied to an invoice.
CreditNoteNumber	String	False	A user-friendly reference number for the credit note. This helps users identify and differentiate credit notes, typically displayed on invoices or statements.
Reference	String	False	An optional field for storing additional reference information related to the credit note. This could include external identifiers or internal references for tracking purposes.
Type	String	False	The type of the credit note. Valid values are 'ACCPAYCREDIT' (credit note for accounts payable) and 'ACCRECCREDIT' (credit note for accounts receivable), indicating the nature of the transaction.
Contact_ContactId	String	False	The unique identifier of the contact associated with this credit note. This links the credit note to a specific customer or vendor in the system.
Contact_Name	String	False	The name of the contact associated with this credit note. This is typically the customer or supplier linked to the credit note.
Date	Date	False	The date when the credit note was created. This marks the date the credit note was issued and typically appears on the credit note document.
Status	String	False	The status of the credit note, which could indicate whether it is 'DRAFT', 'SUBMITTED', 'APPROVED', or 'DELETED', reflecting the current state of the credit note in the system.
LineAmountTypes	String	False	The line amount type, determining how the line amounts are calculated relative to tax. Possible values are 'Exclusive' (tax excluded), 'Inclusive' (tax included), and 'NoTax' (no tax applied). This field must be defined for credit notes to be approved.
LineItem_LineItemId	String	False	The unique identifier for a line item in the credit note. This Xero-generated ID is used to reference specific line items within the credit note. If line item IDs are not provided in updates, line items are deleted and recreated.
LineItem_Description	String	False	The description for the line item in the credit note. This is typically a short text that describes the goods or services being credited. The description must be at least one character long for the credit note to be approved.
LineItem_Quantity	Double	False	The quantity of the items involved in the line item. This must be a non-negative value and represents how many units of the product or service are being credited.
LineItem_UnitAmount	Decimal	False	The unit price of the items involved in the line item. This must be a positive value, representing the price per unit of the credited items or services.
LineItem_ItemCode	String	False	The user-defined item code for the product or service being credited. This code helps identify the item, usually for inventory or sales tracking.
LineItem_AccountCode	String	False	The account code associated with the line item. This account code must be active for the organization and is used to categorize the financial impact of the credit note line item.
LineItem_Item_ItemId	String	False	The unique identifier for the item being credited. This ID links the line item to a specific product or service in the system.
LineItem_Item_Name	String	False	The name of the item being credited. This is typically the product or service description, providing clarity on what the credit is applied to.
LineItem_Item_Code	String	False	The code of the item being credited. This code helps identify and classify the credited product or service within the system.
LineItem_TaxType	String	False	The tax type for the line item. This overrides the default tax code for the account, allowing customization of tax rules specific to this credit note line.
LineItem_TaxAmount	Decimal	False	The calculated tax amount for the line item, based on the 'UnitAmount' and 'Quantity' with the applied tax rate. This reflects the tax charged for the credited item.
LineItem_LineAmount	Decimal	False	The total value of the line item, calculated as 'Quantity x UnitAmount', with discounts and taxes applied. This amount represents the monetary value of the credited item.
LineItem_TrackingCategory1_CategoryId	String	False	The ID of the first tracking category associated with the line item. Xero allows up to two tracking categories for each transaction, helping to categorize the transaction for reporting.
LineItem_TrackingCategory1_CategoryName	String	False	The name of the first tracking category. This provides a label for the category used in the line item, offering further classification of the credit note.
LineItem_TrackingCategory1_OptionId	String	False	The ID of the option selected within the first tracking category. This ID links the line item to a specific option within the tracking category.
LineItem_TrackingCategory1_OptionName	String	False	The name of the option selected within the first tracking category. This provides a label for the selected option used to further categorize the line item.
LineItem_TrackingCategory1_Option_Stat	String	False	The status of the option selected within the first tracking category. This indicates whether the selected option is active or inactive.
LineItem_TrackingCategory2_CategoryId	String	False	The ID of the second tracking category associated with the line item. This allows additional categorization of the line item for more detailed financial reporting.
LineItem_TrackingCategory2_CategoryName	String	False	The name of the second tracking category. This provides a label for the second category used to classify the line item.
LineItem_TrackingCategory2_OptionId	String	False	The ID of the option selected within the second tracking category. This links the line item to a specific option within the second tracking category.
LineItem_TrackingCategory2_OptionName	String	False	The name of the option selected within the second tracking category. This provides a label for the selected option used to further categorize the line item.
LineItem_TrackingCategory2_Option_Stat	String	False	The status of the option selected within the second tracking category. This indicates whether the selected option is active or inactive.
LineItem_DiscountRate	Double	False	The discount percentage applied to the line item. This field is only supported on 'ACCREC' type credit notes and is used to reduce the total amount of the credit for this line item.
LineItemAggregate	String	False	Defines how multiple line items should be structured when inserted into the system using XML values. This field is only used during the 'INSERT' operation to create new line items.
SubTotal	Decimal	False	The total amount of the credit note excluding taxes. This value is calculated by summing all line item amounts before tax is applied.
TotalTax	Decimal	False	The total tax applied to the credit note. This is calculated by summing the tax amounts of all line items based on their respective tax rates.
Total	Decimal	False	The total amount of the credit note, including taxes. This is the sum of the 'SubTotal' and 'TotalTax', representing the full amount of the credit.
UpdatedDateUTC	Datetime	True	The date and time when the credit note was last updated, stored in UTC format. This timestamp reflects any changes made to the credit note after its creation.
CurrencyCode	String	False	The currency used for the credit note. This defines the currency for all amounts within the credit note, ensuring proper handling of different currencies.
FullyPaidOnDate	Date	False	The date when the credit note was fully paid, marking the completion of the payment process and closing out the credit note.
SentToContact	Boolean	False	Indicates whether the credit note has been sent to the contact (customer or supplier) via the Xero application. 'True' means it has been sent.
BrandingThemeId	String	False	The unique identifier for the branding theme applied to this credit note. This allows the contact to customize the look of their credit note using a specific branding template.
CurrencyRate	Decimal	False	The exchange rate used to convert the credit note's amounts to the base currency. This is applied only when the credit note involves a non-base currency.
RemainingCredit	Decimal	False	The remaining balance of the credit note that has not yet been applied to invoices or payments. This field helps track the unallocated portion of the credit note.
Allocation1_AppliedAmount	Decimal	True	The amount applied from this credit note to the first invoice. This value reduces the outstanding balance on the specified invoice.
Allocation1_Date	Date	True	The date when the first allocation from the credit note was made to the invoice.
Allocation1_InvoiceId	String	True	The unique identifier for the invoice that the first allocation has been applied to.
Allocation1_InvoiceNumber	String	True	The reference number of the invoice that the first allocation has been applied to.
Allocation2_AppliedAmount	Decimal	True	The amount applied from this credit note to the second invoice, reducing the outstanding balance of that invoice.
Allocation2_Date	Date	True	The date when the second allocation from the credit note was made to the invoice.
Allocation2_InvoiceId	String	True	The unique identifier for the invoice that the second allocation has been applied to.
Allocation2_InvoiceNumber	String	True	The reference number of the invoice that the second allocation has been applied to.
PaymentIds	String	True	A comma-separated list of payment IDs associated with this credit note, indicating which payments have been linked to this credit note.
HasAttachments	Boolean	True	Indicates whether the credit note has any attached files, such as receipts or documents, supporting the transaction.
TenantId	String	False	The unique identifier for the tenant, allowing queries to access data specific to a particular tenant rather than using the default connection tenant.

CData Python Connector for Xero