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 docid\ sza vx5sfteruivtsw6kc ] 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 https //app archbee com/docs/sbaaakcjtohpz0 vs6kmy/nrcfjtn 8le8ywxxzkzr #dl0tt ) 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 https //app archbee com/docs/sbaaakcjtohpz0 vs6kmy/nrcfjtn 8le8ywxxzkzr #ujsab \ \ object in request and response the customer or supplier contact associated with the credit note see contact fields lineitems https //app archbee com/docs/sbaaakcjtohpz0 vs6kmy/nrcfjtn 8le8ywxxzkzr #nf77r list\<lineitem> in request and response the line items on the credit note see line item fields payments https //app archbee com/docs/sbaaakcjtohpz0 vs6kmy/nrcfjtn 8le8ywxxzkzr #itnyp list\<payment> response payments that have been applied to this credit note see payment fields allocations https //app archbee com/docs/sbaaakcjtohpz0 vs6kmy/nrcfjtn 8le8ywxxzkzr #0uayd 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 contact docid\ xpsz7qutzphbpo3vustz 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 https //app archbee com/docs/sbaaakcjtohpz0 vs6kmy/nrcfjtn 8le8ywxxzkzr #3iybw 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 invoice docid\ f8lgp4lhyt7h w6npdlcn 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