Retrieve a commitment
Skip to content
v1 API
/
/
Retrieve a commitment

Retrieve a commitment

Request

Retrieves the details of a specific commitment using its ID or number.

Security
bearerAuth
Path
commitmentKeystringrequired

The unique identifier (ID or number) of the commitment.

Query
includeChildCommitmentsboolean

When true, childCommitments contains full child commitment objects. When false or omitted, childCommitments is an empty array. Defaults to false.

Default:false
Headers
Accept-Encodingstring

Include the Accept-Encoding: gzip header to compress responses as a gzipped file. It can significantly reduce the bandwidth required for a response.

If specified, Zuora automatically compresses responses that contain over 1000 bytes of data, and the response contains a Content-Encoding header with the compression algorithm so that your client can decompress it.

Content-Encodingstring

Include the Content-Encoding: gzip header to compress a request. With this header specified, you should upload a gzipped file for the request payload instead of sending the JSON payload.

Zuora-Entity-Idsstring

An entity ID. If you have Zuora Multi-entity enabled and the OAuth token is valid for more than one entity, you must use this header to specify which entity to perform the operation in. If the OAuth token is only valid for a single entity, or you do not have Zuora Multi-entity enabled, you should not set this header.

Zuora-Org-Idsstring

Comma separated IDs. If you have Zuora Multi-Org enabled, you can use this header to specify which orgs to perform the operation in. If you do not have Zuora Multi-Org enabled, you should not set this header.

The IDs must be a sub-set of the user's accessible orgs. If you specify an org that the user does not have access to, the operation fails. This header is important in Multi-Org (MO) setups because it defines the organization context under which the API should operate—mainly used for read access or data visibility filtering. If the header is not set, the operation is performed in scope of the user's accessible orgs.

Zuora-Track-Idstring, <= 64 characters

A custom identifier for tracing the API call. If you set a value for this header, Zuora returns the same value in the response headers. This header enables you to associate your system process identifiers with Zuora API calls, to assist with troubleshooting in the event of an issue.

The value of this field must use the US-ASCII character set and must not include any of the following characters: colon (:), semicolon (;), double quote ("), and quote (').

Zuora-Versionstring

The minor API version.

For a list of available minor versions, see API upgrades.

cURL
curl -i -X GET \
  'https://rest.test.zuora.com/commitments/{commitmentKey}?includeChildCommitments=false' \
  -H 'Accept-Encoding: string' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Encoding: string' \
  -H 'Zuora-Entity-Ids: string' \
  -H 'Zuora-Org-Ids: string' \
  -H 'Zuora-Track-Id: string' \
  -H 'Zuora-Version: string'

Responses

OK

Headers
Content-Encodingstring

This header is returned if you specify the Accept-Encoding: gzip request header and the response contains over 1000 bytes of data.

Note that only the following MIME types support gzipped responses:

  • application/json
  • application/xml
  • text/html
  • text/csv
  • text/plain
RateLimit-Limitstring

The request limit quota for the time window closest to exhaustion. See rate limits for more information.

RateLimit-Remainingnumber

The number of requests remaining in the time window closest to quota exhaustion. See rate limits for more information.

RateLimit-Resetnumber

The number of seconds until the quota resets for the time window closest to quota exhaustion. See rate limits for more information.

Zuora-Request-Idstring, = 36 characters

The Zuora internal identifier of the API call. You cannot control the value of this header.

Zuora-Track-Idstring, <= 64 characters

A custom identifier for tracing the API call. If you specified a tracing identifier in the request headers, Zuora returns the same tracing identifier. Otherwise, Zuora does not set this header.

Bodyapplication/json
idstring

ID of the commitment.

statusstring(CommitmentStatus)

Status of the commitment.

Enum:"Active""Cancelled""Evaluated""CancelledPendingEvaluation"
versioninteger

Version of the commitment.

startDatestring, (date)

The start date of the commitment.

endDatestring, (date)

The end date of the commitment.

totalAmountnumber, (double)

The commitment amount.

currencystring

Currency of the commitment.

orderNumberstring, <= 32 characters

The number of the order.

orderIdstring, <= 32 characters

The ID of the order.

accountIdstring, <= 32 characters

The ID of the commitment owner account.

accountNumberstring, <= 100 characters

Use this field to assign an existing account as the owner of an Commitment.

commitmentNumberstring, <= 100 characters

The number of the commitment.

namestring, <= 255 characters

The name of the commitment.

typestring

The type of the commitment.

Enum:"MinCommitment""MaxCommitment"
prepaymentTypestring(PrepaymentTypeEnum)

The prepayment type of the commitment.

Note: FullyPrepaid commitments will not be considered for true-up during invoice generation.

Enum:"FullyPrepaid""NotPrepaid"
descriptionstring, <= 500 characters

The description about this commitment.

priorityinteger

The priority of the commitment. It defines the evaluation order of the commitment. The lower the number, the higher the priority. When two commitments have the same priority, the one with the earlier created time will be evaluated first.

customFieldsobject(CommitmentCustomFields)

Container for custom fields of a Commitment object.

aceIdinteger, (int64)

The account code entity ID.

accountReceivableAccountingCodestring, <= 200 characters

The accounting code on the Commitment object for customers

adjustmentLiabilityAccountingCodestring, <= 100 characters

The accounting code on the commitment for customers.

Note: This field is only available if you have the Order to Revenue feature enabled.

adjustmentRevenueAccountingCodestring, <= 100 characters

The accounting code on the commitment for customers.

Note: This field is only available if you have the Order to Revenue feature enabled.

cancellationPolicyobject(CancellationPolicy)

Cancellation policy configuration for a commitment. Defines how settlements are handled when a commitment is cancelled.

cancellationEffectiveDatestring, (date)

The effective date when the commitment cancellation takes effect.

childCommitmentsArray of objects(GetCommitmentResponse)

Child commitments nested under this parent. Never null. When includeChildCommitments is false or omitted, this array is empty. When includeChildCommitments is true, this array contains full child commitment objects, or an empty array when there are no children.

Example:
[
  {
    "id": "8ad08ca797ef6ca50197f3cce6267992",
    "status": "Active",
    "version": 1,
    "currency": "USD",
    "startDate": "2024-01-01",
    "endDate": "2024-12-31",
    "totalAmount": 50000,
    "orderNumber": "O-0001",
    "orderId": "00989e98483e00030a2733ee989e9815",
    "accountId": "8a8aa0ac7f3b4c1d017f3b4c1d0a0001",
    "accountNumber": "ACC-0001",
    "commitmentNumber": "CMT-CHILD-001",
    "name": "Child Commitment",
    "type": "MinCommitment",
    "prepaymentType": "NotPrepaid",
    "description": "Child commitment created from parent",
    "priority": 1,
    "eligibleAccountConditions": { … },
    "eligibleChargeConditions": { … },
    "periodAlignmentOption": "SpecificDate",
    "specificPeriodAlignmentDate": "2020-01-15",
    "customFields": {},
    "aceId": 15837365486485894,
    "excludeItemBookingFromRevenueAccounting": true,
    "adjustmentLiabilityAccountingCode": "Accounts Receivable",
    "adjustmentRevenueAccountingCode": "Accounts Receivable",
    "contractAssetAccountingCode": "Accounts Receivable",
    "contractLiabilityAccountingCode": "Accounts Receivable",
    "contractRecognizedRevenueAccountingCode": "Accounts Receivable",
    "deferredRevenueAccountingCode": "Accounts Receivable",
    "excludeItemBillingFromRevenueAccounting": false,
    "isAllocationEligible": true,
    "isUnbilled": false,
    "recognizedRevenueAccountingCode": "Accounts Receivable",
    "revenueRecognitionRule": "Recognize upon invoicing",
    "unbilledReceivablesAccountingCode": "Accounts Receivable",
    "revenueRecognitionTiming": "Upon Order Activation Date",
    "revenueAmortizationMethod": "Immediate",
    "accountReceivableAccountingCode": "Accounts Receivable",
    "cancellationPolicy": { … },
    "cancellationEffectiveDate": "2020-06-30",
    "childCommitments": [],
    "taxable": true,
    "taxCode": "SalesTax_US",
    "taxMode": "TaxInclusive"
  }
]
contractAssetAccountingCodestring, <= 100 characters

The accounting code on the commitment for customers.

Note: This field is only available if you have the Order to Revenue feature enabled.

contractLiabilityAccountingCodestring, <= 100 characters

The accounting code on the commitment for customers.

Note: This field is only available if you have the Order to Revenue feature enabled.

contractRecognizedRevenueAccountingCodestring, <= 100 characters

The accounting code on the commitment for customers.

Note: This field is only available if you have the Order to Revenue feature enabled.

deferredRevenueAccountingCodestring, <= 100 characters

The deferred revenue accounting code for the commitment.

excludeItemBookingFromRevenueAccountingboolean

The flag to exclude commitment related booking items from revenue accounting.

Default:true
excludeItemBillingFromRevenueAccountingboolean

The flag to exclude commitment related invoice items, invoice item adjustments, credit memo items, and debit memo items from revenue accounting.

Note: This field is only available if you have the Order to Revenue feature enabled.

eligibleAccountConditionsobject(EligibleAccountCondition)

The conditions for account level filters for the commitment.

eligibleChargeConditionsobject(EligibleChargeCondition)

The conditions for charge level filters for the commitment.

periodAlignmentOptionstring(PeriodAlignmentOptionEnum)

Options for aligning the commitment periods within a commitment.

Default:"CommitmentStartDate"
Enum:"CommitmentStartDate""SpecificDate"
specificPeriodAlignmentDatestring, (date)

The specific date for period alignment, required if periodAlignmentOption is SpecificDate.

isAllocationEligibleboolean

This field is used to identify if the commitment is allocation eligible in revenue recognition.

Note: This field is only available if you have the Order to Revenue feature enabled.

isUnbilledboolean

This field is used to dictate how to perform the accounting during revenue recognition.

Note: This field is only available if you have the Order to Revenue feature enabled.

recognizedRevenueAccountingCodestring, <= 100 characters

The recognized revenue accounting code for the commitment.

revenueAmortizationMethodstring, <= 200 characters

This field is used to dictate the type of revenue amortization method.

revenueRecognitionRulestring

The revenue recognition rule for the commitment.

revenueRecognitionTimingstring, <= 200 characters

This field is used to dictate the type of revenue recognition timing.

unbilledReceivablesAccountingCodestring, <= 100 characters

The accounting code on the commitment for customers.

Note: This field is only available if you have the Order to Revenue feature enabled.

taxableboolean

Determines whether the true-up invoice of a commitment is taxable. If the value is true, the tax code and tax mode are required.

taxCodestring

Identifies which tax rules and tax rates to apply to the corresponding billing document.

taxModestring

The tax mode that determines whether tax is included or exclueded from the billing document.

Enum:"TaxInclusive""TaxExclusive"
Response
{
  "id": "8ad08ca797ef6ca50197f3cce6267991",
  "status": "Active",
  "version": 1,
  "currency": "USD",
  "startDate": "2020-01-01",
  "endDate": "2020-12-31",
  "amount": 100,
  "orderNumber": "O-0001",
  "orderId": "00989e98483e00030a2733ee989e9815",
  "accountId": "8a8aa0ac7f3b4c1d017f3b4c1d0a0001",
  "accountNumber": "ACC-0001",
  "commitmentNumber": "TW-0001",
  "name": "Example Commitment",
  "type": "MinCommitment",
  "prepaymentType": "NotPrepaid",
  "description": "This a example commitment.",
  "priority": 1,
  "eligibleAccountConditions": {
    "field": "Account.AccountNumber",
    "operator": "eq",
    "value": "ACC-0001",
    "conditions": [ … ],
    "relation": "and"
  },
  "eligibleChargeConditions": {
    "field": "RatePlanCharge.ChargeNumber",
    "operator": "in",
    "value": "C-0001,C-0002",
    "conditions": [ … ],
    "relation": "and"
  },
  "periodAlignmentOption": "SpecificDate",
  "specificPeriodAlignmentDate": "2020-01-15",
  "customFields": {},
  "aceId": "15837365486485820",
  "excludeItemBookingFromRevenueAccounting": true,
  "adjustmentLiabilityAccountingCode": "Accounts Receivable",
  "adjustmentRevenueAccountingCode": "Accounts Receivable",
  "contractAssetAccountingCode": "Accounts Receivable",
  "contractLiabilityAccountingCode": "Accounts Receivable",
  "contractRecognizedRevenueAccountingCode": "Accounts Receivable",
  "deferredRevenueAccountingCode": "Accounts Receivable",
  "excludeItemBillingFromRevenueAccounting": false,
  "isAllocationEligible": true,
  "isUnbilled": false,
  "recognizedRevenueAccountingCode": "Accounts Receivable",
  "revenueRecognitionRule": "Recognize upon invoicing",
  "unbilledReceivablesAccountingCode": "Accounts Receivable",
  "revenueRecognitionTiming": "Upon Order Activation Date",
  "revenueAmortizationMethod": "Immediate",
  "accountReceivableAccountingCode": "Accounts Receivable",
  "cancellationPolicy": {
    "settlementType": "NoSettlement"
  },
  "cancellationEffectiveDate": "2020-06-30",
  "childCommitments": [
    { … }
  ],
  "taxable": true,
  "taxCode": "SalesTax_US",
  "taxMode": "TaxInclusive"
}