Credit Note

9 min

In Breadwinner for Xero, "Credit Note" records are available under the Breadwinner Invoice object when they are imported from Xero into Salesforce.

A Sales Credit Note (ACCRECCREDIT) is used to reduce or refund an amount to a customer, adjusting an Invoice.

A Bill Credit Note (ACCPAYCREDIT) is used when a supplier owes you money, reducing the amount you need to pay on a Bill.

See Code Example [Create and Apply Credit Note] to Create and Apply a Credit Note in a single Request.

When applying or allocating a Credit Note to an Invoice or Bill, you can use requestJSON to pass the required Credit Note Data and the Invoice ID to which the Credit Note is to be applied. The response will include responseJSON, which contains the data returned by Xero.

The Credit Note has the following parameters:

Breadwinner Fields

These fields are specific to the Breadwinner Global API and are not part of the Xero API directly. They wrap every request made via the Breadwinner Xero integration.

Field Name	Data Type	Used In	Description
action	String	Request	The action to perform on the Xero Credit Note. Use "createCreditNote" to create a new Credit Note, or "applyCreditNoteAllocation" to allocate an existing Credit Note against an Invoice or Bill in your request.
version	String	Request	The API version to use when calling the Breadwinner Xero API. Always set this to 1.0
xeroOrgId	String	Request	The unique identifier of the Xero organisation to target. Required when Xero Multi-Org is enabled in Breadwinner (e.g. !aa00TM).
skipDML	Boolean	Request	Controls whether Salesforce records are updated after the Xero operation. Set to true to push data to Xero without saving changes to Salesforce. Set to false to allow Breadwinner to create or update the related Credit Note, Invoice, and Payment records in Salesforce.
requestJSON	String (JSON-serialised creditNoteMap)	Request	A JSON-serialised string containing the Credit Note payload. For createCreditNote, wrap the credit note details under the CreditNotes key. For applyCreditNoteAllocation, include CreditNoteID, CreditNoteType, and Allocations. Serialise the map using JSON.serialize() before passing it here.
Below are standard Salesforce fields that Breadwinner will create or update automatically
Salesforce_Account_Id	Id	In Request and Response	The Salesforce Account record ID linked to this Credit Note. Passed in the request to associate the Credit Note with a Salesforce Account, and returned in the response to confirm the link.
Salesforce_Opportunity_Id	Id	In Request and Response	The Salesforce Opportunity record ID linked to this Credit Note. Passed in the request to associate the Credit Note with a Salesforce Opportunity, and returned in the response to confirm the link.
SalesforceRecordId	String	Response	The Salesforce record ID of the Credit Note object created or updated in Salesforce after the Xero sync. Only populated when skipDML is false.

Credit Note

These are the fields on the Credit Note object itself. Fields marked Request are passed in via requestJSON when creating a Credit Note. Fields marked Response are returned by Xero after the operation completes. Fields marked Both apply to both.

Field Name	Data Type	Used In	Description
Type*	String	In Request and Response	Defines whether the Credit Note is for a Sales Invoice or a Bill. Use ACCRECCREDIT for a Sales Credit Note (accounts receivable) or ACCPAYCREDIT for a Bill Credit Note (accounts payable). Required.
Status	String	In Request and Response	The status of the Credit Note. On creation, use DRAFT to save without approving, SUBMITTED to submit for approval, or AUTHORISED to approve immediately. The response may also return PAID or VOIDED.
DateString	String	In Request and Response	The date the Credit Note was issued. Pass in YYYY-MM-DD format in the request. Returned by Xero in ISO format (e.g. 2026-03-11T00:00:00) in the response.
CreditNoteNumber	String	In Request and Response	A unique alphanumeric reference number for the Credit Note. If not provided, Xero auto-generates one. Once set and approved, this cannot be changed.
Reference	String	In Request and Response	An optional internal reference for the Credit Note.
BrandingThemeID	String	In Request and Response	The Xero identifier of the branding theme to apply to the Credit Note. If not specified, the contact's default branding theme is used.
LineAmountTypes	String	Request	Specifies how tax is handled for line item amounts. Use Exclusive if line amounts exclude tax, Inclusive if they include tax, or NoTax if no tax applies. Defaults to Exclusive if not specified.
CurrencyCode	String	In Request and Response	The ISO 4217 currency code for the Credit Note (e.g. USD, AUD, GBP). Defaults to the base currency of the Xero organisation if not provided.
CurrencyRate	Decimal	In Request and Response	The exchange rate between the Credit Note currency and the organisation's base currency. Required only for foreign currency Credit Notes. If not provided, Xero uses the current exchange rate.
CreditNoteID	String	Response	The Xero-generated unique identifier (UUID) for the Credit Note. Returned after creation and used as the input for applyCreditNoteAllocation in a Create & Apply flow.
SubTotal	Decimal	Response	The total value of all line items on the Credit Note before tax is applied.
TotalTax	Decimal	Response	The total tax amount on the Credit Note.
Total	Decimal	Response	The final total including tax.
TotalDiscount	Decimal	Response	The total discount amount applied across all line items on the Credit Note.
AmountCredited	Decimal	Response	The total credit amount from this Credit Note that has been applied to Invoices or Bills via allocations.
AmountPaid	Decimal	Response	The total amount that has been paid or applied against this Credit Note to date.
AmountDue	Decimal	Response	The outstanding balance remaining on the Credit Note after payments and allocations have been applied.
RemainingCredit	Decimal	Response	The unused credit balance still available on this Credit Note.
DateVariable	String	Response	The Credit Note date returned by Xero in internal timestamp format (e.g. /Date(1234567890000+0000)/).
UpdatedDateUTC	String	Response	The UTC timestamp of the last modification to the Credit Note in Xero.
IsDiscounted	Boolean	Response	Returns true if one or more line items on the Credit Note have a discount applied.
SentToContact	Boolean	Response	Returns true if the Credit Note has been emailed to the associated contact from Xero.
HasErrors	Boolean	Response	Returns true if Xero returned validation errors for this Credit Note. Check the accompanying error details when this is true.
Contact*	Object	In Request and Response	The customer or supplier contact associated with the Credit Note. See Contact Fields.
LineItems	List<LineItem>	In Request and Response	The line items on the Credit Note. See Line Item Fields.
Payments	List<Payment>	Response	Payments that have been applied to this Credit Note. See Payment Fields.
Allocations	List<Allocation>	Response	Allocation records for this Credit Note. See Allocation Fields.

Contact

Only ContactID is required in the request. The response returns the full ContactContact object from Xero including addresses, phone numbers, and other contact details.

Field Name	Data Type	Used In	Description
ContactID*	String	In Request and Response	The Xero-generated unique identifier (UUID) of the contact (customer or supplier). Either ContactID or Name is required when creating a Credit Note. If both are provided, ContactID takes precedence.
Name	String	In Request and Response	The full name of the contact as it appears in Xero.
ContactStatus	String	Response	The current status of the contact in Xero. Common values: ACTIVE, ARCHIVED.

Line Item

Field Name	Data Type	Used In	Description
ItemCode	String	In Request and Response	The inventory item code in Xero. If provided, Xero auto-populates Description, AccountCode, UnitAmount, and TaxType. Optional if Description is provided.
Description*	String	In Request and Response	A text description of the goods or services being credited on this line. Displayed on the Credit Note PDF. At least one of ItemCode or Description must be provided per line item.
AccountCode*	String	In Request and Response	The chart of accounts code to assign this line item to (e.g. 200 for Sales). Required if no ItemCode is provided.
TaxType	String	In Request and Response	The tax rate applied to this line item (e.g. OUTPUT). Overrides the default tax rate for the AccountCode.
UnitAmount*	Decimal	In Request and Response	The price per unit of the item being credited. Combined with Quantity to calculate the line total before discounts and tax.
Quantity*	Decimal	In Request and Response	The number of units being credited on this line. Combined with UnitAmount to calculate the line total.
DiscountRate	Decimal	In Request and Response	An optional percentage discount applied to this line item. The LineAmount is calculated as: Quantity × UnitAmount × ((100 − DiscountRate) / 100).
TaxAmount	Decimal	In Request and Response	The tax amount for the line, auto-calculated by Xero based on the TaxType and line total. Can be manually overridden if required.
LineAmount	Decimal	In Request and Response	The total amount for the line after applying any discount, excluding tax (when LineAmountTypes is Exclusive).
LineItemID	String	Response	The Xero-generated unique identifier for the line item.
AccountID	String	Response	The Xero-generated unique identifier of the account assigned to the line item.
ValidationErrors	List	Response	Validation errors returned by Xero for this line item.
Tracking	List<TrackingCategory>	In Request and Response	Up to 2 tracking categories assigned to this line item. See Tracking Category Fields.

Tracking Category

These fields are valid when tracking categories are configured in your Xero organisation.

Field Name	Data Type	Used In	Description
Name	String	In Request and Response	The name of the tracking category (e.g. Department, Region).
Option	String	In Request and Response	The selected option value within the tracking category (e.g. Marketing, North). Required when tracking is applied.
TrackingCategoryID	String	In Request and Response	The Xero-generated unique identifier for the tracking category (e.g. ae777a87-5ef3-4fa0-a4f0-d10e1f13073a).

Payment

Returned in the response when payments have been applied to the Credit Note.

Field Name	Data Type	Used In	Description
PaymentID	String	Response	The Xero-generated unique identifier for the payment.
PaymentDate	Date	Response	The date the payment was made, in YYYY-MM-DD format.
DateVariable	String	Response	The payment date in Xero's internal date format (e.g. /Date(1234567890000+0000)/).
Reference	String	Response	An optional reference or note associated with this payment.
Amount	Decimal	Response	The value of the payment applied to the Credit Note.
CurrencyRate	Decimal	Response	The exchange rate applied to this payment for multi-currency transactions.
HasAccount	Boolean	Response	Indicates whether this payment is associated with a bank account or ledger account in Xero.

Allocation

Used when applying a Credit Note to an Invoice or Bill via applyCreditNoteAllocation, and returned in the response after a successful allocation.

Field Name	Data Type	Used In	Description
CreditNoteID*	String	Request	The Xero-generated unique identifier of the Credit Note to apply. In a Create & Apply flow, extract this from the create response (createResp → responseJSON → creditNotes[0].CreditNoteID).
CreditNoteType*	String	Request	Specifies whether the Credit Note is being applied to an Invoice or a Bill. Set to Invoice for a Sales Credit Note (ACCRECCREDIT) or Bill for a Bill Credit Note (ACCPAYCREDIT). Required.
Date	String	Request	The date the allocation is applied, in YYYY-MM-DD format.
InvoiceInvoice	Object	In Request and Response	The Invoice or Bill this Credit Note was applied to.
InvoiceID*	String	In Request and Response	The Xero unique identifier of the Invoice or Bill to apply the Credit Note to. Despite the field name, this is used for both Invoices and Bills — the key must always be Invoice as per the Xero API specification.
InvoiceNumber	String	Response	The reference number of the Invoice or Bill this Credit Note was applied to, as it appears in Xero.
Amount*	Decimal	In Request and Response	The amount to allocate from the Credit Note to the Invoice or Bill. Must not exceed the remaining credit on the Credit Note or the outstanding amount on the Invoice or Bill.
AllocationID	String	Response	The Xero-generated unique identifier for this allocation record.
DateVariable	String	Response	The allocation date in Xero's internal date format (e.g. /Date(1234567890000+0000)/).
AppliedAmount	Decimal	Response	The amount of credit utilised against the Invoice. Returned when the Credit Note appears on an Invoice response.
ID	String	Response	An alternative Xero identifier for the Credit Note. Returned when the Credit Note appears on an Invoice response.

Note: * indicates a required field. Two exceptions apply. In the Contact table, ContactID* and Name* are mutually conditional - at least one must be provided, but not both are needed. In the Line Items table, fields marked * are only required when the Credit Note Status is AUTHORISED.