Skip to content
/Revenue Holds

Revenue Holds

Look up revenue hold definitions to apply or release with the Manual Action APIs.

Operations

List revenue hold definitions

Request

Purpose

Returns a paginated list of the revenue hold definitions configured in Zuora Revenue setup.

When to use

  • Find the holdId to pass to the apply-hold and release-hold Manual Action APIs.
  • Check which holds are enabled and whether they allow manual apply or release.

Behavior notes

Only holds at the requested holdLevel are returned, and the level defaults to RC. Request holdLevel=LINE, POB, or CHARGE to list holds at other levels. The level filter always counts toward the limit of 5 filters. These are hold definitions, not the holds currently applied to contracts.

Filtering

Every query parameter other than page, size, and sort is treated as a filter.

  • field=value matches records where the field equals the value.
  • field[op]=value applies an operator. URL-encode the brackets as %5B and %5D, for example id%5Bgt%5D=1000. Operators: eq, ne, gt, gte, lt, lte, like (supply % wildcards yourself).
  • All filters are combined with AND. At most 5 filters are allowed per request.
  • Blank filter values are ignored.
  • An unknown field or operator returns HTTP 400.
Security
bearerAuth
Query
pageinteger, (int32), >= 0

Page number, starting at 1. 0 and an omitted value both return the first page.

Default:1
Example:page=1
sizeinteger, (int32), [ 1 .. 100 ]

Records per page. Default 20, maximum 100.

Default:20
Example:size=20
sortstring

Sort order as field,direction. Separate several sort fields with ; (for example id,desc;rcId,asc). Direction is asc or desc; any other value sorts ascending. Sortable fields: id, name, startDate, endDate, holdLevel. When sort is omitted the order is not guaranteed, so always sort when paging through results.

Example:sort=id,asc
holdLevelstring

Hold level to list. Case-insensitive.

Default:"RC"
Enum:"RC""POB""LINE""CHARGE"
Example:holdLevel=RC
idinteger, (int64)

Filter by hold definition ID.

Example:id=20
namestring

Filter by hold name. Use name[like]=%Acceptance% for a partial match.

Example:name=Pending Acceptance
startDatestring

Filter by hold start date.

Example:startDate=2026-01-01
endDatestring

Filter by hold end date.

Example:endDate=2026-12-31
Headers
Zuora-Request-Idstring, <= 64 characters

Optional correlation ID, echoed in the traceId response header.

Example:b8f1c2d4-6e1a-4c7b-9d2e-0f3a5b7c9e11
cURL
curl -i -X GET \
  'https://one.zuora.com/revenue/services/v1/revenue-holds?page=1&size=20&sort=id%2Casc&holdLevel=RC&id=20&name=Pending%20Acceptance&startDate=2026-01-01&endDate=2026-12-31' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Zuora-Request-Id: b8f1c2d4-6e1a-4c7b-9d2e-0f3a5b7c9e11'

Responses

A page of records. An empty data array means no record matched.

Headers
traceIdstring

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

Bodyapplication/json
dataArray of objects(RevenueHold)required
pageobject(PageMetadata)required

Pagination details for a list response.

Response
{
  "data": [
    { … }
  ],
  "page": {
    "number": 1,
    "size": 20,
    "totalElements": 1,
    "totalPages": 1,
    "first": true,
    "last": true
  }
}