The zqu.CommitmentApi class is a global Apex API for managing commitments and their schedules on Zuora CPQ quotes. Commitments represent minimum or maximum spend agreements tied to a quote, and each commitment contains one or more schedules that define the commitment periods and amounts.

Use this API when you need to programmatically manage commitments from custom Apex, flows, or integrations instead of using only the standard user interface.

Other considerations

• Validate feature-flag dependencies before you use optional fields such as prepaymentType, commitmentCurrency, or MaxCommitment.

• When you update active commitments, match existing schedules by the exact startDate and endDate pair.

• For multi-schedule commitments, ensure the schedules are contiguous with no gaps.

• Use getCommitmentsByQuote or getCommitment to verify the resulting commitment and schedules after create or update operations.

Method summary

Feature flags and prerequisites

Some fields require feature flags to be enabled:

Commitment creation

Use createCommitment to create a new commitment and link it to a quote. New commitments are created in Draft status.

Key request fields:

Example: Prepaid commitment creation

zqu.CommitmentApi.CommitmentRequest request = new zqu.CommitmentApi.CommitmentRequest();
request.name = 'Annual Min Commitment';
request.type = 'MinCommitment';
request.priority = 1;
request.quoteId = 'a18O900000Kfqn7IAB';
request.periodAlignmentOption = 'CommitmentStartDate';
request.applicableAccounts = 'Commitment Account Only';
request.applicableCharges = 'All Charges';
request.prepaymentType = 'FullyPrepaid';

zqu.CommitmentApi.ScheduleData schedule = new zqu.CommitmentApi.ScheduleData();
schedule.startDate = Date.newInstance(2026, 5, 1);
schedule.endDate = Date.newInstance(2027, 5, 1);
schedule.amount = 2000;
schedule.periodType = 'Month';
schedule.prepaymentFrequency = 'Quarter';

request.schedules = new List<zqu.CommitmentApi.ScheduleData>{ schedule };

zqu.CommitmentApi.CommitmentResult result = zqu.CommitmentApi.createCommitment(request);
System.debug('Success: ' + result.success);
System.debug('Commitment ID: ' + result.commitmentId);

Example: Commitment creation with multiple schedules

When you use multiple schedules, the schedules must be contiguous. Each schedule startDate must match the previous schedule endDate with no gaps.

zqu.CommitmentApi.CommitmentRequest request = new zqu.CommitmentApi.CommitmentRequest();
request.name = 'Two-Phase Commitment';
request.type = 'MinCommitment';
request.priority = 1;
request.quoteId = 'a18O900000Kfqn7IAB';
request.periodAlignmentOption = 'CommitmentStartDate';
request.applicableAccounts = 'Commitment Account Only';
request.applicableCharges = 'All Charges';

zqu.CommitmentApi.ScheduleData schedule1 = new zqu.CommitmentApi.ScheduleData();
schedule1.startDate = Date.newInstance(2026, 5, 1);
schedule1.endDate = Date.newInstance(2026, 11, 1);
schedule1.amount = 1500;
schedule1.periodType = 'Month';

zqu.CommitmentApi.ScheduleData schedule2 = new zqu.CommitmentApi.ScheduleData();
schedule2.startDate = Date.newInstance(2026, 11, 1);
schedule2.endDate = Date.newInstance(2027, 5, 1);
schedule2.amount = 2500;
schedule2.periodType = 'Quarter';

request.schedules = new List<zqu.CommitmentApi.ScheduleData>{ schedule1, schedule2 };

zqu.CommitmentApi.CommitmentResult result = zqu.CommitmentApi.createCommitment(request);
System.debug('Success: ' + result.success);
System.debug('Schedules Created: ' + result.schedules?.size());

Example: Filtered-charge commitment creation

Use Filtered Charges when the commitment should apply only to selected charges instead of all charges on the quote. The API supports existing subscription charge numbers, product rate plan charge filters from the current quote, and newly added product rate plan Zuora IDs.

zqu.CommitmentApi.CommitmentRequest request = new zqu.CommitmentApi.CommitmentRequest();
request.name = 'Filtered Charge Commitment';
request.type = 'MinCommitment';
request.priority = 2;
request.quoteId = 'a18O900000Kfqn7IAB';
request.periodAlignmentOption = 'CommitmentStartDate';
request.applicableAccounts = 'Commitment Account Only';
request.applicableCharges = 'Filtered Charges';

zqu.CommitmentApi.CommitmentCharges charges = new zqu.CommitmentApi.CommitmentCharges();
charges.chargeNumbers = new List<String>{ 'C-00000123', 'C-00000456' };
charges.productRatePlanChargeFilters = new List<zqu.CommitmentApi.ChargeFilter>{
    new zqu.CommitmentApi.ChargeFilter('prpc-zuora-id-1', null),
    new zqu.CommitmentApi.ChargeFilter('prpc-zuora-id-2', '1')
};
charges.productRatePlanZuoraIds = new List<String>{ 'prp-zuora-id-1' };

request.selectedCharges = charges;

zqu.CommitmentApi.ScheduleData schedule = new zqu.CommitmentApi.ScheduleData();
schedule.startDate = Date.newInstance(2026, 5, 1);
schedule.endDate = Date.newInstance(2027, 5, 1);
schedule.amount = 5000;
schedule.periodType = 'Year';

request.schedules = new List<zqu.CommitmentApi.ScheduleData>{ schedule };

zqu.CommitmentApi.CommitmentResult result = zqu.CommitmentApi.createCommitment(request);
System.debug('Success: ' + result.success);

Other create scenarios

The API also supports:

• Specific date alignment using SpecificDate and specificPeriodAlignmentDate.

• Commitments across multiple billing accounts using comma-separated account numbers.

• Passing custom fields through customFields, while protected standard fields are skipped automatically.

Commitment updates

Use updateCommitment to update an existing commitment. The allowed changes depend on the commitment status.

Update behavior by status:

Example: Draft commitment updates

String commitmentId = 'a1XO9000000XXXXX';

zqu.CommitmentApi.CommitmentRequest updateReq = new zqu.CommitmentApi.CommitmentRequest();
updateReq.commitmentId = commitmentId;
updateReq.name = 'Updated Commitment Name';
updateReq.type = 'MinCommitment';
updateReq.priority = 3;
updateReq.description = 'Updated via API';
updateReq.quoteId = 'a18O900000Kfqn7IAB';
updateReq.periodAlignmentOption = 'CommitmentStartDate';
updateReq.applicableAccounts = 'Commitment Account and its Direct Children';
updateReq.applicableCharges = 'All Charges';

zqu.CommitmentApi.ScheduleData newSchedule = new zqu.CommitmentApi.ScheduleData();
newSchedule.startDate = Date.newInstance(2026, 6, 1);
newSchedule.endDate = Date.newInstance(2027, 6, 1);
newSchedule.amount = 5000;
newSchedule.periodType = 'Quarter';

updateReq.schedules = new List<zqu.CommitmentApi.ScheduleData>{ newSchedule };

zqu.CommitmentApi.CommitmentResult result = zqu.CommitmentApi.updateCommitment(updateReq);
System.debug('Success: ' + result.success);

Example: Active commitment updates

For commitments in Active or Update status, existing schedules are matched by their startDate and endDate pair. You can update the amount of an existing schedule and add new schedules, but you cannot fully edit all fields as you can in Draft status.

String activeCommitmentId = 'a1XO9000000XXXXX';

zqu.CommitmentApi.CommitmentRequest updateReq = new zqu.CommitmentApi.CommitmentRequest();
updateReq.commitmentId = activeCommitmentId;
updateReq.name = 'Renamed Active Commitment';
updateReq.quoteId = 'a18O900000Kfqn7IAB';
updateReq.applicableAccounts = 'Commitment Account Only';
updateReq.applicableCharges = 'All Charges';

// Update amount on an existing schedule
zqu.CommitmentApi.ScheduleData existingSchedule = new zqu.CommitmentApi.ScheduleData();
existingSchedule.startDate = Date.newInstance(2026, 5, 1);
existingSchedule.endDate = Date.newInstance(2027, 5, 1);
existingSchedule.amount = 7500;

// Add a new schedule
zqu.CommitmentApi.ScheduleData newSchedule = new zqu.CommitmentApi.ScheduleData();
newSchedule.startDate = Date.newInstance(2027, 5, 1);
newSchedule.endDate = Date.newInstance(2028, 5, 1);
newSchedule.amount = 3000;
newSchedule.periodType = 'Year';

updateReq.schedules = new List<zqu.CommitmentApi.ScheduleData>{ existingSchedule, newSchedule };
updateReq.customFields = new Map<String, Object>{
    'Description__c' => 'Updated via API on active commitment'
};

zqu.CommitmentApi.CommitmentResult result = zqu.CommitmentApi.updateCommitment(updateReq);
System.debug('Success: ' + result.success);

Commitment deletion

Use deleteCommitment to delete a commitment and its associated schedules. Only commitments in Draft status can be deleted. If you try to delete a commitment in Active or Update status, the API returns an INVALID_STATUS error.

Required field:

Example: Draft commitment deletion

zqu.CommitmentApi.DeleteCommitmentRequest deleteReq = new zqu.CommitmentApi.DeleteCommitmentRequest();
deleteReq.commitmentId = 'a1XO9000000XXXXX';

zqu.CommitmentApi.CommitmentResult result = zqu.CommitmentApi.deleteCommitment(deleteReq);

if (result.success) {
    System.debug('Commitment deleted successfully');
} else {
    System.debug('Delete failed: ' + result.errorMessage);
    System.debug('Error code: ' + result.errorCode);
}

Commitments retrieval

Quote Commitment Retrieval

Use getCommitmentsByQuote to retrieve all commitments associated with a quote, including schedule records.

List<zqu.CommitmentApi.CommitmentResult> results =
    zqu.CommitmentApi.getCommitmentsByQuote('a18O900000Kfqn7IAB');

System.debug('Total commitments found: ' + results.size());

for (zqu.CommitmentApi.CommitmentResult r : results) {
    if (r.success) {
        System.debug('Name: ' + r.commitment.Name);
        System.debug('Number: ' + r.commitmentNumber);
        System.debug('Status: ' + r.commitment.Status__c);
        System.debug('Schedules: ' + r.schedules?.size());
    } else {
        System.debug('Error: ' + r.errorMessage);
    }
}

Single Commitment Retrieval

Use getCommitment to retrieve one commitment by its Salesforce record ID, including schedule records.

zqu.CommitmentApi.CommitmentResult result =
    zqu.CommitmentApi.getCommitment('a1XO9000000XXXXX');

if (result.success) {
    System.debug('Name: ' + result.commitment.Name);
    System.debug('Type: ' + result.commitment.Type__c);
    System.debug('Status: ' + result.commitment.Status__c);
    System.debug('Priority: ' + result.commitment.Priority__c);

    for (CommitmentSchedule__c sched : result.schedules) {
        System.debug(sched.StartDate__c + ' to ' + sched.EndDate__c
            + ' | Amount: $' + sched.Amount__c);
    }
} else {
    System.debug('Error: ' + result.errorMessage);
}