Skip to content
/Apply and Release Holds

Apply a hold to a revenue contract

Request

Purpose

Applies a revenue hold definition to the whole revenue contract. While the hold is in place, Zuora Revenue blocks the revenue recognition (or transfer) that the hold type covers.

When to use

  • Revenue must not be recognized until a condition is met, for example customer acceptance, a credit check, or an audit, and the condition applies to the whole contract.
  • Use a hold definition whose flags.holdLevel is RC and whose flags.allowManualApply is Y. List them with GET /revenue-holds?holdLevel=RC.
Security
bearerAuth
Path
rcIdinteger, (int64)required

Revenue contract ID.

Example:111442
holdIdinteger, (int64)required

Revenue hold definition ID. List holds with GET /revenue-holds.

Example:20
Headers
X-REV-BOOK-IDinteger, (int64)

Revenue book to work in. Defaults to 1 (the primary book). Ignored by the revenue hold definition endpoints, because hold definitions are shared across books.

Default:1
Example:1
Zuora-Request-Idstring, <= 64 characters

Optional correlation ID, echoed in the traceId response header.

Example:b8f1c2d4-6e1a-4c7b-9d2e-0f3a5b7c9e11
Bodyapplication/jsonrequired
commentsstring

Comment stored with the hold.

Default:""
objectVersioninteger, (int64)

Current version of the revenue contract, used for optimistic locking. Omit it to use the contract's current version. If you send a version that is no longer current, the revenue engine rejects the action.

Example:5
{
  "comments": "Hold pending customer acceptance"
}

Responses

Processed. success: true means the action completed; success: false means a business rule rejected it and message explains why.

Headers
traceIdstring

Correlation ID of the request. Quote it when you contact Zuora Global Support.

Bodyapplication/json
successbooleanrequired

true when the action completed. false when the revenue engine rejected it under a business rule; see message.

processIdstringrequired

Unique ID generated for this request. Quote it when you contact Zuora Global Support.

messagestring

Result message from the revenue engine. May be empty on success.

changeIdsstring

Comma-separated IDs of records changed by the action, when the action reports them. Omitted otherwise.

holdRecordsArray of objects(HoldRecord)

Hold records created by the action. Omitted when none were created.

Response
{
  "success": true,
  "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11",
  "message": "Hold applied successfully",
  "holdRecords": [
    { … }
  ]
}