Create and Apply Credit Note

1 min

In this example, we first create a Credit Note and then immediately apply it to an Invoice within a single request without requiring separate manual steps. This process involves two actions:

Creating the Credit Note with the required details such as contact, line items, and amount.

Extracting the generated CreditNoteID from the response and using it to apply the Credit Note to an existing Invoice by specifying the InvoiceID and Allocation amount.

Two separate responses are returned as part of this process:

Create Response: contains the details of the newly created Credit Note, including the CreditNoteID.

Apply Response: contains the allocation details showing how the Credit Note was applied to the Invoice.

// STEP 1: Create Credit Note

List<Object> creditNoteList = new List<Object>();
Map<String, Object> creditNoteMap = new Map<String, Object>();

// REQUIRED: Credit Note type
// Use 'ACCRECCREDIT' for Sales Credit Note
// Use 'ACCPAYCREDIT' for Bill Credit Note
creditNoteMap.put('Type', 'ACCRECCREDIT');

creditNoteMap.put('Date', '2026-11-14'); // Set the Credit Note Date
creditNoteMap.put('LineAmountTypes', 'Exclusive'); // Line amount type (Exclusive / Inclusive / NoTax)
creditNoteMap.put('Status', 'AUTHORISED'); // Status of the Credit Note

//Contact Information
Map<String, Object> contactMap = new Map<String, Object>();
contactMap.put('ContactID', 'cf8dd2e8-32b7-42ed-bdd7-c2021576d789');
creditNoteMap.put('Contact', contactMap);

// Credit Note Line Items
List<Object> lineItemList = new List<Object>();
Map<String, Object> lineItemMap = new Map<String, Object>();
lineItemMap.put('Description', 'Line Item Description');
lineItemMap.put('Quantity', 10);
lineItemMap.put('UnitAmount', 100);
lineItemMap.put('AccountCode', '200');

lineItemList.add(lineItemMap);
creditNoteMap.put('LineItems', lineItemList);

// Add Credit Note to list
creditNoteList.add(creditNoteMap);

// Request JSON
Map<String, Object> reqJSONMap = new Map<String, Object>();
reqJSONMap.put('creditnotes', creditNoteList);

String reqJSON = JSON.serialize(reqJSONMap);

// Final request
Map<String, Object> finalReqMap = new Map<String, Object>();
finalReqMap.put('queryParameters', new Map<String, Object>());
finalReqMap.put('version', '1.0');
finalReqMap.put('action', 'createCreditNote');
finalReqMap.put('RequestJSON', reqJSON);
finalReqMap.put('skipDML', true);
finalReqMap.put('xeroOrgId', '!n5t1z'); // Replace with your Xero Org ID

Map<String, Object> createResp = bread_winner.BreadwinnerXeroAPI.call(finalReqMap);
System.debug('Create Response ::: ' + createResp);

// STEP 2: Extract CreditNoteID from response (FIXED)

// responseJSON comes as String → must deserialize
String responseStr = (String) createResp.get('responseJSON');

// Convert String → Map
Map<String, Object> responseJSON = (Map<String, Object>) JSON.deserializeUntyped(responseStr);

// Extract creditnotes list
List<Object> creditNotes = (List<Object>) responseJSON.get('creditNotes');

// Get first Credit Note record
Map<String, Object> createdCN = (Map<String, Object>) creditNotes[0];

// Extract CreditNoteID
String creditNoteID = (String) createdCN.get('CreditNoteID');

// STEP 3: Apply Credit Note

List<Object> allocationList = new List<Object>();
Map<String, Object> allocationMap = new Map<String, Object>();

// Allocation details
allocationMap.put('Amount', 10); // Set the allocation amount (amount to apply from Credit Note to Invoice)
allocationMap.put('Date', '2026-11-14'); // Set the allocation date

// Invoice / Bill reference ID
Map<String, Object> invoiceMap = new Map<String, Object>();
invoiceMap.put('InvoiceID', 'd238e0b3-34e7-41df-9168-8a944bda4b8e'); // Replace the ID with your valid Invoice or Bill ID

// Key must always be 'Invoice'
allocationMap.put('Invoice', invoiceMap);

// Add allocation to list
allocationList.add(allocationMap);

// Allocation request JSON
Map<String, Object> allocReqJSONMap = new Map<String, Object>();
allocReqJSONMap.put('CreditNoteID', creditNoteID);
allocReqJSONMap.put('CreditNoteType', 'Invoice'); // REQUIRED: Enter 'Invoice' for Sales credit notes or 'Bill' for Bill credit notes
allocReqJSONMap.put('Allocations', allocationList);

String allocReqJSON = JSON.serialize(allocReqJSONMap);

// Final allocation request
Map<String, Object> finalAllocReq = new Map<String, Object>();
finalAllocReq.put('queryParameters', new Map<String, Object>());
finalAllocReq.put('version', '1.0');
finalAllocReq.put('action', 'applyCreditNoteAllocation');
finalAllocReq.put('RequestJSON', allocReqJSON);
finalAllocReq.put('skipDML', false); // skipDML = false → Applies the Credit Note to the Invoice/Bill and updates related records (Credit Note, Invoice, Payment) in Salesforce
finalAllocReq.put('xeroOrgId', '!n5t1z'); // Replace with your Xero Org ID

// Call allocation API
Map<String, Object> allocResp = bread_winner.BreadwinnerXeroAPI.call(finalAllocReq);