{ "openapi": "3.0.1", "info": { "title": "Revenue API Reference", "description": "\n# Introduction\n\n\nWelcome to the reference for Zuora Revenue REST API!\n\n\nREST is a web-service protocol that lends itself to rapid development by \nusing everyday HTTP and JSON technology. Zuora Revenue provides various REST \nAPIs for data integration. Use these REST APIs to authenticate and integrate \ndata from the source ERP systems with Zuora Revenue.\n\n\nAll Zuora Revenue REST APIs are secured by using HTTPS. The authentication scheme is token-based authentication, \nwhich means an authenticated user must generate a token and then use it for all subsequent APIs until the token expires.\n\n\nThis reference provides detailed descriptions about functions, requests, and responses of each REST API.\n\nZuora Revenue REST APIs can be broadly classified into the following categories:\n\n * Authentication\n\n * Inbound\n\n * Outbound \n \n**Remember:** \n\n\n * The API service must be enabled for your tenant in the first place. Otherwise, the 405 error will be returned for every API request you submitted. To enable the API service, contact Zuora Revenue Support.\n\n * Both the inbound and outbound operations require an authentication token to perform integration.\nYou can obtain the token by using the Authentication operation.\n\n\n## Endpoints\n\nAfter the APIs are provisioned in Zuora Revenue Cloud, you can get the endpoint and use that endpoint to call the APIs.\n\n\n\n## Requirements\n\nBefore you use the Zuora Revenue APIs, make sure the following requirements are met:\n\n * Zuora Revenue uses role based access control to restrict system access to authorized users. \nTo use the Zuora Revenue APIs, make sure that your user role has the **Webservices Inbound** \nand **Webservices Outbound** previleges in Zuora Revenue security settings. For more information, \nsee Manage User Access. \n * To use the inbound operations to upload data into Zuora Revenue, the upload templates must be created by using the **File Upload** menu options in the Zuora Revenue UI. \n Currently, the APIs support transaction upload, bundle upload, and event upload.\n * To use the outbound operations, the outbound GL interface mapping must be set up in the Zuora Revenue UI (**Setups > Application > Interface Setup**). \n\n\n## Requests and Responses\n\nZuora Revenue APIs support the JSON format of HTTP responses. Inbound operations for data upload support the CSV format only.\n\n\n## Inbound Data Error\n\nAll the inbound data into Zuora Revenue are first loaded into pre-stage tables, namely CUST_UI tables in Zuora Revenue,\nand then pushed to the corresponding staging tables from CUST_UI tables. \n\n\nIf the data fails in the CUST_UI tables, the entire batch of records will be marked as `Failed`.\nIt means All or Nothing approach will be followed when data is being inserted to the CUST_UI tables. \nIf the data has been successfully inserted into the CUST_UI tables, it will then be automatically pushed to \nthe staging tables and no manual work is required. \n\n\nAny uncollected data that remains in the staging tables can be manually fixed or downloaded, and can be reposted from the upstream systems. \n\n\nYou can use the Stage Error operations to retrieve error information about the uploaded data.\n", "version": "2026-10-16", "x-logo": { "url": "https://www.zuora.com/wp-content/uploads/2016/10/zuora-dev-logo-api-ref.svg" } }, "servers": [ { "url": "https://one.zuora.com", "description": "Zuora OneID production URL." } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Authentication", "description": "The Authentication operation is the authentication layer when you integrate\ndata with Zuora Revenue APIs. Use this operation to authenticate and generate a token\nthat can be valid for a specific time period. The token is required for all the subsequent\nAPI calls. By default, a token will be valid for 30 minutes before it expires. If the issued \ntoken expires, call this operation again with valid credentials to get a new token. \n\n\nTo acquire the token, you must provide the user role and client name as well as basic \nauthorization in the HTTP request header. An example of basic authorization header is as follows: \n\n`Basic c3lzYWRtaW46fsDFsgsV2cHJvJTEyMw==`\n\n\nAn example of the returned authentication token is as follows: \n\n```eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2V\nybmFtZSI6InZpbm90aC5iYWFsYWppIiwiaXNzIjoiUkV```\n" }, { "name": "Adapter", "description": "The Adapter operation is used to retrieve field mapping information in an upload template definitions. The field mapping information determines the mapping between the staging field names and the label names in the upload file.\n" }, { "name": "File Upload", "description": "The File Upload operations are used to upload large volumes of data as a CSV file in the HTTP body to Zuora Revenue and to get status information about the file upload.\n\nIf the data volume is in the range of 40k-60k records per file per request, the Upload file operation can process the data quickly. \nA unique request ID is generated after the file is successfully received, which can be used to query the upload status in the Get file upload status operation. \n" }, { "name": "Inbound", "description": "The Inbound operations are used to upload data in the CSV format to Zuora Revenue. As a prerequisite, the upload template definitions must be present in Zuora Revenue. Then, you specify the template name, file name, authentication token, and the CSV data in HTTP body of the inbound operations to upload data. It is recommended to use the Create upload operation for the CSV file than contains less than 20k lines. \n\nAfter the data is uploaded to the pre-stage table, Zuora Revenue scheduler will load the CSV content to corresponding staging tables in Zuora Revenue. You can query the upload status by using the Get upload status operation.\n" }, { "name": "Revenue Jobs", "description": "The Revenue Jobs operations are used to submit the following programs with Revenue APIs:\n* RevPro3.0 Data Collection Master\n* RevPro3.0 Event Process\n* RevPro3.0 Event Process Master\n* Revpro3.0 Accounting Transfer Master\n* RevPro3.0 Transfer Batch for Org\n\nNo matter what program is to be started, two path parameters are required for the Submit a program with specified parameters operation. One is the program ID and the other is the organization ID. Operations are also provided to retrieve the program ID and organization ID.\n\nFor an example of using API to submit the Revpro3.0 Accounting Transfer Master program, see Us API to submit a predefined program in the Knowledge Center.\n" }, { "name": "Stage Error", "description": "The Stage Error operation is used to get the list of records that contain errors in the Zuora Revenue staging tables for transactions or events.\n" }, { "name": "Transfer Accounting", "description": "The Transfer Accounting operations are used to support outbound data integrations. You can use these operations to query the transfer batch information and to update the transfer batch status.\n" }, { "name": "Transfer Accounting Files", "description": "The Transfer Accounting Files operation is used to download the transfer accounting data in a CSV file from Zuora Revenue for a specific transfer batch.\n" }, { "name": "Data Collection", "description": "The Data Collection operations are used to submit the data collection jobs and query the status of the submitted jobs.\n" }, { "name": "Report Catalog", "description": "Discover the reports in your tenant, their layouts, output columns, filters and metadata." }, { "name": "Report Runs", "description": "Submit a report layout for execution, poll the run, and download the result file." }, { "name": "Report Files", "description": "List completed report files and download them through the Integration service." }, { "name": "BI Views", "description": "Extract BI View data (revenue contracts, lines, schedules, journal data and more) in pages, count rows, describe columns, or submit a BI View as a background report." }, { "name": "BI View Tasks", "description": "Monitor and cancel the background tasks that prepare BI View pages." }, { "name": "Journal Entries", "description": "Create, read, list, search, update, copy and delete manual journal entries (header plus lines)." }, { "name": "Service Health", "description": "Check that the Manual Journal Entry API is available." }, { "name": "Journal Entry Lines", "description": "List, search, copy and delete the debit/credit lines of a journal entry." }, { "name": "Schedules and Waterfall", "description": "Inspect the revenue schedules and revenue waterfall generated from a journal entry, and retry waterfall generation." }, { "name": "Approval Workflow", "description": "Submit, approve, reject, recall, reverse and bulk-delete journal entries; check privileges, audit trail and validation status." }, { "name": "Reference Data", "description": "Look up the valid values (periods, books, organizations, currencies, account types, categories) and configuration needed to build a journal entry." }, { "name": "Attachments", "description": "Attach supporting files and notes to a journal entry, list, download and delete them." }, { "name": "Templates and Exports", "description": "Download the CSV upload template and export entries, lines, schedules and waterfall entries as CSV." }, { "name": "Revenue Contracts", "description": "Look up revenue contract header records." }, { "name": "Revenue Contract Lines", "description": "Look up the lines grouped into revenue contracts, including lines by Zuora Billing charge number." }, { "name": "Revenue Holds", "description": "Look up revenue hold definitions to apply or release with the Manual Action APIs." }, { "name": "Contract Status", "description": "Open, close, and unfreeze revenue contracts." }, { "name": "Apply and Release Holds", "description": "Apply and release revenue holds at contract, line, POB, or charge level." }, { "name": "Revenue Deferral and Release", "description": "Manually defer and release revenue." }, { "name": "Cost Deferral and Release", "description": "Defer and release contract costs on a line." }, { "name": "Allocation", "description": "Reallocate the transaction price and change allocation treatment." }, { "name": "Lines and POBs", "description": "Edit lines and POBs, copy lines, switch lead lines, and move POBs." }, { "name": "Contract Grouping", "description": "Link, delink, undo delink, and manually create revenue contracts." }, { "name": "Variable Consideration", "description": "List, apply, and expire variable consideration." }, { "name": "Impairment", "description": "Apply impairment to contract lines." }, { "name": "Usage", "description": "Correct and cancel usage records." }, { "name": "Billing", "description": "Void billing documents on a contract." }, { "name": "Forecast", "description": "Regenerate forecast revenue schedules." } ], "paths": { "/api/integration/v1/authenticate": { "post": { "tags": [ "Authentication" ], "summary": "Create authentication", "description": "Authenticates and gets the Json Web Token to push and pull data from your Zuora Revenue instance.\n", "operationId": "POST_Authenticate", "parameters": [ { "name": "role", "in": "header", "required": true, "schema": { "type": "string", "default": "API Role" } }, { "name": "clientname", "in": "header", "required": true, "schema": { "type": "string", "default": "Default" } } ], "responses": { "200": { "description": "Authentication token is returned.", "content": { "application/json; charset=utf-8": { "schema": { "type": "object", "properties": { "Message": { "type": "string", "description": "Token", "default": "Token Generated" }, "status": { "type": "string", "description": "Response Status", "default": "success" } } } } } } }, "security": [ { "basicAuth": [] } ], "x-code-samples": [ { "lang": "Curl", "source": "curl -X POST --header \"role: API Role\" --header \"clientname: Default\" --header \"Authorization: Basic WklOR0FQSToxffN4JKaOPw==\" \"https://one.zuora.com/api/integration/v1/authenticate\"\n" } ] } }, "/api/integration/v1/fileupload/status/{file_request_id}": { "get": { "tags": [ "File Upload" ], "summary": "Retrieve the file upload status", "description": "Gets the status information about the specified file upload request.", "operationId": "GET_FileUploadStatus", "parameters": [ { "name": "token", "in": "header", "description": "The valid authentication token that is generated by the Authentication operation.", "required": true, "schema": { "type": "string" } }, { "name": "file_request_id", "in": "path", "description": "The request ID of the file upload to be queried.", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "The status information is returned for the requested file upload.", "content": { "application/json; charset=utf-8": { "schema": { "type": "object", "properties": { "Result": { "type": "array", "items": { "$ref": "#/components/schemas/uploadStatus" } }, "message": { "type": "string", "description": "Response Message", "default": "Data Staged Successfully" }, "status": { "type": "string", "description": "Response Status", "default": "Success" } } } } } }, "204": { "description": "The status information cannot be retrieved for the specified request ID.", "content": {} } }, "x-code-samples": [ { "lang": "Curl", "source": "curl -X GET --header \"token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6IlpJTkdBUEkiLCJpc3MiOiJSRVZQUk8gMy4wIFdlYnNlcnZpY2VzIiwicm9sZSI6IlJldnBybyBBUEkgUm9sZSIsImV4cCI6MTUwNDc0NTIxMywiaWF0IjoxNTA0NzQzNDEzLCJuYmYiOjE1MDQ3NDM0MTMsImNsaWVudG5hbWUiOiJEZWZhdWx0In0.umtarSxRc0KUld5RZkrZMwzIypQYdwFYBP5-d1Cbi1Q\" \"https://one.zuora.com/api/integration/v1/fileupload/status/12333\"\n" } ] } }, "/api/integration/v1/upload/file": { "post": { "tags": [ "File Upload" ], "summary": "Upload file", "description": "Upload the event or transaction data in a CSV file to Zuora Revenue in UTF-8.\n\n**Note:** It is recommended to have up to 60k lines per request in this operation.\n", "operationId": "POST_UploadFile", "parameters": [ { "name": "token", "in": "header", "description": "The valid authentication token that is generated by the Authentication operation.", "required": true, "schema": { "type": "string" } }, { "name": "templatename", "in": "header", "description": "Name of the upload template that you want to use.", "required": true, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "description": "Must be set to \"multipart/form-data\".", "required": true, "schema": { "type": "string", "enum": [ "multipart/form-data" ] } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "required": [ "file" ], "type": "object", "properties": { "file": { "type": "string", "description": "The path to the CSV file that is to be uploaded.", "format": "binary" } } } } }, "required": true }, "responses": { "200": { "description": "The file is uploaded to Zuora Revenue.", "content": { "application/json; charset=utf-8": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response Message", "default": "File received successfully" }, "status": { "type": "string", "description": "Response Status", "default": "Success" } } } } } }, "400": { "description": "Exception occurs. Please contact Zuora Revenue Support.", "content": { "application/json; charset=utf-8": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response Message", "default": "Exception occurred. Please contact Zuora Revenue Support" }, "status": { "type": "string", "description": "Response Status", "default": "Error" } } } } } } }, "x-code-samples": [ { "lang": "Curl", "source": "curl -X POST \\\n https://one.zuora.com/api/integration/v1/upload/file \\\n -H 'cache-control: no-cache' \\\n -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \\\n -H 'templatename: sample_upload_template.csv' \\\n -H 'token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6IlpJTkdBUEkiLCJpc3MiOiJSRVZQUk8gMy4wIFdlYnNlcnZpY2VzIiwicm9sZSI6IlJldnBybyBBUEkgUm9sZSIsImV4cCI6MTUwNDc0NTIxMywiaWF0IjoxNTA0NzQzNDEzLCJuYmYiOjE1MDQ3NDM0MTMsImNsaWVudG5hbWUiOiJEZWZhdWx0In0.umtarSxRc0KUld5RZkrZMwzIypQYdwFYBP5-d1Cbi1Q' \\\n -F 'file=@/Users/user1/Downloads/Upload Template MO.csv'\n" } ] } }, "/api/integration/v1/csv/upload/status": { "get": { "tags": [ "Inbound" ], "summary": "Retrieve the upload status", "description": "Gets the status information about the Create upload operation.", "operationId": "GET_UploadStatus", "parameters": [ { "name": "token", "in": "header", "description": "The valid authentication token that is generated by the Authentication operation.", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "query", "description": "The request ID of the uploaded file for which the status information is being queried.", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "The status information is returned for the requested upload.", "content": { "application/json; charset=utf-8": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "client_id": { "type": "integer" }, "id": { "type": "integer" }, "message": { "type": "string", "default": "Data Received" }, "status": { "type": "string", "default": "Successfully Uploaded" } } }, "status": { "type": "string", "description": "Response Response", "default": "Success" } } } } } }, "400": { "description": "The status information cannot be retrieved for the specified request ID.", "content": { "application/json; charset=utf-8": { "schema": { "type": "object", "properties": { "Result": { "type": "string" }, "message": { "type": "string", "description": "Default error message", "default": "No data found" }, "status": { "type": "string", "description": "Error Response", "default": "Error" } } } } } } }, "x-code-samples": [ { "lang": "Curl", "source": "curl -X GET --header \"token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6IlpJTkdBUEkiLCJpc3MiOiJSRVZQUk8gMy4wIFdlYnNlcnZpY2VzIiwicm9sZSI6IlJldnBybyBBUEkgUm9sZSIsImV4cCI6MTUwNDc0NTIxMywiaWF0IjoxNTA0NzQzNDEzLCJuYmYiOjE1MDQ3NDM0MTMsImNsaWVudG5hbWUiOiJEZWZhdWx0In0.umtarSxRc0KUld5RZkrZMwzIypQYdwFYBP5-d1Cbi1Q\" \"https://one.zuora.com/api/integration/v1/csv/upload/status?id=10002\"\n" } ] } }, "/api/integration/v1/csv/upload": { "post": { "tags": [ "Inbound" ], "summary": "Create upload", "description": "Uploads the transaction, events, or bundle configuration data as a CSV (text/plain) file with UTF-8 encoding.\n\n**Note:** Up to 20k lines per request can be supported by this operation. If the CSV file contains more than 20k lines, it is recommended to use the Upload file operation. \n", "operationId": "POST_Upload", "parameters": [ { "name": "token", "in": "header", "description": "The valid authentication token that is generated by the Authentication operation.", "required": true, "schema": { "type": "string" } }, { "name": "templatename", "in": "header", "description": "The name of the upload template that you want to use.", "required": true, "schema": { "type": "string" } }, { "name": "filename", "in": "header", "description": "The unique file name to populate the data in the Zuora Revenue UI.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "text/plain": { "schema": { "type": "array", "items": { "type": "string", "description": "The actual data to be uploaded." } } } }, "required": true }, "responses": { "200": { "description": "Data is uploaded to the staging tables in Zuora Revenue.", "content": { "application/json; charset=utf-8": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response Message", "default": "Data Staged Successfully" }, "result": { "type": "object", "properties": { "client_id": { "type": "integer" }, "id": { "type": "integer" }, "message": { "type": "string" }, "status": { "type": "string" } } }, "status": { "type": "string", "description": "Response Status", "default": "Success" } } } } } }, "400": { "description": "Error occurs when data is being uploaded to Zuora Revenue staging tables.", "content": { "application/json; charset=utf-8": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error Message", "default": "Error loading Data into Staging Area" }, "result": { "type": "object", "properties": { "client_id": { "type": "integer" }, "id": { "type": "integer" }, "message": { "type": "string" }, "status": { "type": "string" } } }, "status": { "type": "string", "description": "Error Response", "default": "Error" } } } } } } }, "x-code-samples": [ { "lang": "Curl", "source": "curl -X POST --header \"Content-Type: text/plain\" --header \"token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6IlpJTkdBUEkiLCJpc3MiOiJSRVZQUk8gMy4wIFdlYnNlcnZpY2VzIiwicm9sZSI6IlJldnBybyBBUEkgUm9sZSIsImV4cCI6MTUwNDc0NTIxMywiaWF0IjoxNTA0NzQzNDEzLCJuYmYiOjE1MDQ3NDM0MTMsImNsaWVudG5hbWUiOiJEZWZhdWx0In0.umtarSxRc0KUld5RZkrZMwzIypQYdwFYBP5-d1Cbi1Q\" --header \"templatename: TEST TEMPLATE\" --header \"filename: TEST.csv\" -d \"\\\"Batch Id\\\",\\\"Process Flag\\\",\\\"Created By\\\",\\\"Creation Date\\\",\\\"Type\\\",\\\"Business Unit\\\",\\\"Atr48\\\",\\\"Atr8\\\",\\\"Atr60\\\",\\\"Ct Line Num\\\",\\\"Doc Num\\\",\\\"Doc Line Num\\\",\\\"Doc Line Id\\\",\\\"Doc Date\\\",\\\"Start Date\\\",\\\"End Date\\\",\\\"Date1\\\",\\\"Ct Mod Date\\\",\\\"Cust Num\\\",\\\"Cstmr Nm\\\",\\\"Atr45\\\",\\\"Curr\\\",\\\"F Cur\\\",\\\"F Ex Rate\\\",\\\"G Ex Rate\\\",\\\"Item Num\\\",\\\"Prod Ctgry\\\",\\\"Inv Num\\\",\\\"Inv Line Num\\\",\\\"Inv Line Id\\\",\\\"Orig Inv Line Id\\\",\\\"Orig So Line Id\\\",\\\"Inv Date\\\",\\\"Atr58\\\",\\\"Ord Qty\\\",\\\"Unit List Prc\\\",\\\"Ext Lst Prc\\\",\\\"Unit Sell Prc\\\",\\\"Ext Sll Prc\\\",\\\"Atr9\\\",\\\"Inv Qty\\\",\\\"Return Flag\\\",\\\"Ret Qty\\\",\\\"Def Segments\\\",\\\"Rev Segments\\\",\\\"Al Account\\\",\\\"Ar Account\\\",\\\"Ca Account\\\",\\\"Cv Eligible Flag\\\",\\\"Atr50\\\",\\\"Atr51\\\",\\\"Atr52\\\",\\\"Atr53\\\",\\\"Atr54\\\",\\\"Atr55\\\",\\\"Atr56\\\",\\\"Atr46\\\",\\\"Prod Class\\\",\\\"Prod Fmly\\\",\\\"Prod Ln\\\",\\\"Atr49\\\",\\\"Atr14\\\",\\\"Atr15\\\",\\\"Atr12\\\",\\\"Atr13\\\",\\\"Atr47\\\",\\\"Sob Id\\\",\\\"Credit Rule\\\",\\\"Num1\\\",\\\"Num2\\\",\\\"Date2\\\",\\\"Date3\\\",\\\"Atr10\\\",\\\"Atr11\\\",\\\"Atr57\\\",\\\"Atr5\\\",\\\"Atr6\\\"\" \"https://one.zuora.com/api/integration/v1/csv/upload\"\n" } ], "x-codegen-request-body-name": "data" } }, "/api/integration/v1/journal/batch/status/{batch_id}": { "put": { "tags": [ "Transfer Accounting" ], "summary": "Update transfer batch status", "description": "Updates the transfer batch status to `Transferred` in Zuora Revenue.", "operationId": "PUT_TransferBatchStatus", "parameters": [ { "name": "token", "in": "header", "description": "The valid authentication token that is generated by the Authentication operation.", "required": true, "schema": { "type": "string" } }, { "name": "batch_id", "in": "path", "description": "The batch ID of the transfer accounting batch.", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "The status of the transfer batch is changed to `Transferred`.", "content": { "application/json; charset=utf-8": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Response Status", "default": "Success" } } } } } }, "400": { "description": "Only the batch in Ready TO Transfer status can be updated.", "content": { "application/json; charset=utf-8": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Response Status", "default": "Error" }, "message": { "type": "string", "description": "0 row(s) updated. Only the batch in Ready TO Transfer status can be updated." } } } } } } }, "x-code-samples": [ { "lang": "Curl", "source": "curl -X PUT --header \"token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6IlpJTkdBUEkiLCJpc3MiOiJSRVZQUk8gMy4wIFdlYnNlcnZpY2VzIiwicm9sZSI6IlJldnBybyBBUEkgUm9sZSIsImV4cCI6MTUwNDc0ODE4MywiaWF0IjoxNTA0NzQ2MzgzLCJuYmYiOjE1MDQ3NDYzODMsImNsaWVudG5hbWUiOiJEZWZhdWx0In0.k1usDPkgldj-OG9-ga-jn5B2Axx-HG4D0chytx5JPIg\" \"https://one.zuora.com/api/integration/v1/journal/batch/status/10110\"\n" } ] } }, "/api/integration/v1/journal/batch/{batchid}/{pagenum}": { "get": { "tags": [ "Transfer Accounting" ], "summary": "Retrieve a transfer batch", "description": "Downloads the general ledger (GL) transfer batch data for the specified batch ID and page number. \nFor more information, see Best practice for using Revenue APIs.\n", "operationId": "GET_TransferBatch", "parameters": [ { "name": "token", "in": "header", "description": "The valid authentication token that is generated by the Authentication operation.", "required": true, "schema": { "type": "string" } }, { "name": "batchid", "in": "path", "description": "The batch ID of the transfer accounting batch.", "required": true, "schema": { "type": "integer" } }, { "name": "pagenum", "in": "path", "description": "The number of page to be downloaded.", "required": true, "schema": { "type": "integer" } }, { "name": "pagesize", "in": "query", "description": "The number of records to be downloaded per request. The default is 1000 and the maximum is 10000.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Operation is successful.", "content": { "application/json; charset=utf-8": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Response Status", "default": "Success" } } } } } } }, "x-code-samples": [ { "lang": "Curl", "source": "curl -X GET --header \"token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6IlpJTkdBUEkiLCJpc3MiOiJSRVZQUk8gMy4wIFdlYnNlcnZpY2VzIiwicm9sZSI6IlJldnBybyBBUEkgUm9sZSIsImV4cCI6MTUwNDc0ODE4MywiaWF0IjoxNTA0NzQ2MzgzLCJuYmYiOjE1MDQ3NDYzODMsImNsaWVudG5hbWUiOiJEZWZhdWx0In0.k1usDPkgldj-OG9-ga-jn5B2Axx-HG4D0chytx5JPIg\" \"https://one.zuora.com/api/integration/v1/journal/batch/10000/1?Output=CSV\"\n" } ] } }, "/api/integration/v1/journal/list": { "get": { "tags": [ "Transfer Accounting" ], "summary": "List transfer batches", "description": "Gets a list of the transfer accounting batches that are available in Zuora Revenue.", "operationId": "GET_TransferBatchList", "parameters": [ { "name": "token", "in": "header", "description": "The valid authentication token that is generated by the Authentication operation.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Operation is successful.", "content": { "application/json; charset=utf-8": { "schema": { "type": "object", "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/Journal" } }, "status": { "type": "string", "description": "Response Status", "default": "Success" } } } } } }, "204": { "description": "No GL Transfer batches in Ready to Transfer status are available.", "content": {} }, "400": { "description": "Error occurs when fetching the GL batch list.", "content": {} } }, "x-code-samples": [ { "lang": "Curl", "source": "curl -X GET --header \"token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6IlpJTkdBUEkiLCJpc3MiOiJSRVZQUk8gMy4wIFdlYnNlcnZpY2VzIiwicm9sZSI6IlJldnBybyBBUEkgUm9sZSIsImV4cCI6MTUwNDc0ODE4MywiaWF0IjoxNTA0NzQ2MzgzLCJuYmYiOjE1MDQ3NDYzODMsImNsaWVudG5hbWUiOiJEZWZhdWx0In0.k1usDPkgldj-OG9-ga-jn5B2Axx-HG4D0chytx5JPIg\" \"https://one.zuora.com/api/integration/v1/journal/list\"\n" } ] } }, "/api/integration/v1/download/transferbatchfile/{batch_id}": { "get": { "tags": [ "Transfer Accounting Files" ], "summary": "Download a transfer batch file", "description": "Downloads the GL transfer batch files from Zuora Revenue for the specified batch ID. \n\n\n**Note:** \n\n* Only the transfer accounting files that are created in the last 48 hours are available for download.\n\n* The maximum downloadable file size is 1 GB.\n", "operationId": "GET_TransferBatchFile", "parameters": [ { "name": "token", "in": "header", "description": "The valid authentication token that is generated by the Authentication operation.", "required": true, "schema": { "type": "string" } }, { "name": "batch_id", "in": "path", "description": "The batch ID of the transfer accounting batch.", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Operation is successful.", "content": { "application/json; charset=utf-8": { "schema": { "type": "object", "properties": { "active": { "type": "array", "description": "Response Status" } } } } } }, "204": { "description": "The batch file is not generated for the batch ID or the batch file is not found.", "content": {} } }, "x-code-samples": [ { "lang": "Curl", "source": "curl -X GET --header \"token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6IlpJTkdBUEkiLCJpc3MiOiJSRVZQUk8gMy4wIFdlYnNlcnZpY2VzIiwicm9sZSI6IlJldnBybyBBUEkgUm9sZSIsImV4cCI6MTUwNDc0ODE4MywiaWF0IjoxNTA0NzQ2MzgzLCJuYmYiOjE1MDQ3NDYzODMsImNsaWVudG5hbWUiOiJEZWZhdWx0In0.k1usDPkgldj-OG9-ga-jn5B2Axx-HG4D0chytx5JPIg\" \"https://one.zuora.com/api/integration/v1/download/transferbatchfile/10110\"\n" } ] } }, "/api/integration/v1/stage/error/{errortype}": { "get": { "tags": [ "Stage Error" ], "summary": "List staging errors", "description": "Gets the information about transaction staging errors or event staging errors.", "operationId": "GET_StaggingError", "parameters": [ { "name": "token", "in": "header", "description": "The valid authentication token that is generated by the Authentication operation.", "required": true, "schema": { "type": "string" } }, { "name": "errortype", "in": "path", "description": "The type of errors that you want to retrieve.", "required": true, "schema": { "type": "string", "enum": [ "transaction", "event" ] } } ], "responses": { "200": { "description": "Staging errors of the specified type are returned.", "content": { "application/json; charset=utf-8": { "schema": { "type": "object", "properties": { "Result": { "type": "array", "items": { "$ref": "#/components/schemas/stageError" } }, "status": { "type": "string", "description": "Response Status", "default": "Success" } } } } } }, "204": { "description": "No record is found for the error type specified in the path parameter.", "content": {} } }, "x-code-samples": [ { "lang": "Curl", "source": "curl -X GET --header \"token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6IlpJTkdBUEkiLCJpc3MiOiJSRVZQUk8gMy4wIFdlYnNlcnZpY2VzIiwicm9sZSI6IlJldnBybyBBUEkgUm9sZSIsImV4cCI6MTUwNDc0ODE4MywiaWF0IjoxNTA0NzQ2MzgzLCJuYmYiOjE1MDQ3NDYzODMsImNsaWVudG5hbWUiOiJEZWZhdWx0In0.k1usDPkgldj-OG9-ga-jn5B2Axx-HG4D0chytx5JPIg\" \"https://one.zuora.com/api/integration/v1/stage/error/transaction\"\n" } ] } }, "/api/integration/v1/upload/mapping": { "get": { "tags": [ "Adapter" ], "summary": "List upload field mappings", "description": "Gets the field mapping information in the upload template definitions for transactions, events, or bundle configuration from Zuora Revenue.", "operationId": "GET_FileUploadMapping", "parameters": [ { "name": "token", "in": "header", "description": "The valid authentication token that is generated by the Authentication operation.", "required": true, "schema": { "type": "string" } }, { "name": "templatename", "in": "query", "description": "Name of the upload template that contains the field mapping information.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Field mapping data is returned.", "content": { "application/json; charset=utf-8": { "schema": { "type": "object", "properties": { "Dateformat": { "type": "string", "description": "Response Status", "default": "DD-MON-YYYY" }, "Mapping": { "type": "array", "items": { "$ref": "#/components/schemas/uploadMapping" } } } } } } }, "400": { "description": "Error fetching the mapping details.", "content": {} } }, "x-code-samples": [ { "lang": "Curl", "source": "curl -X GET --header \"token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6IlpJTkdBUEkiLCJpc3MiOiJSRVZQUk8gMy4wIFdlYnNlcnZpY2VzIiwicm9sZSI6IlJldnBybyBBUEkgUm9sZSIsImV4cCI6MTUwNDc0ODE4MywiaWF0IjoxNTA0NzQ2MzgzLCJuYmYiOjE1MDQ3NDYzODMsImNsaWVudG5hbWUiOiJEZWZhdWx0In0.k1usDPkgldj-OG9-ga-jn5B2Axx-HG4D0chytx5JPIg\" \"https://one.zuora.com/api/integration/v1/upload/mapping?templatename=TEST\"\n" } ] } }, "/api/integration/v1/job/collection/template": { "post": { "tags": [ "Data Collection" ], "summary": "Submit data collection job", "description": "Submit a data collection job based on the specified RC template.\n\n\nAfter the data collection job is submitted, the following validations are applied:\n\n\n* The specified RC template name must be valid.\n* For multi-organization tenants, the the organization ID is required and must be valid.\n* If there are more than 2 data collection jobs in Running/Pending/Incompatible status for the specified organization, the API request will be rejected with error message returned.\n", "operationId": "POST_Collection", "requestBody": { "content": { "application/json; charset=utf-8": { "schema": { "$ref": "#/components/schemas/RevenueJobRequest" } } }, "required": true }, "responses": { "200": { "description": "The request is submitted successfully and the job ID is returned. You can use the returned ID to query the job status later.", "content": { "application/json; charset=utf-8": { "schema": { "$ref": "#/components/schemas/RevenueJobResponse" } } } }, "401": { "description": "The provided authentication token is invalid or the token has expired. Send the Authentication request again to get a new token.", "content": {} }, "403": { "description": "You are not authorized to access this endpoint. Please contact Zuora Revenue Support.", "content": {} } }, "x-codegen-request-body-name": "request" } }, "/api/integration/v1/job/collection/template/{job_id}": { "get": { "tags": [ "Data Collection" ], "summary": "Retrieve data collection job details", "description": "Get the status of the data collection job.", "operationId": "GET_CollectionDetails", "parameters": [ { "name": "job_id", "in": "path", "description": "The ID of the data collection job that you want to query. This is the ID that is returned when you submitted the data collection job.", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "The request is submitted successfully.", "content": { "application/json; charset=utf-8": { "schema": { "$ref": "#/components/schemas/RevenueJobDetail" } } } }, "401": { "description": "The provided authentication token has expired. Send the Authentication request again to get a new token.", "content": {} }, "403": { "description": "You are not authorized to access this endpoint. Please contact Zuora Revenue Support.", "content": {} } } } }, "/api/integration/v1/programs": { "get": { "tags": [ "Revenue Jobs" ], "summary": "List available programs and program parameters", "description": "Retrieves a list of programs that can be started with Revenue APIs and the program parameters that you can specify.\n", "operationId": "GET_ProgramDetails", "responses": { "200": { "description": "A list of available programs is returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProgramDetailsResponse" } } } }, "400": { "description": "The input parameter is invalid.", "content": {} } } } }, "/api/integration/v1/revenue-orgs": { "get": { "tags": [ "Revenue Jobs" ], "summary": "List available organizations", "description": "Retrieves the list of organizations that are set up in Zuora Revenue.\n", "operationId": "GET_RevenueOrgDetails", "responses": { "200": { "description": "A list of available organizations is returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProgramDetailsResponse" } } } }, "400": { "description": "The input parameter is invalid.", "content": {} } } } }, "/api/integration/v1/{orgId}/programs/{programId}/submit": { "post": { "tags": [ "Revenue Jobs" ], "summary": "Submit a program with specified parameters", "description": "Submits a program in Zuora Revenue and returns the job ID.\n", "operationId": "POST_SubmitRevenueJob", "parameters": [ { "name": "programId", "in": "path", "description": "The ID of the program that is to be submitted in Zuora Revenue. You can get the program ID by using the \"Get list of available programs and program parameters\" operation.", "required": true, "schema": { "type": "integer" } }, { "name": "orgId", "in": "path", "description": "The ID of the organization for which the program is to be submitted. You can get the organization ID by using the \"Get list of available organizations\" operation.", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "description": "An array that contains the parameter values to be used for the program. For each parameter, you need to specify the parameter ID, sequence, and desired value. \nYou can get the parameter name, ID, and sequence by using the \"Get list of available programs and program parameters\" operation.\n", "content": { "application/json; charset=utf-8": { "schema": { "$ref": "#/components/schemas/SubmitJobRequest" } } }, "required": true }, "responses": { "200": { "description": "The job status is returned with the job ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobStatusResponse" } } } }, "400": { "description": "The specified program is not supported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitJobFailureResponse" } } } }, "403": { "description": "The specified organization ID does not match the organization assigned to the current user role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitJobFailureResponse" } } } } }, "x-codegen-request-body-name": "data" } }, "/api/integration/v1/{orgId}/jobs/{jobId}": { "get": { "tags": [ "Revenue Jobs" ], "summary": "Retrieve the job status", "description": "Retrieves the status of a submitted job in Zuora Revenue.\n", "operationId": "GET_RevenueJobStatus", "parameters": [ { "name": "jobId", "in": "path", "description": "The ID of the job.", "required": true, "schema": { "type": "integer" } }, { "name": "orgId", "in": "path", "description": "The ID of the organization that is specified when the job is submitted.", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "The job status is returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobStatusResponse" } } } }, "400": { "description": "The input parameter is invalid.", "content": {} } } } }, "/api/integration/v2/biviews/{tmpl_name}": { "servers": [ { "url": "https://one.zuora.com", "description": "Zuora OneID production. Revenue Reporting paths start with /revenue/services/v1; Integration paths start with /api/integration/v1 or /api/integration/v2." } ], "get": { "security": [ { "OneIdOAuth": [] } ], "tags": [ "BI Views" ], "summary": "Retrieve BI View data (v2, paged)", "description": "Returns one page of BI View rows for a date range as CSV or gzip-compressed CSV. Page 1 starts a background task that writes all pages; the response carries a `continuation-token` header that you send to read pages 2, 3 and so on. Use POST with a `Fields` body to return only selected columns.\n\n**Purpose:** Extract large volumes of Zuora Revenue data (contracts, lines, schedules, bills, journal data) into a data warehouse or reconciliation process efficiently.\n\n**Notes:**\n\n- `fromDate` and `toDate` use `yyyy-MM-ddTHH:mm:ss` and filter on the view's incremental update date (`INCR_UPDT_DT`), so consecutive ranges give you incremental (changed-data) extracts.\n- Request `pagenum=1` first without a `continuation-token`. For every later page, send the token from the page 1 response. Increase `pagenum` until the response is `404` (\"This page will not exist\"), which also tells you the total pages and rows.\n- `pageSize` maximum: 10,000 rows for `csv` and 20,000 rows for `gzip` (your tenant may have lower limits).\n- `pagenum=0` returns `204 No Content`.\n- For `BI3_LINE_STAGE_HISTORY` and `BI3_EVENT_STAGE_HISTORY`, `fromDate` and `toDate` are optional when you filter by `batchId`. Always send `pagenum=1` (or higher); without it the response is `204`.\n- A later page can return `400` \"Page still not yet cached. Please retry.\" while the background task is still writing it. Wait a few seconds and retry; check the task with Get a BI View task if it keeps happening.\n- The default `gzip` output is returned with content type `application/gzip`; `csv` with `text/csv`.\n- Rows are limited to the organizations your role can access.", "operationId": "getBiViewDataV2", "parameters": [ { "name": "tmpl_name", "in": "path", "required": true, "description": "BI View API name. Standard views: `BI3_ACCT_TYPE`, `BI3_APPR_DTL`, `BI3_BOOK`, `BI3_CALENDAR`, `BI3_MJE`, `BI3_ORG`, `BI3_PERIODS`, `BI3_RC_BILL`, `BI3_RC_HEAD`, `BI3_RC_LNS`, `BI3_RC_LN_COST`, `BI3_RC_POB`, `BI3_RC_SCHD`, `BI3_RC_SCHD_DEL`, `BI3_RI_ACCT_SUMM`, `BI3_LINE_STAGE_HISTORY`, `BI3_EVENT_STAGE_HISTORY`, `BI3_CT_MOD_DETAIL`, `BI3_RC_LNS_VERSION`, `BI3_POB_ACTIONS`, `BI3_RC_CT_MOD_DET`, `BI3_RC_HOLD`. Custom views configured for your tenant are also accepted.", "schema": { "type": "string" }, "example": "BI3_RC_LNS" }, { "name": "fromDate", "in": "query", "required": true, "description": "Start of the date range, `yyyy-MM-ddTHH:mm:ss`.", "schema": { "type": "string" }, "example": "2026-09-01T00:00:00" }, { "name": "toDate", "in": "query", "required": true, "description": "End of the date range, `yyyy-MM-ddTHH:mm:ss`.", "schema": { "type": "string" }, "example": "2026-09-30T23:59:59" }, { "name": "pagenum", "in": "query", "required": true, "description": "Page to return, starting at 1.", "schema": { "type": "integer" }, "example": 1 }, { "name": "pageSize", "in": "query", "required": false, "description": "Rows per page.", "schema": { "type": "integer", "default": 1000 }, "example": 5000 }, { "name": "outputType", "in": "query", "required": false, "description": "Response format: `gzip` (gzip-compressed CSV) or `csv`.", "schema": { "type": "string", "default": "gzip", "enum": [ "gzip", "csv" ] }, "example": "csv" }, { "name": "max_pages", "in": "query", "required": false, "description": "Maximum number of pages the background task prepares.", "schema": { "type": "integer", "default": 1000 }, "example": 100 }, { "name": "add_record_count", "in": "query", "required": false, "description": "Send `true` to have the task count the rows first. Slower on large views. Omit the parameter to turn counting off: any non-empty value, including `false`, turns it on.", "schema": { "type": "boolean" }, "example": true }, { "name": "batchId", "in": "query", "required": false, "description": "Batch identifier. Used only by `BI3_LINE_STAGE_HISTORY` and `BI3_EVENT_STAGE_HISTORY`, where it replaces the date range filter.", "schema": { "type": "string" }, "example": "20260930001" }, { "name": "clientId", "in": "query", "required": false, "description": "Accepted for compatibility with v1. Not used by v2.", "schema": { "type": "integer" }, "example": 1 }, { "name": "continuation-token", "in": "header", "required": false, "description": "Task identifier returned in the `continuation-token` response header of page 1. Required for every page after the first.", "schema": { "type": "string" }, "example": "3f6c2d0a-8b1e-4f7a-9d2c-55e1a7b0c9f4" }, { "name": "Zuora-Track-Id", "in": "header", "required": false, "description": "Optional correlation identifier (up to 64 characters) that you choose. The Zuora One gateway records it; quote it to Zuora Support when you report a problem.", "schema": { "type": "string" }, "example": "close-run-2026-09-001" } ], "responses": { "200": { "$ref": "#/components/responses/Response2002" }, "204": { "$ref": "#/components/responses/NoContent" }, "400": { "$ref": "#/components/responses/BadRequest4" }, "401": { "$ref": "#/components/responses/Unauthorized2" }, "403": { "$ref": "#/components/responses/Forbidden2" }, "404": { "$ref": "#/components/responses/NotFound4" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError3" }, "502": { "$ref": "#/components/responses/BadGateway" } } }, "post": { "security": [ { "OneIdOAuth": [] } ], "tags": [ "BI Views" ], "summary": "Get BI View data (v2, paged) (POST)", "description": "Returns one page of BI View rows for a date range as CSV or gzip-compressed CSV. Page 1 starts a background task that writes all pages; the response carries a `continuation-token` header that you send to read pages 2, 3 and so on. Use POST with a `Fields` body to return only selected columns.\n\n**Purpose:** Extract large volumes of Zuora Revenue data (contracts, lines, schedules, bills, journal data) into a data warehouse or reconciliation process efficiently.\n\n**Notes:**\n\n- `fromDate` and `toDate` use `yyyy-MM-ddTHH:mm:ss` and filter on the view's incremental update date (`INCR_UPDT_DT`), so consecutive ranges give you incremental (changed-data) extracts.\n- Request `pagenum=1` first without a `continuation-token`. For every later page, send the token from the page 1 response. Increase `pagenum` until the response is `404` (\"This page will not exist\"), which also tells you the total pages and rows.\n- `pageSize` maximum: 10,000 rows for `csv` and 20,000 rows for `gzip` (your tenant may have lower limits).\n- `pagenum=0` returns `204 No Content`.\n- For `BI3_LINE_STAGE_HISTORY` and `BI3_EVENT_STAGE_HISTORY`, `fromDate` and `toDate` are optional when you filter by `batchId`. Always send `pagenum=1` (or higher); without it the response is `204`.\n- A later page can return `400` \"Page still not yet cached. Please retry.\" while the background task is still writing it. Wait a few seconds and retry; check the task with Get a BI View task if it keeps happening.\n- The default `gzip` output is returned with content type `application/gzip`; `csv` with `text/csv`.\n- Rows are limited to the organizations your role can access.", "operationId": "getBiViewDataV2Post", "parameters": [ { "name": "tmpl_name", "in": "path", "required": true, "description": "BI View API name. Standard views: `BI3_ACCT_TYPE`, `BI3_APPR_DTL`, `BI3_BOOK`, `BI3_CALENDAR`, `BI3_MJE`, `BI3_ORG`, `BI3_PERIODS`, `BI3_RC_BILL`, `BI3_RC_HEAD`, `BI3_RC_LNS`, `BI3_RC_LN_COST`, `BI3_RC_POB`, `BI3_RC_SCHD`, `BI3_RC_SCHD_DEL`, `BI3_RI_ACCT_SUMM`, `BI3_LINE_STAGE_HISTORY`, `BI3_EVENT_STAGE_HISTORY`, `BI3_CT_MOD_DETAIL`, `BI3_RC_LNS_VERSION`, `BI3_POB_ACTIONS`, `BI3_RC_CT_MOD_DET`, `BI3_RC_HOLD`. Custom views configured for your tenant are also accepted.", "schema": { "type": "string" }, "example": "BI3_RC_LNS" }, { "name": "fromDate", "in": "query", "required": true, "description": "Start of the date range, `yyyy-MM-ddTHH:mm:ss`.", "schema": { "type": "string" }, "example": "2026-09-01T00:00:00" }, { "name": "toDate", "in": "query", "required": true, "description": "End of the date range, `yyyy-MM-ddTHH:mm:ss`.", "schema": { "type": "string" }, "example": "2026-09-30T23:59:59" }, { "name": "pagenum", "in": "query", "required": true, "description": "Page to return, starting at 1.", "schema": { "type": "integer" }, "example": 1 }, { "name": "pageSize", "in": "query", "required": false, "description": "Rows per page.", "schema": { "type": "integer", "default": 1000 }, "example": 5000 }, { "name": "outputType", "in": "query", "required": false, "description": "Response format: `gzip` (gzip-compressed CSV) or `csv`.", "schema": { "type": "string", "default": "gzip", "enum": [ "gzip", "csv" ] }, "example": "csv" }, { "name": "max_pages", "in": "query", "required": false, "description": "Maximum number of pages the background task prepares.", "schema": { "type": "integer", "default": 1000 }, "example": 100 }, { "name": "add_record_count", "in": "query", "required": false, "description": "Send `true` to have the task count the rows first. Slower on large views. Omit the parameter to turn counting off: any non-empty value, including `false`, turns it on.", "schema": { "type": "boolean" }, "example": true }, { "name": "batchId", "in": "query", "required": false, "description": "Batch identifier. Used only by `BI3_LINE_STAGE_HISTORY` and `BI3_EVENT_STAGE_HISTORY`, where it replaces the date range filter.", "schema": { "type": "string" }, "example": "20260930001" }, { "name": "clientId", "in": "query", "required": false, "description": "Accepted for compatibility with v1. Not used by v2.", "schema": { "type": "integer" }, "example": 1 }, { "name": "continuation-token", "in": "header", "required": false, "description": "Task identifier returned in the `continuation-token` response header of page 1. Required for every page after the first.", "schema": { "type": "string" }, "example": "3f6c2d0a-8b1e-4f7a-9d2c-55e1a7b0c9f4" }, { "name": "Zuora-Track-Id", "in": "header", "required": false, "description": "Optional correlation identifier (up to 64 characters) that you choose. The Zuora One gateway records it; quote it to Zuora Support when you report a problem.", "schema": { "type": "string" }, "example": "close-run-2026-09-001" } ], "requestBody": { "required": false, "description": "POST only. Columns to return. Omit to return all columns.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BiViewFieldsRequest" }, { "type": "array", "items": { "type": "string" } } ] }, "examples": { "fields": { "summary": "Select three columns", "value": { "Fields": [ "RC_ID", "RC_NUM", "UPDT_DT" ] } }, "array": { "summary": "Plain array form", "value": [ "RC_ID", "RC_NUM", "UPDT_DT" ] } } } } }, "responses": { "200": { "$ref": "#/components/responses/Response2002" }, "204": { "$ref": "#/components/responses/NoContent" }, "400": { "$ref": "#/components/responses/BadRequest4" }, "401": { "$ref": "#/components/responses/Unauthorized2" }, "403": { "$ref": "#/components/responses/Forbidden2" }, "404": { "$ref": "#/components/responses/NotFound4" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError3" }, "502": { "$ref": "#/components/responses/BadGateway" } } } }, "/api/integration/v2/biviews/count/{tmpl_name}": { "servers": [ { "url": "https://one.zuora.com", "description": "Zuora One production. Revenue Reporting paths start with /revenue/services/v1; Integration paths start with /api/integration/v1 or /api/integration/v2." } ], "get": { "security": [ { "OneIdOAuth": [] } ], "tags": [ "BI Views" ], "summary": "Count BI View rows", "description": "Returns the number of rows in a BI View for a date range, limited to the organizations your role can access.\n\n**Purpose:** Size an extraction before you start it, choose a page size, and reconcile the rows you loaded.\n\n**Notes:**\n\n- Counting a large view over a wide range can take a while; narrow the date range where you can.", "operationId": "countBiViewRowsV2", "parameters": [ { "name": "tmpl_name", "in": "path", "required": true, "description": "BI View API name. Standard views: `BI3_ACCT_TYPE`, `BI3_APPR_DTL`, `BI3_BOOK`, `BI3_CALENDAR`, `BI3_MJE`, `BI3_ORG`, `BI3_PERIODS`, `BI3_RC_BILL`, `BI3_RC_HEAD`, `BI3_RC_LNS`, `BI3_RC_LN_COST`, `BI3_RC_POB`, `BI3_RC_SCHD`, `BI3_RC_SCHD_DEL`, `BI3_RI_ACCT_SUMM`, `BI3_LINE_STAGE_HISTORY`, `BI3_EVENT_STAGE_HISTORY`, `BI3_CT_MOD_DETAIL`, `BI3_RC_LNS_VERSION`, `BI3_POB_ACTIONS`, `BI3_RC_CT_MOD_DET`, `BI3_RC_HOLD`. Custom views configured for your tenant are also accepted.", "schema": { "type": "string" }, "example": "BI3_RC_LNS" }, { "name": "fromDate", "in": "query", "required": true, "description": "Start of the date range, `yyyy-MM-ddTHH:mm:ss`.", "schema": { "type": "string" }, "example": "2026-09-01T00:00:00" }, { "name": "toDate", "in": "query", "required": true, "description": "End of the date range, `yyyy-MM-ddTHH:mm:ss`.", "schema": { "type": "string" }, "example": "2026-09-30T23:59:59" }, { "name": "Zuora-Track-Id", "in": "header", "required": false, "description": "Optional correlation identifier (up to 64 characters) that you choose. The Zuora One gateway records it; quote it to Zuora Support when you report a problem.", "schema": { "type": "string" }, "example": "close-run-2026-09-001" } ], "responses": { "200": { "description": "The row count.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BiViewCount" }, "examples": { "count": { "summary": "Row count", "value": { "count": 12430 } } } } } }, "400": { "description": "A date is missing or invalid, the view name is unknown, or the count failed. Also returned when the database connection fails (retry with backoff).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RiaError" }, "examples": { "missingParam": { "summary": "toDate missing", "value": { "Status": "Error", "Message": "Mandatory field toDate is missing in path" } }, "badDate": { "summary": "Wrong date format", "value": { "Status": "Error", "Message": "Invalid date format 09/30/2026 for toDate" } }, "badView": { "$ref": "#/components/examples/BadView" }, "dbConnect": { "$ref": "#/components/examples/DbConnect" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized2" }, "403": { "$ref": "#/components/responses/Forbidden2" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError2" }, "502": { "$ref": "#/components/responses/BadGateway" } } } }, "/api/integration/v2/biviews/{tmpl_name}/describe-columns": { "servers": [ { "url": "https://one.zuora.com", "description": "Zuora One production. Revenue Reporting paths start with /revenue/services/v1; Integration paths start with /api/integration/v1 or /api/integration/v2." } ], "get": { "security": [ { "OneIdOAuth": [] } ], "tags": [ "BI Views" ], "summary": "List BI View columns", "description": "Returns the columns of a BI View with their data types and sizes.\n\n**Purpose:** Build target tables in your warehouse and choose the column names to send in a `Fields` list.", "operationId": "describeBiViewColumnsV2", "parameters": [ { "name": "tmpl_name", "in": "path", "required": true, "description": "BI View API name. Standard views: `BI3_ACCT_TYPE`, `BI3_APPR_DTL`, `BI3_BOOK`, `BI3_CALENDAR`, `BI3_MJE`, `BI3_ORG`, `BI3_PERIODS`, `BI3_RC_BILL`, `BI3_RC_HEAD`, `BI3_RC_LNS`, `BI3_RC_LN_COST`, `BI3_RC_POB`, `BI3_RC_SCHD`, `BI3_RC_SCHD_DEL`, `BI3_RI_ACCT_SUMM`, `BI3_LINE_STAGE_HISTORY`, `BI3_EVENT_STAGE_HISTORY`, `BI3_CT_MOD_DETAIL`, `BI3_RC_LNS_VERSION`, `BI3_POB_ACTIONS`, `BI3_RC_CT_MOD_DET`, `BI3_RC_HOLD`. Custom views configured for your tenant are also accepted.", "schema": { "type": "string" }, "example": "BI3_RC_HEAD" }, { "name": "Zuora-Track-Id", "in": "header", "required": false, "description": "Optional correlation identifier (up to 64 characters) that you choose. The Zuora One gateway records it; quote it to Zuora Support when you report a problem.", "schema": { "type": "string" }, "example": "close-run-2026-09-001" } ], "responses": { "200": { "description": "The columns of the view, as JSON text (served with content type `text/html`; parse the body as JSON).", "content": { "text/html": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BiViewColumn" } }, "examples": { "columns": { "summary": "Columns", "value": [ { "column_name": "RC_ID", "data_type": "NUMBER", "data_length": 22, "data_precision": null, "data_scale": null }, { "column_name": "RC_NUM", "data_type": "VARCHAR2", "data_length": 200, "data_precision": null, "data_scale": null }, { "column_name": "UPDT_DT", "data_type": "DATE", "data_length": 7, "data_precision": null, "data_scale": null } ] } } } } }, "204": { "description": "No column information is available for the view. No body." }, "400": { "description": "The view name is unknown. Also returned when the database connection fails (retry with backoff).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RiaError" }, "examples": { "badView": { "$ref": "#/components/examples/BadView" }, "dbConnect": { "$ref": "#/components/examples/DbConnect" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized2" }, "403": { "$ref": "#/components/responses/Forbidden2" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError2" }, "502": { "$ref": "#/components/responses/BadGateway" } } } }, "/api/integration/v2/biviews/report/{in_view_name}": { "servers": [ { "url": "https://one.zuora.com", "description": "Zuora One production. Revenue Reporting paths start with /revenue/services/v1; Integration paths start with /api/integration/v1 or /api/integration/v2." } ], "post": { "security": [ { "OneIdOAuth": [] } ], "tags": [ "BI Views" ], "summary": "Submit a BI View report", "description": "Submits a background job that writes the whole BI View for a date range to a report file. Returns the submission ID of the job.\n\n**Purpose:** Produce a complete extract as one file instead of paging through the data. When the file is ready, download it with *Get a signed URL*.\n\n**Notes:**\n\n- Dates use `DD-Mon-YYYY`, for example `01-Sep-2026` (different from the paged operations).\n- Poll *Get a report file by submission ID* with `report_id` until the file appears, then call *Get a signed URL*.", "operationId": "submitBiViewReport", "parameters": [ { "name": "in_view_name", "in": "path", "required": true, "description": "BI View API name. Standard views: `BI3_ACCT_TYPE`, `BI3_APPR_DTL`, `BI3_BOOK`, `BI3_CALENDAR`, `BI3_MJE`, `BI3_ORG`, `BI3_PERIODS`, `BI3_RC_BILL`, `BI3_RC_HEAD`, `BI3_RC_LNS`, `BI3_RC_LN_COST`, `BI3_RC_POB`, `BI3_RC_SCHD`, `BI3_RC_SCHD_DEL`, `BI3_RI_ACCT_SUMM`, `BI3_LINE_STAGE_HISTORY`, `BI3_EVENT_STAGE_HISTORY`, `BI3_CT_MOD_DETAIL`, `BI3_RC_LNS_VERSION`, `BI3_POB_ACTIONS`, `BI3_RC_CT_MOD_DET`, `BI3_RC_HOLD`. Custom views configured for your tenant are also accepted.", "schema": { "type": "string" }, "example": "BI3_RC_SCHD" }, { "name": "fromDate", "in": "query", "required": true, "description": "Start date, `DD-Mon-YYYY`.", "schema": { "type": "string" }, "example": "01-Sep-2026" }, { "name": "toDate", "in": "query", "required": true, "description": "End date, `DD-Mon-YYYY`.", "schema": { "type": "string" }, "example": "30-Sep-2026" }, { "name": "Zuora-Track-Id", "in": "header", "required": false, "description": "Optional correlation identifier (up to 64 characters) that you choose. The Zuora One gateway records it; quote it to Zuora Support when you report a problem.", "schema": { "type": "string" }, "example": "close-run-2026-09-001" } ], "responses": { "200": { "description": "The job was accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BiViewReportSubmitResponse" }, "examples": { "accepted": { "summary": "Job accepted", "value": { "success": true, "report_id": 482455 } } } } } }, "400": { "description": "A date is missing or invalid, the view name is unknown, or the job was rejected. Also returned when the database connection fails (retry with backoff).", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/RiaError" }, { "$ref": "#/components/schemas/BiViewReportSubmitResponse" } ] }, "examples": { "missingParam": { "$ref": "#/components/examples/MissingParam" }, "badDate": { "$ref": "#/components/examples/BadDate" }, "rejected": { "summary": "Job rejected", "value": { "success": false, "message": "Unable to submit" }, "description": "`message` holds the reason returned by Zuora Revenue, or `Unable to submit`." }, "badView": { "$ref": "#/components/examples/BadView" }, "dbConnect": { "$ref": "#/components/examples/DbConnect" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized2" }, "403": { "$ref": "#/components/responses/Forbidden2" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError2" }, "502": { "$ref": "#/components/responses/BadGateway" } } } }, "/api/integration/v1/biviews/{tmpl_name}": { "servers": [ { "url": "https://one.zuora.com", "description": "Zuora One production. Revenue Reporting paths start with /revenue/services/v1; Integration paths start with /api/integration/v1 or /api/integration/v2." } ], "get": { "security": [ { "OneIdOAuth": [] } ], "tags": [ "BI Views" ], "summary": "Retrieve BI View data (v1)", "description": "Returns BI View rows as CSV, one page per call, for a date range. Without a date range it returns the view's columns; with `count=true` it returns the row count; with `format=csv` and no dates it returns only the CSV header row. Use POST with a `Fields` body to select columns.\n\n**Purpose:** Existing integrations built on v1. New integrations should use the v2 operations, which handle large volumes better.\n\n**Notes:**\n\n- `clientId` is required and must match the client of your user (usually `1`).\n- `fromDate` and `toDate` use `yyyy-MM-ddTHH:mm:ss`; `toDate` must be later than `fromDate`.\n- Pages start at 1. Increase `pagenum` until the response is `204`.\n- `pagesize` (lowercase) accepts 1 to 10,000; other values fall back to 1,000.\n- When `Fields` are selected, the response headers `pagenum` (next page) and `record_count` (rows in this page) are added.\n- CSV rows are returned with content type `text/html`; read the body as CSV text.", "operationId": "getBiViewDataV1", "parameters": [ { "name": "tmpl_name", "in": "path", "required": true, "description": "BI View API name. Standard views: `BI3_ACCT_TYPE`, `BI3_APPR_DTL`, `BI3_BOOK`, `BI3_CALENDAR`, `BI3_MJE`, `BI3_ORG`, `BI3_PERIODS`, `BI3_RC_BILL`, `BI3_RC_HEAD`, `BI3_RC_LNS`, `BI3_RC_LN_COST`, `BI3_RC_POB`, `BI3_RC_SCHD`, `BI3_RC_SCHD_DEL`, `BI3_RI_ACCT_SUMM`, `BI3_LINE_STAGE_HISTORY`, `BI3_EVENT_STAGE_HISTORY`, `BI3_CT_MOD_DETAIL`, `BI3_RC_LNS_VERSION`, `BI3_POB_ACTIONS`, `BI3_RC_CT_MOD_DET`, `BI3_RC_HOLD`. Custom views configured for your tenant are also accepted.", "schema": { "type": "string" }, "example": "BI3_RC_HEAD" }, { "name": "clientId", "in": "query", "required": true, "description": "Zuora Revenue client ID of your user.", "schema": { "type": "integer" }, "example": 1 }, { "name": "fromDate", "in": "query", "required": false, "description": "Start of the date range, `yyyy-MM-ddTHH:mm:ss`.", "schema": { "type": "string" }, "example": "2026-09-01T00:00:00" }, { "name": "toDate", "in": "query", "required": false, "description": "End of the date range, `yyyy-MM-ddTHH:mm:ss`.", "schema": { "type": "string" }, "example": "2026-09-30T23:59:59" }, { "name": "pagenum", "in": "query", "required": false, "description": "Page to return, starting at 1.", "schema": { "type": "integer", "default": 1 }, "example": 1 }, { "name": "pagesize", "in": "query", "required": false, "description": "Rows per page, 1 to 10,000.", "schema": { "type": "integer", "default": 1000 }, "example": 1000 }, { "name": "count", "in": "query", "required": false, "description": "When `true` (with `fromDate` and `toDate`), return the row count instead of rows.", "schema": { "type": "boolean" }, "example": false }, { "name": "format", "in": "query", "required": false, "description": "With `csv` and no dates, return only the CSV header row.", "schema": { "type": "string", "enum": [ "csv" ] }, "example": "csv" }, { "name": "Zuora-Track-Id", "in": "header", "required": false, "description": "Optional correlation identifier (up to 64 characters) that you choose. The Zuora One gateway records it; quote it to Zuora Support when you report a problem.", "schema": { "type": "string" }, "example": "close-run-2026-09-001" } ], "responses": { "200": { "$ref": "#/components/responses/Response2003" }, "204": { "$ref": "#/components/responses/NoContent2" }, "400": { "$ref": "#/components/responses/BadRequest5" }, "401": { "$ref": "#/components/responses/Unauthorized2" }, "403": { "$ref": "#/components/responses/Forbidden2" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError4" }, "502": { "$ref": "#/components/responses/BadGateway" } } }, "post": { "security": [ { "OneIdOAuth": [] } ], "tags": [ "BI Views" ], "summary": "Get BI View data (v1) (POST)", "description": "Returns BI View rows as CSV, one page per call, for a date range. Without a date range it returns the view's columns; with `count=true` it returns the row count; with `format=csv` and no dates it returns only the CSV header row. Use POST with a `Fields` body to select columns.\n\n**Purpose:** Existing integrations built on v1. New integrations should use the v2 operations, which handle large volumes better.\n\n**Notes:**\n\n- `clientId` is required and must match the client of your user (usually `1`).\n- `fromDate` and `toDate` use `yyyy-MM-ddTHH:mm:ss`; `toDate` must be later than `fromDate`.\n- Pages start at 1. Increase `pagenum` until the response is `204`.\n- `pagesize` (lowercase) accepts 1 to 10,000; other values fall back to 1,000.\n- When `Fields` are selected, the response headers `pagenum` (next page) and `record_count` (rows in this page) are added.\n- CSV rows are returned with content type `text/html`; read the body as CSV text.", "operationId": "getBiViewDataV1Post", "parameters": [ { "name": "tmpl_name", "in": "path", "required": true, "description": "BI View API name. Standard views: `BI3_ACCT_TYPE`, `BI3_APPR_DTL`, `BI3_BOOK`, `BI3_CALENDAR`, `BI3_MJE`, `BI3_ORG`, `BI3_PERIODS`, `BI3_RC_BILL`, `BI3_RC_HEAD`, `BI3_RC_LNS`, `BI3_RC_LN_COST`, `BI3_RC_POB`, `BI3_RC_SCHD`, `BI3_RC_SCHD_DEL`, `BI3_RI_ACCT_SUMM`, `BI3_LINE_STAGE_HISTORY`, `BI3_EVENT_STAGE_HISTORY`, `BI3_CT_MOD_DETAIL`, `BI3_RC_LNS_VERSION`, `BI3_POB_ACTIONS`, `BI3_RC_CT_MOD_DET`, `BI3_RC_HOLD`. Custom views configured for your tenant are also accepted.", "schema": { "type": "string" }, "example": "BI3_RC_HEAD" }, { "name": "clientId", "in": "query", "required": true, "description": "Zuora Revenue client ID of your user.", "schema": { "type": "integer" }, "example": 1 }, { "name": "fromDate", "in": "query", "required": false, "description": "Start of the date range, `yyyy-MM-ddTHH:mm:ss`.", "schema": { "type": "string" }, "example": "2026-09-01T00:00:00" }, { "name": "toDate", "in": "query", "required": false, "description": "End of the date range, `yyyy-MM-ddTHH:mm:ss`.", "schema": { "type": "string" }, "example": "2026-09-30T23:59:59" }, { "name": "pagenum", "in": "query", "required": false, "description": "Page to return, starting at 1.", "schema": { "type": "integer", "default": 1 }, "example": 1 }, { "name": "pagesize", "in": "query", "required": false, "description": "Rows per page, 1 to 10,000.", "schema": { "type": "integer", "default": 1000 }, "example": 1000 }, { "name": "count", "in": "query", "required": false, "description": "When `true` (with `fromDate` and `toDate`), return the row count instead of rows.", "schema": { "type": "boolean" }, "example": false }, { "name": "format", "in": "query", "required": false, "description": "With `csv` and no dates, return only the CSV header row.", "schema": { "type": "string", "enum": [ "csv" ] }, "example": "csv" }, { "name": "Zuora-Track-Id", "in": "header", "required": false, "description": "Optional correlation identifier (up to 64 characters) that you choose. The Zuora One gateway records it; quote it to Zuora Support when you report a problem.", "schema": { "type": "string" }, "example": "close-run-2026-09-001" } ], "requestBody": { "required": false, "description": "POST only. Columns to return.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BiViewFieldsRequest" }, { "type": "array", "items": { "type": "string" } } ] }, "examples": { "fields": { "summary": "Select two columns", "value": { "Fields": [ "RC_ID", "RC_NUM" ] } } } } } }, "responses": { "200": { "$ref": "#/components/responses/Response2003" }, "204": { "$ref": "#/components/responses/NoContent2" }, "400": { "$ref": "#/components/responses/BadRequest5" }, "401": { "$ref": "#/components/responses/Unauthorized2" }, "403": { "$ref": "#/components/responses/Forbidden2" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError4" }, "502": { "$ref": "#/components/responses/BadGateway" } } } }, "/api/integration/v2/biviews-status": { "servers": [ { "url": "https://one.zuora.com", "description": "Zuora One production. Revenue Reporting paths start with /revenue/services/v1; Integration paths start with /api/integration/v1 or /api/integration/v2." } ], "get": { "security": [ { "OneIdOAuth": [] } ], "tags": [ "BI View Tasks" ], "summary": "List BI View tasks", "description": "Returns the tenant's background BI View tasks grouped into active, completed, stale and draining.\n\n**Purpose:** See which extractions are running before you start another one (each tenant has a query quota), and find stuck tasks to cancel.\n\n**Notes:**\n\n- A task is stale when it has reported no progress for 240 seconds (tenant-configurable).", "operationId": "listBiViewTasks", "parameters": [ { "name": "Zuora-Track-Id", "in": "header", "required": false, "description": "Optional correlation identifier (up to 64 characters) that you choose. The Zuora One gateway records it; quote it to Zuora Support when you report a problem.", "schema": { "type": "string" }, "example": "close-run-2026-09-001" } ], "responses": { "200": { "description": "Tasks grouped by state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BiViewTaskQueues" }, "examples": { "tasks": { "summary": "One active task", "value": { "active": [ { "task_id": "3f6c2d0a-8b1e-4f7a-9d2c-55e1a7b0c9f4", "status": "COMMITING-PAGE-3", "message": null, "metric": 1000, "accumulate": 3000, "query_config": { "object_name": "RPRO_BI3_RC_LNS_V", "filter_params": { "fromDate": "2026-09-01 00:00:00", "toDate": "2026-09-30 23:59:59" } }, "activity_tracker": { "initated_time": "2026-10-09T07:20:01.512000", "last_activity": "2026-10-09T07:21:44.008000", "elapsed_time": "0:00:03.112000" } } ], "completed": [], "stale": [], "draining": [] } } } } } }, "204": { "description": "The tenant has no tracked tasks. No body." }, "400": { "$ref": "#/components/responses/BadRequest6" }, "401": { "$ref": "#/components/responses/Unauthorized2" }, "403": { "$ref": "#/components/responses/Forbidden2" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError2" }, "502": { "$ref": "#/components/responses/BadGateway" } } } }, "/api/integration/v2/biviews-status/{task_id}": { "servers": [ { "url": "https://one.zuora.com", "description": "Zuora One production. Revenue Reporting paths start with /revenue/services/v1; Integration paths start with /api/integration/v1 or /api/integration/v2." } ], "get": { "security": [ { "OneIdOAuth": [] } ], "tags": [ "BI View Tasks" ], "summary": "Retrieve a BI View task", "description": "Returns the state of one background BI View task.\n\n**Purpose:** Track the progress of an extraction you started (the task ID is the `continuation-token`).", "operationId": "getBiViewTask", "parameters": [ { "name": "task_id", "in": "path", "required": true, "description": "Task identifier (the `continuation-token` value).", "schema": { "type": "string" }, "example": "3f6c2d0a-8b1e-4f7a-9d2c-55e1a7b0c9f4" }, { "name": "Zuora-Track-Id", "in": "header", "required": false, "description": "Optional correlation identifier (up to 64 characters) that you choose. The Zuora One gateway records it; quote it to Zuora Support when you report a problem.", "schema": { "type": "string" }, "example": "close-run-2026-09-001" } ], "responses": { "200": { "description": "The task.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BiViewTask" }, "examples": { "task": { "summary": "Task in progress", "value": { "task_id": "3f6c2d0a-8b1e-4f7a-9d2c-55e1a7b0c9f4", "status": "SCANNING-PAGE-4", "message": null, "metric": 1000, "accumulate": 3000, "query_config": { "object_name": "RPRO_BI3_RC_LNS_V", "filter_params": { "fromDate": "2026-09-01 00:00:00", "toDate": "2026-09-30 23:59:59" } }, "activity_tracker": { "initated_time": "2026-10-09T07:20:01.512000", "last_activity": "2026-10-09T07:22:10.330000", "elapsed_time": "0:00:01.870000" } } } } } } }, "204": { "$ref": "#/components/responses/NoContent3" }, "400": { "$ref": "#/components/responses/BadRequest6" }, "401": { "$ref": "#/components/responses/Unauthorized2" }, "403": { "$ref": "#/components/responses/Forbidden2" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError2" }, "502": { "$ref": "#/components/responses/BadGateway" } } }, "delete": { "security": [ { "OneIdOAuth": [] } ], "tags": [ "BI View Tasks" ], "summary": "Cancel a BI View task", "description": "Stops a background BI View task and marks it `CANCELLED`. Pages already written can no longer be relied on.\n\n**Purpose:** Free your tenant's query quota when an extraction was started by mistake or is stuck.\n\n**Notes:**\n\n- The stop request is sent even when the task details have expired; in that case the response is `204`.", "operationId": "cancelBiViewTask", "parameters": [ { "name": "task_id", "in": "path", "required": true, "description": "Task identifier (the `continuation-token` value).", "schema": { "type": "string" }, "example": "3f6c2d0a-8b1e-4f7a-9d2c-55e1a7b0c9f4" }, { "name": "Zuora-Track-Id", "in": "header", "required": false, "description": "Optional correlation identifier (up to 64 characters) that you choose. The Zuora One gateway records it; quote it to Zuora Support when you report a problem.", "schema": { "type": "string" }, "example": "close-run-2026-09-001" } ], "responses": { "200": { "description": "The task was cancelled. Returns its final state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BiViewTask" }, "examples": { "cancelled": { "summary": "Task cancelled", "value": { "task_id": "3f6c2d0a-8b1e-4f7a-9d2c-55e1a7b0c9f4", "status": "CANCELLED", "message": null, "metric": 1000, "accumulate": 4000, "query_config": { "object_name": "RPRO_BI3_RC_LNS_V", "filter_params": { "fromDate": "2026-09-01 00:00:00", "toDate": "2026-09-30 23:59:59" } }, "activity_tracker": { "initated_time": "2026-10-09T07:20:01.512000", "last_activity": "2026-10-09T07:23:00.101000", "elapsed_time": "0:00:00.004000" } } } } } } }, "204": { "$ref": "#/components/responses/NoContent3" }, "400": { "$ref": "#/components/responses/BadRequest6" }, "401": { "$ref": "#/components/responses/Unauthorized2" }, "403": { "$ref": "#/components/responses/Forbidden2" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError2" }, "502": { "$ref": "#/components/responses/BadGateway" } } } }, "/journal-entries/healthcheck": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Zuora Revenue API (base URL)" } ], "get": { "tags": [ "Service Health" ], "security": [ { "OneIdOAuth": [] } ], "summary": "Check service health", "description": "**Purpose**\n\nConfirms that the Manual Journal Entry API and the journal entry processing service behind it are reachable. Use it in monitoring or before a batch run.\n\n**When to use**\n\n* Before starting a batch load or an automated close job, to fail fast if the service is unavailable.\n* From monitoring or alerting tools that poll API availability.", "operationId": "checkJournalEntryServiceHealth", "responses": { "200": { "description": "Service is available", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthCheckResponse" }, "examples": { "serviceIsAvailable": { "summary": "Service is available", "value": { "success": true, "status": "UP", "target": "mje-backend" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenRead" }, "429": { "$ref": "#/components/responses/MjeTooManyRequests" }, "500": { "$ref": "#/components/responses/UnexpectedError" }, "502": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/journal-entries": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Zuora Revenue API (base URL)" } ], "post": { "tags": [ "Journal Entries" ], "security": [ { "OneIdOAuth": [] } ], "summary": "Create a journal entry", "description": "**Purpose**\n\nCreates a manual journal entry (header plus at least one line) in a single atomic call. Choose the request format:\n\n* **JSON** (`application/json`) - send `jeHeader` and `lines`.\n* **CSV upload** (`multipart/form-data`) - send the `lines` file part. Use a *combined* CSV (header section, blank line, lines section) or a *lines-only* CSV together with a `jeHeader` JSON part. Supplying the header in both places is rejected.\n\nAll mandatory fields are validated before anything is saved; if any check fails, nothing is created and every problem is reported in one message. The new entry starts in status `New` and is validated asynchronously - poll GET /journal-entries/{jeId}/validation-status, then submit it for approval.\n\n**When to use**\n\n* You need to record a new manual adjustment (reclass, accrual, correction) in Zuora Revenue from an external system.\n* Use **JSON** when your integration builds entries programmatically; use **CSV upload** when users prepare entries in a spreadsheet or when migrating many lines at once.\n* Do not use it to change an existing entry - use PATCH /journal-entries/{jeId}; to repeat an existing entry use POST /journal-entries/{jeId}/copy.", "operationId": "createJournalEntry", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional client-generated unique key (for example a UUID). Accepted for forward compatibility; **not currently enforced** - the service does not de-duplicate retries, so do not rely on it to prevent duplicate entries.", "schema": { "type": "string" }, "example": "6f1c2c3e-0b7a-4d1e-9a51-1f1e2a3b4c5d" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateJournalEntryRequest" }, "examples": { "balancedReclass": { "summary": "Balanced two-line reclass", "value": { "jeHeader": { "name": "SEP-2026 Revenue Reclass", "description": "Reclass deferred revenue for contract RC-1001", "bookId": 1, "orgId": "101", "periodId": 202609, "categoryCode": "RECLASS", "sobId": 1, "functionalCurrency": "USD", "exchangeRateType": "User", "accountMethod": "Standard", "glTransfer": "Yes", "approvalCurrency": "USD" }, "lines": [ { "jeSetNo": 1, "accountType": "Contract Liability", "accountCode": "2400-100-000", "currency": "USD", "drAmount": 1500, "exchangeRate": 1, "gexchangeRate": 1, "exchangeRateDate": "2026-09-30", "startDate": "2026-09-01", "endDate": "2026-09-30", "rcId": 1001, "soNum": "SO-50012", "soLineId": "SO-50012-1", "description": "Release deferred revenue", "reference1": "TCK-4471" }, { "jeSetNo": 1, "accountType": "Revenue", "accountCode": "4000-100-000", "currency": "USD", "crAmount": 1500, "exchangeRate": 1, "gexchangeRate": 1, "exchangeRateDate": "2026-09-30", "startDate": "2026-09-01", "endDate": "2026-09-30", "rcId": 1001, "soNum": "SO-50012", "soLineId": "SO-50012-1", "description": "Recognize revenue", "reference1": "TCK-4471" } ] } } } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CreateJournalEntryMultipartRequest" }, "examples": { "combinedCsv": { "summary": "Combined CSV (header + lines in one file)", "value": { "lines": "Name,Description,Category Code,Ex Rate Type,Period Name,Reversal Period Name,SOB Name,SOB ID,Functional Currency,Book Id,Org Id,GL Transfer,Rev Rec Type,Account Method,Approval Currency\nSEP-2026 Revenue Reclass,Reclass deferred revenue,RECLASS,User,202609,,,1,USD,1,101,Yes,,Standard,USD\n\nSet No,Account Type,Account Code,Currency,Debit,Credit,Ex Rate Date,Ex Rate,G Ex Rate,Start Date,End Date,RC Id,SO Number,Description\n1,Contract Liability,2400-100-000,USD,1500.00,,2026-09-30,1,1,2026-09-01,2026-09-30,1001,SO-50012,Release deferred revenue\n1,Revenue,4000-100-000,USD,,1500.00,2026-09-30,1,1,2026-09-01,2026-09-30,1001,SO-50012,Recognize revenue\n" } } }, "encoding": { "jeHeader": { "contentType": "application/json" }, "lines": { "contentType": "text/csv" } } } } }, "responses": { "201": { "description": "Journal entry created", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JournalEntryResponse" }, "examples": { "journalEntryCreated": { "summary": "Journal entry created", "value": { "success": true, "id": 10045, "name": "SEP-2026 Revenue Reclass", "status": "New", "description": "Reclass deferred revenue for contract RC-1001", "waterfallStatus": "NEW", "jeHeader": { "id": 10045, "name": "SEP-2026 Revenue Reclass", "description": "Reclass deferred revenue for contract RC-1001", "categoryCode": "RECLASS", "exchangeRateType": "User", "sobId": 1, "sobName": "US Primary SOB", "functionalCurrency": "USD", "periodId": 202609, "clientId": 1, "orgId": "101", "bookId": 1, "accountMethod": "Standard", "status": "New", "approvalCurrency": "USD", "glTransfer": "Yes", "waterfallStatus": "NEW", "createdBy": "jane.doe@example.com", "createdDate": "2026-09-28T10:21:04.000+00:00", "updatedBy": "jane.doe@example.com", "updatedDate": "2026-09-28T10:21:04.000+00:00" } } } } } } }, "400": { "description": "Missing required fields; Invalid values; Unknown Set of Books; Invalid CSV; Header supplied twice", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missingRequiredFields": { "summary": "Missing required fields", "description": "One or more mandatory header or line fields are missing. All missing fields are listed in one message.", "value": { "success": false, "reasons": [ { "code": "MISSING_REQUIRED_FIELD", "message": "Missing required fields: categoryCode; line 2, exchangeRateDate; line 2, at least one of drAmount or crAmount is required" } ] } }, "invalidValues": { "summary": "Invalid values", "description": "All mandatory fields are present but a value breaks a rule, for example an exchange rate of 0 or an end date before the start date.", "value": { "success": false, "reasons": [ { "code": "INVALID_VALUE", "message": "Invalid values: line 1, exchangeRate: must be a number greater than 0; line 1, endDate must be on or after startDate" } ] } }, "unknownSetOfBooks": { "summary": "Unknown Set of Books", "description": "`sobId` does not match any Set of Books in your tenant.", "value": { "success": false, "reasons": [ { "code": "INVALID_VALUE", "message": "sobId: no set of books found with id 99", "field": "sobId" } ] } }, "invalidCsv": { "summary": "Invalid CSV", "description": "(CSV upload) The file is empty, the layout is wrong, a column is duplicated, or a cell cannot be parsed. Every problem is listed.", "value": { "success": false, "reasons": [ { "code": "INVALID_CSV", "message": "CSV validation failed: Row 2, Debit: must be non-negative, got '-1500'; Row 3, Ex Rate: not a valid number 'one'" } ] } }, "headerSuppliedTwice": { "summary": "Header supplied twice", "description": "(CSV upload) The CSV contains a header section **and** a `jeHeader` part was sent.", "value": { "success": false, "reasons": [ { "code": "CONFLICTING_HEADER", "message": "Journal entry header supplied both as the 'jeHeader' part and in the CSV header section; supply only one", "field": "jeHeader" } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenEdit" }, "429": { "$ref": "#/components/responses/MjeTooManyRequests" }, "500": { "$ref": "#/components/responses/UnexpectedError" }, "502": { "description": "Entry rejected by journal entry processing; Journal entry service unavailable", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "entryRejectedByJournalEntryProcessing": { "summary": "Entry rejected by journal entry processing", "description": "The journal entry processing service rejected the entry, for example because the period is closed or soft-frozen, or a value (account code, category, currency) is not valid in your tenant. `reasons[0].code` carries the processing status and `message` the detail.", "value": { "success": false, "reasons": [ { "code": "500 INTERNAL_SERVER_ERROR", "message": "500 Internal Server Error: \"Period is not open for the given book and org\"" } ] } }, "journalEntryServiceUnavailable": { "$ref": "#/components/examples/ServiceUnavailable" } } } } } } }, "get": { "tags": [ "Journal Entries" ], "security": [ { "OneIdOAuth": [] } ], "summary": "List journal entries", "description": "**Purpose**\n\nReturns a page of journal entries visible to the caller. Supports filtering, sorting, field selection and page-based pagination.\n\n**When to use**\n\n* Build a work list or dashboard of entries, for example all `New` entries for this period or everything waiting for approval.\n* Reconcile during close: find entries by status, category, creator or date and page through the results.\n* Use POST /journal-entries/query instead when the filter is long or needs several values in an `IN` list.\n\n**Notes**\n\n* `periodId` and `reversalPeriodId` in list results contain the period **name** (for example `SEP-2026`), and filters on them compare against the name: `filter=periodId.EQ:SEP-2026`.\n* With `fields`, date-time properties are returned as epoch milliseconds instead of formatted strings.\n* `fields` names must match the response property names, so use `exRateType` (not `exchangeRateType`) in `fields`, while `filter` and `sort` use `exchangeRateType`.\n* Multi-value `IN` lists: when the request has only one `filter` parameter, commas inside its value are treated as list separators. To filter on several values reliably, add a second `filter` parameter or use POST /journal-entries/query.", "operationId": "listJournalEntries", "parameters": [ { "name": "filter", "in": "query", "required": false, "description": "Filter clause in the form `field.OPERATOR:value`. Repeat the parameter to combine clauses with AND. Operators: `EQ` (equals), `NE` (not equals), `LT`, `GT`, `LE`, `GE` (comparisons for numbers and dates), `SW` (starts with) and `IN` (any of a list: `field.IN:[v1,v2]`). Values are not quoted. Allowed fields for journal entries: `approverName`, `categoryCode`, `createdBy`, `createdDate`, `description`, `exchangeRateType`, `functionalCurrency`, `hashTotal`, `id`, `name`, `periodId`, `reversalPeriodId`, `reversalStatus`, `sobId`, `sobName`, `status`, `updatedBy`, `updatedDate`. Unknown fields return 400 `INVALID_VALUE`.", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true, "example": [ "status.EQ:New" ] }, { "name": "sort", "in": "query", "required": false, "description": "Sort clause `field.ASC` or `field.DESC`. Only the first sort clause is applied. Uses the same field names as `filter`.", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true, "example": [ "createdDate.DESC" ] }, { "name": "fields", "in": "query", "required": false, "description": "Comma-separated list of properties to return for each record (the `id` property is always returned). Names must match the response property names exactly. When supplied, each record contains only these properties. Unknown names return 400 `INVALID_VALUE`.", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": false, "example": [ "name", "status" ] }, { "name": "expand", "in": "query", "required": false, "description": "Reserved for future use; currently ignored.", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": false }, { "name": "pageSize", "in": "query", "required": false, "description": "Number of records per page. Defaults to 20. Values above 40 are reduced to 40.", "schema": { "type": "integer", "format": "int32", "default": 20 }, "example": 20 }, { "name": "cursor", "in": "query", "required": false, "description": "Page to return. Use the 1-based page number (`1`, `2`, ...). Defaults to the first page. A non-numeric or non-positive value returns 400 `INVALID_VALUE`.", "schema": { "type": "string" }, "example": "2" } ], "responses": { "200": { "description": "Page of journal entries", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JournalEntryListPage" }, "examples": { "pageOfJournalEntries": { "summary": "Page of journal entries", "value": { "pageNumber": 1, "pageSize": 20, "totalRecords": 2, "result": [ { "id": 10045, "name": "SEP-2026 Revenue Reclass", "description": "Reclass deferred revenue for contract RC-1001", "reversalStatus": "", "categoryCode": "RECLASS", "exRateType": "User", "periodId": "SEP-2026", "status": "New", "reversalPeriodId": "OCT-2026", "hashTotal": 3000, "sobName": "US Primary SOB", "sobId": 1, "functionalCurrency": "USD", "createdBy": "jane.doe@example.com", "createdDate": "2026-09-28 10:21:04", "updatedBy": "jane.doe@example.com", "updatedDate": "2026-09-28 10:21:04", "approverName": null, "bookId": 1, "secAtrVal": "101" }, { "id": 10046, "name": "SEP-2026 Accrual", "description": "Reclass deferred revenue for contract RC-1001", "reversalStatus": "", "categoryCode": "ACCRUAL", "exRateType": "User", "periodId": "SEP-2026", "status": "Validated", "reversalPeriodId": "OCT-2026", "hashTotal": 840, "sobName": "US Primary SOB", "sobId": 1, "functionalCurrency": "USD", "createdBy": "jane.doe@example.com", "createdDate": "2026-09-28 10:21:04", "updatedBy": "jane.doe@example.com", "updatedDate": "2026-09-28 10:21:04", "approverName": null, "bookId": 1, "secAtrVal": "101" } ] } }, "projected": { "summary": "With `fields=name,status`", "value": { "pageNumber": 1, "pageSize": 20, "totalRecords": 2, "result": [ { "id": 10045, "name": "SEP-2026 Revenue Reclass", "status": "New" }, { "id": 10046, "name": "SEP-2026 Accrual", "status": "Validated" } ] } } } } } }, "400": { "description": "Unknown filter field; Unsupported operator; Invalid cursor", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unknownFilterField": { "summary": "Unknown filter field", "description": "`filter` or `sort` names a field that is not in the allowed list.", "value": { "success": false, "reasons": [ { "code": "INVALID_VALUE", "message": "Unknown field 'state'. Allowed fields: approverName, categoryCode, createdBy, createdDate, description, exchangeRateType, functionalCurrency, hashTotal, id, name, periodId, reversalPeriodId, reversalStatus, sobId, sobName, status, updatedBy, updatedDate" } ] } }, "unsupportedOperator": { "summary": "Unsupported operator", "description": "The filter operator is not one of EQ, NE, LT, GT, LE, GE, SW, IN.", "value": { "success": false, "reasons": [ { "code": "INVALID_VALUE", "message": "Unsupported filter operator 'CONTAINS' in 'name.CONTAINS:Reclass'" } ] } }, "invalidCursor": { "summary": "Invalid cursor", "description": "`cursor` is not a number (a value below 1 returns *Invalid cursor '0': must be a positive page number*).", "value": { "success": false, "reasons": [ { "code": "INVALID_VALUE", "message": "Invalid cursor 'abc': not a valid page reference" } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenRead" }, "429": { "$ref": "#/components/responses/MjeTooManyRequests" }, "500": { "$ref": "#/components/responses/UnexpectedError" }, "502": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/journal-entries/query": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Zuora Revenue API (base URL)" } ], "post": { "tags": [ "Journal Entries" ], "security": [ { "OneIdOAuth": [] } ], "summary": "Search journal entries (filter in body)", "description": "**Purpose**\n\nSame result as GET /journal-entries, but the filter, sort and page criteria are sent in the request body. Use it for long filters that would exceed URL length limits or for multi-value `IN` filters.\n\n**When to use**\n\n* Your filter is too long for a URL, or you need multi-value `IN` / `NOT IN` filters.\n* You prefer to send search criteria as JSON (for example from a reporting tool) rather than as query parameters.\n\n**Notes**\n\n* Body filter `fieldName` values are passed through as-is and must be one of: `id`, `name`, `description`, `reversalStatus`, `categoryCode`, `exRateType`, `periodId`, `status`, `reversalPeriodId`, `hashTotal`, `sobName`, `sobId`, `functionalCurrency`, `createdBy`, `createdDate`, `updatedBy`, `updatedDate`, `approverName`.\n* `values` must contain at least one element for every operator (including `IS NULL` / `IS NOT NULL`).\n* Filters on `periodId` / `reversalPeriodId` compare against the period **name** (for example `SEP-2026`).\n* `pageNumber` defaults to 1 and `pageSize` to 20 when omitted; `pageSize` above 40 is reduced to 40.\n* Use `IN` / `NOT IN` for text comparisons; other operators compare values as-is and are intended for numeric and date fields.", "operationId": "queryJournalEntries", "parameters": [ { "name": "fields", "in": "query", "required": false, "description": "Comma-separated list of properties to return for each record (`id` is always returned).", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": false, "example": [ "name", "status" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryRequest" }, "examples": { "openEntries": { "summary": "New or validated entries posted to SEP-2026", "value": { "pageNumber": 1, "pageSize": 20, "filters": [ { "fieldName": "status", "operator": "IN", "values": [ "New", "Validated" ] }, { "fieldName": "periodId", "operator": "IN", "values": [ "SEP-2026" ] } ], "ordering": { "fieldName": "createdDate", "orderBy": "DESC" } } } } } } }, "responses": { "200": { "description": "Page of journal entries", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JournalEntryListPage" }, "examples": { "pageOfJournalEntries": { "summary": "Page of journal entries", "value": { "pageNumber": 1, "pageSize": 20, "totalRecords": 2, "result": [ { "id": 10045, "name": "SEP-2026 Revenue Reclass", "description": "Reclass deferred revenue for contract RC-1001", "reversalStatus": "", "categoryCode": "RECLASS", "exRateType": "User", "periodId": "SEP-2026", "status": "New", "reversalPeriodId": "OCT-2026", "hashTotal": 3000, "sobName": "US Primary SOB", "sobId": 1, "functionalCurrency": "USD", "createdBy": "jane.doe@example.com", "createdDate": "2026-09-28 10:21:04", "updatedBy": "jane.doe@example.com", "updatedDate": "2026-09-28 10:21:04", "approverName": null, "bookId": 1, "secAtrVal": "101" }, { "id": 10046, "name": "SEP-2026 Accrual", "description": "Reclass deferred revenue for contract RC-1001", "reversalStatus": "", "categoryCode": "ACCRUAL", "exRateType": "User", "periodId": "SEP-2026", "status": "Validated", "reversalPeriodId": "OCT-2026", "hashTotal": 840, "sobName": "US Primary SOB", "sobId": 1, "functionalCurrency": "USD", "createdBy": "jane.doe@example.com", "createdDate": "2026-09-28 10:21:04", "updatedBy": "jane.doe@example.com", "updatedDate": "2026-09-28 10:21:04", "approverName": null, "bookId": 1, "secAtrVal": "101" } ] } } } } } }, "400": { "description": "Unknown projection field", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unknownProjectionField": { "summary": "Unknown projection field", "description": "A name in `fields` is not a property of the list item.", "value": { "success": false, "reasons": [ { "code": "INVALID_VALUE", "message": "Unknown field 'foo'. Available fields: [id, name, description, ...]" } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenEdit" }, "429": { "$ref": "#/components/responses/MjeTooManyRequests" }, "500": { "$ref": "#/components/responses/UnexpectedError" }, "502": { "description": "Invalid filter field or operator; Journal entry service unavailable", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalidFilterFieldOrOperator": { "summary": "Invalid filter field or operator", "description": "A `fieldName` or `operator` in the body is not one of the supported values, or `values` is empty.", "value": { "success": false, "reasons": [ { "code": "500 INTERNAL_SERVER_ERROR", "message": "500 Internal Server Error: [no body]" } ] } }, "journalEntryServiceUnavailable": { "$ref": "#/components/examples/ServiceUnavailable" } } } } } } } }, "/journal-entries/{jeId}": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Zuora Revenue API (base URL)" } ], "get": { "tags": [ "Journal Entries" ], "security": [ { "OneIdOAuth": [] } ], "summary": "Retrieve a journal entry", "description": "**Purpose**\n\nReturns the full header of one journal entry, including status, waterfall status, error count and validation messages. Use GET /journal-entries/{jeId}/lines to read its lines.\n\n**When to use**\n\n* You know the `jeId` and need the entry's current status, waterfall status, error count or validation messages.\n* After create, update or a workflow action, to confirm the resulting state.\n* Use `fields` when you only need a few properties (for example `status` while polling).\n\n**Notes**\n\n* With `fields`, date-time properties (for example `createdDate`) are returned as epoch milliseconds.", "operationId": "getJournalEntry", "parameters": [ { "name": "jeId", "in": "path", "required": true, "description": "ID of the journal entry.", "schema": { "type": "integer", "format": "int64" }, "example": 10045 }, { "name": "fields", "in": "query", "required": false, "description": "Comma-separated list of header properties to return. When supplied, the response is a flat object containing only `id` and the requested header properties (no `success` / `jeHeader` wrapper).", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": false, "example": [ "name", "status", "waterfallStatus" ] } ], "responses": { "200": { "description": "Journal entry", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/JournalEntryResponse" }, { "type": "object", "description": "Projected header (when `fields` is supplied): `id` plus the requested properties.", "additionalProperties": true } ] }, "examples": { "journalEntry": { "summary": "Journal entry", "value": { "success": true, "id": 10045, "name": "SEP-2026 Revenue Reclass", "status": "New", "description": "Reclass deferred revenue for contract RC-1001", "waterfallStatus": "NEW", "jeHeader": { "id": 10045, "name": "SEP-2026 Revenue Reclass", "description": "Reclass deferred revenue for contract RC-1001", "categoryCode": "RECLASS", "exchangeRateType": "User", "sobId": 1, "sobName": "US Primary SOB", "functionalCurrency": "USD", "periodId": 202609, "periodDisplayValue": "SEP-2026", "clientId": 1, "orgId": "101", "orgName": "US Operations", "bookId": 1, "bookName": "Primary Book", "accountMethod": "Standard", "revRecType": "STANDARD", "status": "New", "jeStatus": "New", "approvalCurrency": "USD", "glTransfer": "Yes", "waterfallStatus": "NEW", "jeWaterfallStatus": "NEW", "jeTempWaterfallStatus": "NEW", "reversalStatus": "", "errorCount": 0, "errorMessages": [], "createdBy": "jane.doe@example.com", "createdDate": "2026-09-28T10:21:04.000+00:00", "updatedBy": "jane.doe@example.com", "updatedDate": "2026-09-28T10:21:04.000+00:00" } } }, "projected": { "summary": "With `fields=name,status,waterfallStatus`", "value": { "id": 10045, "name": "SEP-2026 Revenue Reclass", "status": "New", "waterfallStatus": "NEW" } } } } } }, "400": { "description": "Unknown projection field", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unknownProjectionField": { "summary": "Unknown projection field", "description": "A name in `fields` is not a header property.", "value": { "success": false, "reasons": [ { "code": "INVALID_VALUE", "message": "Unknown field 'state'. Available fields: [id, name, description, categoryCode, ...]" } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenRead" }, "429": { "$ref": "#/components/responses/MjeTooManyRequests" }, "500": { "description": "Journal entry not found; Unexpected error", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "journalEntryNotFound": { "summary": "Journal entry not found", "description": "No journal entry with this ID exists, or it belongs to an organization not assigned to your role.", "value": { "success": false, "reasons": [ { "code": "SystemError", "message": "internal server error" } ] } }, "unexpectedError": { "$ref": "#/components/examples/UnexpectedError" } } } } }, "502": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "patch": { "tags": [ "Journal Entries" ], "security": [ { "OneIdOAuth": [] } ], "summary": "Update a journal entry", "description": "**Purpose**\n\nUpdates a journal entry that is still editable (for example `New`, `Validated`, `Error` or `Rejected`). Two request formats:\n\n* **JSON** (`application/json`) - partial header update. Send only the fields to change; lines are not touched.\n* **CSV full-file update** (`multipart/form-data`) - the `lines` file is the **complete** new set of lines. Rows whose `ID` column matches an existing line are updated, other rows are inserted, and existing lines missing from the file are **deleted**. Header changes may be sent in an optional CSV header section or a `jeHeader` JSON part (not both). The file must contain at least one line.\n\nAfter an update the entry is re-validated and the preview waterfall is regenerated.\n\n**When to use**\n\n* Correct an entry that failed validation or was rejected, before (re)submitting it.\n* Use **JSON** to change header values only (name, period, category, description...).\n* Use **CSV full-file update** to replace the entry's lines in one atomic operation (edit, add and remove lines together).\n* Not possible once the entry is `Approval Pending` or `Approved` - recall it first, or reverse an approved entry.\n\n**Notes**\n\n* Full-file CSV update: a row whose `ID` is blank **or does not match an existing line of this entry** is inserted as a new line, and every existing line not matched is deleted. The lines export (POST /{jeId}/lines/export) does **not** include an `ID` column - add an `ID` column with the line IDs from GET /journal-entries/{jeId}/lines before re-uploading, otherwise all lines are replaced.\n* Reference columns must be titled `Reference1` ... `Reference15` on upload; tenant-specific labels used in the template or export (for example *Ticket Number*) are not recognized and their values are ignored.\n* A JSON header update is checked by journal entry processing, not by the up-front field validation used on create.", "operationId": "updateJournalEntry", "parameters": [ { "name": "jeId", "in": "path", "required": true, "description": "ID of the journal entry.", "schema": { "type": "integer", "format": "int64" }, "example": 10045 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateJournalEntryRequest" }, "examples": { "renameAndMove": { "summary": "Rename and move to another period", "value": { "name": "SEP-2026 Revenue Reclass v2", "periodId": 202609, "description": "Corrected amounts" } } } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/UpdateJournalEntryMultipartRequest" }, "examples": { "fullFile": { "summary": "Lines-only full file: update line 70001, insert a new line, delete all others", "value": { "lines": "ID,Set No,Account Type,Account Code,Currency,Debit,Credit,Ex Rate Date,Ex Rate,G Ex Rate,Start Date,End Date\n70001,1,Contract Liability,2400-100-000,USD,1200.00,,2026-09-30,1,1,2026-09-01,2026-09-30\n,1,Revenue,4000-100-000,USD,,1200.00,2026-09-30,1,1,2026-09-01,2026-09-30\n" } } }, "encoding": { "jeHeader": { "contentType": "application/json" }, "lines": { "contentType": "text/csv" } } } } }, "responses": { "200": { "description": "Journal entry updated", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JournalEntryUpdateResponse" }, "examples": { "journalEntryUpdated": { "summary": "Journal entry updated", "value": { "id": 10045, "status": "New", "waterfallStatus": "IN PROGRESS" } } } } } }, "400": { "description": "Invalid CSV or line values; Unknown Set of Books", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalidCsvOrLineValues": { "summary": "Invalid CSV or line values", "description": "(CSV) The file cannot be parsed, has no lines, or an inserted/updated line is missing a mandatory value.", "value": { "success": false, "reasons": [ { "code": "MISSING_REQUIRED_FIELD", "message": "Missing required fields: line 2, accountCode" } ] } }, "unknownSetOfBooks": { "summary": "Unknown Set of Books", "description": "`sobId` was supplied but does not match a Set of Books.", "value": { "success": false, "reasons": [ { "code": "INVALID_VALUE", "message": "sobId: no set of books found with id 99", "field": "sobId" } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenEdit" }, "429": { "$ref": "#/components/responses/MjeTooManyRequests" }, "500": { "$ref": "#/components/responses/UnexpectedError" }, "502": { "description": "Entry cannot be edited; Journal entry service unavailable", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "entryCannotBeEdited": { "summary": "Entry cannot be edited", "description": "The entry's status does not allow editing (for example it is `Approval Pending` or `Approved`), or your role cannot edit it.", "value": { "success": false, "reasons": [ { "code": "500 INTERNAL_SERVER_ERROR", "message": "500 Internal Server Error: \"Not Allowed .Please check the object status and your role\"" } ] } }, "journalEntryServiceUnavailable": { "$ref": "#/components/examples/ServiceUnavailable" } } } } } } }, "delete": { "tags": [ "Journal Entries" ], "security": [ { "OneIdOAuth": [] } ], "summary": "Delete a journal entry", "description": "**Purpose**\n\nPermanently deletes a journal entry together with its lines and preview schedules. Only entries that have not been approved can be deleted, and only by a caller whose role allows it. To delete several entries at once use POST /journal-entries/bulk-delete.\n\n**When to use**\n\n* Discard a single entry that was created by mistake or is no longer needed, before it is approved.\n* Use POST /journal-entries/bulk-delete to remove several entries in one call.", "operationId": "deleteJournalEntry", "parameters": [ { "name": "jeId", "in": "path", "required": true, "description": "ID of the journal entry.", "schema": { "type": "integer", "format": "int64" }, "example": 10045 } ], "responses": { "204": { "description": "Journal entry deleted (no response body)", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenEdit" }, "429": { "$ref": "#/components/responses/MjeTooManyRequests" }, "500": { "$ref": "#/components/responses/UnexpectedError" }, "502": { "description": "Delete not allowed; Journal entry service unavailable", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "deleteNotAllowed": { "summary": "Delete not allowed", "description": "The entry's status (for example `Approved` or `Approval Pending`) or your role does not allow deletion.", "value": { "success": false, "reasons": [ { "code": "500 INTERNAL_SERVER_ERROR", "message": "500 Internal Server Error: \"Not Allowed .Please check the object status and your role\"" } ] } }, "journalEntryServiceUnavailable": { "$ref": "#/components/examples/ServiceUnavailable" } } } } } } } }, "/journal-entries/{jeId}/copy": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Zuora Revenue API (base URL)" } ], "post": { "tags": [ "Journal Entries" ], "security": [ { "OneIdOAuth": [] } ], "summary": "Copy a journal entry", "description": "**Purpose**\n\nCreates a new journal entry by copying the header and all lines of an existing one - useful for recurring entries. By default the copy is named `Copy of ` and posted to the current open period; override either with the optional body. The copy starts in status `New`.\n\n**When to use**\n\n* Recurring adjustments: copy last month's entry into the new period instead of rebuilding it.\n* Start a corrected version of an approved entry while keeping the original for audit.\n\n**Notes**\n\n* When `name` or `periodId` is supplied, the copy is created first and then renamed/moved. If the second step fails the call returns an error but the copy already exists (named `Copy of `); look it up with GET /journal-entries/search/{jeName} before retrying.", "operationId": "copyJournalEntry", "parameters": [ { "name": "jeId", "in": "path", "required": true, "description": "ID of the journal entry.", "schema": { "type": "integer", "format": "int64" }, "example": 10045 } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CopyJournalEntryRequest" }, "examples": { "nextMonth": { "summary": "Copy into October", "value": { "name": "OCT-2026 Revenue Reclass", "periodId": 202610 } } } } } }, "responses": { "201": { "description": "Copy created", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JournalEntryResponse" }, "examples": { "copyCreated": { "summary": "Copy created", "value": { "success": true, "id": 10047, "name": "OCT-2026 Revenue Reclass", "status": "New", "description": "Reclass deferred revenue for contract RC-1001", "waterfallStatus": "NEW", "jeHeader": { "id": 10047, "name": "OCT-2026 Revenue Reclass", "description": "Reclass deferred revenue for contract RC-1001", "categoryCode": "RECLASS", "exchangeRateType": "User", "sobId": 1, "sobName": "US Primary SOB", "functionalCurrency": "USD", "periodId": 202610, "clientId": 1, "orgId": "101", "bookId": 1, "accountMethod": "Standard", "status": "New", "approvalCurrency": "USD", "glTransfer": "Yes", "waterfallStatus": "NEW", "createdBy": "jane.doe@example.com", "createdDate": "2026-09-28T10:21:04.000+00:00", "updatedBy": "jane.doe@example.com", "updatedDate": "2026-09-28T10:21:04.000+00:00" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenEdit" }, "429": { "$ref": "#/components/responses/MjeTooManyRequests" }, "500": { "$ref": "#/components/responses/UnexpectedError" }, "502": { "description": "Source entry cannot be copied; Journal entry service unavailable", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "sourceEntryCannotBeCopied": { "summary": "Source entry cannot be copied", "description": "The source entry does not exist or is not visible to you, or the override `periodId` is not open.", "value": { "success": false, "reasons": [ { "code": "500 INTERNAL_SERVER_ERROR", "message": "500 Internal Server Error: [no body]" } ] } }, "journalEntryServiceUnavailable": { "$ref": "#/components/examples/ServiceUnavailable" } } } } } } } }, "/journal-entries/search/{jeName}": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Zuora Revenue API (base URL)" } ], "get": { "tags": [ "Journal Entries" ], "security": [ { "OneIdOAuth": [] } ], "summary": "List journal entries by name", "description": "**Purpose**\n\nReturns the journal entries whose name matches the given text. Use it for quick look-ups (for example a type-ahead); use GET /journal-entries with `filter=name.SW:...` for paginated searches.\n\n**When to use**\n\n* Quick look-up of an entry by (part of) its name, for example in a type-ahead search box.\n* Before retrying a create call that timed out, to check whether the entry was already created.", "operationId": "searchJournalEntriesByName", "parameters": [ { "name": "jeName", "in": "path", "required": true, "description": "Name (or part of the name) to search for. URL-encode spaces and special characters.", "schema": { "type": "string" }, "example": "SEP-2026" } ], "responses": { "200": { "description": "Matching journal entries (may be empty)", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/JournalEntryListItem" } }, "examples": { "matchingJournalEntriesMayBeEmpty": { "summary": "Matching journal entries (may be empty)", "value": [ { "id": 10045, "name": "SEP-2026 Revenue Reclass", "description": "Reclass deferred revenue for contract RC-1001", "reversalStatus": "", "categoryCode": "RECLASS", "exRateType": "User", "periodId": "SEP-2026", "status": "New", "reversalPeriodId": "OCT-2026", "hashTotal": 3000, "sobName": "US Primary SOB", "sobId": 1, "functionalCurrency": "USD", "createdBy": "jane.doe@example.com", "createdDate": "2026-09-28 10:21:04", "updatedBy": "jane.doe@example.com", "updatedDate": "2026-09-28 10:21:04", "approverName": null, "bookId": 1, "secAtrVal": "101" } ] }, "noMatch": { "summary": "No matches", "value": [] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenRead" }, "429": { "$ref": "#/components/responses/MjeTooManyRequests" }, "500": { "$ref": "#/components/responses/UnexpectedError" }, "502": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/journal-entries/by-org/{secAtrVal}/book/{bookId}": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Zuora Revenue API (base URL)" } ], "get": { "tags": [ "Journal Entries" ], "security": [ { "OneIdOAuth": [] } ], "summary": "List journal entries for an organization and book", "description": "**Purpose**\n\nReturns all journal entries for one organization and accounting book (not paginated). Use GET /journal-entries for large result sets.\n\n**When to use**\n\n* You need every entry for one organization and book in a single response (small data sets, for example a nightly sync).\n* For large or filtered result sets use GET /journal-entries with pagination instead.", "operationId": "listJournalEntriesByOrgAndBook", "parameters": [ { "name": "secAtrVal", "in": "path", "required": true, "description": "Organization ID (security attribute value), the same value as `orgId`.", "schema": { "type": "string" }, "example": "101" }, { "name": "bookId", "in": "path", "required": true, "description": "Accounting book ID.", "schema": { "type": "integer", "format": "int32" }, "example": 1 } ], "responses": { "200": { "description": "Journal entries for the organization and book", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/JournalEntryListItem" } }, "examples": { "journalEntriesForTheOrganizationAndBook": { "summary": "Journal entries for the organization and book", "value": [ { "id": 10045, "name": "SEP-2026 Revenue Reclass", "description": "Reclass deferred revenue for contract RC-1001", "reversalStatus": "", "categoryCode": "RECLASS", "exRateType": "User", "periodId": "SEP-2026", "status": "New", "reversalPeriodId": "OCT-2026", "hashTotal": 3000, "sobName": "US Primary SOB", "sobId": 1, "functionalCurrency": "USD", "createdBy": "jane.doe@example.com", "createdDate": "2026-09-28 10:21:04", "updatedBy": "jane.doe@example.com", "updatedDate": "2026-09-28 10:21:04", "approverName": null, "bookId": 1, "secAtrVal": "101" }, { "id": 10046, "name": "SEP-2026 Accrual", "description": "Reclass deferred revenue for contract RC-1001", "reversalStatus": "", "categoryCode": "ACCRUAL", "exRateType": "User", "periodId": "SEP-2026", "status": "Validated", "reversalPeriodId": "OCT-2026", "hashTotal": 840, "sobName": "US Primary SOB", "sobId": 1, "functionalCurrency": "USD", "createdBy": "jane.doe@example.com", "createdDate": "2026-09-28 10:21:04", "updatedBy": "jane.doe@example.com", "updatedDate": "2026-09-28 10:21:04", "approverName": null, "bookId": 1, "secAtrVal": "101" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenRead" }, "429": { "$ref": "#/components/responses/MjeTooManyRequests" }, "500": { "description": "Non-numeric book ID; Unexpected error", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "nonNumericBookId": { "summary": "Non-numeric book ID", "description": "`bookId` in the path is not an integer.", "value": { "success": false, "reasons": [ { "code": "SystemError", "message": "internal server error" } ] } }, "unexpectedError": { "$ref": "#/components/examples/UnexpectedError" } } } } }, "502": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/journal-entries/{jeId}/lines": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Zuora Revenue API (base URL)" } ], "get": { "tags": [ "Journal Entry Lines" ], "security": [ { "OneIdOAuth": [] } ], "summary": "List journal entry lines", "description": "**Purpose**\n\nReturns a page of the lines of a journal entry, with filtering, sorting and field selection. Each line's `errorMessage` shows any validation error recorded on it.\n\n**When to use**\n\n* Review or reconcile the debit/credit lines of an entry, for example to show them in your own UI.\n* After validation fails (`validationStatus` = `Error`), to find which lines have an `errorMessage`.\n* Get line IDs before a CSV full-file update, line copy or line delete.\n\n**Notes**\n\n* Without `fields`, the page is wrapped in a `JournalEntryResponse` under `lines`. With `fields`, the page object is returned directly.", "operationId": "listJournalEntryLines", "parameters": [ { "name": "jeId", "in": "path", "required": true, "description": "ID of the journal entry.", "schema": { "type": "integer", "format": "int64" }, "example": 10045 }, { "name": "filter", "in": "query", "required": false, "description": "Filter clause in the form `field.OPERATOR:value`. Repeat the parameter to combine clauses with AND. Operators: `EQ` (equals), `NE` (not equals), `LT`, `GT`, `LE`, `GE` (comparisons for numbers and dates), `SW` (starts with) and `IN` (any of a list: `field.IN:[v1,v2]`). Values are not quoted. Allowed fields for lines: `accountCode`, `accountType`, `bookId`, `comments`, `costOrVcType`, `createdBy`, `createdDate`, `credit`, `currency`, `debit`, `description`, `endDate`, `errorMessage`, `exchangeRate`, `exchangeRateDate`, `gexchangeRate`, `id`, `jeSetNo`, `orgId`, `rcId`, `rcLineId`, `reason`, `reference1`, `reference2`, `reference3`, `reference4`, `reference5`, `reference6`, `reference7`, `reference8`, `reference9`, `reference10`, `reference11`, `reference12`, `reference13`, `reference14`, `reference15`, `soLineId`, `soNum`, `startDate`, `typeName`, `updatedBy`, `updatedDate`. Unknown fields return 400 `INVALID_VALUE`.", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true, "example": [ "accountType.EQ:Revenue" ] }, { "name": "sort", "in": "query", "required": false, "description": "Sort clause `field.ASC` or `field.DESC`. Only the first sort clause is applied. Uses the same field names as `filter`.", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true, "example": [ "id.ASC" ] }, { "name": "fields", "in": "query", "required": false, "description": "Comma-separated list of properties to return for each record (the `id` property is always returned). Names must match the response property names exactly. When supplied, each record contains only these properties. Unknown names return 400 `INVALID_VALUE`.", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": false, "example": [ "accountCode", "debit", "credit" ] }, { "name": "expand", "in": "query", "required": false, "description": "Reserved for future use; currently ignored.", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": false }, { "name": "pageSize", "in": "query", "required": false, "description": "Number of records per page. Defaults to 20. Values above 40 are reduced to 40.", "schema": { "type": "integer", "format": "int32", "default": 20 }, "example": 20 }, { "name": "cursor", "in": "query", "required": false, "description": "Page to return. Use the 1-based page number (`1`, `2`, ...). Defaults to the first page. A non-numeric or non-positive value returns 400 `INVALID_VALUE`.", "schema": { "type": "string" }, "example": "2" } ], "responses": { "200": { "description": "Journal entry with a page of lines", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/JournalEntryResponse" }, { "$ref": "#/components/schemas/JournalEntryLinesPage" } ] }, "examples": { "journalEntryWithAPageOfLines": { "summary": "Journal entry with a page of lines", "value": { "success": true, "lines": { "pageNumber": 1, "pageSize": 20, "totalRecords": 2, "result": [ { "id": 70001, "headerId": 10045, "clientId": 1, "orgId": "101", "bookId": 1, "rcId": 1001, "rcLineId": 50001, "currency": "USD", "debit": 1500, "credit": null, "exchangeRateDate": "2026-09-30T00:00:00.000+00:00", "exchangeRate": 1, "gexchangeRate": 1, "startDate": "2026-09-01T00:00:00.000+00:00", "endDate": "2026-09-30T00:00:00.000+00:00", "accountType": "Contract Liability", "accountCode": "2400-100-000", "jeSetNo": 1, "soNum": "SO-50012", "soLineId": "SO-50012-1", "unbillAccounting": "N", "description": "Release deferred revenue", "errorMessage": null, "reference1": "TCK-4471", "createdBy": "jane.doe@example.com", "createdDate": "2026-09-28T10:21:04.000+00:00", "updatedBy": "jane.doe@example.com", "updatedDate": "2026-09-28T10:21:04.000+00:00" }, { "id": 70002, "headerId": 10045, "clientId": 1, "orgId": "101", "bookId": 1, "rcId": 1001, "rcLineId": 50001, "currency": "USD", "debit": null, "credit": 1500, "exchangeRateDate": "2026-09-30T00:00:00.000+00:00", "exchangeRate": 1, "gexchangeRate": 1, "startDate": "2026-09-01T00:00:00.000+00:00", "endDate": "2026-09-30T00:00:00.000+00:00", "accountType": "Revenue", "accountCode": "4000-100-000", "jeSetNo": 1, "soNum": "SO-50012", "soLineId": "SO-50012-1", "unbillAccounting": "N", "description": "Recognize revenue", "errorMessage": null, "reference1": "TCK-4471", "createdBy": "jane.doe@example.com", "createdDate": "2026-09-28T10:21:04.000+00:00", "updatedBy": "jane.doe@example.com", "updatedDate": "2026-09-28T10:21:04.000+00:00" } ] } } }, "projected": { "summary": "With `fields=accountCode,debit,credit` (returns the page directly)", "value": { "pageNumber": 1, "pageSize": 20, "totalRecords": 2, "result": [ { "id": 70001, "accountCode": "2400-100-000", "debit": 1500, "credit": null }, { "id": 70002, "accountCode": "4000-100-000", "debit": null, "credit": 1500 } ] } } } } } }, "400": { "description": "Unknown filter field", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unknownFilterField": { "summary": "Unknown filter field", "description": "`filter` or `sort` names a field that is not allowed for lines.", "value": { "success": false, "reasons": [ { "code": "INVALID_VALUE", "message": "Unknown field 'amount'. Allowed fields: accountCode, accountType, bookId, comments, ..." } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenRead" }, "429": { "$ref": "#/components/responses/MjeTooManyRequests" }, "500": { "$ref": "#/components/responses/UnexpectedError" }, "502": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/journal-entries/{jeId}/lines/{lineId}": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Zuora Revenue API (base URL)" } ], "delete": { "tags": [ "Journal Entry Lines" ], "security": [ { "OneIdOAuth": [] } ], "summary": "Delete a journal entry line", "description": "**Purpose**\n\nDeletes one line from an editable journal entry. Remember to keep each `jeSetNo` balanced; delete or adjust the offsetting line too.\n\n**When to use**\n\n* Remove one incorrect line from an editable entry without re-uploading the whole entry.\n* For several changes at once, a CSV full-file update (PATCH) is usually simpler.\n\n**Notes**\n\n* The line is identified by `lineId` alone. Make sure the line belongs to the entry in the path before deleting.", "operationId": "deleteJournalEntryLine", "parameters": [ { "name": "jeId", "in": "path", "required": true, "description": "ID of the journal entry.", "schema": { "type": "integer", "format": "int64" }, "example": 10045 }, { "name": "lineId", "in": "path", "required": true, "description": "ID of the line to delete.", "schema": { "type": "integer", "format": "int64" }, "example": 70002 } ], "responses": { "204": { "description": "Line deleted (no response body)", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenEdit" }, "429": { "$ref": "#/components/responses/MjeTooManyRequests" }, "500": { "$ref": "#/components/responses/UnexpectedError" }, "502": { "description": "Line cannot be deleted; Journal entry service unavailable", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "lineCannotBeDeleted": { "summary": "Line cannot be deleted", "description": "The entry is no longer editable or your role cannot edit it.", "value": { "success": false, "reasons": [ { "code": "500 INTERNAL_SERVER_ERROR", "message": "500 Internal Server Error: \"Not Allowed .Please check the object status and your role\"" } ] } }, "journalEntryServiceUnavailable": { "$ref": "#/components/examples/ServiceUnavailable" } } } } } } } }, "/journal-entries/{jeId}/lines/copy": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Zuora Revenue API (base URL)" } ], "post": { "tags": [ "Journal Entry Lines" ], "security": [ { "OneIdOAuth": [] } ], "summary": "Copy journal entry lines", "description": "**Purpose**\n\nCopies selected lines of a journal entry, either within the same entry or into another editable entry (`targetJeId`). Returns the newly created lines.\n\n**When to use**\n\n* Duplicate selected lines inside the same entry (for example to add a similar set), or reuse lines from one entry in another editable entry.", "operationId": "copyJournalEntryLines", "parameters": [ { "name": "jeId", "in": "path", "required": true, "description": "ID of the journal entry.", "schema": { "type": "integer", "format": "int64" }, "example": 10045 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CopyJournalEntryLinesRequest" }, "examples": { "toOtherEntry": { "summary": "Copy two lines to entry 10046", "value": { "targetJeId": 10046, "lineIds": [ 70001, 70002 ] } } } } } }, "responses": { "200": { "description": "Copied lines", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/JournalEntryLineDataset" } }, "examples": { "copiedLines": { "summary": "Copied lines", "value": [ { "id": 70101, "headerId": 10046, "clientId": 1, "orgId": "101", "bookId": 1, "rcId": 1001, "rcLineId": 50001, "currency": "USD", "debit": 1500, "credit": null, "exchangeRateDate": "2026-09-30T00:00:00.000+00:00", "exchangeRate": 1, "gexchangeRate": 1, "startDate": "2026-09-01T00:00:00.000+00:00", "endDate": "2026-09-30T00:00:00.000+00:00", "accountType": "Contract Liability", "accountCode": "2400-100-000", "jeSetNo": 1, "soNum": "SO-50012", "soLineId": "SO-50012-1", "unbillAccounting": "N", "description": "Release deferred revenue", "errorMessage": null, "reference1": "TCK-4471", "createdBy": "jane.doe@example.com", "createdDate": "2026-09-28T10:21:04.000+00:00", "updatedBy": "jane.doe@example.com", "updatedDate": "2026-09-28T10:21:04.000+00:00", "createPeriodId": "202609" }, { "id": 70102, "headerId": 10046, "clientId": 1, "orgId": "101", "bookId": 1, "rcId": 1001, "rcLineId": 50001, "currency": "USD", "debit": null, "credit": 1500, "exchangeRateDate": "2026-09-30T00:00:00.000+00:00", "exchangeRate": 1, "gexchangeRate": 1, "startDate": "2026-09-01T00:00:00.000+00:00", "endDate": "2026-09-30T00:00:00.000+00:00", "accountType": "Revenue", "accountCode": "4000-100-000", "jeSetNo": 1, "soNum": "SO-50012", "soLineId": "SO-50012-1", "unbillAccounting": "N", "description": "Recognize revenue", "errorMessage": null, "reference1": "TCK-4471", "createdBy": "jane.doe@example.com", "createdDate": "2026-09-28T10:21:04.000+00:00", "updatedBy": "jane.doe@example.com", "updatedDate": "2026-09-28T10:21:04.000+00:00", "createPeriodId": "202609" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenEdit" }, "429": { "$ref": "#/components/responses/MjeTooManyRequests" }, "500": { "$ref": "#/components/responses/UnexpectedError" }, "502": { "description": "Target entry not editable; Journal entry service unavailable", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "targetEntryNotEditable": { "summary": "Target entry not editable", "description": "The target entry is not editable or the line IDs do not exist.", "value": { "success": false, "reasons": [ { "code": "500 INTERNAL_SERVER_ERROR", "message": "500 Internal Server Error: \"Not Allowed .Please check the object status and your role\"" } ] } }, "journalEntryServiceUnavailable": { "$ref": "#/components/examples/ServiceUnavailable" } } } } } } } }, "/journal-entries/{jeId}/lines/search/{soNumber}": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Zuora Revenue API (base URL)" } ], "get": { "tags": [ "Journal Entry Lines" ], "security": [ { "OneIdOAuth": [] } ], "summary": "List journal entry lines by sales order number", "description": "**Purpose**\n\nReturns the lines of a journal entry that reference the given sales order number (`soNum`).\n\n**When to use**\n\n* Find the lines of an entry that relate to a specific sales order, for example when an auditor or customer asks about one order.", "operationId": "searchJournalEntryLinesBySalesOrder", "parameters": [ { "name": "jeId", "in": "path", "required": true, "description": "ID of the journal entry.", "schema": { "type": "integer", "format": "int64" }, "example": 10045 }, { "name": "soNumber", "in": "path", "required": true, "description": "Sales order number to search for.", "schema": { "type": "string" }, "example": "SO-50012" } ], "responses": { "200": { "description": "Matching lines (may be empty)", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/JournalEntryLine" } }, "examples": { "matchingLinesMayBeEmpty": { "summary": "Matching lines (may be empty)", "value": [ { "id": 70001, "headerId": 10045, "clientId": 1, "orgId": "101", "bookId": 1, "rcId": 1001, "rcLineId": 50001, "currency": "USD", "debit": 1500, "credit": null, "exchangeRateDate": "2026-09-30T00:00:00.000+00:00", "exchangeRate": 1, "gexchangeRate": 1, "startDate": "2026-09-01T00:00:00.000+00:00", "endDate": "2026-09-30T00:00:00.000+00:00", "accountType": "Contract Liability", "accountCode": "2400-100-000", "jeSetNo": 1, "soNum": "SO-50012", "soLineId": "SO-50012-1", "unbillAccounting": "N", "description": "Release deferred revenue", "errorMessage": null, "reference1": "TCK-4471", "createdBy": "jane.doe@example.com", "createdDate": "2026-09-28T10:21:04.000+00:00", "updatedBy": "jane.doe@example.com", "updatedDate": "2026-09-28T10:21:04.000+00:00" }, { "id": 70002, "headerId": 10045, "clientId": 1, "orgId": "101", "bookId": 1, "rcId": 1001, "rcLineId": 50001, "currency": "USD", "debit": null, "credit": 1500, "exchangeRateDate": "2026-09-30T00:00:00.000+00:00", "exchangeRate": 1, "gexchangeRate": 1, "startDate": "2026-09-01T00:00:00.000+00:00", "endDate": "2026-09-30T00:00:00.000+00:00", "accountType": "Revenue", "accountCode": "4000-100-000", "jeSetNo": 1, "soNum": "SO-50012", "soLineId": "SO-50012-1", "unbillAccounting": "N", "description": "Recognize revenue", "errorMessage": null, "reference1": "TCK-4471", "createdBy": "jane.doe@example.com", "createdDate": "2026-09-28T10:21:04.000+00:00", "updatedBy": "jane.doe@example.com", "updatedDate": "2026-09-28T10:21:04.000+00:00" } ] }, "noMatch": { "summary": "No matches", "value": [] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenRead" }, "429": { "$ref": "#/components/responses/MjeTooManyRequests" }, "500": { "$ref": "#/components/responses/UnexpectedError" }, "502": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/journal-entries/{jeId}/schedules": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Zuora Revenue API (base URL)" } ], "get": { "tags": [ "Schedules and Waterfall" ], "security": [ { "OneIdOAuth": [] } ], "summary": "List journal entry schedules", "description": "**Purpose**\n\nReturns a page of the revenue schedules (period-by-period accounting entries) that a journal entry generates. Available once waterfall generation has succeeded (`waterfallStatus` = `SUCCESS`).\n\n**When to use**\n\n* See the period-by-period accounting (debits/credits by account and period) the entry produces, for GL reconciliation.\n* Available after waterfall generation has succeeded (`waterfallStatus` = `SUCCESS`).", "operationId": "listJournalEntrySchedules", "parameters": [ { "name": "jeId", "in": "path", "required": true, "description": "ID of the journal entry.", "schema": { "type": "integer", "format": "int64" }, "example": 10045 }, { "name": "filter", "in": "query", "required": false, "description": "Filter clause in the form `field.OPERATOR:value`. Repeat the parameter to combine clauses with AND. Operators: `EQ` (equals), `NE` (not equals), `LT`, `GT`, `LE`, `GE` (comparisons for numbers and dates), `SW` (starts with) and `IN` (any of a list: `field.IN:[v1,v2]`). Values are not quoted. Allowed fields for schedules: `periodName`, `accountType`, `accountCode`, `acountCode`, `currencyCode`, `drAmount`, `crAmount`, `funcDrAmount`, `funcCrAmount`, `rcurrDrAmount`, `rcurrCrAmount`, `schdRcId`. Unknown fields return 400 `INVALID_VALUE`.", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true, "example": [ "periodName.EQ:SEP-2026" ] }, { "name": "sort", "in": "query", "required": false, "description": "Sort clause `field.ASC` or `field.DESC`. Only the first sort clause is applied. Uses the same field names as `filter`.", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true, "example": [ "periodName.ASC" ] }, { "name": "fields", "in": "query", "required": false, "description": "Accepted for consistency with other list endpoints; not applied by this endpoint.", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": false }, { "name": "expand", "in": "query", "required": false, "description": "Reserved for future use; currently ignored.", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": false }, { "name": "pageSize", "in": "query", "required": false, "description": "Number of records per page. Defaults to 20. Values above 40 are reduced to 40.", "schema": { "type": "integer", "format": "int32", "default": 20 }, "example": 20 }, { "name": "cursor", "in": "query", "required": false, "description": "Page to return. Use the 1-based page number (`1`, `2`, ...). Defaults to the first page. A non-numeric or non-positive value returns 400 `INVALID_VALUE`.", "schema": { "type": "string" }, "example": "2" } ], "responses": { "200": { "description": "Journal entry with a page of schedules", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JournalEntryResponse" }, "examples": { "journalEntryWithAPageOfSchedules": { "summary": "Journal entry with a page of schedules", "value": { "success": true, "schedules": { "pageNumber": 1, "pageSize": 20, "totalRecords": 2, "result": [ { "periodName": "SEP-2026", "accountType": "Contract Liability", "acountCode": "2400-100-000", "currencyCode": "USD", "drAmount": 1500, "crAmount": 0, "funcDrAmount": 1500, "funcCrAmount": 0, "rcurrDrAmount": 1500, "rcurrCrAmount": 0, "schdRcId": 1001, "interfaceFlag": "N" }, { "periodName": "SEP-2026", "accountType": "Revenue", "acountCode": "4000-100-000", "currencyCode": "USD", "drAmount": 0, "crAmount": 1500, "funcDrAmount": 0, "funcCrAmount": 1500, "rcurrDrAmount": 0, "rcurrCrAmount": 1500, "schdRcId": 1001, "interfaceFlag": "N" } ] } } } } } } }, "400": { "description": "Unknown filter field", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unknownFilterField": { "summary": "Unknown filter field", "description": "`filter` or `sort` names a field that is not allowed for schedules.", "value": { "success": false, "reasons": [ { "code": "INVALID_VALUE", "message": "Unknown field 'period'. Allowed fields: accountCode, accountType, acountCode, crAmount, ..." } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenRead" }, "429": { "$ref": "#/components/responses/MjeTooManyRequests" }, "500": { "$ref": "#/components/responses/UnexpectedError" }, "502": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/journal-entries/{jeId}/waterfall-entries": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Zuora Revenue API (base URL)" } ], "get": { "tags": [ "Schedules and Waterfall" ], "security": [ { "OneIdOAuth": [] } ], "summary": "List revenue waterfall entries", "description": "**Purpose**\n\nReturns a page of the revenue waterfall for a journal entry: for each line, the amount recognized in each period. Use it to review the revenue impact before approving.\n\n**When to use**\n\n* Preview the revenue impact of an entry by period before approving it.\n* Explain to stakeholders how an adjustment changes future revenue.", "operationId": "listJournalEntryWaterfallEntries", "parameters": [ { "name": "jeId", "in": "path", "required": true, "description": "ID of the journal entry.", "schema": { "type": "integer", "format": "int64" }, "example": 10045 }, { "name": "filter", "in": "query", "required": false, "description": "Filter clause in the form `field.OPERATOR:value`. Repeat the parameter to combine clauses with AND. Operators: `EQ` (equals), `NE` (not equals), `LT`, `GT`, `LE`, `GE` (comparisons for numbers and dates), `SW` (starts with) and `IN` (any of a list: `field.IN:[v1,v2]`). Values are not quoted. Allowed fields for waterfall entries: `jeSetNo`, `soNumber`, `soLineId`, `accountCode`, `jeAmount`, `startDate`, `endDate`, `accountType`. Unknown fields return 400 `INVALID_VALUE`.", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true, "example": [ "accountType.EQ:Revenue" ] }, { "name": "sort", "in": "query", "required": false, "description": "Sort clause `field.ASC` or `field.DESC`. Only the first sort clause is applied. Uses the same field names as `filter`.", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true, "example": [ "jeSetNo.ASC" ] }, { "name": "fields", "in": "query", "required": false, "description": "Accepted for consistency with other list endpoints; not applied by this endpoint.", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": false }, { "name": "expand", "in": "query", "required": false, "description": "Reserved for future use; currently ignored.", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": false }, { "name": "pageSize", "in": "query", "required": false, "description": "Number of records per page. Defaults to 20. Values above 40 are reduced to 40.", "schema": { "type": "integer", "format": "int32", "default": 20 }, "example": 20 }, { "name": "cursor", "in": "query", "required": false, "description": "Page to return. Use the 1-based page number (`1`, `2`, ...). Defaults to the first page. A non-numeric or non-positive value returns 400 `INVALID_VALUE`.", "schema": { "type": "string" }, "example": "2" } ], "responses": { "200": { "description": "Page of waterfall entries", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WaterfallEntriesPage" }, "examples": { "pageOfWaterfallEntries": { "summary": "Page of waterfall entries", "value": { "pageNumber": 1, "pageSize": 20, "totalRecords": 1, "result": [ { "jeSetNo": "1", "soNumber": "SO-50012", "soLineId": "SO-50012-1", "accountCode": "4000-100-000", "jeAmount": 1500, "startDate": "2026-09-01T00:00:00.000+00:00", "endDate": "2026-11-30T00:00:00.000+00:00", "accountType": "Revenue", "entries": { "SEP-2026": "500.00", "OCT-2026": "500.00", "NOV-2026": "500.00" } } ] } } } } } }, "400": { "description": "Unknown filter field", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unknownFilterField": { "summary": "Unknown filter field", "description": "`filter` or `sort` names a field that is not allowed for waterfall entries.", "value": { "success": false, "reasons": [ { "code": "INVALID_VALUE", "message": "Unknown field 'period'. Allowed fields: accountCode, accountType, endDate, jeAmount, jeSetNo, soLineId, soNumber, startDate" } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenRead" }, "429": { "$ref": "#/components/responses/MjeTooManyRequests" }, "500": { "$ref": "#/components/responses/UnexpectedError" }, "502": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/journal-entries/{jeId}/waterfall-status": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Zuora Revenue API (base URL)" } ], "get": { "tags": [ "Schedules and Waterfall" ], "security": [ { "OneIdOAuth": [] } ], "summary": "Retrieve the waterfall status", "description": "**Purpose**\n\nReturns the status of waterfall (schedule) generation for a journal entry. Poll this after create, update or approval until it is `SUCCESS` or `ERROR`.\n\n**When to use**\n\n* Poll after create, update or approval until waterfall generation finishes (`SUCCESS` or `ERROR`), before reading schedules or waterfall entries.\n\n**Notes**\n\n* For an ID that does not exist, the call returns HTTP 200 with an empty `waterfallStatus`.", "operationId": "getJournalEntryWaterfallStatus", "parameters": [ { "name": "jeId", "in": "path", "required": true, "description": "ID of the journal entry.", "schema": { "type": "integer", "format": "int64" }, "example": 10045 } ], "responses": { "200": { "description": "Waterfall status", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WaterfallStatusResponse" }, "examples": { "waterfallStatus": { "summary": "Waterfall status", "value": { "id": 10045, "waterfallStatus": "SUCCESS" } }, "inProgress": { "summary": "Still generating", "value": { "id": 10045, "waterfallStatus": "IN PROGRESS" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenRead" }, "429": { "$ref": "#/components/responses/MjeTooManyRequests" }, "500": { "description": "Non-numeric ID; Unexpected error", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "nonNumericId": { "summary": "Non-numeric ID", "description": "`jeId` is not an integer.", "value": { "success": false, "reasons": [ { "code": "SystemError", "message": "internal server error" } ] } }, "unexpectedError": { "$ref": "#/components/examples/UnexpectedError" } } } } }, "502": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/journal-entries/{jeId}/waterfall-retry": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Zuora Revenue API (base URL)" } ], "post": { "tags": [ "Schedules and Waterfall" ], "security": [ { "OneIdOAuth": [] } ], "summary": "Retry waterfall generation", "description": "**Purpose**\n\nRe-triggers waterfall (schedule) generation for a journal entry whose `waterfallStatus` is `ERROR`. Returns the new status, normally `IN PROGRESS`.\n\n**When to use**\n\n* Waterfall generation ended in `ERROR` (for example after a temporary issue) and you want to run it again without editing the entry.", "operationId": "retryJournalEntryWaterfall", "parameters": [ { "name": "jeId", "in": "path", "required": true, "description": "ID of the journal entry.", "schema": { "type": "integer", "format": "int64" }, "example": 10045 } ], "responses": { "200": { "description": "Waterfall generation re-triggered", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WaterfallStatusResponse" }, "examples": { "waterfallGenerationReTriggered": { "summary": "Waterfall generation re-triggered", "value": { "id": 10045, "waterfallStatus": "IN PROGRESS" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenEdit" }, "429": { "$ref": "#/components/responses/MjeTooManyRequests" }, "500": { "$ref": "#/components/responses/UnexpectedError" }, "502": { "description": "Retry not allowed; Journal entry service unavailable", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "retryNotAllowed": { "summary": "Retry not allowed", "description": "The current `waterfallStatus` is not `ERROR`.", "value": { "success": false, "reasons": [ { "code": "500 INTERNAL_SERVER_ERROR", "message": "500 Internal Server Error: \"Waterfall Retry not allowed as the job status is NOT in Error. Please check\"" } ] } }, "journalEntryServiceUnavailable": { "$ref": "#/components/examples/ServiceUnavailable" } } } } } } } }, "/journal-entries/{jeId}/submit": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Zuora Revenue API (base URL)" } ], "post": { "tags": [ "Approval Workflow" ], "security": [ { "OneIdOAuth": [] } ], "summary": "Submit a journal entry for approval", "description": "**Purpose**\n\nSubmits a validated journal entry into the approval workflow. The approval rule that matches the entry determines the approvers; if no approval rule matches, the submit is refused. Only the `comment` property of the body is used.\n\n**When to use**\n\n* An entry is complete and `Validated`, and should now go to its approvers.\n* Call GET /journal-entries/{jeId}/validation-status first; submitting an entry with line errors fails.", "operationId": "submitJournalEntry", "parameters": [ { "name": "jeId", "in": "path", "required": true, "description": "ID of the journal entry.", "schema": { "type": "integer", "format": "int64" }, "example": 10045 }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional client-generated unique key (for example a UUID). Accepted for forward compatibility; **not currently enforced** - the service does not de-duplicate retries, so do not rely on it to prevent duplicate entries.", "schema": { "type": "string" }, "example": "6f1c2c3e-0b7a-4d1e-9a51-1f1e2a3b4c5d" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusRequest" }, "examples": { "withComment": { "summary": "Submit with a comment", "value": { "comment": "Ready for September close review" } } } } } }, "responses": { "200": { "description": "Entry submitted", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkActionResponse" }, "examples": { "entrySubmitted": { "summary": "Entry submitted", "value": { "success": true, "status": "Approval Pending", "results": [ { "id": "10045", "success": true, "message": "10045 is Submitted Successfully" } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenEdit" }, "429": { "$ref": "#/components/responses/MjeTooManyRequests" }, "500": { "$ref": "#/components/responses/UnexpectedError" }, "502": { "description": "Entry has validation errors; No approval rule; Journal entry service unavailable", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "entryHasValidationErrors": { "summary": "Entry has validation errors", "description": "One or more lines have validation errors, the entry is already submitted or approved, or your role cannot submit it. `message` contains the details returned by journal entry processing.", "value": { "success": false, "reasons": [ { "code": "400 BAD_REQUEST", "message": "400 Bad Request: \"{\"header\":{},\"jeline\":{\"70002\":\"Invalid account code\"}}\"" } ] } }, "noApprovalRule": { "summary": "No approval rule", "description": "No approval rule matches the entry, so it cannot enter the approval workflow. Ask your administrator to configure an approval rule.", "value": { "success": false, "reasons": [ { "code": "403 FORBIDDEN", "message": "403 Forbidden: \"{\"header\":{\"10045\":\"Approval Rule not Defined\"}}\"" } ] } }, "journalEntryServiceUnavailable": { "$ref": "#/components/examples/ServiceUnavailable" } } } } } } } }, "/journal-entries/approve": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Zuora Revenue API (base URL)" } ], "post": { "tags": [ "Approval Workflow" ], "security": [ { "OneIdOAuth": [] } ], "summary": "Approve journal entries", "description": "**Purpose**\n\nApproves one or more journal entries that are `Approval Pending` and assigned to the caller. On final approval the entry's schedules are posted and the final waterfall is generated asynchronously (track it with GET /journal-entries/{jeId}/waterfall-status).\n\n**When to use**\n\n* An approver (or an approval step in your workflow tool) accepts one or more entries that are `Approval Pending`.\n* Approving several entries at once during period close.\n\n**Notes**\n\n* Check `success` on the response and on every item in `results`. HTTP 200 is also returned when **every** entry failed; HTTP 207 means a mix of successes and failures.\n* Each `results` item currently reports the entry inside `message`; `id` may be omitted.", "operationId": "approveJournalEntries", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional client-generated unique key (for example a UUID). Accepted for forward compatibility; **not currently enforced** - the service does not de-duplicate retries, so do not rely on it to prevent duplicate entries.", "schema": { "type": "string" }, "example": "6f1c2c3e-0b7a-4d1e-9a51-1f1e2a3b4c5d" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusRequest" }, "examples": { "example": { "summary": "Approve journal entries", "value": { "jeIds": [ 10045, 10046 ], "comment": "Approved for September close", "bookId": 1 } } } } } }, "responses": { "200": { "description": "All entries approved", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkActionResponse" }, "examples": { "allEntriesApproved": { "summary": "All entries approved", "value": { "success": true, "status": "Approved", "results": [ { "success": true, "message": "Journal entry 10045 approved successfully" }, { "success": true, "message": "Journal entry 10046 approved successfully" } ] } }, "allFailed": { "summary": "Every entry was refused (still HTTP 200)", "value": { "success": false, "status": "Approval Pending", "results": [ { "success": false, "code": "BUSINESS_RULE_VIOLATION", "message": "Journal entry 10046 failed to approve." } ] } } } } } }, "207": { "description": "Some entries succeeded and some failed", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkActionResponse" }, "examples": { "someEntriesSucceededAndSomeFailed": { "summary": "Some entries succeeded and some failed", "value": { "success": false, "status": "Approved", "results": [ { "success": true, "message": "Journal entry 10045 approved successfully" }, { "success": false, "code": "BUSINESS_RULE_VIOLATION", "message": "Journal entry 10046 failed to approve." } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenEdit" }, "429": { "$ref": "#/components/responses/MjeTooManyRequests" }, "500": { "$ref": "#/components/responses/UnexpectedError" }, "502": { "description": "Action rejected; Journal entry service unavailable", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "actionRejected": { "summary": "Action rejected", "description": "The journal entry processing service refused the whole request, for example because the entries are in a status that does not allow this action.", "value": { "success": false, "reasons": [ { "code": "500 INTERNAL_SERVER_ERROR", "message": "500 Internal Server Error: \"Not Allowed .Please check the object status and your role\"" } ] } }, "journalEntryServiceUnavailable": { "$ref": "#/components/examples/ServiceUnavailable" } } } } } } } }, "/journal-entries/reject": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Zuora Revenue API (base URL)" } ], "post": { "tags": [ "Approval Workflow" ], "security": [ { "OneIdOAuth": [] } ], "summary": "Reject journal entries", "description": "**Purpose**\n\nRejects one or more journal entries that are `Approval Pending`. Rejected entries can be edited and resubmitted. Provide a `comment` explaining the rejection; it is stored in the audit trail.\n\n**When to use**\n\n* An approver sends one or more entries back to the preparer for correction. Always include a `comment` explaining why.\n\n**Notes**\n\n* Check `success` on the response and on every item in `results`. HTTP 200 is also returned when **every** entry failed; HTTP 207 means a mix of successes and failures.\n* Each `results` item currently reports the entry inside `message`; `id` may be omitted.", "operationId": "rejectJournalEntries", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional client-generated unique key (for example a UUID). Accepted for forward compatibility; **not currently enforced** - the service does not de-duplicate retries, so do not rely on it to prevent duplicate entries.", "schema": { "type": "string" }, "example": "6f1c2c3e-0b7a-4d1e-9a51-1f1e2a3b4c5d" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusRequest" }, "examples": { "example": { "summary": "Reject journal entries", "value": { "jeIds": [ 10046 ], "comment": "Account code is wrong; please correct line 2" } } } } } }, "responses": { "200": { "description": "All entries rejected", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkActionResponse" }, "examples": { "allEntriesRejected": { "summary": "All entries rejected", "value": { "success": true, "status": "Rejected", "results": [ { "success": true, "message": "Journal entry 10045 rejected successfully" }, { "success": true, "message": "Journal entry 10046 rejected successfully" } ] } }, "allFailed": { "summary": "Every entry was refused (still HTTP 200)", "value": { "success": false, "status": "Approval Pending", "results": [ { "success": false, "code": "BUSINESS_RULE_VIOLATION", "message": "Journal entry 10046 failed to reject." } ] } } } } } }, "207": { "description": "Some entries succeeded and some failed", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkActionResponse" }, "examples": { "someEntriesSucceededAndSomeFailed": { "summary": "Some entries succeeded and some failed", "value": { "success": false, "status": "Rejected", "results": [ { "success": true, "message": "Journal entry 10045 rejected successfully" }, { "success": false, "code": "BUSINESS_RULE_VIOLATION", "message": "Journal entry 10046 failed to reject." } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenEdit" }, "429": { "$ref": "#/components/responses/MjeTooManyRequests" }, "500": { "$ref": "#/components/responses/UnexpectedError" }, "502": { "description": "Action rejected; Journal entry service unavailable", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "actionRejected": { "summary": "Action rejected", "description": "The journal entry processing service refused the whole request, for example because the entries are in a status that does not allow this action.", "value": { "success": false, "reasons": [ { "code": "500 INTERNAL_SERVER_ERROR", "message": "500 Internal Server Error: \"Not Allowed .Please check the object status and your role\"" } ] } }, "journalEntryServiceUnavailable": { "$ref": "#/components/examples/ServiceUnavailable" } } } } } } } }, "/journal-entries/recall": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Zuora Revenue API (base URL)" } ], "post": { "tags": [ "Approval Workflow" ], "security": [ { "OneIdOAuth": [] } ], "summary": "Recall journal entries", "description": "**Purpose**\n\nWithdraws one or more submitted journal entries from approval so they can be edited again. Usually performed by the submitter.\n\n**When to use**\n\n* The submitter notices a mistake after submitting and wants to withdraw the entry from approval to edit it.\n\n**Notes**\n\n* Check `success` on the response and on every item in `results`. HTTP 200 is also returned when **every** entry failed; HTTP 207 means a mix of successes and failures.\n* Each `results` item currently reports the entry inside `message`; `id` may be omitted.", "operationId": "recallJournalEntries", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional client-generated unique key (for example a UUID). Accepted for forward compatibility; **not currently enforced** - the service does not de-duplicate retries, so do not rely on it to prevent duplicate entries.", "schema": { "type": "string" }, "example": "6f1c2c3e-0b7a-4d1e-9a51-1f1e2a3b4c5d" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusRequest" }, "examples": { "example": { "summary": "Recall journal entries", "value": { "jeIds": [ 10045 ], "comment": "Recalling to fix amount" } } } } } }, "responses": { "200": { "description": "All entries recalled", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkActionResponse" }, "examples": { "allEntriesRecalled": { "summary": "All entries recalled", "value": { "success": true, "results": [ { "success": true, "message": "Journal entry 10045 recalled successfully" }, { "success": true, "message": "Journal entry 10046 recalled successfully" } ] } }, "allFailed": { "summary": "Every entry was refused (still HTTP 200)", "value": { "success": false, "results": [ { "success": false, "code": "BUSINESS_RULE_VIOLATION", "message": "Journal entry 10046 failed to recall." } ] } } } } } }, "207": { "description": "Some entries succeeded and some failed", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkActionResponse" }, "examples": { "someEntriesSucceededAndSomeFailed": { "summary": "Some entries succeeded and some failed", "value": { "success": false, "results": [ { "success": true, "message": "Journal entry 10045 recalled successfully" }, { "success": false, "code": "BUSINESS_RULE_VIOLATION", "message": "Journal entry 10046 failed to recall." } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenEdit" }, "429": { "$ref": "#/components/responses/MjeTooManyRequests" }, "500": { "$ref": "#/components/responses/UnexpectedError" }, "502": { "description": "Action rejected; Journal entry service unavailable", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "actionRejected": { "summary": "Action rejected", "description": "The journal entry processing service refused the whole request, for example because the entries are in a status that does not allow this action.", "value": { "success": false, "reasons": [ { "code": "500 INTERNAL_SERVER_ERROR", "message": "500 Internal Server Error: \"Not Allowed .Please check the object status and your role\"" } ] } }, "journalEntryServiceUnavailable": { "$ref": "#/components/examples/ServiceUnavailable" } } } } } } } }, "/journal-entries/reverse": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Zuora Revenue API (base URL)" } ], "post": { "tags": [ "Approval Workflow" ], "security": [ { "OneIdOAuth": [] } ], "summary": "Reverse a journal entry", "description": "**Purpose**\n\nCreates the reversal of an approved journal entry in the given `reversalPeriod`. Exactly one `jeIds` value and `reversalPeriod` are required.\n\n**When to use**\n\n* An approved entry must be undone (fully offset) in a later period - for example an accrual that reverses next month, or an approved entry that turned out to be wrong.\n\n**Notes**\n\n* Check `success` on the response and on every item in `results`. HTTP 200 is also returned when **every** entry failed; HTTP 207 means a mix of successes and failures.\n* Each `results` item currently reports the entry inside `message`; `id` may be omitted.", "operationId": "reverseJournalEntry", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional client-generated unique key (for example a UUID). Accepted for forward compatibility; **not currently enforced** - the service does not de-duplicate retries, so do not rely on it to prevent duplicate entries.", "schema": { "type": "string" }, "example": "6f1c2c3e-0b7a-4d1e-9a51-1f1e2a3b4c5d" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusRequest" }, "examples": { "example": { "summary": "Reverse a journal entry", "value": { "jeIds": [ 10045 ], "reversalPeriod": 202610, "comment": "Reverse September reclass" } } } } } }, "responses": { "200": { "description": "Entry reversed", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkActionResponse" }, "examples": { "entryReversed": { "summary": "Entry reversed", "value": { "success": true, "results": [ { "success": true, "message": "Journal entry 10045 reversed successfully" } ] } }, "allFailed": { "summary": "Every entry was refused (still HTTP 200)", "value": { "success": false, "results": [ { "success": false, "code": "BUSINESS_RULE_VIOLATION", "message": "Journal entry 10046 failed to reverse." } ] } } } } } }, "400": { "description": "More than one entry; Reversal period missing", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moreThanOneEntry": { "summary": "More than one entry", "description": "`jeIds` does not contain exactly one ID.", "value": { "success": false, "reasons": [ { "code": "INVALID_VALUE", "message": "jeIds: reverse accepts exactly one journal entry id", "field": "jeIds" } ] } }, "reversalPeriodMissing": { "summary": "Reversal period missing", "description": "`reversalPeriod` was not supplied.", "value": { "success": false, "reasons": [ { "code": "MISSING_REQUIRED_FIELD", "message": "Missing required fields: reversalPeriod", "field": "reversalPeriod" } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenEdit" }, "429": { "$ref": "#/components/responses/MjeTooManyRequests" }, "500": { "$ref": "#/components/responses/UnexpectedError" }, "502": { "description": "Action rejected; Journal entry service unavailable", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "actionRejected": { "summary": "Action rejected", "description": "The journal entry processing service refused the whole request, for example because the entries are in a status that does not allow this action.", "value": { "success": false, "reasons": [ { "code": "500 INTERNAL_SERVER_ERROR", "message": "500 Internal Server Error: \"Not Allowed .Please check the object status and your role\"" } ] } }, "journalEntryServiceUnavailable": { "$ref": "#/components/examples/ServiceUnavailable" } } } } } } } }, "/journal-entries/bulk-delete": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Zuora Revenue API (base URL)" } ], "post": { "tags": [ "Approval Workflow" ], "security": [ { "OneIdOAuth": [] } ], "summary": "Delete several journal entries", "description": "**Purpose**\n\nDeletes one or more journal entries that have not been approved. Entries that cannot be deleted are reported individually.\n\n**When to use**\n\n* Clean up several draft or rejected entries in one call, for example after a failed batch load.\n\n**Notes**\n\n* Check `success` on the response and on every item in `results`. HTTP 200 is also returned when **every** entry failed; HTTP 207 means a mix of successes and failures.\n* Each `results` item currently reports the entry inside `message`; `id` may be omitted.", "operationId": "bulkDeleteJournalEntries", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional client-generated unique key (for example a UUID). Accepted for forward compatibility; **not currently enforced** - the service does not de-duplicate retries, so do not rely on it to prevent duplicate entries.", "schema": { "type": "string" }, "example": "6f1c2c3e-0b7a-4d1e-9a51-1f1e2a3b4c5d" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusRequest" }, "examples": { "example": { "summary": "Delete several journal entries", "value": { "jeIds": [ 10045, 10046 ] } } } } } }, "responses": { "200": { "description": "All entries deleted", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkActionResponse" }, "examples": { "allEntriesDeleted": { "summary": "All entries deleted", "value": { "success": true, "results": [ { "success": true, "message": "Journal entry 10045 deleted successfully" }, { "success": true, "message": "Journal entry 10046 deleted successfully" } ] } }, "allFailed": { "summary": "Every entry was refused (still HTTP 200)", "value": { "success": false, "results": [ { "success": false, "code": "BUSINESS_RULE_VIOLATION", "message": "Journal entry 10046 failed to delete." } ] } } } } } }, "207": { "description": "Some entries succeeded and some failed", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkActionResponse" }, "examples": { "someEntriesSucceededAndSomeFailed": { "summary": "Some entries succeeded and some failed", "value": { "success": false, "results": [ { "success": true, "message": "Journal entry 10045 deleted successfully" }, { "success": false, "code": "BUSINESS_RULE_VIOLATION", "message": "Journal entry 10046 failed to delete." } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenEdit" }, "429": { "$ref": "#/components/responses/MjeTooManyRequests" }, "500": { "$ref": "#/components/responses/UnexpectedError" }, "502": { "description": "Action rejected; Journal entry service unavailable", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "actionRejected": { "summary": "Action rejected", "description": "The journal entry processing service refused the whole request, for example because the entries are in a status that does not allow this action.", "value": { "success": false, "reasons": [ { "code": "500 INTERNAL_SERVER_ERROR", "message": "500 Internal Server Error: \"Not Allowed .Please check the object status and your role\"" } ] } }, "journalEntryServiceUnavailable": { "$ref": "#/components/examples/ServiceUnavailable" } } } } } } } }, "/journal-entries/privileges": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Zuora Revenue API (base URL)" } ], "post": { "tags": [ "Approval Workflow" ], "security": [ { "OneIdOAuth": [] } ], "summary": "Check allowed actions", "description": "**Purpose**\n\nTells you which actions (submit, approve, reject, recall, delete, update, reverse) the caller may perform on the selected journal entries right now, considering their status, the approval rule, soft freeze and the caller's role. Call it before showing action buttons or before running an automated workflow step.\n\n**When to use**\n\n* Decide which actions to offer a user (show or hide Submit, Approve, Delete ... buttons) in your own UI.\n* Check up front, in an automated workflow, whether a step will be allowed before calling it.", "operationId": "getJournalEntryPrivileges", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivilegesRequest" }, "examples": { "single": { "summary": "One entry", "value": { "jeIds": [ 10045 ], "bookId": 1 } } } } } }, "responses": { "200": { "description": "Allowed actions", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Privileges" }, "examples": { "allowedActions": { "summary": "Allowed actions", "value": { "submitAllowed": true, "approveAllowed": false, "rejectAllowed": false, "recallAllowed": false, "deleteAllowed": true, "updateAllowed": true, "revertAllowed": false } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenEdit" }, "429": { "$ref": "#/components/responses/MjeTooManyRequests" }, "500": { "description": "Malformed body; Unexpected error", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "malformedBody": { "summary": "Malformed body", "description": "The body is not valid JSON or `jeIds` is not an array of integers.", "value": { "success": false, "reasons": [ { "code": "SystemError", "message": "internal server error" } ] } }, "unexpectedError": { "$ref": "#/components/examples/UnexpectedError" } } } } }, "502": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/journal-entries/{jeId}/events": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Zuora Revenue API (base URL)" } ], "get": { "tags": [ "Approval Workflow" ], "security": [ { "OneIdOAuth": [] } ], "summary": "List journal entry audit events", "description": "**Purpose**\n\nReturns the audit trail of a journal entry: who saved, updated, submitted, approved, rejected, recalled or deleted it, when, and with which comment.\n\n**When to use**\n\n* Audit and compliance reviews: who created, changed, submitted, approved or rejected an entry, and when.\n* Show the history and approval comments of an entry.", "operationId": "listJournalEntryEvents", "parameters": [ { "name": "jeId", "in": "path", "required": true, "description": "ID of the journal entry.", "schema": { "type": "integer", "format": "int64" }, "example": 10045 } ], "responses": { "200": { "description": "Audit events (oldest first)", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AuditEvent" } }, "examples": { "auditEventsOldestFirst": { "summary": "Audit events (oldest first)", "value": [ { "id": 900001, "action": "SAVE", "headerId": 10045, "bookId": 1, "clientId": 1, "createdPeriodId": 202609, "createdBy": "jane.doe@example.com", "createdDate": "2026-09-28 10:21:04", "secAtrValue": "101" }, { "id": 900002, "action": "SUBMIT", "headerId": 10045, "comments": "Ready for September close review", "bookId": 1, "clientId": 1, "createdPeriodId": 202609, "createdBy": "jane.doe@example.com", "createdDate": "2026-09-28 11:02:44", "secAtrValue": "101" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenRead" }, "429": { "$ref": "#/components/responses/MjeTooManyRequests" }, "500": { "description": "Non-numeric ID; Unexpected error", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "nonNumericId": { "summary": "Non-numeric ID", "description": "`jeId` is not an integer.", "value": { "success": false, "reasons": [ { "code": "SystemError", "message": "internal server error" } ] } }, "unexpectedError": { "$ref": "#/components/examples/UnexpectedError" } } } } }, "502": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/journal-entries/{jeId}/validation-status": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Zuora Revenue API (base URL)" } ], "get": { "tags": [ "Approval Workflow" ], "security": [ { "OneIdOAuth": [] } ], "summary": "Retrieve the validation status", "description": "**Purpose**\n\nReturns the progress of asynchronous line validation for a journal entry. Poll after create or update; submit when the status is `Validated`. When it is `Error`, read the lines' `errorMessage` values (GET /journal-entries/{jeId}/lines) and correct them.\n\n**When to use**\n\n* Poll after create or update until validation finishes, then either submit (`Validated`) or fix the lines (`Error`).\n\n**Notes**\n\n* For an ID that does not exist, the call returns HTTP 200 with an empty `validationStatus`.", "operationId": "getJournalEntryValidationStatus", "parameters": [ { "name": "jeId", "in": "path", "required": true, "description": "ID of the journal entry.", "schema": { "type": "integer", "format": "int64" }, "example": 10045 } ], "responses": { "200": { "description": "Validation status", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationStatusResponse" }, "examples": { "validationStatus": { "summary": "Validation status", "value": { "id": 10045, "validationStatus": "Validated" } }, "errors": { "summary": "Validation found errors", "value": { "id": 10045, "validationStatus": "Error" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenRead" }, "429": { "$ref": "#/components/responses/MjeTooManyRequests" }, "500": { "description": "Non-numeric ID; Unexpected error", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "nonNumericId": { "summary": "Non-numeric ID", "description": "`jeId` is not an integer.", "value": { "success": false, "reasons": [ { "code": "SystemError", "message": "internal server error" } ] } }, "unexpectedError": { "$ref": "#/components/examples/UnexpectedError" } } } } }, "502": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/journal-entries/metadata": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Zuora Revenue API (base URL)" } ], "get": { "tags": [ "Reference Data" ], "security": [ { "OneIdOAuth": [] } ], "summary": "Retrieve reference data", "description": "**Purpose**\n\nReturns the lists of valid values you need to build a journal entry: books, organizations, category codes, exchange rate types, approval and functional currencies, Set of Books names, GL transfer values, accounting methods, account types, accounting segments, VC types and cost types. Call it once and cache the result. Period lists are returned by GET /journal-entries/metadata/periods.\n\n**When to use**\n\n* Before building entries: get the valid books, organizations, categories, exchange rate types, account types, currencies and other code lists.\n* Populate drop-downs in your own UI, or validate data in your source system before sending it. Cache the result.", "operationId": "getJournalEntryMetadata", "responses": { "200": { "description": "Reference data", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Metadata" }, "examples": { "referenceData": { "summary": "Reference data", "value": { "createDate": "2026-10-07", "bookId": [ { "id": 1, "name": "Primary Book" } ], "orgId": [ { "id": 101, "name": "US Operations" } ], "categoryId": [ { "key": "ACCRUAL", "value": "Accrual" }, { "key": "RECLASS", "value": "Reclassification" } ], "exchangeRates": [ { "key": "User", "value": "User" }, { "key": "Corporate", "value": "Corporate" } ], "approvalCurrency": [ "USD", "EUR" ], "sobName": [ "US Primary SOB" ], "functionalCurrency": [ "USD" ], "glTransfer": [ "YES", "NO" ], "accountingMethod": [ { "key": "Standard", "value": "Standard" } ], "accountTypes": [ { "key": "Revenue", "value": "Revenue" }, { "key": "Contract Liability", "value": "Contract Liability" } ], "accountingSegments": [ { "key": "Company", "value": "Company" }, { "key": "Department", "value": "Department" }, { "key": "Account", "value": "Account" } ], "vcTypes": [ { "key": "Rebate", "value": "Rebate" } ], "costTypes": [ { "key": "Commission", "value": "Commission" } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenRead" }, "429": { "$ref": "#/components/responses/MjeTooManyRequests" }, "500": { "$ref": "#/components/responses/UnexpectedError" }, "502": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/journal-entries/metadata/periods": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Zuora Revenue API (base URL)" } ], "get": { "tags": [ "Reference Data" ], "security": [ { "OneIdOAuth": [] } ], "summary": "List posting and reversal periods", "description": "**Purpose**\n\nReturns the posting periods and reversal periods available for a book (and optionally an organization). Use the returned `id` as `periodId` or `reversalPeriodId`.\n\n**When to use**\n\n* Find which periods are open for posting (`periodId`) or available for reversal (`reversalPeriodId`) for a book and organization.", "operationId": "getJournalEntryPeriods", "parameters": [ { "name": "bookId", "in": "query", "required": true, "description": "Accounting book ID.", "schema": { "type": "integer", "format": "int32" }, "example": 1 }, { "name": "orgId", "in": "query", "required": false, "description": "Organization ID. **Supply it** - omitting it currently causes an error.", "schema": { "type": "string" }, "example": "101" }, { "name": "isJeApproved", "in": "query", "required": false, "description": "Set to `true` to get the periods that apply to an approved entry (for example when choosing a reversal period).", "schema": { "type": "boolean" }, "example": false } ], "responses": { "200": { "description": "Periods", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Metadata" }, "examples": { "periods": { "summary": "Periods", "value": { "postingPeriod": [ { "id": 202609, "name": "SEP-2026" }, { "id": 202610, "name": "OCT-2026" } ], "reversalPeriod": [ { "id": 202610, "name": "OCT-2026" }, { "id": 202611, "name": "NOV-2026" } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenRead" }, "429": { "$ref": "#/components/responses/MjeTooManyRequests" }, "500": { "description": "bookId missing; Unexpected error", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "bookidMissing": { "summary": "bookId missing", "description": "The required `bookId` query parameter is missing or not an integer.", "value": { "success": false, "reasons": [ { "code": "SystemError", "message": "internal server error" } ] } }, "unexpectedError": { "$ref": "#/components/examples/UnexpectedError" } } } } }, "502": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/journal-entries/configurations": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Zuora Revenue API (base URL)" } ], "get": { "tags": [ "Reference Data" ], "security": [ { "OneIdOAuth": [] } ], "summary": "Retrieve field configuration", "description": "**Purpose**\n\nReturns your tenant's journal entry field configuration, such as the labels assigned to `reference1`...`reference15`.\n\n**When to use**\n\n* Learn your tenant's labels for configurable fields (for example what `reference1` means) so you can map your data to the right fields.", "operationId": "getJournalEntryConfigurations", "responses": { "200": { "description": "Field configuration", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Configurations" }, "examples": { "fieldConfiguration": { "summary": "Field configuration", "value": { "fields": [ { "code": "REFERENCE1", "value": "Ticket Number", "sequence": 29 }, { "code": "REFERENCE2", "value": "Source System", "sequence": 30 } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenRead" }, "429": { "$ref": "#/components/responses/MjeTooManyRequests" }, "500": { "$ref": "#/components/responses/UnexpectedError" }, "502": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/journal-entries/current-period": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Zuora Revenue API (base URL)" } ], "get": { "tags": [ "Reference Data" ], "security": [ { "OneIdOAuth": [] } ], "summary": "Retrieve the current open period", "description": "**Purpose**\n\nReturns the current open accounting period for a book (and optionally an organization). Handy as the default `periodId` for new entries.\n\n**When to use**\n\n* Default the posting period of a new entry to the current open period.", "operationId": "getCurrentOpenPeriod", "parameters": [ { "name": "bookId", "in": "query", "required": true, "description": "Accounting book ID.", "schema": { "type": "integer", "format": "int32" }, "example": 1 }, { "name": "orgId", "in": "query", "required": false, "description": "Organization ID. **Supply it** - omitting it currently causes an error.", "schema": { "type": "string" }, "example": "101" } ], "responses": { "200": { "description": "Current open period", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrentPeriod" }, "examples": { "currentOpenPeriod": { "summary": "Current open period", "value": { "periodId": 202610, "periodDisplayValue": "OCT-2026" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenRead" }, "429": { "$ref": "#/components/responses/MjeTooManyRequests" }, "500": { "description": "bookId missing; Unexpected error", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "bookidMissing": { "summary": "bookId missing", "description": "The required `bookId` query parameter is missing or not an integer.", "value": { "success": false, "reasons": [ { "code": "SystemError", "message": "internal server error" } ] } }, "unexpectedError": { "$ref": "#/components/examples/UnexpectedError" } } } } }, "502": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/journal-entries/currencies": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Zuora Revenue API (base URL)" } ], "get": { "tags": [ "Reference Data" ], "security": [ { "OneIdOAuth": [] } ], "summary": "List transaction currencies", "description": "**Purpose**\n\nReturns the ISO 4217 currency codes that can be used as a line `currency`.\n\n**When to use**\n\n* Validate or offer the transaction currencies that can be used on lines.", "operationId": "listJournalEntryCurrencies", "responses": { "200": { "description": "Currency codes", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } }, "examples": { "currencyCodes": { "summary": "Currency codes", "value": [ "USD", "EUR", "GBP", "JPY" ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenRead" }, "429": { "$ref": "#/components/responses/MjeTooManyRequests" }, "500": { "$ref": "#/components/responses/UnexpectedError" }, "502": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/journal-entries/functional-currencies": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Zuora Revenue API (base URL)" } ], "get": { "tags": [ "Reference Data" ], "security": [ { "OneIdOAuth": [] } ], "summary": "List functional currencies for a Set of Books", "description": "**Purpose**\n\nReturns the functional currency codes available for a Set of Books. Use it to fill `functionalCurrency` on the header.\n\n**When to use**\n\n* Fill or validate the header `functionalCurrency` for a chosen Set of Books.", "operationId": "listFunctionalCurrencies", "parameters": [ { "name": "sobName", "in": "query", "required": true, "description": "Set of Books name (from `sobName` in GET /journal-entries/metadata).", "schema": { "type": "string" }, "example": "US Primary SOB" } ], "responses": { "200": { "description": "Functional currencies", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } }, "examples": { "functionalCurrencies": { "summary": "Functional currencies", "value": [ "USD" ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenRead" }, "429": { "$ref": "#/components/responses/MjeTooManyRequests" }, "500": { "description": "sobName missing; Unexpected error", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "sobnameMissing": { "summary": "sobName missing", "description": "The required `sobName` query parameter is missing.", "value": { "success": false, "reasons": [ { "code": "SystemError", "message": "internal server error" } ] } }, "unexpectedError": { "$ref": "#/components/examples/UnexpectedError" } } } } }, "502": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/journal-entries/{jeId}/summary": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Zuora Revenue API (base URL)" } ], "get": { "tags": [ "Reference Data" ], "security": [ { "OneIdOAuth": [] } ], "summary": "Retrieve debit and credit totals", "description": "**Purpose**\n\nReturns the total debits, credits and net amount of a journal entry in transaction, functional and reporting currency. A balanced entry has `netAmt` = `0.00`.\n\n**When to use**\n\n* Check that an entry is balanced (`netAmt` = `0.00`) and see its totals before submitting or approving.\n* Control totals for reconciliation with the source system.", "operationId": "getJournalEntrySummary", "parameters": [ { "name": "jeId", "in": "path", "required": true, "description": "ID of the journal entry.", "schema": { "type": "integer", "format": "int64" }, "example": 10045 } ], "responses": { "200": { "description": "Totals by currency type", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SummaryValue" } }, "examples": { "totalsByCurrencyType": { "summary": "Totals by currency type", "value": [ { "currencyType": "Transaction", "currency": "USD", "drAmt": "1500.00", "crAmt": "1500.00", "netAmt": "0.00" }, { "currencyType": "Functional", "currency": "USD", "drAmt": "1500.00", "crAmt": "1500.00", "netAmt": "0.00" }, { "currencyType": "Reporting", "currency": "USD", "drAmt": "1500.00", "crAmt": "1500.00", "netAmt": "0.00" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenRead" }, "429": { "$ref": "#/components/responses/MjeTooManyRequests" }, "500": { "description": "Non-numeric ID; Unexpected error", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "nonNumericId": { "summary": "Non-numeric ID", "description": "`jeId` is not an integer.", "value": { "success": false, "reasons": [ { "code": "SystemError", "message": "internal server error" } ] } }, "unexpectedError": { "$ref": "#/components/examples/UnexpectedError" } } } } }, "502": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/journal-entries/soft-freeze-check": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Zuora Revenue API (base URL)" } ], "get": { "tags": [ "Reference Data" ], "security": [ { "OneIdOAuth": [] } ], "summary": "Check the soft-freeze status", "description": "**Purpose**\n\nReturns, for each book and organization available to the caller, whether a soft freeze is in effect. During a soft freeze (typically during period close) journal entry changes are restricted.\n\n**When to use**\n\n* Before creating or changing entries during period close, to know whether changes are currently restricted for a book and organization.", "operationId": "checkSoftFreeze", "responses": { "200": { "description": "Soft-freeze state", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SoftFreeze" } }, "examples": { "softFreezeState": { "summary": "Soft-freeze state", "value": [ { "bookId": 1, "secAtrVal": "101", "softFreezeApplied": false }, { "bookId": 1, "secAtrVal": "102", "softFreezeApplied": true } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenRead" }, "429": { "$ref": "#/components/responses/MjeTooManyRequests" }, "500": { "$ref": "#/components/responses/UnexpectedError" }, "502": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/journal-entries/role": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Zuora Revenue API (base URL)" } ], "get": { "tags": [ "Reference Data" ], "security": [ { "OneIdOAuth": [] } ], "summary": "Retrieve the caller's access level", "description": "**Purpose**\n\nReturns the caller's level of access to manual journal entries: `FULL_ACCESS`, `READ_ONLY` or `NONE`.\n\n**When to use**\n\n* Find out whether the API user (or the user your integration acts for) has full, read-only or no access to manual journal entries.", "operationId": "getJournalEntryUserRole", "responses": { "200": { "description": "Access level", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserRole" }, "examples": { "accessLevel": { "summary": "Access level", "value": { "role": "FULL_ACCESS" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenRead" }, "429": { "$ref": "#/components/responses/MjeTooManyRequests" }, "500": { "$ref": "#/components/responses/UnexpectedError" }, "502": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/journal-entries/describe": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Zuora Revenue API (base URL)" } ], "get": { "tags": [ "Reference Data" ], "security": [ { "OneIdOAuth": [] } ], "summary": "List journal entry object definitions", "description": "**Purpose**\n\nReturns the column catalog (name, label, data type, order) of the journal entry header (`jeHead`), line (`jeLine`) and schedule (`rcSchedule`) objects, with your tenant's custom labels applied. Use it to build field mappings for integrations or CSV uploads.\n\n**When to use**\n\n* Build or maintain a field mapping between your system and Zuora Revenue (header, line and schedule columns), including your tenant's custom labels.\n* Generate your own CSV templates or validation rules.", "operationId": "describeJournalEntryObjects", "parameters": [ { "name": "object", "in": "query", "required": false, "description": "Return only one object. Case-insensitive.", "schema": { "type": "string", "enum": [ "jeHead", "jeLine", "rcSchedule" ] }, "example": "jeLine" } ], "responses": { "200": { "description": "Column catalog", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DescribeResponse" }, "examples": { "columnCatalog": { "summary": "Column catalog", "value": { "objects": { "jeLine": { "columns": [ { "name": "JE_SET_NO", "label": "JE Set No", "dataType": "id", "sequence": 1 }, { "name": "DR_ACTIVITY_TYPE", "label": "Dr Activity Type", "dataType": "string", "sequence": 2 }, { "name": "DR_SEGMENTS", "label": "Account Code", "dataType": "string", "sequence": 3 }, { "name": "REFERENCE1", "label": "Ticket Number", "dataType": "string", "sequence": 29 } ] } } } } } } } }, "400": { "description": "Unknown object", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unknownObject": { "summary": "Unknown object", "description": "`object` is not `jeHead`, `jeLine` or `rcSchedule`.", "value": { "success": false, "reasons": [ { "code": "INVALID_VALUE", "message": "The parameter 'object' has an invalid value: 'jeHeader'. Expected one of: jeHead, jeLine, rcSchedule.", "field": "object" } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenRead" }, "429": { "$ref": "#/components/responses/MjeTooManyRequests" }, "500": { "$ref": "#/components/responses/UnexpectedError" }, "502": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/journal-entries/rc-redirection": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Zuora Revenue API (base URL)" } ], "get": { "tags": [ "Reference Data" ], "security": [ { "OneIdOAuth": [] } ], "summary": "Retrieve the revenue contract for an RC, sales order, or line", "description": "**Purpose**\n\nResolves the revenue contract (RC) that contains a given revenue contract ID, sales order number or line ID, so you can link a journal entry line to its contract.\n\n**When to use**\n\n* You have a sales order number, line ID or RC ID and need the revenue contract to link a journal entry line to (`rcId`).", "operationId": "getRevenueContractRedirection", "parameters": [ { "name": "type", "in": "query", "required": true, "description": "What `id` represents: `RC` (revenue contract ID), `SO` (sales order number) or `LINE` (line ID). Case-insensitive.", "schema": { "type": "string", "enum": [ "RC", "SO", "LINE" ] }, "example": "SO" }, { "name": "id", "in": "query", "required": true, "description": "The identifier to resolve.", "schema": { "type": "string" }, "example": "SO-50012" }, { "name": "bookId", "in": "query", "required": true, "description": "Accounting book ID.", "schema": { "type": "integer", "format": "int32" }, "example": 1 } ], "responses": { "200": { "description": "Revenue contract found", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RcRedirection" }, "examples": { "revenueContractFound": { "summary": "Revenue contract found", "value": { "rcId": 1001, "retCode": "0", "errMsg": null } }, "notFound": { "summary": "No contract found (still HTTP 200)", "value": { "rcId": null, "retCode": "1", "errMsg": "Invalid Id" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenRead" }, "429": { "$ref": "#/components/responses/MjeTooManyRequests" }, "500": { "description": "Invalid type; Unexpected error", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalidType": { "summary": "Invalid type", "description": "`type` is not `RC`, `SO` or `LINE`, or a required parameter is missing.", "value": { "success": false, "reasons": [ { "code": "SystemError", "message": "internal server error" } ] } }, "unexpectedError": { "$ref": "#/components/examples/UnexpectedError" } } } } }, "502": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/journal-entries/{jeId}/attachments": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Zuora Revenue API (base URL)" } ], "post": { "tags": [ "Attachments" ], "security": [ { "OneIdOAuth": [] } ], "summary": "Upload an attachment", "description": "**Purpose**\n\nAttaches a supporting file (for example a calculation workbook or approval email) to a journal entry, optionally with a note and a link. Files up to 100 MB are accepted.\n\n**When to use**\n\n* Attach supporting evidence (calculation workbook, approval email, contract) or a note/link to an entry, typically before submitting it for approval.", "operationId": "uploadJournalEntryAttachment", "parameters": [ { "name": "jeId", "in": "path", "required": true, "description": "ID of the journal entry.", "schema": { "type": "integer", "format": "int64" }, "example": 10045 }, { "name": "bookId", "in": "query", "required": true, "description": "Accounting book ID of the journal entry.", "schema": { "type": "integer", "format": "int32" }, "example": 1 }, { "name": "comments", "in": "query", "required": false, "description": "Note stored with the attachment.", "schema": { "type": "string" }, "example": "Supporting calculation" }, { "name": "addLink", "in": "query", "required": false, "description": "Optional URL stored with the attachment.", "schema": { "type": "string" }, "example": "https://example.com/docs/123" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/AttachmentUploadRequest" }, "examples": { "file": { "summary": "Upload a workbook", "value": { "file": "(binary content of support.xlsx)" } } } } } }, "responses": { "200": { "description": "Attachment uploaded", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentUploadResponse" }, "examples": { "attachmentUploaded": { "summary": "Attachment uploaded", "value": { "status": "success", "message": "Notes/Attachments are successfully uploaded" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenEdit" }, "413": { "description": "File too large", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformErrorResponse" }, "examples": { "fileTooLarge": { "summary": "File too large", "description": "The file exceeds the 100 MB upload limit.", "value": { "timestamp": "2026-10-07T10:15:30.123+00:00", "status": 413, "error": "Payload Too Large", "message": "Maximum upload size exceeded", "path": "/journal-entries/10045/attachments" } } } } } }, "429": { "$ref": "#/components/responses/MjeTooManyRequests" }, "500": { "description": "File part or bookId missing; Unexpected error", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "filePartOrBookidMissing": { "summary": "File part or bookId missing", "description": "The `file` part or the `bookId` query parameter is missing.", "value": { "success": false, "reasons": [ { "code": "SystemError", "message": "internal server error" } ] } }, "unexpectedError": { "$ref": "#/components/examples/UnexpectedError" } } } } }, "502": { "description": "Executable file rejected; Journal entry service unavailable", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "executableFileRejected": { "summary": "Executable file rejected", "description": "Executable files (`.exe`, `.bat`, `.sh`, `.msi`, `.cmd`) cannot be attached.", "value": { "success": false, "reasons": [ { "code": "400 BAD_REQUEST", "message": "400 Bad Request: \"{\"status\":\"failure\",\"message\":\"Executable files are not allowed\"}\"" } ] } }, "journalEntryServiceUnavailable": { "$ref": "#/components/examples/ServiceUnavailable" } } } } } } }, "get": { "tags": [ "Attachments" ], "security": [ { "OneIdOAuth": [] } ], "summary": "List journal entry attachments", "description": "**Purpose**\n\nLists the files and notes attached to a journal entry.\n\n**When to use**\n\n* See which supporting documents and notes an entry has, for example during approval or audit.", "operationId": "listJournalEntryAttachments", "parameters": [ { "name": "jeId", "in": "path", "required": true, "description": "ID of the journal entry.", "schema": { "type": "integer", "format": "int64" }, "example": 10045 }, { "name": "bookId", "in": "query", "required": true, "description": "Accounting book ID of the journal entry.", "schema": { "type": "integer", "format": "int32" }, "example": 1 } ], "responses": { "200": { "description": "Attachments (may be empty)", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Attachment" } }, "examples": { "attachmentsMayBeEmpty": { "summary": "Attachments (may be empty)", "value": [ { "id": 501, "fileName": "support.xlsx", "comments": "Supporting calculation", "addLink": null, "jeId": 10045, "bookId": 1, "contentType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", "fileSize": 18432, "crtdBy": "jane.doe@example.com", "crtdDt": "2026-09-28T11:05:00" } ] }, "none": { "summary": "No attachments", "value": [] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenRead" }, "429": { "$ref": "#/components/responses/MjeTooManyRequests" }, "500": { "description": "bookId missing; Unexpected error", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "bookidMissing": { "summary": "bookId missing", "description": "The required `bookId` query parameter is missing or not an integer.", "value": { "success": false, "reasons": [ { "code": "SystemError", "message": "internal server error" } ] } }, "unexpectedError": { "$ref": "#/components/examples/UnexpectedError" } } } } }, "502": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/journal-entries/{jeId}/attachments/{attachmentId}": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Zuora Revenue API (base URL)" } ], "delete": { "tags": [ "Attachments" ], "security": [ { "OneIdOAuth": [] } ], "summary": "Delete an attachment", "description": "**Purpose**\n\nDeletes an attachment from a journal entry.\n\n**When to use**\n\n* Remove an attachment that was added by mistake or replaced by a newer version.\n\n**Notes**\n\n* The attachment is identified by `attachmentId` alone. Make sure it belongs to the entry in the path.", "operationId": "deleteJournalEntryAttachment", "parameters": [ { "name": "jeId", "in": "path", "required": true, "description": "ID of the journal entry.", "schema": { "type": "integer", "format": "int64" }, "example": 10045 }, { "name": "attachmentId", "in": "path", "required": true, "description": "ID of the attachment.", "schema": { "type": "integer", "format": "int64" }, "example": 501 } ], "responses": { "204": { "description": "Attachment deleted (no response body)", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenEdit" }, "429": { "$ref": "#/components/responses/MjeTooManyRequests" }, "500": { "$ref": "#/components/responses/UnexpectedError" }, "502": { "description": "Invalid attachment ID; Journal entry service unavailable", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalidAttachmentId": { "summary": "Invalid attachment ID", "description": "The attachment does not exist.", "value": { "success": false, "reasons": [ { "code": "400 BAD_REQUEST", "message": "400 Bad Request: \"{\"status\":\"failure\",\"message\":\"The provided attachment ID is invalid\"}\"" } ] } }, "journalEntryServiceUnavailable": { "$ref": "#/components/examples/ServiceUnavailable" } } } } } } } }, "/journal-entries/{jeId}/attachments/{attachmentId}/download": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Zuora Revenue API (base URL)" } ], "get": { "tags": [ "Attachments" ], "security": [ { "OneIdOAuth": [] } ], "summary": "Download an attachment", "description": "**Purpose**\n\nDownloads an attachment. For files stored in cloud storage the response is JSON with a short-lived presigned `url` - fetch the file from that URL with a plain GET (no Authorization header). Older attachments are streamed directly as `application/octet-stream`.\n\n**When to use**\n\n* Retrieve a supporting document for review, audit or archiving.", "operationId": "downloadJournalEntryAttachment", "parameters": [ { "name": "jeId", "in": "path", "required": true, "description": "ID of the journal entry.", "schema": { "type": "integer", "format": "int64" }, "example": 10045 }, { "name": "attachmentId", "in": "path", "required": true, "description": "ID of the attachment.", "schema": { "type": "integer", "format": "int64" }, "example": 501 } ], "responses": { "200": { "description": "Presigned download URL (cloud-stored files)", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentDownloadUrl" }, "examples": { "presignedDownloadUrlCloudStoredFiles": { "summary": "Presigned download URL (cloud-stored files)", "value": { "url": "https://zr-attachments.s3.amazonaws.com/t1/je/10045/501?X-Amz-Expires=300&X-Amz-Signature=..." } } } }, "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenRead" }, "429": { "$ref": "#/components/responses/MjeTooManyRequests" }, "500": { "$ref": "#/components/responses/UnexpectedError" }, "502": { "description": "File not found; Journal entry service unavailable", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "fileNotFound": { "summary": "File not found", "description": "The attachment does not exist or has no file (for example a note-only entry).", "value": { "success": false, "reasons": [ { "code": "400 BAD_REQUEST", "message": "400 Bad Request: \"{\"status\":\"failure\",\"message\":\"The requested file could not be found\"}\"" } ] } }, "journalEntryServiceUnavailable": { "$ref": "#/components/examples/ServiceUnavailable" } } } } } } } }, "/journal-entries/template": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Zuora Revenue API (base URL)" } ], "get": { "tags": [ "Templates and Exports" ], "security": [ { "OneIdOAuth": [] } ], "summary": "Download the CSV upload template", "description": "**Purpose**\n\nDownloads the combined CSV template for POST /journal-entries (multipart). Row 1 holds the header column titles; fill row 2 with the header values, keep the blank line, then add one row per line under the line column titles. Column titles are matched case-insensitively ignoring spaces and punctuation; both friendly titles (for example `Account Code`, `Debit`) and legacy codes (for example `DR_SEGMENTS`, `AMOUNT`) are accepted. Reference columns show your tenant's labels; rename them to `Reference1` ... `Reference15` before uploading.\n\n**When to use**\n\n* Before preparing a CSV upload: get the exact column layout expected by POST /journal-entries (multipart).", "operationId": "downloadJournalEntryTemplate", "responses": { "200": { "description": "CSV template (`je-template.csv`)", "headers": { "traceId": { "$ref": "#/components/headers/traceId" }, "Content-Disposition": { "description": "Attachment file name, for example `attachment; filename=\"je-list.csv\"`.", "schema": { "type": "string" } } }, "content": { "text/csv": { "schema": { "type": "string" }, "example": "Name,Description,Category Code,Ex Rate Type,Period Name,Reversal Period Name,SOB Name,SOB ID,Functional Currency,Book Id,Org Id,GL Transfer,Rev Rec Type,Account Method,Approval Currency\n\n\nSet No,Account Type,Account Code,Currency,Debit,Credit,Ex Rate Date,Functional Ex Rate,Global Ex Rate,Start Date,End Date,So Line Id,Unbill Flag,Description,Rc Id,Rc Line Id,SO Number,Type Name,Cost Or Vc Type,Reference 1,...,Reference 15,Comments\n" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenRead" }, "429": { "$ref": "#/components/responses/MjeTooManyRequests" }, "500": { "$ref": "#/components/responses/UnexpectedError" }, "502": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/journal-entries/export": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Zuora Revenue API (base URL)" } ], "post": { "tags": [ "Templates and Exports" ], "security": [ { "OneIdOAuth": [] } ], "summary": "Export journal entries to CSV", "description": "**Purpose**\n\nExports journal entries matching the body criteria as CSV.\n\n**When to use**\n\n* Produce a CSV list of entries for reporting, audit or reconciliation in a spreadsheet.\n\n**Notes**\n\n* Body filter `fieldName` values are passed through as-is and must be one of: `id`, `name`, `description`, `reversalStatus`, `categoryCode`, `exRateType`, `periodId`, `status`, `reversalPeriodId`, `hashTotal`, `sobName`, `sobId`, `functionalCurrency`, `createdBy`, `createdDate`, `updatedBy`, `updatedDate`, `approverName`.\n* Exports return **all** matching rows; `pageNumber` and `pageSize` are not applied.\n* `values` must contain at least one element for every operator.", "operationId": "exportJournalEntries", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryRequest" }, "examples": { "all": { "summary": "Export all rows", "value": { "pageNumber": 1, "pageSize": 40, "filters": [] } } } } } }, "responses": { "200": { "description": "CSV file (`je-list.csv`)", "headers": { "traceId": { "$ref": "#/components/headers/traceId" }, "Content-Disposition": { "description": "Attachment file name, for example `attachment; filename=\"je-list.csv\"`.", "schema": { "type": "string" } } }, "content": { "text/csv": { "schema": { "type": "string" }, "example": "Name,ID,Description,Reversal Status,Category Code,Ex Rate Type,Period Name,Status,Reversal Period Name,Hash Total,SOB Name,SOB ID,Functional Currency,Created By,Creation Date,Last Updated By,Last Updated Date,Approver Name\nSEP-2026 Revenue Reclass,10045,Reclass deferred revenue,,RECLASS,User,SEP-2026,New,OCT-2026,3000,US Primary SOB,1,USD,jane.doe@example.com,2026-09-28,jane.doe@example.com,2026-09-28,\n" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenEdit" }, "429": { "$ref": "#/components/responses/MjeTooManyRequests" }, "500": { "description": "Missing body; Unexpected error", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missingBody": { "summary": "Missing body", "description": "The request body is missing or not valid JSON.", "value": { "success": false, "reasons": [ { "code": "SystemError", "message": "internal server error" } ] } }, "unexpectedError": { "$ref": "#/components/examples/UnexpectedError" } } } } }, "502": { "description": "Invalid filter; Journal entry service unavailable", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalidFilter": { "summary": "Invalid filter", "description": "A `fieldName` or `operator` in the body is not supported, or `values` is empty.", "value": { "success": false, "reasons": [ { "code": "500 INTERNAL_SERVER_ERROR", "message": "500 Internal Server Error: [no body]" } ] } }, "journalEntryServiceUnavailable": { "$ref": "#/components/examples/ServiceUnavailable" } } } } } } } }, "/journal-entries/{jeId}/lines/export": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Zuora Revenue API (base URL)" } ], "post": { "tags": [ "Templates and Exports" ], "security": [ { "OneIdOAuth": [] } ], "summary": "Export lines to CSV", "description": "**Purpose**\n\nExports the lines of a journal entry as CSV using the template column titles plus audit columns. The export has no line `ID` column; to use it for a full-file update (PATCH /journal-entries/{jeId}), add an `ID` column first.\n\n**When to use**\n\n* Download all lines of an entry to review or reconcile them in a spreadsheet.\n\n**Notes**\n\n* Body filter `fieldName` values are passed through as-is and must be one of: `id`, `headerId`, `clientId`, `orgId`, `createdBy`, `createdDate`, `updatedBy`, `updatedDate`, `bookId`, `rcId`, `rcLineId`, `currency`, `debit`, `credit`, `exchangeRateDate`, `exchangeRate`, `gexchangeRate`, `startDate`, `endDate`, `reason`, `errorMessage`, `description`, `comments`, `accountType`, `soLineId`, `soNum`, `costOrVcType`, `jeSetNo`, `accountCode`, `typeName`, `reference1`, `reference2`, `reference3`, `reference4`, `reference5`, `reference6`, `reference7`, `reference8`, `reference9`, `reference10`, `reference11`, `reference12`, `reference13`, `reference14`, `reference15`.\n* Exports return **all** matching rows; `pageNumber` and `pageSize` are not applied.\n* `values` must contain at least one element for every operator.", "operationId": "exportJournalEntryLines", "parameters": [ { "name": "jeId", "in": "path", "required": true, "description": "ID of the journal entry.", "schema": { "type": "integer", "format": "int64" }, "example": 10045 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryRequest" }, "examples": { "all": { "summary": "Export all rows", "value": { "pageNumber": 1, "pageSize": 40, "filters": [] } } } } } }, "responses": { "200": { "description": "CSV file (`je-lines-{jeId}.csv`)", "headers": { "traceId": { "$ref": "#/components/headers/traceId" }, "Content-Disposition": { "description": "Attachment file name, for example `attachment; filename=\"je-list.csv\"`.", "schema": { "type": "string" } } }, "content": { "text/csv": { "schema": { "type": "string" }, "example": "Set No,Account Type,Account Code,Currency,Debit,Credit,Ex Rate Date,Functional Ex Rate,Global Ex Rate,Start Date,End Date,...,Error Message,Org Id,Book Id,Created By\n1,Contract Liability,2400-100-000,USD,1500,,2026-09-30,1,1,2026-09-01,2026-09-30,...,,101,1,jane.doe@example.com\n1,Revenue,4000-100-000,USD,,1500,2026-09-30,1,1,2026-09-01,2026-09-30,...,,101,1,jane.doe@example.com\n" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenEdit" }, "429": { "$ref": "#/components/responses/MjeTooManyRequests" }, "500": { "description": "Missing body; Unexpected error", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missingBody": { "summary": "Missing body", "description": "The request body is missing or not valid JSON.", "value": { "success": false, "reasons": [ { "code": "SystemError", "message": "internal server error" } ] } }, "unexpectedError": { "$ref": "#/components/examples/UnexpectedError" } } } } }, "502": { "description": "Invalid filter; Journal entry service unavailable", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalidFilter": { "summary": "Invalid filter", "description": "A `fieldName` or `operator` in the body is not supported, or `values` is empty.", "value": { "success": false, "reasons": [ { "code": "500 INTERNAL_SERVER_ERROR", "message": "500 Internal Server Error: [no body]" } ] } }, "journalEntryServiceUnavailable": { "$ref": "#/components/examples/ServiceUnavailable" } } } } } } } }, "/journal-entries/{jeId}/schedules/export": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Zuora Revenue API (base URL)" } ], "post": { "tags": [ "Templates and Exports" ], "security": [ { "OneIdOAuth": [] } ], "summary": "Export schedules to CSV", "description": "**Purpose**\n\nExports the revenue schedules generated by a journal entry as CSV.\n\n**When to use**\n\n* Download the schedules of an entry for GL reconciliation or audit.\n\n**Notes**\n\n* Body filter `fieldName` values are passed through as-is and must be one of: `periodName`, `accountType`, `acountCode`, `currencyCode`, `drAmount`, `crAmount`, `funcDrAmount`, `funcCrAmount`, `rcurrDrAmount`, `rcurrCrAmount`, `schdRcId`.\n* Exports return **all** matching rows; `pageNumber` and `pageSize` are not applied.\n* `values` must contain at least one element for every operator.", "operationId": "exportJournalEntrySchedules", "parameters": [ { "name": "jeId", "in": "path", "required": true, "description": "ID of the journal entry.", "schema": { "type": "integer", "format": "int64" }, "example": 10045 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryRequest" }, "examples": { "all": { "summary": "Export all rows", "value": { "pageNumber": 1, "pageSize": 40, "filters": [] } } } } } }, "responses": { "200": { "description": "CSV file (`je-schedules-{jeId}.csv`)", "headers": { "traceId": { "$ref": "#/components/headers/traceId" }, "Content-Disposition": { "description": "Attachment file name, for example `attachment; filename=\"je-list.csv\"`.", "schema": { "type": "string" } } }, "content": { "text/csv": { "schema": { "type": "string" }, "example": "Period,Account Type,Account Code,Currency,Debit Amount,Credit Amount\nSEP-2026,Revenue,4000-100-000,USD,0,1500\n" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenEdit" }, "429": { "$ref": "#/components/responses/MjeTooManyRequests" }, "500": { "description": "Missing body; Unexpected error", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missingBody": { "summary": "Missing body", "description": "The request body is missing or not valid JSON.", "value": { "success": false, "reasons": [ { "code": "SystemError", "message": "internal server error" } ] } }, "unexpectedError": { "$ref": "#/components/examples/UnexpectedError" } } } } }, "502": { "description": "Invalid filter; Journal entry service unavailable", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalidFilter": { "summary": "Invalid filter", "description": "A `fieldName` or `operator` in the body is not supported, or `values` is empty.", "value": { "success": false, "reasons": [ { "code": "500 INTERNAL_SERVER_ERROR", "message": "500 Internal Server Error: [no body]" } ] } }, "journalEntryServiceUnavailable": { "$ref": "#/components/examples/ServiceUnavailable" } } } } } } } }, "/journal-entries/{jeId}/waterfall-entries/export": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Zuora Revenue API (base URL)" } ], "post": { "tags": [ "Templates and Exports" ], "security": [ { "OneIdOAuth": [] } ], "summary": "Export waterfall to CSV", "description": "**Purpose**\n\nExports the revenue waterfall of a journal entry as CSV (one column per period).\n\n**When to use**\n\n* Download the revenue waterfall of an entry (one column per period) for analysis or sharing with stakeholders.\n\n**Notes**\n\n* Body filter `fieldName` values are passed through as-is and must be one of: `jeSetNo`, `soNumber`, `soLineId`, `accountCode`, `jeAmount`, `startDate`, `endDate`, `accountType`.\n* Exports return **all** matching rows; `pageNumber` and `pageSize` are not applied.\n* `values` must contain at least one element for every operator.", "operationId": "exportJournalEntryWaterfall", "parameters": [ { "name": "jeId", "in": "path", "required": true, "description": "ID of the journal entry.", "schema": { "type": "integer", "format": "int64" }, "example": 10045 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryRequest" }, "examples": { "all": { "summary": "Export all rows", "value": { "pageNumber": 1, "pageSize": 40, "filters": [] } } } } } }, "responses": { "200": { "description": "CSV file (`je-waterfall-{jeId}.csv`)", "headers": { "traceId": { "$ref": "#/components/headers/traceId" }, "Content-Disposition": { "description": "Attachment file name, for example `attachment; filename=\"je-list.csv\"`.", "schema": { "type": "string" } } }, "content": { "text/csv": { "schema": { "type": "string" }, "example": "Set No,SO Number,SO Line ID,Account Code,JE Amount,Start Date,End Date,Account Type,SEP-2026,OCT-2026,NOV-2026\n1,SO-50012,SO-50012-1,4000-100-000,1500,2026-09-01,2026-11-30,Revenue,500.00,500.00,500.00\n" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenEdit" }, "429": { "$ref": "#/components/responses/MjeTooManyRequests" }, "500": { "description": "Missing body; Unexpected error", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missingBody": { "summary": "Missing body", "description": "The request body is missing or not valid JSON.", "value": { "success": false, "reasons": [ { "code": "SystemError", "message": "internal server error" } ] } }, "unexpectedError": { "$ref": "#/components/examples/UnexpectedError" } } } } }, "502": { "description": "Invalid filter; Journal entry service unavailable", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalidFilter": { "summary": "Invalid filter", "description": "A `fieldName` or `operator` in the body is not supported, or `values` is empty.", "value": { "success": false, "reasons": [ { "code": "500 INTERNAL_SERVER_ERROR", "message": "500 Internal Server Error: [no body]" } ] } }, "journalEntryServiceUnavailable": { "$ref": "#/components/examples/ServiceUnavailable" } } } } } } } }, "/contracts/list": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Production" } ], "get": { "tags": [ "Revenue Contracts" ], "operationId": "listRevenueContracts", "summary": "List revenue contracts", "description": "**Purpose**\n\nReturns a paginated list of revenue contract header records for the book.\n\n**When to use**\n\n- Build a contract inventory or reconcile Zuora Revenue contracts with an external system.\n- Look up contract IDs (`rcId`) before you call the line, hold, or Manual Action APIs.\n- Check `indicators` and amounts across many contracts in one pass.\n\n**Behavior notes**\n\nThe only filterable and sortable field is `id`.\n\n**Filtering**\n\nEvery query parameter other than `page`, `size`, and `sort` is treated as a filter.\n\n- `field=value` matches records where the field equals the value.\n- `field[op]=value` applies an operator. URL-encode the brackets as `%5B` and `%5D`, for example\n `id%5Bgt%5D=1000`. Operators: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `like` (supply `%` wildcards yourself).\n- All filters are combined with AND. At most 5 filters are allowed per request.\n- Blank filter values are ignored.\n- An unknown field or operator returns HTTP 400.\n", "parameters": [ { "$ref": "#/components/parameters/BookId" }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Size" }, { "name": "sort", "in": "query", "required": false, "description": "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`. When `sort` is omitted the order is not guaranteed, so always sort when paging through results.", "schema": { "type": "string" }, "example": "id,asc" }, { "name": "id", "in": "query", "required": false, "description": "Filter by revenue contract ID. Supports `id[op]` forms such as `id[gte]=100000`.", "schema": { "type": "integer", "format": "int64" }, "example": 111442 } ], "responses": { "200": { "description": "A page of records. An empty `data` array means no record matched.", "headers": { "traceId": { "$ref": "#/components/headers/TraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevenueContractHeadPage" }, "examples": { "firstPage": { "summary": "First page of contracts", "value": { "data": [ { "id": 111442, "bookId": 1, "indicators": { "allocationEligible": "Y", "multiCurrency": "N" }, "totalCarveAmount": "1250.00" } ], "page": { "number": 1, "size": 20, "totalElements": 57, "totalPages": 3, "first": true, "last": false } } }, "empty": { "summary": "No contract matched", "value": { "data": [], "page": { "number": 1, "size": 20, "totalElements": 0, "totalPages": 0, "first": true, "last": true } } } } } } }, "400": { "description": "The request is invalid. Correct the request and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractQueryErrorResponse" }, "examples": { "unknownFilter": { "summary": "Unsupported filter field", "value": { "error": "Cannot filter by: customerName. Supported filter fields: id" } }, "unknownSort": { "summary": "Unsupported sort field", "value": { "error": "Cannot sort by: bookId. Supported sort fields: id" } }, "pageSizeTooLarge": { "summary": "Page size above 100", "value": { "error": "Page size exceeds maximum. Maximum allowed: 100, requested: 500" } }, "pageSizeNotPositive": { "summary": "Page size zero or negative", "value": { "error": "Page size must be positive. Requested: 0" } }, "negativePage": { "summary": "Negative page number", "value": { "error": "Page number must be non-negative. Requested: -1" } }, "invalidPage": { "summary": "Non-numeric page", "value": { "error": "Invalid value 'x' for parameter 'page': expected a valid Integer" } }, "tooManyFilters": { "summary": "More than five filters", "value": { "error": "Too many filters. Maximum allowed: 5, provided: 6" } }, "unsupportedOperator": { "summary": "Unsupported filter operator", "value": { "error": "Unsupported operator: 'between'. Supported operators: eq, ne, gt, gte, lt, lte, like, in, nin" } } } } } }, "500": { "description": "Unexpected failure inside Zuora Revenue, such as a database error or a non-numeric value supplied for a numeric filter. Retry later; contact Zuora Global Support if it persists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractQueryErrorResponse" }, "examples": { "internalError": { "summary": "Internal server error", "value": { "error": "Internal server error" } } } } } } } } }, "/contracts/{rcId}": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Production" } ], "get": { "tags": [ "Revenue Contracts" ], "operationId": "getRevenueContract", "summary": "Retrieve a revenue contract", "description": "**Purpose**\n\nReturns the header record of one revenue contract.\n\n**When to use**\n\n- Read the current state, indicators, and amounts of a contract before you perform a manual action.\n- Confirm that a contract exists in the book you are working in.\n", "parameters": [ { "$ref": "#/components/parameters/RcId" }, { "$ref": "#/components/parameters/BookId" }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "The revenue contract header.", "headers": { "traceId": { "$ref": "#/components/headers/TraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevenueContractHead" }, "examples": { "contract": { "summary": "Revenue contract", "value": { "id": 111442, "bookId": 1, "indicators": { "allocationEligible": "Y", "multiCurrency": "N" }, "totalCarveAmount": "1250.00" } } } } } }, "400": { "description": "The request is invalid. Correct the request and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractQueryErrorResponse" }, "examples": { "invalidRcId": { "summary": "Non-numeric rcId", "value": { "error": "Invalid value 'abc' for parameter 'rcId': expected a valid Long" } } } } } }, "404": { "description": "The revenue contract does not exist in this tenant and book, or the caller's organization cannot see it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractQueryErrorResponse" }, "examples": { "notFound": { "summary": "Revenue contract not found", "value": { "error": "Revenue contract 999999 not found" } } } } } }, "500": { "description": "Unexpected failure inside Zuora Revenue, such as a database error or a non-numeric value supplied for a numeric filter. Retry later; contact Zuora Global Support if it persists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractQueryErrorResponse" }, "examples": { "internalError": { "summary": "Internal server error", "value": { "error": "Internal server error" } } } } } } } } }, "/contracts/{rcId}/lines": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Production" } ], "get": { "tags": [ "Revenue Contract Lines" ], "operationId": "listRevenueContractLines", "summary": "List lines of a revenue contract", "description": "**Purpose**\n\nReturns a paginated list of the transaction lines grouped into one revenue contract.\n\n**When to use**\n\n- Review the sales order, contract, and invoice lines that make up a contract.\n- Find line IDs, POB IDs, and charge numbers to use in Manual Action calls such as edit line, line-level holds, or variable consideration.\n\n**Behavior notes**\n\nA contract that does not exist returns HTTP 200 with an empty `data` array, not HTTP 404.\n\n**Filtering**\n\nEvery query parameter other than `page`, `size`, and `sort` is treated as a filter.\n\n- `field=value` matches records where the field equals the value.\n- `field[op]=value` applies an operator. URL-encode the brackets as `%5B` and `%5D`, for example\n `id%5Bgt%5D=1000`. Operators: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `like` (supply `%` wildcards yourself).\n- All filters are combined with AND. At most 5 filters are allowed per request.\n- Blank filter values are ignored.\n- An unknown field or operator returns HTTP 400.\n", "parameters": [ { "$ref": "#/components/parameters/RcId" }, { "$ref": "#/components/parameters/BookId" }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Size" }, { "name": "sort", "in": "query", "required": false, "description": "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`, `rcId`, `rcPobId`, `batchId`, `chargeNumber`. When `sort` is omitted the order is not guaranteed, so always sort when paging through results.", "schema": { "type": "string" }, "example": "id,asc" }, { "name": "id", "in": "query", "required": false, "description": "Filter by revenue contract line ID.", "schema": { "type": "integer", "format": "int64" }, "example": 85922 }, { "name": "rcPobId", "in": "query", "required": false, "description": "Filter by performance obligation (POB) ID.", "schema": { "type": "integer", "format": "int64" }, "example": 156912 }, { "name": "batchId", "in": "query", "required": false, "description": "Filter by the data-collection batch that created the line.", "schema": { "type": "integer", "format": "int64" }, "example": 5001 }, { "name": "chargeNumber", "in": "query", "required": false, "description": "Filter by Zuora Billing rate plan charge number.", "schema": { "type": "string" }, "example": "C-00012345" } ], "responses": { "200": { "description": "A page of records. An empty `data` array means no record matched.", "headers": { "traceId": { "$ref": "#/components/headers/TraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevenueContractLinePage" }, "examples": { "firstPage": { "summary": "Lines of a contract", "value": { "data": [ { "id": 85922, "rcId": 111442, "indicators": { "allocationEligible": "Y" }, "stringAttributes": { "atr1": "EMEA", "atr2": null }, "numberAttributes": { "num1": "12.50", "num2": null }, "dateAttributes": { "date1": "2026-01-31", "date2": null }, "rcLineOtrAttributes": { "rpcNum": "C-00012345" } } ], "page": { "number": 1, "size": 20, "totalElements": 1, "totalPages": 1, "first": true, "last": true } } }, "empty": { "summary": "No line matched", "value": { "data": [], "page": { "number": 1, "size": 20, "totalElements": 0, "totalPages": 0, "first": true, "last": true } } } } } } }, "400": { "description": "The request is invalid. Correct the request and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractQueryErrorResponse" }, "examples": { "unknownFilter": { "summary": "Unsupported filter field", "value": { "error": "Cannot filter by: lineId. Supported filter fields: id, rcId, rcPobId, batchId, chargeNumber" } }, "unknownSort": { "summary": "Unsupported sort field", "value": { "error": "Cannot sort by: amount. Supported sort fields: id, rcId, rcPobId, batchId, chargeNumber" } }, "invalidRcId": { "summary": "Non-numeric rcId", "value": { "error": "Invalid value 'abc' for parameter 'rcId': expected a valid Long" } }, "pageSizeTooLarge": { "summary": "Page size above 100", "value": { "error": "Page size exceeds maximum. Maximum allowed: 100, requested: 500" } }, "pageSizeNotPositive": { "summary": "Page size zero or negative", "value": { "error": "Page size must be positive. Requested: 0" } }, "negativePage": { "summary": "Negative page number", "value": { "error": "Page number must be non-negative. Requested: -1" } }, "invalidPage": { "summary": "Non-numeric page", "value": { "error": "Invalid value 'x' for parameter 'page': expected a valid Integer" } }, "tooManyFilters": { "summary": "More than five filters", "value": { "error": "Too many filters. Maximum allowed: 5, provided: 6" } }, "unsupportedOperator": { "summary": "Unsupported filter operator", "value": { "error": "Unsupported operator: 'between'. Supported operators: eq, ne, gt, gte, lt, lte, like, in, nin" } } } } } }, "500": { "description": "Unexpected failure inside Zuora Revenue, such as a database error or a non-numeric value supplied for a numeric filter. Retry later; contact Zuora Global Support if it persists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractQueryErrorResponse" }, "examples": { "internalError": { "summary": "Internal server error", "value": { "error": "Internal server error" } } } } } } } } }, "/contracts/{rcId}/lines/{lineId}": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Production" } ], "get": { "tags": [ "Revenue Contract Lines" ], "operationId": "getRevenueContractLine", "summary": "Retrieve a revenue contract line", "description": "**Purpose**\n\nReturns one line of a revenue contract.\n\n**When to use**\n\n- Read the attributes of a specific line before or after you edit it.\n- Verify that a line belongs to the contract you expect.\n\n**Behavior notes**\n\nA line that exists but belongs to a different contract returns HTTP 404.\n", "parameters": [ { "$ref": "#/components/parameters/RcId" }, { "$ref": "#/components/parameters/LineId" }, { "$ref": "#/components/parameters/BookId" }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "The revenue contract line.", "headers": { "traceId": { "$ref": "#/components/headers/TraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevenueContractLine" }, "examples": { "line": { "summary": "Revenue contract line", "value": { "id": 85922, "rcId": 111442, "indicators": { "allocationEligible": "Y" }, "stringAttributes": { "atr1": "EMEA", "atr2": null }, "numberAttributes": { "num1": "12.50", "num2": null }, "dateAttributes": { "date1": "2026-01-31", "date2": null }, "rcLineOtrAttributes": { "rpcNum": "C-00012345" } } } } } } }, "400": { "description": "The request is invalid. Correct the request and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractQueryErrorResponse" }, "examples": { "invalidRcId": { "summary": "Non-numeric rcId", "value": { "error": "Invalid value 'abc' for parameter 'rcId': expected a valid Long" } }, "invalidLineId": { "summary": "Non-numeric lineId", "value": { "error": "Invalid value 'x1' for parameter 'lineId': expected a valid Long" } } } } } }, "404": { "description": "The revenue contract line does not exist in this tenant and book, or the caller's organization cannot see it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractQueryErrorResponse" }, "examples": { "notFound": { "summary": "Revenue contract line not found", "value": { "error": "Revenue contract line 85999 not found" } } } } } }, "500": { "description": "Unexpected failure inside Zuora Revenue, such as a database error or a non-numeric value supplied for a numeric filter. Retry later; contact Zuora Global Support if it persists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractQueryErrorResponse" }, "examples": { "internalError": { "summary": "Internal server error", "value": { "error": "Internal server error" } } } } } } } } }, "/contracts/{rcId}/lines/charge-number/{chargeNumber}": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Production" } ], "get": { "tags": [ "Revenue Contract Lines" ], "operationId": "listRevenueContractLinesByChargeNumber", "summary": "List contract lines for a charge number", "description": "**Purpose**\n\nReturns the lines of a revenue contract that came from one Zuora Billing rate plan charge.\n\n**When to use**\n\n- Trace a subscription charge from Zuora Billing to its revenue lines.\n- Find the lines to target with a charge-level hold or charge-level link and delink.\n\n**Behavior notes**\n\nThe path `chargeNumber` always wins over a `chargeNumber` query parameter. The charge-number filter counts toward the limit of 5 filters, so you can add at most 4 more. No match returns HTTP 200 with an empty `data` array.\n\n**Filtering**\n\nEvery query parameter other than `page`, `size`, and `sort` is treated as a filter.\n\n- `field=value` matches records where the field equals the value.\n- `field[op]=value` applies an operator. URL-encode the brackets as `%5B` and `%5D`, for example\n `id%5Bgt%5D=1000`. Operators: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `like` (supply `%` wildcards yourself).\n- All filters are combined with AND. At most 5 filters are allowed per request.\n- Blank filter values are ignored.\n- An unknown field or operator returns HTTP 400.\n", "parameters": [ { "$ref": "#/components/parameters/RcId" }, { "name": "chargeNumber", "in": "path", "required": true, "description": "Zuora Billing rate plan charge number.", "schema": { "type": "string" }, "example": "C-00012345" }, { "$ref": "#/components/parameters/BookId" }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Size" }, { "name": "sort", "in": "query", "required": false, "description": "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`, `rcId`, `rcPobId`, `batchId`, `chargeNumber`. When `sort` is omitted the order is not guaranteed, so always sort when paging through results.", "schema": { "type": "string" }, "example": "id,asc" }, { "name": "id", "in": "query", "required": false, "description": "Filter by revenue contract line ID.", "schema": { "type": "integer", "format": "int64" }, "example": 85922 }, { "name": "rcPobId", "in": "query", "required": false, "description": "Filter by performance obligation (POB) ID.", "schema": { "type": "integer", "format": "int64" }, "example": 156912 }, { "name": "batchId", "in": "query", "required": false, "description": "Filter by the data-collection batch that created the line.", "schema": { "type": "integer", "format": "int64" }, "example": 5001 } ], "responses": { "200": { "description": "A page of records. An empty `data` array means no record matched.", "headers": { "traceId": { "$ref": "#/components/headers/TraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevenueContractLinePage" }, "examples": { "lines": { "summary": "Lines for the charge", "value": { "data": [ { "id": 85922, "rcId": 111442, "indicators": { "allocationEligible": "Y" }, "stringAttributes": { "atr1": "EMEA", "atr2": null }, "numberAttributes": { "num1": "12.50", "num2": null }, "dateAttributes": { "date1": "2026-01-31", "date2": null }, "rcLineOtrAttributes": { "rpcNum": "C-00012345" } } ], "page": { "number": 1, "size": 20, "totalElements": 1, "totalPages": 1, "first": true, "last": true } } }, "empty": { "summary": "No line for the charge", "value": { "data": [], "page": { "number": 1, "size": 20, "totalElements": 0, "totalPages": 0, "first": true, "last": true } } } } } } }, "400": { "description": "The request is invalid. Correct the request and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractQueryErrorResponse" }, "examples": { "unknownFilter": { "summary": "Unsupported filter field", "value": { "error": "Cannot filter by: sku. Supported filter fields: id, rcId, rcPobId, batchId, chargeNumber" } }, "pageSizeTooLarge": { "summary": "Page size above 100", "value": { "error": "Page size exceeds maximum. Maximum allowed: 100, requested: 500" } }, "pageSizeNotPositive": { "summary": "Page size zero or negative", "value": { "error": "Page size must be positive. Requested: 0" } }, "negativePage": { "summary": "Negative page number", "value": { "error": "Page number must be non-negative. Requested: -1" } }, "invalidPage": { "summary": "Non-numeric page", "value": { "error": "Invalid value 'x' for parameter 'page': expected a valid Integer" } }, "tooManyFilters": { "summary": "More than five filters", "value": { "error": "Too many filters. Maximum allowed: 5, provided: 6" } }, "unsupportedOperator": { "summary": "Unsupported filter operator", "value": { "error": "Unsupported operator: 'between'. Supported operators: eq, ne, gt, gte, lt, lte, like, in, nin" } } } } } }, "500": { "description": "Unexpected failure inside Zuora Revenue, such as a database error or a non-numeric value supplied for a numeric filter. Retry later; contact Zuora Global Support if it persists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractQueryErrorResponse" }, "examples": { "internalError": { "summary": "Internal server error", "value": { "error": "Internal server error" } } } } } } } } }, "/contracts/charges": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Production" } ], "get": { "tags": [ "Revenue Contract Lines" ], "operationId": "listChargeLines", "summary": "List charge lines across contracts", "description": "**Purpose**\n\nReturns every revenue contract line in the book that carries a Zuora Billing charge number, across all revenue contracts.\n\n**When to use**\n\n- Find which revenue contract a billing charge landed in when you do not know the `rcId`. Filter by `chargeNumber`.\n- Reconcile Zuora Billing charges with Zuora Revenue lines.\n\n**Behavior notes**\n\nAlways filter or page through the results; the unfiltered list can be large.\n\n**Filtering**\n\nEvery query parameter other than `page`, `size`, and `sort` is treated as a filter.\n\n- `field=value` matches records where the field equals the value.\n- `field[op]=value` applies an operator. URL-encode the brackets as `%5B` and `%5D`, for example\n `id%5Bgt%5D=1000`. Operators: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `like` (supply `%` wildcards yourself).\n- All filters are combined with AND. At most 5 filters are allowed per request.\n- Blank filter values are ignored.\n- An unknown field or operator returns HTTP 400.\n", "parameters": [ { "$ref": "#/components/parameters/BookId" }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Size" }, { "name": "sort", "in": "query", "required": false, "description": "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`, `rcId`, `rcPobId`, `batchId`, `chargeNumber`. When `sort` is omitted the order is not guaranteed, so always sort when paging through results.", "schema": { "type": "string" }, "example": "id,asc" }, { "name": "id", "in": "query", "required": false, "description": "Filter by revenue contract line ID.", "schema": { "type": "integer", "format": "int64" }, "example": 85922 }, { "name": "rcPobId", "in": "query", "required": false, "description": "Filter by performance obligation (POB) ID.", "schema": { "type": "integer", "format": "int64" }, "example": 156912 }, { "name": "batchId", "in": "query", "required": false, "description": "Filter by the data-collection batch that created the line.", "schema": { "type": "integer", "format": "int64" }, "example": 5001 }, { "name": "chargeNumber", "in": "query", "required": false, "description": "Filter by Zuora Billing rate plan charge number.", "schema": { "type": "string" }, "example": "C-00012345" }, { "name": "rcId", "in": "query", "required": false, "description": "Filter by revenue contract ID.", "schema": { "type": "integer", "format": "int64" }, "example": 111442 } ], "responses": { "200": { "description": "A page of records. An empty `data` array means no record matched.", "headers": { "traceId": { "$ref": "#/components/headers/TraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevenueContractLinePage" }, "examples": { "byCharge": { "summary": "Lines for charge C-00012345", "value": { "data": [ { "id": 85922, "rcId": 111442, "indicators": { "allocationEligible": "Y" }, "stringAttributes": { "atr1": "EMEA", "atr2": null }, "numberAttributes": { "num1": "12.50", "num2": null }, "dateAttributes": { "date1": "2026-01-31", "date2": null }, "rcLineOtrAttributes": { "rpcNum": "C-00012345" } } ], "page": { "number": 1, "size": 20, "totalElements": 1, "totalPages": 1, "first": true, "last": true } } }, "empty": { "summary": "No charge line matched", "value": { "data": [], "page": { "number": 1, "size": 20, "totalElements": 0, "totalPages": 0, "first": true, "last": true } } } } } } }, "400": { "description": "The request is invalid. Correct the request and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractQueryErrorResponse" }, "examples": { "unknownFilter": { "summary": "Unsupported filter field", "value": { "error": "Cannot filter by: subscription. Supported filter fields: id, rcId, rcPobId, batchId, chargeNumber" } }, "pageSizeTooLarge": { "summary": "Page size above 100", "value": { "error": "Page size exceeds maximum. Maximum allowed: 100, requested: 500" } }, "pageSizeNotPositive": { "summary": "Page size zero or negative", "value": { "error": "Page size must be positive. Requested: 0" } }, "negativePage": { "summary": "Negative page number", "value": { "error": "Page number must be non-negative. Requested: -1" } }, "invalidPage": { "summary": "Non-numeric page", "value": { "error": "Invalid value 'x' for parameter 'page': expected a valid Integer" } }, "tooManyFilters": { "summary": "More than five filters", "value": { "error": "Too many filters. Maximum allowed: 5, provided: 6" } }, "unsupportedOperator": { "summary": "Unsupported filter operator", "value": { "error": "Unsupported operator: 'between'. Supported operators: eq, ne, gt, gte, lt, lte, like, in, nin" } } } } } }, "500": { "description": "Unexpected failure inside Zuora Revenue, such as a database error or a non-numeric value supplied for a numeric filter. Retry later; contact Zuora Global Support if it persists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractQueryErrorResponse" }, "examples": { "internalError": { "summary": "Internal server error", "value": { "error": "Internal server error" } } } } } } } } }, "/revenue-holds": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Production" } ], "get": { "tags": [ "Revenue Holds" ], "operationId": "listRevenueHolds", "summary": "List revenue hold definitions", "description": "**Purpose**\n\nReturns a paginated list of the revenue hold definitions configured in Zuora Revenue setup.\n\n**When to use**\n\n- Find the `holdId` to pass to the apply-hold and release-hold Manual Action APIs.\n- Check which holds are enabled and whether they allow manual apply or release.\n\n**Behavior notes**\n\nOnly 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.\n\n**Filtering**\n\nEvery query parameter other than `page`, `size`, and `sort` is treated as a filter.\n\n- `field=value` matches records where the field equals the value.\n- `field[op]=value` applies an operator. URL-encode the brackets as `%5B` and `%5D`, for example\n `id%5Bgt%5D=1000`. Operators: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `like` (supply `%` wildcards yourself).\n- All filters are combined with AND. At most 5 filters are allowed per request.\n- Blank filter values are ignored.\n- An unknown field or operator returns HTTP 400.\n", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Size" }, { "name": "sort", "in": "query", "required": false, "description": "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.", "schema": { "type": "string" }, "example": "id,asc" }, { "name": "holdLevel", "in": "query", "required": false, "description": "Hold level to list. Case-insensitive.", "schema": { "type": "string", "enum": [ "RC", "POB", "LINE", "CHARGE" ], "default": "RC" }, "example": "RC" }, { "name": "id", "in": "query", "required": false, "description": "Filter by hold definition ID.", "schema": { "type": "integer", "format": "int64" }, "example": 20 }, { "name": "name", "in": "query", "required": false, "description": "Filter by hold name. Use `name[like]=%Acceptance%` for a partial match.", "schema": { "type": "string" }, "example": "Pending Acceptance" }, { "name": "startDate", "in": "query", "required": false, "description": "Filter by hold start date.", "schema": { "type": "string" }, "example": "2026-01-01" }, { "name": "endDate", "in": "query", "required": false, "description": "Filter by hold end date.", "schema": { "type": "string" }, "example": "2026-12-31" } ], "responses": { "200": { "description": "A page of records. An empty `data` array means no record matched.", "headers": { "traceId": { "$ref": "#/components/headers/TraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevenueHoldPage" }, "examples": { "rcHolds": { "summary": "RC-level holds", "value": { "data": [ { "id": 20, "name": "Pending Acceptance", "description": "Hold revenue until customer acceptance is received", "startDate": "2026-01-01", "endDate": null, "eventId": 1003, "expiryFieldName": null, "expiryNumberType": null, "expiryDuration": null, "flags": { "enabled": "Y", "allowManualRelease": "Y", "allowManualApply": "Y", "holdType": "Revenue Hold", "holdLevel": "RC", "scheduleType": "Both" }, "createdPeriodId": 202601, "clientId": 1, "createdBy": "jsmith", "createdDate": "2026-01-05", "updatedBy": "jsmith", "updatedDate": "2026-02-10" } ], "page": { "number": 1, "size": 20, "totalElements": 1, "totalPages": 1, "first": true, "last": true } } }, "empty": { "summary": "No hold matched", "value": { "data": [], "page": { "number": 1, "size": 20, "totalElements": 0, "totalPages": 0, "first": true, "last": true } } } } } } }, "400": { "description": "The request is invalid. Correct the request and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractQueryErrorResponse" }, "examples": { "invalidHoldLevel": { "summary": "Unknown hold level", "value": { "error": "Unknown holdLevel value: 'ORDER'. Allowed: RC, POB, LINE, CHARGE" } }, "blankHoldLevel": { "summary": "Blank hold level", "value": { "error": "Unknown holdLevel value: ''. Allowed: RC, POB, LINE, CHARGE" } }, "unknownFilter": { "summary": "Unsupported filter field", "value": { "error": "Cannot filter by: type. Supported filter fields: id, name, startDate, endDate, holdLevel" } }, "pageSizeTooLarge": { "summary": "Page size above 100", "value": { "error": "Page size exceeds maximum. Maximum allowed: 100, requested: 500" } }, "pageSizeNotPositive": { "summary": "Page size zero or negative", "value": { "error": "Page size must be positive. Requested: 0" } }, "negativePage": { "summary": "Negative page number", "value": { "error": "Page number must be non-negative. Requested: -1" } }, "invalidPage": { "summary": "Non-numeric page", "value": { "error": "Invalid value 'x' for parameter 'page': expected a valid Integer" } }, "tooManyFilters": { "summary": "More than five filters", "value": { "error": "Too many filters. Maximum allowed: 5, provided: 6" } }, "unsupportedOperator": { "summary": "Unsupported filter operator", "value": { "error": "Unsupported operator: 'between'. Supported operators: eq, ne, gt, gte, lt, lte, like, in, nin" } } } } } }, "500": { "description": "Unexpected failure inside Zuora Revenue, such as a database error or a non-numeric value supplied for a numeric filter. Retry later; contact Zuora Global Support if it persists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractQueryErrorResponse" }, "examples": { "internalError": { "summary": "Internal server error", "value": { "error": "Internal server error" } } } } } } } } }, "/revenue-holds/{holdId}": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Production" } ], "get": { "tags": [ "Revenue Holds" ], "operationId": "getRevenueHold", "summary": "Retrieve a revenue hold definition", "description": "**Purpose**\n\nReturns one revenue hold definition, at any hold level.\n\n**When to use**\n\n- Confirm a hold's level, type, and manual apply or release settings before you apply or release it on a contract.\n", "parameters": [ { "$ref": "#/components/parameters/HoldId" }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "The revenue hold definition.", "headers": { "traceId": { "$ref": "#/components/headers/TraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevenueHold" }, "examples": { "hold": { "summary": "Revenue hold", "value": { "id": 20, "name": "Pending Acceptance", "description": "Hold revenue until customer acceptance is received", "startDate": "2026-01-01", "endDate": null, "eventId": 1003, "expiryFieldName": null, "expiryNumberType": null, "expiryDuration": null, "flags": { "enabled": "Y", "allowManualRelease": "Y", "allowManualApply": "Y", "holdType": "Revenue Hold", "holdLevel": "RC", "scheduleType": "Both" }, "createdPeriodId": 202601, "clientId": 1, "createdBy": "jsmith", "createdDate": "2026-01-05", "updatedBy": "jsmith", "updatedDate": "2026-02-10" } } } } } }, "400": { "description": "The request is invalid. Correct the request and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractQueryErrorResponse" }, "examples": { "invalidHoldId": { "summary": "Non-numeric holdId", "value": { "error": "Invalid value 'x' for parameter 'holdId': expected a valid Long" } } } } } }, "404": { "description": "The revenue hold does not exist in this tenant and book, or the caller's organization cannot see it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractQueryErrorResponse" }, "examples": { "notFound": { "summary": "Revenue hold not found", "value": { "error": "Revenue hold 999 not found" } } } } } }, "500": { "description": "Unexpected failure inside Zuora Revenue, such as a database error or a non-numeric value supplied for a numeric filter. Retry later; contact Zuora Global Support if it persists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractQueryErrorResponse" }, "examples": { "internalError": { "summary": "Internal server error", "value": { "error": "Internal server error" } } } } } } } } }, "/revenue-management/contracts/{rcId}/open-close/{action}": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Production" } ], "post": { "tags": [ "Contract Status" ], "operationId": "openOrCloseRevenueContract", "summary": "Open or close a revenue contract", "description": "**Purpose**\n\nChanges the status of a revenue contract to closed or back to open.\n\n**When to use**\n\n- **close**: when a contract is complete (for example all revenue is recognized) and must no longer be reprocessed or changed by new transactions.\n- **open**: when a closed contract must be changed again, for example to correct data or apply a modification.\n\n**Behavior notes**\n\nThe `action` path value is case-insensitive.\n", "parameters": [ { "$ref": "#/components/parameters/RcId" }, { "name": "action", "in": "path", "required": true, "description": "Status change to make.", "schema": { "type": "string", "enum": [ "open", "close" ] }, "example": "close" }, { "$ref": "#/components/parameters/BookId" }, { "$ref": "#/components/parameters/RequestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenCloseRcRequest" }, "examples": { "currentVersion": { "summary": "Use the current version", "value": {} }, "explicitVersion": { "summary": "Explicit version", "value": { "objectVersion": 5 } } } } } }, "responses": { "200": { "description": "Processed. `success: true` means the action completed; `success: false` means a business rule rejected it and `message` explains why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualActionResponse" }, "examples": { "closed": { "summary": "Contract closed", "value": { "success": true, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Revenue contract closed successfully" } }, "opened": { "summary": "Contract opened", "value": { "success": true, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Revenue contract opened successfully" } }, "rejected": { "summary": "Rejected by a business rule (illustrative message)", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Revenue contract is already closed" } } } } }, "headers": { "traceId": { "$ref": "#/components/headers/TraceId" } } }, "400": { "description": "Invalid request. Each problem is listed in `reasons`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientErrorResponse" }, "examples": { "invalidAction": { "summary": "Unsupported action", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "InvalidRequest", "message": "Action must be either 'open' or 'close'" } ] } }, "malformedBody": { "$ref": "#/components/examples/MalformedBody" }, "objectVersionUnresolved": { "$ref": "#/components/examples/ObjectVersionUnresolved" }, "invalidBookHeader": { "$ref": "#/components/examples/InvalidBookHeader" }, "engineRejected": { "$ref": "#/components/examples/EngineRejected" } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RcTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/RcServiceUnavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/revenue-management/contracts/{rcId}/unfreeze": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Production" } ], "post": { "tags": [ "Contract Status" ], "operationId": "unfreezeRevenueContract", "summary": "Unfreeze a revenue contract", "description": "**Purpose**\n\nRemoves the freeze from a frozen revenue contract so its lines and schedules can be changed and processed again.\n\n**When to use**\n\n- A contract was frozen (for example by a soft-freeze during close) and you need to make a correction.\n- Set `changeModDate` to `N` when the unfreeze must not change the contract modification date.\n\n**Behavior notes**\n\nErrors from the revenue engine for this operation are returned as HTTP 200 with `success: false` and the generic message shown in the examples, not as 4xx/5xx responses.\n", "parameters": [ { "$ref": "#/components/parameters/RcId" }, { "$ref": "#/components/parameters/BookId" }, { "$ref": "#/components/parameters/RequestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnfreezeRcRequest" }, "examples": { "unfreeze": { "summary": "Unfreeze and update the modification date", "value": { "action": "UNFREEZE", "changeModDate": "Y" } }, "keepModDate": { "summary": "Unfreeze without changing the modification date", "value": { "action": "UNFREEZE", "changeModDate": "N", "objectVersion": 5 } } } } } }, "responses": { "200": { "description": "Processed. `success: true` means the action completed; `success: false` means a business rule rejected it and `message` explains why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualActionResponse" }, "examples": { "unfrozen": { "summary": "Contract unfrozen", "value": { "success": true, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Revenue contract unfrozen successfully" } }, "rejected": { "summary": "Rejected by a business rule (illustrative message)", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Revenue contract is not frozen" } }, "engineError": { "summary": "Revenue engine error", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Error while unfreezing RC" } } } } }, "headers": { "traceId": { "$ref": "#/components/headers/TraceId" } } }, "400": { "description": "Invalid request. Each problem is listed in `reasons`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientErrorResponse" }, "examples": { "missingAction": { "summary": "Missing action", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "ValidationError", "message": "action must not be blank" } ] } }, "malformedBody": { "$ref": "#/components/examples/MalformedBody" }, "objectVersionUnresolved": { "$ref": "#/components/examples/ObjectVersionUnresolved" }, "invalidBookHeader": { "$ref": "#/components/examples/InvalidBookHeader" } } } } }, "404": { "$ref": "#/components/responses/ContractNotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/revenue-management/contracts/{rcId}/holds/{holdId}/apply": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Production" } ], "post": { "tags": [ "Apply and Release Holds" ], "operationId": "applyContractHold", "summary": "Apply a hold to a revenue contract", "description": "**Purpose**\n\nApplies 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.\n\n**When to use**\n\n- 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.\n- Use a hold definition whose `flags.holdLevel` is `RC` and whose `flags.allowManualApply` is `Y`. List them with `GET /revenue-holds?holdLevel=RC`.\n", "parameters": [ { "$ref": "#/components/parameters/RcId" }, { "$ref": "#/components/parameters/HoldId" }, { "$ref": "#/components/parameters/BookId" }, { "$ref": "#/components/parameters/RequestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplyHoldRcRequest" }, "examples": { "apply": { "summary": "Apply a contract hold", "value": { "comments": "Hold pending customer acceptance" } } } } } }, "responses": { "200": { "description": "Processed. `success: true` means the action completed; `success: false` means a business rule rejected it and `message` explains why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplyHoldResponse" }, "examples": { "applied": { "summary": "Hold applied", "value": { "success": true, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Hold applied successfully", "holdRecords": [ { "id": 5001, "rcId": 111442, "lineId": 0, "rcPobId": 0, "revHoldId": 20, "bookId": 1, "comments": "Hold pending customer acceptance" } ] } }, "rejected": { "summary": "Rejected by a business rule", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Hold already applied" } }, "unexpected": { "summary": "Unexpected error while applying", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Error while applying holds" } } } } }, "headers": { "traceId": { "$ref": "#/components/headers/TraceId" } } }, "400": { "description": "Invalid request. Each problem is listed in `reasons`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientErrorResponse" }, "examples": { "malformedBody": { "$ref": "#/components/examples/MalformedBody" }, "objectVersionUnresolved": { "$ref": "#/components/examples/ObjectVersionUnresolved" }, "invalidBookHeader": { "$ref": "#/components/examples/InvalidBookHeader" }, "engineRejected": { "$ref": "#/components/examples/EngineRejected" } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RcTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/RcServiceUnavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/revenue-management/contracts/{rcId}/holds/{holdId}/release": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Production" } ], "post": { "tags": [ "Apply and Release Holds" ], "operationId": "releaseContractHold", "summary": "Release a hold from a revenue contract", "description": "**Purpose**\n\nReleases a revenue hold previously applied to the revenue contract, so the blocked revenue recognition (or transfer) resumes. The release comment and reason are recorded for audit.\n\n**When to use**\n\n- The condition behind the hold is met, for example acceptance was received or the audit finished.\n- The hold definition must allow manual release (`flags.allowManualRelease` is `Y`).\n", "parameters": [ { "$ref": "#/components/parameters/RcId" }, { "$ref": "#/components/parameters/HoldId" }, { "$ref": "#/components/parameters/BookId" }, { "$ref": "#/components/parameters/RequestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReleaseHoldRcRequest" }, "examples": { "release": { "summary": "Release a contract hold", "value": { "comments": "Customer acceptance received", "reason": "Acceptance" } } } } } }, "responses": { "200": { "description": "Processed. `success: true` means the action completed; `success: false` means a business rule rejected it and `message` explains why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualActionResponse" }, "examples": { "released": { "summary": "Hold released", "value": { "success": true, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Hold released successfully" } }, "rejected": { "summary": "Rejected by a business rule", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Hold not found" } }, "unexpected": { "summary": "Unexpected error while releasing", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Error while releasing hold" } } } } }, "headers": { "traceId": { "$ref": "#/components/headers/TraceId" } } }, "400": { "description": "Invalid request. Each problem is listed in `reasons`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientErrorResponse" }, "examples": { "malformedBody": { "$ref": "#/components/examples/MalformedBody" }, "objectVersionUnresolved": { "$ref": "#/components/examples/ObjectVersionUnresolved" }, "invalidBookHeader": { "$ref": "#/components/examples/InvalidBookHeader" }, "engineRejected": { "$ref": "#/components/examples/EngineRejected" } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RcTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/RcServiceUnavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/revenue-management/contracts/{rcId}/lines/holds/{holdId}/apply": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Production" } ], "post": { "tags": [ "Apply and Release Holds" ], "operationId": "applyLineHold", "summary": "Apply a hold to contract lines", "description": "**Purpose**\n\nApplies a revenue hold definition to selected lines of a revenue contract. While the hold is in place, Zuora Revenue blocks the revenue recognition (or transfer) that the hold type covers.\n\n**When to use**\n\n- 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 specific lines.\n- Use a hold definition whose `flags.holdLevel` is `LINE` and whose `flags.allowManualApply` is `Y`. List them with `GET /revenue-holds?holdLevel=LINE`.\n\n**Behavior notes**\n\nEach item in `lines` must include `lineId`.\n", "parameters": [ { "$ref": "#/components/parameters/RcId" }, { "$ref": "#/components/parameters/HoldId" }, { "$ref": "#/components/parameters/BookId" }, { "$ref": "#/components/parameters/RequestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplyHoldItemsRequest" }, "examples": { "apply": { "summary": "Apply a line-level hold", "value": { "comments": "Audit review", "lines": [ { "lineId": 85922, "holdComments": "Hold on this line" } ] } } } } } }, "responses": { "200": { "description": "Processed. `success: true` means the action completed; `success: false` means a business rule rejected it and `message` explains why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplyHoldResponse" }, "examples": { "applied": { "summary": "Hold applied", "value": { "success": true, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Hold applied successfully", "holdRecords": [ { "id": 5001, "rcId": 111442, "lineId": 85922, "rcPobId": 0, "revHoldId": 20, "bookId": 1, "comments": "Hold on this line" } ] } }, "rejected": { "summary": "Rejected by a business rule", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Hold already applied" } }, "unexpected": { "summary": "Unexpected error while applying", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Error while applying holds" } } } } }, "headers": { "traceId": { "$ref": "#/components/headers/TraceId" } } }, "400": { "description": "Invalid request. Each problem is listed in `reasons`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientErrorResponse" }, "examples": { "missingLines": { "summary": "No items", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "InvalidRequest", "message": "Lines are required for line-level hold" } ] } }, "missingIdentifier": { "summary": "Item without lineId", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "InvalidRequest", "message": "lineId is mandatory for line-level hold" } ] } }, "malformedBody": { "$ref": "#/components/examples/MalformedBody" }, "objectVersionUnresolved": { "$ref": "#/components/examples/ObjectVersionUnresolved" }, "invalidBookHeader": { "$ref": "#/components/examples/InvalidBookHeader" }, "engineRejected": { "$ref": "#/components/examples/EngineRejected" } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RcTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/RcServiceUnavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/revenue-management/contracts/{rcId}/lines/holds/{holdId}/release": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Production" } ], "post": { "tags": [ "Apply and Release Holds" ], "operationId": "releaseLineHold", "summary": "Release a hold from contract lines", "description": "**Purpose**\n\nReleases a revenue hold previously applied to selected lines, so the blocked revenue recognition (or transfer) resumes. The release comment and reason are recorded for audit.\n\n**When to use**\n\n- The condition behind the hold is met, for example acceptance was received or the audit finished.\n- The hold definition must allow manual release (`flags.allowManualRelease` is `Y`).\n\n**Behavior notes**\n\nEach item in `items` must include `lineId`.\n", "parameters": [ { "$ref": "#/components/parameters/RcId" }, { "$ref": "#/components/parameters/HoldId" }, { "$ref": "#/components/parameters/BookId" }, { "$ref": "#/components/parameters/RequestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReleaseHoldItemsRequest" }, "examples": { "release": { "summary": "Release a line-level hold", "value": { "comments": "Audit complete", "items": [ { "lineId": 85922, "releaseComments": "Releasing hold", "releaseReason": "Audit complete" } ] } } } } } }, "responses": { "200": { "description": "Processed. `success: true` means the action completed; `success: false` means a business rule rejected it and `message` explains why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualActionResponse" }, "examples": { "released": { "summary": "Hold released", "value": { "success": true, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Hold released successfully" } }, "rejected": { "summary": "Rejected by a business rule", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Hold not found" } }, "unexpected": { "summary": "Unexpected error while releasing", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Error while releasing hold" } } } } }, "headers": { "traceId": { "$ref": "#/components/headers/TraceId" } } }, "400": { "description": "Invalid request. Each problem is listed in `reasons`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientErrorResponse" }, "examples": { "missingItems": { "summary": "No items", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "InvalidRequest", "message": "Items are required for line-level hold release" } ] } }, "missingIdentifier": { "summary": "Item without lineId", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "InvalidRequest", "message": "lineId is mandatory for line-level hold release" } ] } }, "malformedBody": { "$ref": "#/components/examples/MalformedBody" }, "objectVersionUnresolved": { "$ref": "#/components/examples/ObjectVersionUnresolved" }, "invalidBookHeader": { "$ref": "#/components/examples/InvalidBookHeader" }, "engineRejected": { "$ref": "#/components/examples/EngineRejected" } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RcTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/RcServiceUnavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/revenue-management/contracts/{rcId}/pobs/holds/{holdId}/apply": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Production" } ], "post": { "tags": [ "Apply and Release Holds" ], "operationId": "applyPobHold", "summary": "Apply a hold to contract POBs", "description": "**Purpose**\n\nApplies a revenue hold definition to selected POBs of a revenue contract. While the hold is in place, Zuora Revenue blocks the revenue recognition (or transfer) that the hold type covers.\n\n**When to use**\n\n- 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 specific POBs.\n- Use a hold definition whose `flags.holdLevel` is `POB` and whose `flags.allowManualApply` is `Y`. List them with `GET /revenue-holds?holdLevel=POB`.\n\n**Behavior notes**\n\nEach item in `lines` must include `rcPobId`.\n", "parameters": [ { "$ref": "#/components/parameters/RcId" }, { "$ref": "#/components/parameters/HoldId" }, { "$ref": "#/components/parameters/BookId" }, { "$ref": "#/components/parameters/RequestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplyHoldItemsRequest" }, "examples": { "apply": { "summary": "Apply a POB-level hold", "value": { "comments": "Audit review", "lines": [ { "rcPobId": 156912, "holdComments": "Hold on this POB" } ] } } } } } }, "responses": { "200": { "description": "Processed. `success: true` means the action completed; `success: false` means a business rule rejected it and `message` explains why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplyHoldResponse" }, "examples": { "applied": { "summary": "Hold applied", "value": { "success": true, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Hold applied successfully", "holdRecords": [ { "id": 5001, "rcId": 111442, "lineId": 0, "rcPobId": 156912, "revHoldId": 20, "bookId": 1, "comments": "Hold on this POB" } ] } }, "rejected": { "summary": "Rejected by a business rule", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Hold already applied" } }, "unexpected": { "summary": "Unexpected error while applying", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Error while applying holds" } } } } }, "headers": { "traceId": { "$ref": "#/components/headers/TraceId" } } }, "400": { "description": "Invalid request. Each problem is listed in `reasons`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientErrorResponse" }, "examples": { "missingLines": { "summary": "No items", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "InvalidRequest", "message": "Lines are required for POB-level hold" } ] } }, "missingIdentifier": { "summary": "Item without rcPobId", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "InvalidRequest", "message": "rcPobId is mandatory for POB-level hold" } ] } }, "malformedBody": { "$ref": "#/components/examples/MalformedBody" }, "objectVersionUnresolved": { "$ref": "#/components/examples/ObjectVersionUnresolved" }, "invalidBookHeader": { "$ref": "#/components/examples/InvalidBookHeader" }, "engineRejected": { "$ref": "#/components/examples/EngineRejected" } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RcTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/RcServiceUnavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/revenue-management/contracts/{rcId}/pobs/holds/{holdId}/release": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Production" } ], "post": { "tags": [ "Apply and Release Holds" ], "operationId": "releasePobHold", "summary": "Release a hold from contract POBs", "description": "**Purpose**\n\nReleases a revenue hold previously applied to selected POBs, so the blocked revenue recognition (or transfer) resumes. The release comment and reason are recorded for audit.\n\n**When to use**\n\n- The condition behind the hold is met, for example acceptance was received or the audit finished.\n- The hold definition must allow manual release (`flags.allowManualRelease` is `Y`).\n\n**Behavior notes**\n\nEach item in `items` must include `rcPobId`.\n", "parameters": [ { "$ref": "#/components/parameters/RcId" }, { "$ref": "#/components/parameters/HoldId" }, { "$ref": "#/components/parameters/BookId" }, { "$ref": "#/components/parameters/RequestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReleaseHoldItemsRequest" }, "examples": { "release": { "summary": "Release a POB-level hold", "value": { "comments": "Audit complete", "items": [ { "rcPobId": 156912, "releaseComments": "Releasing hold", "releaseReason": "Audit complete" } ] } } } } } }, "responses": { "200": { "description": "Processed. `success: true` means the action completed; `success: false` means a business rule rejected it and `message` explains why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualActionResponse" }, "examples": { "released": { "summary": "Hold released", "value": { "success": true, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Hold released successfully" } }, "rejected": { "summary": "Rejected by a business rule", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Hold not found" } }, "unexpected": { "summary": "Unexpected error while releasing", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Error while releasing hold" } } } } }, "headers": { "traceId": { "$ref": "#/components/headers/TraceId" } } }, "400": { "description": "Invalid request. Each problem is listed in `reasons`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientErrorResponse" }, "examples": { "missingItems": { "summary": "No items", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "InvalidRequest", "message": "Items are required for POB-level hold release" } ] } }, "missingIdentifier": { "summary": "Item without rcPobId", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "InvalidRequest", "message": "rcPobId is mandatory for POB-level hold release" } ] } }, "malformedBody": { "$ref": "#/components/examples/MalformedBody" }, "objectVersionUnresolved": { "$ref": "#/components/examples/ObjectVersionUnresolved" }, "invalidBookHeader": { "$ref": "#/components/examples/InvalidBookHeader" }, "engineRejected": { "$ref": "#/components/examples/EngineRejected" } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RcTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/RcServiceUnavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/revenue-management/contracts/{rcId}/charges/holds/{holdId}/apply": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Production" } ], "post": { "tags": [ "Apply and Release Holds" ], "operationId": "applyChargeHold", "summary": "Apply a hold to contract charges", "description": "**Purpose**\n\nApplies a revenue hold definition to selected charges of a revenue contract. While the hold is in place, Zuora Revenue blocks the revenue recognition (or transfer) that the hold type covers.\n\n**When to use**\n\n- 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 specific charges.\n- Use a hold definition whose `flags.holdLevel` is `CHARGE` and whose `flags.allowManualApply` is `Y`. List them with `GET /revenue-holds?holdLevel=CHARGE`.\n\n**Behavior notes**\n\nEach item in `lines` must include `chargeNumber`.\n", "parameters": [ { "$ref": "#/components/parameters/RcId" }, { "$ref": "#/components/parameters/HoldId" }, { "$ref": "#/components/parameters/BookId" }, { "$ref": "#/components/parameters/RequestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplyHoldItemsRequest" }, "examples": { "apply": { "summary": "Apply a charge-level hold", "value": { "comments": "Audit review", "lines": [ { "chargeNumber": "C-00012345", "holdComments": "Hold on this charge" } ] } } } } } }, "responses": { "200": { "description": "Processed. `success: true` means the action completed; `success: false` means a business rule rejected it and `message` explains why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplyHoldResponse" }, "examples": { "applied": { "summary": "Hold applied", "value": { "success": true, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Hold applied successfully", "holdRecords": [ { "id": 5001, "rcId": 111442, "lineId": 85922, "rcPobId": 0, "revHoldId": 20, "bookId": 1, "comments": "Hold on this charge" } ] } }, "rejected": { "summary": "Rejected by a business rule", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Hold already applied" } }, "unexpected": { "summary": "Unexpected error while applying", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Error while applying holds" } } } } }, "headers": { "traceId": { "$ref": "#/components/headers/TraceId" } } }, "400": { "description": "Invalid request. Each problem is listed in `reasons`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientErrorResponse" }, "examples": { "missingLines": { "summary": "No items", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "InvalidRequest", "message": "Lines are required for charge-level hold" } ] } }, "missingIdentifier": { "summary": "Item without chargeNumber", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "InvalidRequest", "message": "chargeNumber is mandatory for charge-level hold" } ] } }, "malformedBody": { "$ref": "#/components/examples/MalformedBody" }, "objectVersionUnresolved": { "$ref": "#/components/examples/ObjectVersionUnresolved" }, "invalidBookHeader": { "$ref": "#/components/examples/InvalidBookHeader" }, "engineRejected": { "$ref": "#/components/examples/EngineRejected" } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RcTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/RcServiceUnavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/revenue-management/contracts/{rcId}/charges/holds/{holdId}/release": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Production" } ], "post": { "tags": [ "Apply and Release Holds" ], "operationId": "releaseChargeHold", "summary": "Release a hold from contract charges", "description": "**Purpose**\n\nReleases a revenue hold previously applied to selected charges, so the blocked revenue recognition (or transfer) resumes. The release comment and reason are recorded for audit.\n\n**When to use**\n\n- The condition behind the hold is met, for example acceptance was received or the audit finished.\n- The hold definition must allow manual release (`flags.allowManualRelease` is `Y`).\n\n**Behavior notes**\n\nEach item in `items` must include `chargeNumber`.\n", "parameters": [ { "$ref": "#/components/parameters/RcId" }, { "$ref": "#/components/parameters/HoldId" }, { "$ref": "#/components/parameters/BookId" }, { "$ref": "#/components/parameters/RequestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReleaseHoldItemsRequest" }, "examples": { "release": { "summary": "Release a charge-level hold", "value": { "comments": "Audit complete", "items": [ { "chargeNumber": "C-00012345", "releaseComments": "Releasing hold", "releaseReason": "Audit complete" } ] } } } } } }, "responses": { "200": { "description": "Processed. `success: true` means the action completed; `success: false` means a business rule rejected it and `message` explains why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualActionResponse" }, "examples": { "released": { "summary": "Hold released", "value": { "success": true, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Hold released successfully" } }, "rejected": { "summary": "Rejected by a business rule", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Hold not found" } }, "unexpected": { "summary": "Unexpected error while releasing", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Error while releasing hold" } } } } }, "headers": { "traceId": { "$ref": "#/components/headers/TraceId" } } }, "400": { "description": "Invalid request. Each problem is listed in `reasons`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientErrorResponse" }, "examples": { "missingItems": { "summary": "No items", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "InvalidRequest", "message": "Items are required for charge-level hold release" } ] } }, "missingIdentifier": { "summary": "Item without chargeNumber", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "InvalidRequest", "message": "chargeNumber is mandatory for charge-level hold release" } ] } }, "malformedBody": { "$ref": "#/components/examples/MalformedBody" }, "objectVersionUnresolved": { "$ref": "#/components/examples/ObjectVersionUnresolved" }, "invalidBookHeader": { "$ref": "#/components/examples/InvalidBookHeader" }, "engineRejected": { "$ref": "#/components/examples/EngineRejected" } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RcTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/RcServiceUnavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/revenue-management/contracts/{rcId}/defer-revenue": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Production" } ], "post": { "tags": [ "Revenue Deferral and Release" ], "operationId": "deferRevenueForContract", "summary": "Defer revenue for a revenue contract", "description": "**Purpose**\n\nPlaces a manual deferral on the revenue contract, or on selected POBs of it, so its scheduled revenue is held back instead of being recognized, optionally for a date window.\n\n**When to use**\n\n- Revenue must not be recognized yet even though the schedule says so, for example because of an unresolved contingency.\n- Pair it with the release-revenue operation when the contingency is resolved.\n\n**Behavior notes**\n\nErrors from the revenue engine for this operation are returned as HTTP 200 with `success: false` and the generic message shown in the examples, not as 4xx/5xx responses.\n", "parameters": [ { "$ref": "#/components/parameters/RcId" }, { "$ref": "#/components/parameters/BookId" }, { "$ref": "#/components/parameters/RequestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeferReleaseRevenueRcRequest" }, "examples": { "window": { "summary": "Defer for a date window", "value": { "comments": "Deferring revenue pending acceptance", "startDate": "2026-01-01", "endDate": "2026-03-31" } }, "somePobs": { "summary": "Defer selected POBs", "value": { "comments": "Deferring revenue for two POBs", "rcPobIds": [ 156912, 156913 ] } } } } } }, "responses": { "200": { "description": "Processed. `success: true` means the action completed; `success: false` means a business rule rejected it and `message` explains why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualActionResponse" }, "examples": { "done": { "summary": "Action completed", "value": { "success": true, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Revenue deferred successfully" } }, "rejected": { "summary": "Rejected by a business rule (illustrative message)", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Revenue contract is frozen" } }, "engineError": { "summary": "Revenue engine error", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Error while deferring/releasing RC" } } } } }, "headers": { "traceId": { "$ref": "#/components/headers/TraceId" } } }, "400": { "description": "Invalid request. Each problem is listed in `reasons`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientErrorResponse" }, "examples": { "missingComments": { "summary": "Missing comments", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "ValidationError", "message": "comments must not be blank" } ] } }, "invalidDate": { "summary": "Invalid date", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "ValidationError", "message": "'startDate' contains an invalid date value '2026-13-01'. Expected format: yyyy-MM-dd" } ] } }, "malformedBody": { "$ref": "#/components/examples/MalformedBody" }, "objectVersionUnresolved": { "$ref": "#/components/examples/ObjectVersionUnresolved" }, "invalidBookHeader": { "$ref": "#/components/examples/InvalidBookHeader" } } } } }, "404": { "$ref": "#/components/responses/ContractNotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/revenue-management/contracts/{rcId}/pobs/{pobId}/defer-revenue": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Production" } ], "post": { "tags": [ "Revenue Deferral and Release" ], "operationId": "deferRevenueForPob", "summary": "Defer revenue for a POB", "description": "**Purpose**\n\nPlaces a manual deferral on one POB so its scheduled revenue is held back instead of being recognized, optionally for a date window.\n\n**When to use**\n\n- Revenue must not be recognized yet even though the schedule says so, for example because of an unresolved contingency.\n- Pair it with the release-revenue operation when the contingency is resolved.\n\n**Behavior notes**\n\nErrors from the revenue engine for this operation are returned as HTTP 200 with `success: false` and the generic message shown in the examples, not as 4xx/5xx responses.\n", "parameters": [ { "$ref": "#/components/parameters/RcId" }, { "$ref": "#/components/parameters/PobId" }, { "$ref": "#/components/parameters/BookId" }, { "$ref": "#/components/parameters/RequestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeferReleaseRevenuePobRequest" }, "examples": { "window": { "summary": "Defer for a date window", "value": { "comments": "Deferring revenue pending acceptance", "startDate": "2026-01-01", "endDate": "2026-03-31" } } } } } }, "responses": { "200": { "description": "Processed. `success: true` means the action completed; `success: false` means a business rule rejected it and `message` explains why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualActionResponse" }, "examples": { "done": { "summary": "Action completed", "value": { "success": true, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Revenue deferred successfully" } }, "rejected": { "summary": "Rejected by a business rule (illustrative message)", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Revenue contract is frozen" } }, "engineError": { "summary": "Revenue engine error", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Error while deferring/releasing RC" } } } } }, "headers": { "traceId": { "$ref": "#/components/headers/TraceId" } } }, "400": { "description": "Invalid request. Each problem is listed in `reasons`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientErrorResponse" }, "examples": { "missingComments": { "summary": "Missing comments", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "ValidationError", "message": "comments must not be blank" } ] } }, "invalidDate": { "summary": "Invalid date", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "ValidationError", "message": "'startDate' contains an invalid date value '2026-13-01'. Expected format: yyyy-MM-dd" } ] } }, "malformedBody": { "$ref": "#/components/examples/MalformedBody" }, "objectVersionUnresolved": { "$ref": "#/components/examples/ObjectVersionUnresolved" }, "invalidBookHeader": { "$ref": "#/components/examples/InvalidBookHeader" } } } } }, "404": { "$ref": "#/components/responses/ContractNotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/revenue-management/contracts/{rcId}/release-revenue": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Production" } ], "post": { "tags": [ "Revenue Deferral and Release" ], "operationId": "releaseRevenueForContract", "summary": "Release revenue for a revenue contract", "description": "**Purpose**\n\nReleases revenue previously deferred on the revenue contract, or on selected POBs of it, so it is recognized. Release the full amount, or part of it by amount or percentage.\n\n**When to use**\n\n- The contingency behind a manual deferral is resolved.\n- Use `releaseAmount` or `releasePercentage` for a partial release.\n\n**Behavior notes**\n\nErrors from the revenue engine for this operation are returned as HTTP 200 with `success: false` and the generic message shown in the examples, not as 4xx/5xx responses.\n", "parameters": [ { "$ref": "#/components/parameters/RcId" }, { "$ref": "#/components/parameters/BookId" }, { "$ref": "#/components/parameters/RequestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeferReleaseRevenueRcRequest" }, "examples": { "full": { "summary": "Release all deferred revenue", "value": { "comments": "Acceptance received" } }, "percentage": { "summary": "Release 50 percent", "value": { "comments": "Partial acceptance", "releasePercentage": 50 } }, "amount": { "summary": "Release an amount", "value": { "comments": "Milestone met", "releaseAmount": 1500 } }, "somePobs": { "summary": "Release selected POBs", "value": { "comments": "Releasing deferred revenue", "rcPobIds": [ 156912 ], "releasePercentage": 100 } } } } } }, "responses": { "200": { "description": "Processed. `success: true` means the action completed; `success: false` means a business rule rejected it and `message` explains why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualActionResponse" }, "examples": { "done": { "summary": "Action completed", "value": { "success": true, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Revenue released successfully" } }, "rejected": { "summary": "Rejected by a business rule (illustrative message)", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "No deferred revenue available to release" } }, "engineError": { "summary": "Revenue engine error", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Error while deferring/releasing RC" } } } } }, "headers": { "traceId": { "$ref": "#/components/headers/TraceId" } } }, "400": { "description": "Invalid request. Each problem is listed in `reasons`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientErrorResponse" }, "examples": { "missingComments": { "summary": "Missing comments", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "ValidationError", "message": "comments must not be blank" } ] } }, "invalidDate": { "summary": "Invalid date", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "ValidationError", "message": "'startDate' contains an invalid date value '2026-13-01'. Expected format: yyyy-MM-dd" } ] } }, "malformedBody": { "$ref": "#/components/examples/MalformedBody" }, "objectVersionUnresolved": { "$ref": "#/components/examples/ObjectVersionUnresolved" }, "invalidBookHeader": { "$ref": "#/components/examples/InvalidBookHeader" } } } } }, "404": { "$ref": "#/components/responses/ContractNotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/revenue-management/contracts/{rcId}/pobs/{pobId}/release-revenue": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Production" } ], "post": { "tags": [ "Revenue Deferral and Release" ], "operationId": "releaseRevenueForPob", "summary": "Release revenue for a POB", "description": "**Purpose**\n\nReleases revenue previously deferred on one POB so it is recognized. Release the full amount, or part of it by amount or percentage.\n\n**When to use**\n\n- The contingency behind a manual deferral is resolved.\n- Use `releaseAmount` or `releasePercentage` for a partial release.\n\n**Behavior notes**\n\nErrors from the revenue engine for this operation are returned as HTTP 200 with `success: false` and the generic message shown in the examples, not as 4xx/5xx responses.\n", "parameters": [ { "$ref": "#/components/parameters/RcId" }, { "$ref": "#/components/parameters/PobId" }, { "$ref": "#/components/parameters/BookId" }, { "$ref": "#/components/parameters/RequestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeferReleaseRevenuePobRequest" }, "examples": { "full": { "summary": "Release all deferred revenue", "value": { "comments": "Acceptance received" } }, "percentage": { "summary": "Release 50 percent", "value": { "comments": "Partial acceptance", "releasePercentage": 50 } }, "amount": { "summary": "Release an amount", "value": { "comments": "Milestone met", "releaseAmount": 1500 } } } } } }, "responses": { "200": { "description": "Processed. `success: true` means the action completed; `success: false` means a business rule rejected it and `message` explains why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualActionResponse" }, "examples": { "done": { "summary": "Action completed", "value": { "success": true, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Revenue released successfully" } }, "rejected": { "summary": "Rejected by a business rule (illustrative message)", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "No deferred revenue available to release" } }, "engineError": { "summary": "Revenue engine error", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Error while deferring/releasing RC" } } } } }, "headers": { "traceId": { "$ref": "#/components/headers/TraceId" } } }, "400": { "description": "Invalid request. Each problem is listed in `reasons`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientErrorResponse" }, "examples": { "missingComments": { "summary": "Missing comments", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "ValidationError", "message": "comments must not be blank" } ] } }, "invalidDate": { "summary": "Invalid date", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "ValidationError", "message": "'startDate' contains an invalid date value '2026-13-01'. Expected format: yyyy-MM-dd" } ] } }, "malformedBody": { "$ref": "#/components/examples/MalformedBody" }, "objectVersionUnresolved": { "$ref": "#/components/examples/ObjectVersionUnresolved" }, "invalidBookHeader": { "$ref": "#/components/examples/InvalidBookHeader" } } } } }, "404": { "$ref": "#/components/responses/ContractNotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/revenue-management/contracts/{rcId}/defer-cost": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Production" } ], "post": { "tags": [ "Cost Deferral and Release" ], "operationId": "deferCost", "summary": "Defer cost on a contract line", "description": "**Purpose**\n\nDefers a cost (for example a commission or fulfillment cost) on a revenue contract line so it is amortized under the cost rule dates instead of being expensed.\n\n**When to use**\n\n- A capitalized contract cost must be amortized over a specific window.\n- Set `ruleStartDate` and `ruleEndDate` to the amortization window.\n\n**Behavior notes**\n\nErrors from the revenue engine for this operation are returned as HTTP 200 with `success: false` and the generic message shown in the examples, not as 4xx/5xx responses.\n", "parameters": [ { "$ref": "#/components/parameters/RcId" }, { "$ref": "#/components/parameters/BookId" }, { "$ref": "#/components/parameters/RequestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeferReleaseCostRequest" }, "examples": { "defer": { "summary": "Defer a commission cost", "value": { "lineId": 85922, "costTypeId": 10000, "comments": "Deferring commission", "ruleStartDate": "2026-01-01", "ruleEndDate": "2026-12-31" } } } } } }, "responses": { "200": { "description": "Processed. `success: true` means the action completed; `success: false` means a business rule rejected it and `message` explains why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualActionResponse" }, "examples": { "done": { "summary": "Action completed", "value": { "success": true, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Cost deferred successfully" } }, "rejected": { "summary": "Rejected by a business rule (illustrative message)", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Cost type is not configured for the line" } }, "engineError": { "summary": "Revenue engine error", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Error while deferring/releasing RC" } } } } }, "headers": { "traceId": { "$ref": "#/components/headers/TraceId" } } }, "400": { "description": "Invalid request. Each problem is listed in `reasons`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientErrorResponse" }, "examples": { "missingFields": { "summary": "Missing required fields", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "ValidationError", "message": "lineId must not be null" }, { "code": "ValidationError", "message": "costTypeId must not be null" }, { "code": "ValidationError", "message": "comments must not be blank" } ] } }, "malformedBody": { "$ref": "#/components/examples/MalformedBody" }, "objectVersionUnresolved": { "$ref": "#/components/examples/ObjectVersionUnresolved" }, "invalidBookHeader": { "$ref": "#/components/examples/InvalidBookHeader" } } } } }, "404": { "$ref": "#/components/responses/ContractNotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/revenue-management/contracts/{rcId}/release-cost": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Production" } ], "post": { "tags": [ "Cost Deferral and Release" ], "operationId": "releaseCost", "summary": "Release cost on a contract line", "description": "**Purpose**\n\nReleases a deferred cost on a revenue contract line so it is expensed, fully or partially by amount, percentage, or quantity.\n\n**When to use**\n\n- A deferred cost must be expensed now, for example when the contract is terminated.\n- Send `releaseAmount`, `releasePercentage`, or `releaseQuantity` for a partial release.\n\n**Behavior notes**\n\nErrors from the revenue engine for this operation are returned as HTTP 200 with `success: false` and the generic message shown in the examples, not as 4xx/5xx responses.\n", "parameters": [ { "$ref": "#/components/parameters/RcId" }, { "$ref": "#/components/parameters/BookId" }, { "$ref": "#/components/parameters/RequestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeferReleaseCostRequest" }, "examples": { "amount": { "summary": "Release an amount", "value": { "lineId": 85922, "costTypeId": 10000, "comments": "Releasing deferred commission", "releaseAmount": 500 } }, "percentage": { "summary": "Release a percentage", "value": { "lineId": 85922, "costTypeId": 10000, "comments": "Contract terminated", "releasePercentage": 100 } } } } } }, "responses": { "200": { "description": "Processed. `success: true` means the action completed; `success: false` means a business rule rejected it and `message` explains why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualActionResponse" }, "examples": { "done": { "summary": "Action completed", "value": { "success": true, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Cost released successfully" } }, "rejected": { "summary": "Rejected by a business rule (illustrative message)", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Cost type is not configured for the line" } }, "engineError": { "summary": "Revenue engine error", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Error while deferring/releasing RC" } } } } }, "headers": { "traceId": { "$ref": "#/components/headers/TraceId" } } }, "400": { "description": "Invalid request. Each problem is listed in `reasons`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientErrorResponse" }, "examples": { "missingFields": { "summary": "Missing required fields", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "ValidationError", "message": "lineId must not be null" }, { "code": "ValidationError", "message": "costTypeId must not be null" }, { "code": "ValidationError", "message": "comments must not be blank" } ] } }, "malformedBody": { "$ref": "#/components/examples/MalformedBody" }, "objectVersionUnresolved": { "$ref": "#/components/examples/ObjectVersionUnresolved" }, "invalidBookHeader": { "$ref": "#/components/examples/InvalidBookHeader" } } } } }, "404": { "$ref": "#/components/responses/ContractNotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/revenue-management/contracts/{rcId}/allocate-action": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Production" } ], "post": { "tags": [ "Allocation" ], "operationId": "performAllocationAction", "summary": "Reallocate or mark a contract allocation-eligible", "description": "**Purpose**\n\nRuns an allocation action on the revenue contract. `REALLOCATE` re-runs the allocation of the transaction price across the contract's POBs based on standalone selling prices (SSP). `ALLOCATION_ELIGIBLE` makes the contract eligible for allocation.\n\n**When to use**\n\n- **REALLOCATE**: after SSPs, prices, or POB structure changed and the allocation must be recalculated.\n- **ALLOCATION_ELIGIBLE**: when a contract that was excluded from allocation must now be allocated.\n\n**Behavior notes**\n\n`action` is case-sensitive.\n", "parameters": [ { "$ref": "#/components/parameters/RcId" }, { "$ref": "#/components/parameters/BookId" }, { "$ref": "#/components/parameters/RequestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllocateActionRequest" }, "examples": { "reallocate": { "summary": "Reallocate", "value": { "action": "REALLOCATE" } }, "eligible": { "summary": "Make allocation-eligible", "value": { "action": "ALLOCATION_ELIGIBLE", "objectVersion": 5 } } } } } }, "responses": { "200": { "description": "Processed. `success: true` means the action completed; `success: false` means a business rule rejected it and `message` explains why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualActionResponse" }, "examples": { "done": { "summary": "Allocation performed", "value": { "success": true, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Allocation performed successfully" } }, "rejected": { "summary": "Rejected by a business rule (illustrative message)", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Revenue contract is not eligible for allocation" } } } } }, "headers": { "traceId": { "$ref": "#/components/headers/TraceId" } } }, "400": { "description": "Invalid request. Each problem is listed in `reasons`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientErrorResponse" }, "examples": { "missingAction": { "summary": "Missing action", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "ValidationError", "message": "action must not be blank" } ] } }, "unknownAction": { "summary": "Unknown action", "description": "The value is not one of the allowed values (values are case-sensitive).", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "InvalidRequest", "message": "No enum constant com.zuora.neo.engine.grpc.manualAction.v1.ReallocationAction.reallocate" } ] } }, "malformedBody": { "$ref": "#/components/examples/MalformedBody" }, "objectVersionUnresolved": { "$ref": "#/components/examples/ObjectVersionUnresolved" }, "invalidBookHeader": { "$ref": "#/components/examples/InvalidBookHeader" }, "engineRejected": { "$ref": "#/components/examples/EngineRejected" } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RcTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/RcServiceUnavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/revenue-management/contracts/{rcId}/switch-allocation": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Production" } ], "post": { "tags": [ "Allocation" ], "operationId": "switchAllocation", "summary": "Switch the allocation treatment of a contract", "description": "**Purpose**\n\nSwitches the allocation treatment of the revenue contract and re-runs the allocation of the transaction price in the revenue engine.\n\n**When to use**\n\n- The contract must move between allocation treatments, for example after a contract modification changes how it should be allocated.\n", "parameters": [ { "$ref": "#/components/parameters/RcId" }, { "$ref": "#/components/parameters/BookId" }, { "$ref": "#/components/parameters/RequestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SwitchAllocationRequest" }, "examples": { "current": { "summary": "Use the current version", "value": {} }, "explicit": { "summary": "Explicit version", "value": { "objectVersion": 5 } } } } } }, "responses": { "200": { "description": "Processed. `success: true` means the action completed; `success: false` means a business rule rejected it and `message` explains why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualActionResponse" }, "examples": { "done": { "summary": "Allocation switched", "value": { "success": true, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Allocation switched successfully" } }, "rejected": { "summary": "Rejected by a business rule (illustrative message)", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Revenue contract is frozen" } }, "unexpected": { "summary": "Unexpected error", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Error occurred during switch allocation" } } } } }, "headers": { "traceId": { "$ref": "#/components/headers/TraceId" } } }, "400": { "description": "Invalid request. Each problem is listed in `reasons`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientErrorResponse" }, "examples": { "malformedBody": { "$ref": "#/components/examples/MalformedBody" }, "objectVersionUnresolved": { "$ref": "#/components/examples/ObjectVersionUnresolved" }, "invalidBookHeader": { "$ref": "#/components/examples/InvalidBookHeader" }, "engineRejected": { "$ref": "#/components/examples/EngineRejected" } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RcTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/RcServiceUnavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/revenue-management/contracts/{rcId}/lines/{lineId}/edit": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Production" } ], "post": { "tags": [ "Lines and POBs" ], "operationId": "editRevenueContractLine", "summary": "Edit custom attributes of a contract line", "description": "**Purpose**\n\nUpdates the custom attributes of one revenue contract line: text attributes `atr1`-`atr60`, number attributes `num1`-`num15`, and date attributes `date1`-`date5`. Only the attributes you send change.\n\n**When to use**\n\n- Correct or enrich reporting attributes (region, segment, product family) on a line after it was collected.\n- Prices, quantities, and transaction dates cannot be changed with this operation.\n", "parameters": [ { "$ref": "#/components/parameters/RcId" }, { "name": "lineId", "in": "path", "required": true, "description": "Revenue contract line ID.", "schema": { "type": "integer", "format": "int64" }, "example": 85922 }, { "$ref": "#/components/parameters/BookId" }, { "$ref": "#/components/parameters/RequestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditLineRequest" }, "examples": { "minimal": { "summary": "Change one attribute", "value": { "comments": "Segment correction", "atr1": "EMEA" } }, "several": { "summary": "Change several attributes", "value": { "comments": "Q4 reporting update", "objectVersion": 5, "atr1": "EMEA", "num1": 12.5, "date1": "2026-01-31" } } } } } }, "responses": { "200": { "description": "Processed. `success: true` means the action completed; `success: false` means a business rule rejected it and `message` explains why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualActionResponse" }, "examples": { "done": { "summary": "Line edited", "value": { "success": true, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Line updated successfully" } }, "rejected": { "summary": "Rejected by a business rule (illustrative message)", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Revenue contract is frozen" } }, "unexpected": { "summary": "Unexpected error", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Error while editing line" } } } } }, "headers": { "traceId": { "$ref": "#/components/headers/TraceId" } } }, "400": { "description": "Invalid request. Each problem is listed in `reasons`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientErrorResponse" }, "examples": { "missingComments": { "summary": "Missing comments", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "ValidationError", "message": "comments must not be blank" } ] } }, "invalidDate": { "summary": "Invalid date", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "ValidationError", "message": "'date1' contains an invalid date value '31-01-2026'. Expected format: yyyy-MM-dd" } ] } }, "malformedBody": { "$ref": "#/components/examples/MalformedBody" }, "objectVersionUnresolved": { "$ref": "#/components/examples/ObjectVersionUnresolved" }, "invalidBookHeader": { "$ref": "#/components/examples/InvalidBookHeader" }, "engineRejected": { "$ref": "#/components/examples/EngineRejected" } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RcTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/RcServiceUnavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/revenue-management/contracts/{rcId}/pobs/edit": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Production" } ], "post": { "tags": [ "Lines and POBs" ], "operationId": "editPobs", "summary": "Edit several POBs of a contract", "description": "**Purpose**\n\nUpdates the name, POB template, template version, expiry date, and lead line of one or more performance obligations (POBs) of a revenue contract in one call.\n\n**When to use**\n\n- Reassign POBs to a different POB template (which changes their recognition rules) or correct POB attributes in bulk.\n- Use the single-POB operation to edit one POB.\n\n**Behavior notes**\n\nErrors from the revenue engine for this operation are returned as HTTP 200 with `success: false` and the generic message shown in the examples, not as 4xx/5xx responses.\n", "parameters": [ { "$ref": "#/components/parameters/RcId" }, { "$ref": "#/components/parameters/BookId" }, { "$ref": "#/components/parameters/RequestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditPobsRequest" }, "examples": { "bulk": { "summary": "Edit two POBs", "value": { "objectVersion": 5, "items": [ { "name": "Annual Support", "pobTemplateId": 100, "pobVersion": 2, "expiryDate": "2026-12-31", "leadLineId": 85922, "comments": "Updating POB attributes", "id": 156912 }, { "name": "Implementation", "pobTemplateId": 100, "pobVersion": 2, "expiryDate": "2026-12-31", "leadLineId": 85923, "comments": "Updating POB attributes", "id": 156913 } ] } } } } } }, "responses": { "200": { "description": "Processed. `success: true` means the action completed; `success: false` means a business rule rejected it and `message` explains why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualActionResponse" }, "examples": { "done": { "summary": "POBs edited", "value": { "success": true, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "POB attributes updated successfully" } }, "rejected": { "summary": "Rejected by a business rule (illustrative message)", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "POB template is not active" } }, "engineError": { "summary": "Revenue engine error", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Error while editing Pob Attributes: UNAVAILABLE: io exception" } } } } }, "headers": { "traceId": { "$ref": "#/components/headers/TraceId" } } }, "400": { "description": "Invalid request. Each problem is listed in `reasons`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientErrorResponse" }, "examples": { "missingItemField": { "summary": "Missing item field", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "ValidationError", "message": "items[0].pobTemplateId must not be null" }, { "code": "ValidationError", "message": "items[0].leadLineId must not be null" } ] } }, "malformedBody": { "$ref": "#/components/examples/MalformedBody" }, "objectVersionUnresolved": { "$ref": "#/components/examples/ObjectVersionUnresolved" }, "invalidBookHeader": { "$ref": "#/components/examples/InvalidBookHeader" } } } } }, "404": { "$ref": "#/components/responses/ContractNotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/revenue-management/contracts/{rcId}/pobs/{pobId}/edit": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Production" } ], "post": { "tags": [ "Lines and POBs" ], "operationId": "editPob", "summary": "Edit one POB of a contract", "description": "**Purpose**\n\nUpdates the name, POB template, template version, expiry date, and lead line of one performance obligation (POB).\n\n**When to use**\n\n- Reassign one POB to a different POB template or correct its attributes.\n\n**Behavior notes**\n\nErrors from the revenue engine for this operation are returned as HTTP 200 with `success: false` and the generic message shown in the examples, not as 4xx/5xx responses.\n", "parameters": [ { "$ref": "#/components/parameters/RcId" }, { "$ref": "#/components/parameters/PobId" }, { "$ref": "#/components/parameters/BookId" }, { "$ref": "#/components/parameters/RequestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditPobRequest" }, "examples": { "edit": { "summary": "Edit a POB", "value": { "name": "Annual Support", "pobTemplateId": 100, "pobVersion": 2, "expiryDate": "2026-12-31", "leadLineId": 85922, "comments": "Updating POB attributes" } } } } } }, "responses": { "200": { "description": "Processed. `success: true` means the action completed; `success: false` means a business rule rejected it and `message` explains why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualActionResponse" }, "examples": { "done": { "summary": "POB edited", "value": { "success": true, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "POB attributes updated successfully" } }, "rejected": { "summary": "Rejected by a business rule (illustrative message)", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "POB template is not active" } }, "engineError": { "summary": "Revenue engine error", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Error while editing Pob Attributes" } } } } }, "headers": { "traceId": { "$ref": "#/components/headers/TraceId" } } }, "400": { "description": "Invalid request. Each problem is listed in `reasons`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientErrorResponse" }, "examples": { "missingField": { "summary": "Missing field", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "ValidationError", "message": "name must not be null" } ] } }, "malformedBody": { "$ref": "#/components/examples/MalformedBody" }, "objectVersionUnresolved": { "$ref": "#/components/examples/ObjectVersionUnresolved" }, "invalidBookHeader": { "$ref": "#/components/examples/InvalidBookHeader" } } } } }, "404": { "$ref": "#/components/responses/ContractNotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/revenue-management/contracts/{rcId}/copyLn": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Production" } ], "post": { "tags": [ "Lines and POBs" ], "operationId": "copyLine", "summary": "Copy a line into a new manual POB", "description": "**Purpose**\n\nCreates a new manual POB and line in the revenue contract by copying a source line, optionally overriding its prices, quantity, and document fields.\n\n**When to use**\n\n- Add a performance obligation that was not in the source data, for example a free service promised outside the order, using an existing line as a template.\n", "parameters": [ { "$ref": "#/components/parameters/RcId" }, { "$ref": "#/components/parameters/BookId" }, { "$ref": "#/components/parameters/RequestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CopyLineRequest" }, "examples": { "minimal": { "summary": "Copy with required fields", "value": { "objectVersion": 5, "docLineId": "SO-1001-1", "pobName": "Free Training", "pobTemplateId": 100 } }, "overrides": { "summary": "Copy with overrides", "value": { "objectVersion": 5, "docLineId": "SO-1001-1", "pobName": "Free Training", "pobTemplateId": 100, "fvPrice": 500, "ordQty": 10, "unitSellPrc": 0, "extSllPrc": 0, "docDate": "2026-01-15", "comments": "Adding promised training" } } } } } }, "responses": { "200": { "description": "Processed. `success: true` means the action completed; `success: false` means a business rule rejected it and `message` explains why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualActionResponse" }, "examples": { "done": { "summary": "Line copied", "value": { "success": true, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Copy Line completed successfully" } }, "rejected": { "summary": "Rejected by a business rule (illustrative message)", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Action not allowed: soft freeze is in progress" } } } } }, "headers": { "traceId": { "$ref": "#/components/headers/TraceId" } } }, "400": { "description": "Invalid request. Each problem is listed in `reasons`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientErrorResponse" }, "examples": { "missingFields": { "summary": "Missing required fields", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "ValidationError", "message": "objectVersion must not be null" }, { "code": "ValidationError", "message": "docLineId must not be blank" }, { "code": "ValidationError", "message": "pobName must not be blank" }, { "code": "ValidationError", "message": "pobTemplateId must not be null" } ] } }, "malformedBody": { "$ref": "#/components/examples/MalformedBody" }, "objectVersionUnresolved": { "$ref": "#/components/examples/ObjectVersionUnresolved" }, "invalidBookHeader": { "$ref": "#/components/examples/InvalidBookHeader" }, "engineRejected": { "$ref": "#/components/examples/EngineRejected" } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RcTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/RcServiceUnavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/revenue-management/contracts/{rcId}/switch-lead-line": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Production" } ], "post": { "tags": [ "Lines and POBs" ], "operationId": "switchLeadLine", "summary": "Switch the lead line of a POB", "description": "**Purpose**\n\nMakes a different line the lead line of a performance obligation (POB). The lead line drives POB-level attributes such as dates and release events.\n\n**When to use**\n\n- The current lead line was cancelled or is no longer representative of the POB.\n", "parameters": [ { "$ref": "#/components/parameters/RcId" }, { "$ref": "#/components/parameters/BookId" }, { "$ref": "#/components/parameters/RequestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SwitchLeadLineRequest" }, "examples": { "switch": { "summary": "Switch lead line", "value": { "lineId": 85923, "rcPobId": 156912 } } } } } }, "responses": { "200": { "description": "Processed. `success: true` means the action completed; `success: false` means a business rule rejected it and `message` explains why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualActionResponse" }, "examples": { "done": { "summary": "Lead line switched", "value": { "success": true, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Lead line switched successfully" } }, "rejected": { "summary": "Rejected by a business rule (illustrative message)", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Line does not belong to the POB" } } } } }, "headers": { "traceId": { "$ref": "#/components/headers/TraceId" } } }, "400": { "description": "Invalid request. Each problem is listed in `reasons`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientErrorResponse" }, "examples": { "missingFields": { "summary": "Missing fields", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "ValidationError", "message": "lineId must not be null" }, { "code": "ValidationError", "message": "rcPobId must not be null" } ] } }, "malformedBody": { "$ref": "#/components/examples/MalformedBody" }, "objectVersionUnresolved": { "$ref": "#/components/examples/ObjectVersionUnresolved" }, "invalidBookHeader": { "$ref": "#/components/examples/InvalidBookHeader" }, "engineRejected": { "$ref": "#/components/examples/EngineRejected" } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RcTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/RcServiceUnavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/revenue-management/contracts/{rcId}/move-pob": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Production" } ], "post": { "tags": [ "Lines and POBs" ], "operationId": "movePob", "summary": "Move a POB to a different derived POB", "description": "**Purpose**\n\nChanges the POB assignment of a performance obligation, or of one of its lines, to a different derived POB.\n\n**When to use**\n\n- Lines were grouped into the wrong POB and must be reclassified.\n- Send `lineId` to move a single line.\n\n**Behavior notes**\n\nErrors from the revenue engine for this operation are returned as HTTP 200 with `success: false` and the generic message shown in the examples, not as 4xx/5xx responses.\n", "parameters": [ { "$ref": "#/components/parameters/RcId" }, { "$ref": "#/components/parameters/BookId" }, { "$ref": "#/components/parameters/RequestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MovePobRequest" }, "examples": { "move": { "summary": "Move a POB", "value": { "rcPobId": 156912, "rcDerivedPobId": 156915, "action": "MOVE", "comments": "Reclassifying POB" } }, "line": { "summary": "Move one line", "value": { "rcPobId": 156912, "rcDerivedPobId": 156915, "action": "MOVE", "lineId": 85923, "comments": "Moving one line" } } } } } }, "responses": { "200": { "description": "Processed. `success: true` means the action completed; `success: false` means a business rule rejected it and `message` explains why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualActionResponse" }, "examples": { "done": { "summary": "POB moved", "value": { "success": true, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "POB moved successfully" } }, "rejected": { "summary": "Rejected by a business rule (illustrative message)", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Target POB is not valid for this line" } }, "engineError": { "summary": "Revenue engine error", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Error occurred while moving Pob" } } } } }, "headers": { "traceId": { "$ref": "#/components/headers/TraceId" } } }, "400": { "description": "Invalid request. Each problem is listed in `reasons`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientErrorResponse" }, "examples": { "missingFields": { "summary": "Missing fields", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "ValidationError", "message": "rcPobId must not be null" }, { "code": "ValidationError", "message": "rcDerivedPobId must not be null" }, { "code": "ValidationError", "message": "comments must not be blank" }, { "code": "ValidationError", "message": "action must not be blank" } ] } }, "malformedBody": { "$ref": "#/components/examples/MalformedBody" }, "objectVersionUnresolved": { "$ref": "#/components/examples/ObjectVersionUnresolved" }, "invalidBookHeader": { "$ref": "#/components/examples/InvalidBookHeader" } } } } }, "404": { "$ref": "#/components/responses/ContractNotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/revenue-management/contracts/{rcId}/link-rc": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Production" } ], "post": { "tags": [ "Contract Grouping" ], "operationId": "linkContracts", "summary": "Link contracts into a revenue contract", "description": "**Purpose**\n\nMerges other revenue contracts into the contract in the path.\n\n**When to use**\n\n- Contracts that belong together (for example a sale and its later add-on) were created separately and must be allocated together.\n\n**Behavior notes**\n\nThe contract version is checked with optimistic locking. The revenue engine validates that the contract and the referenced objects are eligible.\n", "parameters": [ { "$ref": "#/components/parameters/RcId" }, { "$ref": "#/components/parameters/BookId" }, { "$ref": "#/components/parameters/RequestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkRcRequest" }, "examples": { "example": { "summary": "Link contracts into a revenue contract", "value": { "targetRcIds": [ 111450, 111451 ], "comments": "Regrouping per contract review" } } } } } }, "responses": { "200": { "description": "Processed. `success: true` means the action completed; `success: false` means a business rule rejected it and `message` explains why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualActionResponse" }, "examples": { "done": { "summary": "Action completed", "value": { "success": true, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Link completed successfully" } }, "rejected": { "summary": "Rejected by a business rule (illustrative message)", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Revenue contract is frozen" } } } } }, "headers": { "traceId": { "$ref": "#/components/headers/TraceId" } } }, "400": { "description": "Invalid request. Each problem is listed in `reasons`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientErrorResponse" }, "examples": { "emptyList": { "summary": "Empty targetRcIds", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "ValidationError", "message": "targetRcIds must not be empty" } ] } }, "malformedBody": { "$ref": "#/components/examples/MalformedBody" }, "objectVersionUnresolved": { "$ref": "#/components/examples/ObjectVersionUnresolved" }, "invalidBookHeader": { "$ref": "#/components/examples/InvalidBookHeader" }, "engineRejected": { "$ref": "#/components/examples/EngineRejected" } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RcTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/RcServiceUnavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/revenue-management/contracts/{rcId}/pobs/link": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Production" } ], "post": { "tags": [ "Contract Grouping" ], "operationId": "linkPobs", "summary": "Link POBs into a revenue contract", "description": "**Purpose**\n\nMoves the given POBs from other contracts into the contract in the path.\n\n**When to use**\n\n- A POB was grouped into the wrong contract.\n\n**Behavior notes**\n\nThe contract version is checked with optimistic locking. The revenue engine validates that the contract and the referenced objects are eligible.\n", "parameters": [ { "$ref": "#/components/parameters/RcId" }, { "$ref": "#/components/parameters/BookId" }, { "$ref": "#/components/parameters/RequestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkPobsRequest" }, "examples": { "example": { "summary": "Link POBs into a revenue contract", "value": { "rcPobIds": [ 156920 ], "comments": "Regrouping per contract review" } } } } } }, "responses": { "200": { "description": "Processed. `success: true` means the action completed; `success: false` means a business rule rejected it and `message` explains why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualActionResponse" }, "examples": { "done": { "summary": "Action completed", "value": { "success": true, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Link completed successfully" } }, "rejected": { "summary": "Rejected by a business rule (illustrative message)", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Revenue contract is frozen" } } } } }, "headers": { "traceId": { "$ref": "#/components/headers/TraceId" } } }, "400": { "description": "Invalid request. Each problem is listed in `reasons`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientErrorResponse" }, "examples": { "emptyList": { "summary": "Empty rcPobIds", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "ValidationError", "message": "rcPobIds must not be empty" } ] } }, "malformedBody": { "$ref": "#/components/examples/MalformedBody" }, "objectVersionUnresolved": { "$ref": "#/components/examples/ObjectVersionUnresolved" }, "invalidBookHeader": { "$ref": "#/components/examples/InvalidBookHeader" }, "engineRejected": { "$ref": "#/components/examples/EngineRejected" } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RcTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/RcServiceUnavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/revenue-management/contracts/{rcId}/lines/link": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Production" } ], "post": { "tags": [ "Contract Grouping" ], "operationId": "linkLines", "summary": "Link lines into a revenue contract", "description": "**Purpose**\n\nLinks document lines into the contract, attaching them to a POB (`rcPobId`) or grouping them under a lead line (`leadLineId`).\n\n**When to use**\n\n- Specific lines must join this contract.\n\n**Behavior notes**\n\nThe contract version is checked with optimistic locking. The revenue engine validates that the contract and the referenced objects are eligible.\n", "parameters": [ { "$ref": "#/components/parameters/RcId" }, { "$ref": "#/components/parameters/BookId" }, { "$ref": "#/components/parameters/RequestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkLinesRequest" }, "examples": { "example": { "summary": "Link lines into a revenue contract", "value": { "docLineIds": [ "SO-1001-1", "SO-1001-2" ], "comments": "Regrouping per contract review", "rcPobId": 156912 } }, "toLeadLine": { "summary": "Group under a lead line", "value": { "docLineIds": [ "SO-1001-1", "SO-1001-2" ], "leadLineId": 85922, "comments": "Grouping with lead line" } } } } } }, "responses": { "200": { "description": "Processed. `success: true` means the action completed; `success: false` means a business rule rejected it and `message` explains why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualActionResponse" }, "examples": { "done": { "summary": "Action completed", "value": { "success": true, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Link completed successfully" } }, "rejected": { "summary": "Rejected by a business rule (illustrative message)", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Revenue contract is frozen" } } } } }, "headers": { "traceId": { "$ref": "#/components/headers/TraceId" } } }, "400": { "description": "Invalid request. Each problem is listed in `reasons`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientErrorResponse" }, "examples": { "emptyList": { "summary": "Empty docLineIds", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "ValidationError", "message": "docLineIds must not be empty" } ] } }, "malformedBody": { "$ref": "#/components/examples/MalformedBody" }, "objectVersionUnresolved": { "$ref": "#/components/examples/ObjectVersionUnresolved" }, "invalidBookHeader": { "$ref": "#/components/examples/InvalidBookHeader" }, "engineRejected": { "$ref": "#/components/examples/EngineRejected" } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RcTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/RcServiceUnavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/revenue-management/contracts/{rcId}/charges/link": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Production" } ], "post": { "tags": [ "Contract Grouping" ], "operationId": "linkCharges", "summary": "Link charges into a revenue contract", "description": "**Purpose**\n\nLinks all lines of the given Zuora Billing charges into the contract.\n\n**When to use**\n\n- A subscription charge was grouped into a different contract.\n\n**Behavior notes**\n\nThe contract version is checked with optimistic locking. The revenue engine validates that the contract and the referenced objects are eligible.\n", "parameters": [ { "$ref": "#/components/parameters/RcId" }, { "$ref": "#/components/parameters/BookId" }, { "$ref": "#/components/parameters/RequestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkChargesRequest" }, "examples": { "example": { "summary": "Link charges into a revenue contract", "value": { "chargeNumbers": [ "C-00012345" ], "comments": "Regrouping per contract review" } } } } } }, "responses": { "200": { "description": "Processed. `success: true` means the action completed; `success: false` means a business rule rejected it and `message` explains why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualActionResponse" }, "examples": { "done": { "summary": "Action completed", "value": { "success": true, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Link completed successfully" } }, "rejected": { "summary": "Rejected by a business rule (illustrative message)", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Revenue contract is frozen" } } } } }, "headers": { "traceId": { "$ref": "#/components/headers/TraceId" } } }, "400": { "description": "Invalid request. Each problem is listed in `reasons`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientErrorResponse" }, "examples": { "emptyList": { "summary": "Empty chargeNumbers", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "ValidationError", "message": "chargeNumbers must not be empty" } ] } }, "malformedBody": { "$ref": "#/components/examples/MalformedBody" }, "objectVersionUnresolved": { "$ref": "#/components/examples/ObjectVersionUnresolved" }, "invalidBookHeader": { "$ref": "#/components/examples/InvalidBookHeader" }, "engineRejected": { "$ref": "#/components/examples/EngineRejected" } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RcTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/RcServiceUnavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/revenue-management/contracts/{rcId}/subscriptions/link": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Production" } ], "post": { "tags": [ "Contract Grouping" ], "operationId": "linkSubscriptions", "summary": "Link subscriptions into a revenue contract", "description": "**Purpose**\n\nLinks all lines of the given subscriptions into the contract.\n\n**When to use**\n\n- All lines of a subscription must be accounted for in this contract.\n\n**Behavior notes**\n\nThe contract version is checked with optimistic locking. The revenue engine validates that the contract and the referenced objects are eligible.\n", "parameters": [ { "$ref": "#/components/parameters/RcId" }, { "$ref": "#/components/parameters/BookId" }, { "$ref": "#/components/parameters/RequestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkSubscriptionsRequest" }, "examples": { "example": { "summary": "Link subscriptions into a revenue contract", "value": { "subscriptionIds": [ "A-S00001234" ], "comments": "Regrouping per contract review" } } } } } }, "responses": { "200": { "description": "Processed. `success: true` means the action completed; `success: false` means a business rule rejected it and `message` explains why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualActionResponse" }, "examples": { "done": { "summary": "Action completed", "value": { "success": true, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Link completed successfully" } }, "rejected": { "summary": "Rejected by a business rule (illustrative message)", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Revenue contract is frozen" } } } } }, "headers": { "traceId": { "$ref": "#/components/headers/TraceId" } } }, "400": { "description": "Invalid request. Each problem is listed in `reasons`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientErrorResponse" }, "examples": { "emptyList": { "summary": "Empty subscriptionIds", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "ValidationError", "message": "subscriptionIds must not be empty" } ] } }, "malformedBody": { "$ref": "#/components/examples/MalformedBody" }, "objectVersionUnresolved": { "$ref": "#/components/examples/ObjectVersionUnresolved" }, "invalidBookHeader": { "$ref": "#/components/examples/InvalidBookHeader" }, "engineRejected": { "$ref": "#/components/examples/EngineRejected" } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RcTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/RcServiceUnavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/revenue-management/contracts/{rcId}/delink-rc": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Production" } ], "post": { "tags": [ "Contract Grouping" ], "operationId": "delinkContract", "summary": "Delink a revenue contract", "description": "**Purpose**\n\nUndoes a contract-level link, so contracts that were merged into this one separate again.\n\n**When to use**\n\n- Contracts were merged by mistake.\n\n**Behavior notes**\n\nThe contract version is checked with optimistic locking. The revenue engine validates that the contract and the referenced objects are eligible.\n", "parameters": [ { "$ref": "#/components/parameters/RcId" }, { "$ref": "#/components/parameters/BookId" }, { "$ref": "#/components/parameters/RequestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DelinkRcRequest" }, "examples": { "example": { "summary": "Delink a revenue contract", "value": { "comments": "Regrouping per contract review" } } } } } }, "responses": { "200": { "description": "Processed. `success: true` means the action completed; `success: false` means a business rule rejected it and `message` explains why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualActionResponse" }, "examples": { "done": { "summary": "Action completed", "value": { "success": true, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Delink completed successfully" } }, "rejected": { "summary": "Rejected by a business rule (illustrative message)", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Revenue contract is frozen" } } } } }, "headers": { "traceId": { "$ref": "#/components/headers/TraceId" } } }, "400": { "description": "Invalid request. Each problem is listed in `reasons`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientErrorResponse" }, "examples": { "malformedBody": { "$ref": "#/components/examples/MalformedBody" }, "objectVersionUnresolved": { "$ref": "#/components/examples/ObjectVersionUnresolved" }, "invalidBookHeader": { "$ref": "#/components/examples/InvalidBookHeader" }, "engineRejected": { "$ref": "#/components/examples/EngineRejected" } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RcTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/RcServiceUnavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/revenue-management/contracts/{rcId}/pobs/delink": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Production" } ], "post": { "tags": [ "Contract Grouping" ], "operationId": "delinkPobs", "summary": "Delink POBs from a revenue contract", "description": "**Purpose**\n\nRemoves the given POBs, and their lines, from the contract so they regroup into separate contracts.\n\n**When to use**\n\n- A POB does not belong in this contract.\n\n**Behavior notes**\n\nThe contract version is checked with optimistic locking. The revenue engine validates that the contract and the referenced objects are eligible.\n", "parameters": [ { "$ref": "#/components/parameters/RcId" }, { "$ref": "#/components/parameters/BookId" }, { "$ref": "#/components/parameters/RequestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DelinkPobsRequest" }, "examples": { "example": { "summary": "Delink POBs from a revenue contract", "value": { "rcPobIds": [ 156912 ], "comments": "Regrouping per contract review" } } } } } }, "responses": { "200": { "description": "Processed. `success: true` means the action completed; `success: false` means a business rule rejected it and `message` explains why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualActionResponse" }, "examples": { "done": { "summary": "Action completed", "value": { "success": true, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Delink completed successfully" } }, "rejected": { "summary": "Rejected by a business rule (illustrative message)", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Revenue contract is frozen" } } } } }, "headers": { "traceId": { "$ref": "#/components/headers/TraceId" } } }, "400": { "description": "Invalid request. Each problem is listed in `reasons`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientErrorResponse" }, "examples": { "emptyList": { "summary": "Empty rcPobIds", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "ValidationError", "message": "rcPobIds must not be empty" } ] } }, "malformedBody": { "$ref": "#/components/examples/MalformedBody" }, "objectVersionUnresolved": { "$ref": "#/components/examples/ObjectVersionUnresolved" }, "invalidBookHeader": { "$ref": "#/components/examples/InvalidBookHeader" }, "engineRejected": { "$ref": "#/components/examples/EngineRejected" } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RcTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/RcServiceUnavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/revenue-management/contracts/{rcId}/lines/delink": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Production" } ], "post": { "tags": [ "Contract Grouping" ], "operationId": "delinkLines", "summary": "Delink lines from a revenue contract", "description": "**Purpose**\n\nRemoves specific document lines from the contract.\n\n**When to use**\n\n- A line does not belong in this contract.\n\n**Behavior notes**\n\nThe contract version is checked with optimistic locking. The revenue engine validates that the contract and the referenced objects are eligible.\n", "parameters": [ { "$ref": "#/components/parameters/RcId" }, { "$ref": "#/components/parameters/BookId" }, { "$ref": "#/components/parameters/RequestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DelinkLinesRequest" }, "examples": { "example": { "summary": "Delink lines from a revenue contract", "value": { "docLineIds": [ "SO-1001-2" ], "comments": "Regrouping per contract review" } } } } } }, "responses": { "200": { "description": "Processed. `success: true` means the action completed; `success: false` means a business rule rejected it and `message` explains why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualActionResponse" }, "examples": { "done": { "summary": "Action completed", "value": { "success": true, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Delink completed successfully" } }, "rejected": { "summary": "Rejected by a business rule (illustrative message)", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Revenue contract is frozen" } } } } }, "headers": { "traceId": { "$ref": "#/components/headers/TraceId" } } }, "400": { "description": "Invalid request. Each problem is listed in `reasons`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientErrorResponse" }, "examples": { "emptyList": { "summary": "Empty docLineIds", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "ValidationError", "message": "docLineIds must not be empty" } ] } }, "malformedBody": { "$ref": "#/components/examples/MalformedBody" }, "objectVersionUnresolved": { "$ref": "#/components/examples/ObjectVersionUnresolved" }, "invalidBookHeader": { "$ref": "#/components/examples/InvalidBookHeader" }, "engineRejected": { "$ref": "#/components/examples/EngineRejected" } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RcTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/RcServiceUnavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/revenue-management/contracts/{rcId}/charges/delink": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Production" } ], "post": { "tags": [ "Contract Grouping" ], "operationId": "delinkCharges", "summary": "Delink charges from a revenue contract", "description": "**Purpose**\n\nRemoves all lines of the given Zuora Billing charges from the contract.\n\n**When to use**\n\n- A charge must be accounted for separately.\n\n**Behavior notes**\n\nThe contract version is checked with optimistic locking. The revenue engine validates that the contract and the referenced objects are eligible.\n", "parameters": [ { "$ref": "#/components/parameters/RcId" }, { "$ref": "#/components/parameters/BookId" }, { "$ref": "#/components/parameters/RequestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DelinkChargesRequest" }, "examples": { "example": { "summary": "Delink charges from a revenue contract", "value": { "chargeNumbers": [ "C-00012345" ], "comments": "Regrouping per contract review" } } } } } }, "responses": { "200": { "description": "Processed. `success: true` means the action completed; `success: false` means a business rule rejected it and `message` explains why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualActionResponse" }, "examples": { "done": { "summary": "Action completed", "value": { "success": true, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Delink completed successfully" } }, "rejected": { "summary": "Rejected by a business rule (illustrative message)", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Revenue contract is frozen" } } } } }, "headers": { "traceId": { "$ref": "#/components/headers/TraceId" } } }, "400": { "description": "Invalid request. Each problem is listed in `reasons`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientErrorResponse" }, "examples": { "emptyList": { "summary": "Empty chargeNumbers", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "ValidationError", "message": "chargeNumbers must not be empty" } ] } }, "malformedBody": { "$ref": "#/components/examples/MalformedBody" }, "objectVersionUnresolved": { "$ref": "#/components/examples/ObjectVersionUnresolved" }, "invalidBookHeader": { "$ref": "#/components/examples/InvalidBookHeader" }, "engineRejected": { "$ref": "#/components/examples/EngineRejected" } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RcTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/RcServiceUnavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/revenue-management/contracts/{rcId}/subscriptions/delink": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Production" } ], "post": { "tags": [ "Contract Grouping" ], "operationId": "delinkSubscriptions", "summary": "Delink subscriptions from a revenue contract", "description": "**Purpose**\n\nRemoves all lines of the given subscriptions from the contract.\n\n**When to use**\n\n- A subscription must be accounted for separately.\n\n**Behavior notes**\n\nThe contract version is checked with optimistic locking. The revenue engine validates that the contract and the referenced objects are eligible.\n", "parameters": [ { "$ref": "#/components/parameters/RcId" }, { "$ref": "#/components/parameters/BookId" }, { "$ref": "#/components/parameters/RequestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DelinkSubscriptionsRequest" }, "examples": { "example": { "summary": "Delink subscriptions from a revenue contract", "value": { "subscriptionIds": [ "A-S00001234" ], "comments": "Regrouping per contract review" } } } } } }, "responses": { "200": { "description": "Processed. `success: true` means the action completed; `success: false` means a business rule rejected it and `message` explains why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualActionResponse" }, "examples": { "done": { "summary": "Action completed", "value": { "success": true, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Delink completed successfully" } }, "rejected": { "summary": "Rejected by a business rule (illustrative message)", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Revenue contract is frozen" } } } } }, "headers": { "traceId": { "$ref": "#/components/headers/TraceId" } } }, "400": { "description": "Invalid request. Each problem is listed in `reasons`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientErrorResponse" }, "examples": { "emptyList": { "summary": "Empty subscriptionIds", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "ValidationError", "message": "subscriptionIds must not be empty" } ] } }, "malformedBody": { "$ref": "#/components/examples/MalformedBody" }, "objectVersionUnresolved": { "$ref": "#/components/examples/ObjectVersionUnresolved" }, "invalidBookHeader": { "$ref": "#/components/examples/InvalidBookHeader" }, "engineRejected": { "$ref": "#/components/examples/EngineRejected" } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RcTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/RcServiceUnavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/revenue-management/contracts/{rcId}/undoDelink": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Production" } ], "post": { "tags": [ "Contract Grouping" ], "operationId": "undoDelink", "summary": "Undo a delink", "description": "**Purpose**\n\nReverses a previous delink on the revenue contract, restoring the contracts, POBs, or lines that were split off.\n\n**When to use**\n\n- A delink was done by mistake and must be reverted.\n", "parameters": [ { "$ref": "#/components/parameters/RcId" }, { "$ref": "#/components/parameters/BookId" }, { "$ref": "#/components/parameters/RequestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UndoDelinkRequest" }, "examples": { "undo": { "summary": "Undo a delink", "value": { "objectVersion": 5, "comments": "Reverting accidental delink" } } } } } }, "responses": { "200": { "description": "Processed. `success: true` means the action completed; `success: false` means a business rule rejected it and `message` explains why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualActionResponse" }, "examples": { "done": { "summary": "Delink undone", "value": { "success": true, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Undo delink completed successfully" } }, "rejected": { "summary": "Rejected by a business rule (illustrative message)", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "No delink found to undo" } } } } }, "headers": { "traceId": { "$ref": "#/components/headers/TraceId" } } }, "400": { "description": "Invalid request. Each problem is listed in `reasons`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientErrorResponse" }, "examples": { "missingVersion": { "summary": "Missing objectVersion", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "ValidationError", "message": "objectVersion must not be null" } ] } }, "malformedBody": { "$ref": "#/components/examples/MalformedBody" }, "objectVersionUnresolved": { "$ref": "#/components/examples/ObjectVersionUnresolved" }, "invalidBookHeader": { "$ref": "#/components/examples/InvalidBookHeader" }, "engineRejected": { "$ref": "#/components/examples/EngineRejected" } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RcTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/RcServiceUnavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/revenue-management/contracts/create-manual": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Production" } ], "post": { "tags": [ "Contract Grouping" ], "operationId": "createManualRevenueContract", "summary": "Create a manual revenue contract", "description": "**Purpose**\n\nCreates a new revenue contract by manually grouping whole contracts, or selected POBs and document lines.\n\n**When to use**\n\n- Automatic grouping rules did not produce the contract you need, for example lines from different orders must be accounted for as one contract.\n- Set `retain` on a POB to keep it in its source contract as well.\n\n**Behavior notes**\n\nThis operation has no `rcId` path parameter. The revenue engine validates that the selected objects are eligible. Every POB entry must include `id`.\n", "parameters": [ { "$ref": "#/components/parameters/BookId" }, { "$ref": "#/components/parameters/RequestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateManualRcRequest" }, "examples": { "fromContracts": { "summary": "Group whole contracts", "value": { "rcIds": [ 111450, 111451 ], "groupingTemplate": 5, "comments": "Manual grouping for Q2" } }, "fromPobs": { "summary": "Group POBs and lines", "value": { "rcPobIds": [ { "id": 156912, "retain": false } ], "docLineIds": [ "SO-2001-1" ], "comments": "Manual grouping for Q2" } } } } } }, "responses": { "200": { "description": "Processed. `success: true` means the action completed; `success: false` means a business rule rejected it and `message` explains why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualActionResponse" }, "examples": { "done": { "summary": "Contract created", "value": { "success": true, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Revenue contract created successfully" } }, "rejected": { "summary": "Rejected by a business rule (illustrative message)", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "No eligible POBs selected" } } } } }, "headers": { "traceId": { "$ref": "#/components/headers/TraceId" } } }, "400": { "description": "Invalid request. Each problem is listed in `reasons`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientErrorResponse" }, "examples": { "malformedBody": { "$ref": "#/components/examples/MalformedBody" }, "invalidBookHeader": { "$ref": "#/components/examples/InvalidBookHeader" }, "engineRejected": { "$ref": "#/components/examples/EngineRejected" } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/EngineNotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RcTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/RcServiceUnavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/revenue-management/contracts/{rcId}/vc-types": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Production" } ], "get": { "tags": [ "Variable Consideration" ], "operationId": "listVariableConsiderationTypes", "summary": "List variable consideration types for a line", "description": "**Purpose**\n\nReturns the variable consideration (VC) types that can still be applied to a line: enabled types that are configured on the line's POB template and not already applied to the line.\n\n**When to use**\n\n- Before applying variable consideration, to find a valid `vcTypeId`.\n\n**Behavior notes**\n\nPass the lead line of the POB as `rcLineId`; other lines return an empty list. An unknown contract or line also returns an empty list. `rcLineId` is required; omitting it returns HTTP 500.\n", "parameters": [ { "$ref": "#/components/parameters/RcId" }, { "name": "rcLineId", "in": "query", "required": true, "description": "Revenue contract line ID (the POB lead line).", "schema": { "type": "integer", "format": "int64" }, "example": 85922 }, { "name": "vcRuleType", "in": "query", "required": false, "description": "Only return types with this rule type: `E` estimate, `A` actuals, `S` set.", "schema": { "type": "string", "enum": [ "E", "A", "S" ] } }, { "$ref": "#/components/parameters/BookId" }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Applicable variable consideration types, sorted by name. Empty when none apply.", "headers": { "traceId": { "$ref": "#/components/headers/TraceId" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/VcType" } }, "examples": { "types": { "summary": "Applicable types", "value": [ { "id": 1, "value": "Rebate" }, { "id": 2, "value": "Volume Discount" } ] }, "none": { "summary": "No applicable type", "value": [] } } } } }, "400": { "description": "Invalid book header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientErrorResponse" }, "examples": { "invalidBookHeader": { "$ref": "#/components/examples/InvalidBookHeader" } } } } }, "500": { "description": "`rcLineId` is missing or not numeric, `rcId` is not numeric, or an unexpected failure occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerErrorResponse" }, "examples": { "systemError": { "$ref": "#/components/examples/SystemError" } } } } } } } }, "/revenue-management/contracts/{rcId}/apply-vc": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Production" } ], "post": { "tags": [ "Variable Consideration" ], "operationId": "applyVariableConsideration", "summary": "Apply variable consideration to a line", "description": "**Purpose**\n\nApplies variable consideration (for example a rebate, discount, or penalty) of a given type to a revenue contract line, as an amount or a percentage. This creates a line price adjustment that changes the transaction price and flows into allocation and revenue.\n\n**When to use**\n\n- Record an estimated (`E`), actual (`A`), or set (`S`) variable consideration that is not in the source data.\n- Send `dryRun: true` first to preview the effect without saving.\n- Find valid `vcTypeId` values with `GET /revenue-management/contracts/{rcId}/vc-types`.\n", "parameters": [ { "$ref": "#/components/parameters/RcId" }, { "$ref": "#/components/parameters/BookId" }, { "$ref": "#/components/parameters/RequestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplyVcRequest" }, "examples": { "estimate": { "summary": "Apply an estimated rebate", "value": { "rcLineId": 85922, "vcTypeId": 1, "applyValue": 1000, "applyType": "AMOUNT", "vcRuleType": "E", "comments": "Q1 rebate estimate" } }, "percent": { "summary": "Apply a percentage", "value": { "rcLineId": 85922, "vcTypeId": 2, "applyValue": 5, "applyType": "PERCENT", "vcRuleType": "A" } }, "dryRun": { "summary": "Preview only", "value": { "rcLineId": 85922, "vcTypeId": 1, "applyValue": 1000, "applyType": "AMOUNT", "vcRuleType": "E", "dryRun": true } } } } } }, "responses": { "200": { "description": "Processed. `success: true` means the action completed; `success: false` means a business rule rejected it and `message` explains why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplyVcResponse" }, "examples": { "applied": { "summary": "Variable consideration applied", "value": { "success": true, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Variable consideration applied successfully", "rcLineAdjustmentRecords": [ { "id": 7001, "lineId": 85922, "rcId": 111442, "bookId": 1, "vcTypeId": 1 } ] } }, "preview": { "summary": "Dry-run preview", "value": { "success": true, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Preview generated", "previewData": "{\"lineId\":85922,\"adjustmentAmount\":\"1000.00\"}" } }, "rejected": { "summary": "Rejected by a business rule (illustrative message)", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Variable consideration type is already applied to the line" } }, "unexpected": { "summary": "Unexpected error", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Error applying VC" } } } } }, "headers": { "traceId": { "$ref": "#/components/headers/TraceId" } } }, "400": { "description": "Invalid request. Each problem is listed in `reasons`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientErrorResponse" }, "examples": { "missingFields": { "summary": "Missing required fields", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "ValidationError", "message": "rcLineId must not be null" }, { "code": "ValidationError", "message": "vcTypeId must not be null" }, { "code": "ValidationError", "message": "applyValue must not be null" }, { "code": "ValidationError", "message": "applyType must not be null" }, { "code": "ValidationError", "message": "vcRuleType must not be null" } ] } }, "invalidRuleType": { "summary": "Invalid vcRuleType", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "InvalidRequest", "message": "No enum constant com.zuora.neo.engine.grpc.manualAction.v1.variableconsideration.VcRuleType.X" } ] } }, "invalidApplyType": { "summary": "Invalid applyType", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "InvalidRequest", "message": "No enum constant com.zuora.neo.engine.grpc.manualAction.v1.variableconsideration.ApplyType.AMT" } ] } }, "malformedBody": { "$ref": "#/components/examples/MalformedBody" }, "objectVersionUnresolved": { "$ref": "#/components/examples/ObjectVersionUnresolved" }, "invalidBookHeader": { "$ref": "#/components/examples/InvalidBookHeader" }, "engineRejected": { "$ref": "#/components/examples/EngineRejected" } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RcTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/RcServiceUnavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/revenue-management/contracts/{rcId}/expire-vc": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Production" } ], "post": { "tags": [ "Variable Consideration" ], "operationId": "expireVariableConsideration", "summary": "Expire variable consideration", "description": "**Purpose**\n\nExpires, for the given amount, a variable consideration previously applied to a line, for example when an unused rebate or credit lapses.\n\n**When to use**\n\n- The estimate behind a variable consideration will not be realized.\n- Use the `id` from `rcLineAdjustmentRecords` returned by apply-vc as `rcLinePriceAdjustmentId`.\n", "parameters": [ { "$ref": "#/components/parameters/RcId" }, { "$ref": "#/components/parameters/BookId" }, { "$ref": "#/components/parameters/RequestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExpireVcRequest" }, "examples": { "expire": { "summary": "Expire an amount", "value": { "rcLinePriceAdjustmentId": 7001, "amount": 250 } } } } } }, "responses": { "200": { "description": "Processed. `success: true` means the action completed; `success: false` means a business rule rejected it and `message` explains why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualActionResponse" }, "examples": { "done": { "summary": "Variable consideration expired", "value": { "success": true, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Variable consideration expired successfully" } }, "rejected": { "summary": "Rejected by a business rule (illustrative message)", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Expiry amount exceeds the remaining variable consideration" } }, "unexpected": { "summary": "Unexpected error", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Error while processing VC expiry" } } } } }, "headers": { "traceId": { "$ref": "#/components/headers/TraceId" } } }, "400": { "description": "Invalid request. Each problem is listed in `reasons`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientErrorResponse" }, "examples": { "missingFields": { "summary": "Missing fields", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "ValidationError", "message": "rcLinePriceAdjustmentId must not be null" }, { "code": "ValidationError", "message": "amount must not be null" } ] } }, "malformedBody": { "$ref": "#/components/examples/MalformedBody" }, "objectVersionUnresolved": { "$ref": "#/components/examples/ObjectVersionUnresolved" }, "invalidBookHeader": { "$ref": "#/components/examples/InvalidBookHeader" }, "engineRejected": { "$ref": "#/components/examples/EngineRejected" } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RcTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/RcServiceUnavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/revenue-management/contracts/{rcId}/apply-impairment": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Production" } ], "post": { "tags": [ "Impairment" ], "operationId": "applyImpairment", "summary": "Apply impairment to contract lines", "description": "**Purpose**\n\nFlags one or more revenue contract lines with an impairment type, so the revenue engine applies the matching impairment accounting.\n\n**When to use**\n\n- A contract modification or credit event requires impairment accounting for specific lines.\n- Impairment types: `1` contract impairment, `2` new POB ratable, `4` R and R within SSP, `N` none.\n\n**Behavior notes**\n\nErrors from the revenue engine for this operation are returned as HTTP 200 with `success: false` and the generic message shown in the examples, not as 4xx/5xx responses.\n", "parameters": [ { "$ref": "#/components/parameters/RcId" }, { "$ref": "#/components/parameters/BookId" }, { "$ref": "#/components/parameters/RequestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplyImpairmentRequest" }, "examples": { "impair": { "summary": "Impair a line", "value": { "lines": [ { "id": 85922, "comments": "Customer credit impaired", "impairmentType": "1" } ] } } } } } }, "responses": { "200": { "description": "Processed. `success: true` means the action completed; `success: false` means a business rule rejected it and `message` explains why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualActionResponse" }, "examples": { "done": { "summary": "Impairment applied", "value": { "success": true, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Impairment applied successfully" } }, "rejected": { "summary": "Rejected by a business rule (illustrative message)", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Line is not eligible for impairment" } }, "engineError": { "summary": "Revenue engine error", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Error while applying impairment" } } } } }, "headers": { "traceId": { "$ref": "#/components/headers/TraceId" } } }, "400": { "description": "Invalid request. Each problem is listed in `reasons`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientErrorResponse" }, "examples": { "emptyLines": { "summary": "No lines", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "ValidationError", "message": "lines must not be empty" } ] } }, "missingLineFields": { "summary": "Missing line fields", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "ValidationError", "message": "lines[0].comments must not be blank" }, { "code": "ValidationError", "message": "lines[0].impairmentType must not be blank" } ] } }, "malformedBody": { "$ref": "#/components/examples/MalformedBody" }, "objectVersionUnresolved": { "$ref": "#/components/examples/ObjectVersionUnresolved" }, "invalidBookHeader": { "$ref": "#/components/examples/InvalidBookHeader" } } } } }, "404": { "$ref": "#/components/responses/ContractNotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/revenue-management/contracts/{rcId}/edit-usage": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Production" } ], "post": { "tags": [ "Usage" ], "operationId": "editUsage", "summary": "Edit usage records", "description": "**Purpose**\n\nUpdates the quantity, usage amount, unit price, or usage attributes of one or more usage records that feed usage-based revenue. Only the fields you send change.\n\n**When to use**\n\n- Usage data loaded into Zuora Revenue was wrong and must be corrected without reloading it.\n\n**Behavior notes**\n\nUsage records are identified by their own `id`; the contract in the path is not checked.\n", "parameters": [ { "$ref": "#/components/parameters/RcId" }, { "$ref": "#/components/parameters/BookId" }, { "$ref": "#/components/parameters/RequestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditUsageRequest" }, "examples": { "edit": { "summary": "Correct a usage record", "value": { "items": [ { "id": 12345, "quantity": 10, "usageAmount": 250, "unitPrice": 25 } ] } } } } } }, "responses": { "200": { "description": "Processed. `success: true` means the action completed; `success: false` means a business rule rejected it and `message` explains why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualActionResponse" }, "examples": { "done": { "summary": "Usage edited", "value": { "success": true, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Edit usage completed" } }, "rejected": { "summary": "Rejected by a business rule", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "No usage record found" } } } } }, "headers": { "traceId": { "$ref": "#/components/headers/TraceId" } } }, "400": { "description": "Invalid request. Each problem is listed in `reasons`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientErrorResponse" }, "examples": { "emptyItems": { "summary": "No items", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "ValidationError", "message": "items must not be empty" } ] } }, "invalidId": { "summary": "Invalid usage ID", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "ValidationError", "message": "items[0].id must be greater than 0" } ] } }, "malformedBody": { "$ref": "#/components/examples/MalformedBody" }, "invalidBookHeader": { "$ref": "#/components/examples/InvalidBookHeader" }, "engineRejected": { "$ref": "#/components/examples/EngineRejected" } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/EngineNotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RcTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/RcServiceUnavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/revenue-management/contracts/{rcId}/usage-cancel": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Production" } ], "post": { "tags": [ "Usage" ], "operationId": "cancelUsage", "summary": "Cancel a usage record", "description": "**Purpose**\n\nCancels a usage record so it no longer contributes to usage-based revenue.\n\n**When to use**\n\n- A usage record was loaded in error or was reversed in the source system.\n\n**Behavior notes**\n\nThe contract in the path is not checked.\n", "parameters": [ { "$ref": "#/components/parameters/RcId" }, { "$ref": "#/components/parameters/BookId" }, { "$ref": "#/components/parameters/RequestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelUsageRequest" }, "examples": { "cancel": { "summary": "Cancel a usage record", "value": { "usageId": 12345 } } } } } }, "responses": { "200": { "description": "Processed. `success: true` means the action completed; `success: false` means a business rule rejected it and `message` explains why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualActionResponse" }, "examples": { "done": { "summary": "Usage cancelled", "value": { "success": true, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Usage record cancelled successfully" } }, "rejected": { "summary": "Rejected by a business rule", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "No usage record found with id: 12345" } } } } }, "headers": { "traceId": { "$ref": "#/components/headers/TraceId" } } }, "400": { "description": "Invalid request. Each problem is listed in `reasons`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientErrorResponse" }, "examples": { "missingId": { "summary": "Missing usageId", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "ValidationError", "message": "usageId must not be null" } ] } }, "invalidId": { "summary": "Invalid usageId", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "ValidationError", "message": "usageId must be greater than 0" } ] } }, "malformedBody": { "$ref": "#/components/examples/MalformedBody" }, "invalidBookHeader": { "$ref": "#/components/examples/InvalidBookHeader" }, "engineRejected": { "$ref": "#/components/examples/EngineRejected" } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/EngineNotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RcTooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/RcServiceUnavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/revenue-management/contracts/{rcId}/void-billing": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Production" } ], "post": { "tags": [ "Billing" ], "operationId": "voidBilling", "summary": "Void a billing document", "description": "**Purpose**\n\nVoids a billing document (invoice or credit memo) on the revenue contract, reversing its billed amounts from the contract's billing, contract asset, and contract liability balances.\n\n**When to use**\n\n- A billing document was voided or issued in error in the billing system and Zuora Revenue must reflect it.\n\n**Behavior notes**\n\nErrors from the revenue engine for this operation are returned as HTTP 200 with `success: false` and the generic message shown in the examples, not as 4xx/5xx responses. The contract in the path is validated by the revenue engine.\n", "parameters": [ { "$ref": "#/components/parameters/RcId" }, { "$ref": "#/components/parameters/BookId" }, { "$ref": "#/components/parameters/RequestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoidBillingRequest" }, "examples": { "void": { "summary": "Void an invoice", "value": { "billDocNumber": "INV00012345", "reason": "Duplicate invoice", "comment": "Customer requested void" } } } } } }, "responses": { "200": { "description": "Processed. `success: true` means the action completed; `success: false` means a business rule rejected it and `message` explains why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualActionResponse" }, "examples": { "done": { "summary": "Billing voided", "value": { "success": true, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Billing voided successfully" } }, "rejected": { "summary": "Rejected by a business rule (illustrative message)", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Billing document not found on the revenue contract" } }, "engineError": { "summary": "Revenue engine error", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Error while applying void billing" } } } } }, "headers": { "traceId": { "$ref": "#/components/headers/TraceId" } } }, "400": { "description": "Invalid request. Each problem is listed in `reasons`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientErrorResponse" }, "examples": { "missingFields": { "summary": "Missing fields", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "ValidationError", "message": "billDocNumber must not be blank" }, { "code": "ValidationError", "message": "reason must not be blank" } ] } }, "malformedBody": { "$ref": "#/components/examples/MalformedBody" }, "invalidBookHeader": { "$ref": "#/components/examples/InvalidBookHeader" } } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/revenue-management/contracts/{rcId}/generate-forecast": { "servers": [ { "url": "https://one.zuora.com/revenue/services/v1", "description": "Production" } ], "post": { "tags": [ "Forecast" ], "operationId": "generateForecast", "summary": "Generate the revenue forecast", "description": "**Purpose**\n\nRegenerates the forecast revenue schedules of the revenue contract in real time.\n\n**When to use**\n\n- After a change to the contract (for example an edit or a hold release) when you need the forecast to be current immediately, without waiting for the scheduled job.\n\n**Behavior notes**\n\nNo request body is needed. Errors from the revenue engine for this operation are returned as HTTP 200 with `success: false` and the generic message shown in the examples, not as 4xx/5xx responses.\n", "parameters": [ { "$ref": "#/components/parameters/RcId" }, { "$ref": "#/components/parameters/BookId" }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Processed. `success: true` means the action completed; `success: false` means a business rule rejected it and `message` explains why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualActionResponse" }, "examples": { "done": { "summary": "Forecast generated", "value": { "success": true, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Forecast Generated Successfully" } }, "rejected": { "summary": "Rejected by a business rule (illustrative message)", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Revenue contract has no forecastable lines" } }, "engineError": { "summary": "Revenue engine error", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "message": "Error while generating forecast for rc 111442" } } } } }, "headers": { "traceId": { "$ref": "#/components/headers/TraceId" } } }, "400": { "description": "Invalid request. Each problem is listed in `reasons`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientErrorResponse" }, "examples": { "invalidBookHeader": { "$ref": "#/components/examples/InvalidBookHeader" } } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/revenue/services/v1/reports": { "servers": [ { "url": "https://one.zuora.com", "description": "Zuora One production. Revenue Reporting paths start with /revenue/services/v1; Integration Reporting paths start with /api/integration/v1 or /api/integration/v2." } ], "get": { "tags": [ "Report Catalog" ], "security": [ { "OneIdOAuth": [] } ], "summary": "List reports", "description": "Returns the report definitions in your tenant's report catalog, sorted by report name. Each item identifies a report and describes what it contains. This operation does not run a report and returns no report data.\n\n**Purpose:** Use it as the first call of a reporting integration to find the numeric `id` of the report you want to run. Filter by `name` or `category` to avoid paging through the whole catalog.\n\n**When to use:** At the start of any reporting integration, when you know a report's name or category but not its numeric ID, or when you want to show users the reports they can run.\n\n**Notes:**\n\n- `name` and `category` are exact matches that ignore letter case. `name` matches either the stored report name or its translated display name.\n- Pages are zero-based. The response is a plain JSON array; when it has fewer than `size` items you have reached the last page.\n\n### Request definition\n\n| Parameter | In | Type | Required | Default | Description |\n|---|---|---|---|---|---|\n| `id` | query | integer | No | | Return only the report with this identifier. |\n| `name` | query | string | No | | Return only the report with this exact name (case-insensitive). |\n| `category` | query | string | No | | Return only reports in this category (case-insensitive). |\n| `page` | query | integer | No | `0` | Zero-based page number. |\n| `size` | query | integer | No | `20` | Number of reports per page. Must be 1 or greater. |\n| `Accept-Language` | header | string | No | | Optional language for translated report names, labels and filter options, for example `en` or `ja`. Defaults to the user's profile language. |\n| `Zuora-Track-Id` | header | string | No | | Optional correlation identifier (up to 64 characters) that you choose. The Zuora One gateway records it; quote it to Zuora Support when you report a problem. |\n| `Authorization` | header | string | Yes | | `Bearer ` (Zuora OneID OAuth). |\n\n**Request body:** none.\n\n### Response definition\n\n| HTTP status | Content type | Response schema |\n|---|---|---|\n| `200` | `application/json` | array of Report |\n| `400` | `application/json` | ServiceError or SpringError |\n| `401` | `application/json` | GatewayError |\n| `403` | `application/json` | GatewayError |\n| `429` | `application/json` | GatewayError |\n| `500` | `application/json` | ServiceError |\n\n*Report*: A report definition in the tenant's report catalog. A report describes a data set (for example revenue waterfall or deferred revenue balances). It does not contain row data.\n\n| Field | Type | Required | Description |\n|---|---|---|---|\n| `id` | integer | No | Unique numeric identifier of the report definition. Use it as `reportId` in every other Reports call. |\n| `name` | string | No | Display name of the report. List reports returns the translated name when a translation exists for the caller's language; other operations return the stored name. |\n| `description` | string | No | Business description of what the report contains. |\n| `category` | string | No | Catalog grouping the report belongs to, as configured in Zuora Revenue. |\n| `sequence` | integer | No | Display order of the report inside its category. Lower numbers are shown first. |\n| `createdBy` | string | No | User name that created the report definition. |\n| `createdAt` | string (date-time) | No | Date and time the report definition was created, formatted `yyyy-MM-dd'T'HH:mm:ss`. |\n| `updatedBy` | string | No | User name that last changed the report definition. |\n| `updatedAt` | string (date-time) | No | Date and time the report definition was last changed, formatted `yyyy-MM-dd'T'HH:mm:ss`. |\n\nError response schemas (GatewayError, ServiceError, SpringError, SimpleError, MissingFiltersError, RunStatusConflict, RiaError, SignedUrlError) are defined once under *Error response schemas* in the API overview and in `components/schemas`.\n\n\n**Response codes:** `200`, `400`, `401`, `403`, `429`, `500`. Each response with a body includes worked examples; responses without a body say so.", "operationId": "listReports", "parameters": [ { "name": "id", "in": "query", "required": false, "description": "Return only the report with this identifier.", "schema": { "type": "integer", "format": "int32" }, "example": 10021 }, { "name": "name", "in": "query", "required": false, "description": "Return only the report with this exact name (case-insensitive).", "schema": { "type": "string" }, "example": "Revenue Waterfall Report" }, { "name": "category", "in": "query", "required": false, "description": "Return only reports in this category (case-insensitive).", "schema": { "type": "string" }, "example": "Revenue" }, { "name": "page", "in": "query", "required": false, "description": "Zero-based page number.", "schema": { "type": "integer", "default": 0, "format": "int32", "minimum": 0 }, "example": 0 }, { "name": "size", "in": "query", "required": false, "description": "Number of reports per page. Must be 1 or greater.", "schema": { "type": "integer", "default": 20, "format": "int32", "minimum": 1 }, "example": 20 }, { "name": "Accept-Language", "in": "header", "required": false, "description": "Optional language for translated report names, labels and filter options, for example `en` or `ja`. Defaults to the user's profile language.", "schema": { "type": "string" }, "example": "en" }, { "name": "Zuora-Track-Id", "in": "header", "required": false, "description": "Optional correlation identifier (up to 64 characters) that you choose. The Zuora One gateway records it; quote it to Zuora Support when you report a problem.", "schema": { "type": "string" }, "example": "close-run-2026-09-001" } ], "responses": { "200": { "description": "**Success.** The matching reports (possibly an empty array).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Report" } }, "examples": { "byCategory": { "summary": "Reports in the Revenue category", "value": [ { "id": 10021, "name": "Revenue Waterfall Report", "description": "Recognized and scheduled revenue by period for each revenue contract line", "category": "Revenue", "sequence": 3, "createdBy": "SYSADMIN", "createdAt": "2024-01-15T09:30:00", "updatedBy": "FIN.ADMIN", "updatedAt": "2026-08-02T14:05:11" }, { "id": 10034, "name": "Deferred Revenue Roll Forward", "description": "Opening balance, additions, recognition and closing deferred revenue by period", "category": "Revenue", "sequence": 5, "createdBy": "SYSADMIN", "createdAt": "2024-01-15T09:30:00", "updatedBy": "SYSADMIN", "updatedAt": "2025-11-20T08:00:00" } ] }, "empty": { "summary": "No report matches the filters", "value": [] } } } } }, "400": { "description": "**Failure.** A query parameter is invalid, for example a negative `page` or a `size` of 0. Also returned when the tenant could not be resolved for Zuora Revenue.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ServiceError" }, { "$ref": "#/components/schemas/SpringError" } ] }, "examples": { "badPage": { "summary": "Invalid pagination", "value": { "message": "An error occurred: Invalid pagination parameters: page=-1, size=20", "code": "1" } }, "tenant": { "$ref": "#/components/examples/Tenant" } } } } }, "401": { "$ref": "#/components/responses/ReportingUnauthorized" }, "403": { "$ref": "#/components/responses/ReportingForbidden" }, "429": { "$ref": "#/components/responses/ReportingTooManyRequests" }, "500": { "description": "**Failure.** Unexpected server error. A non-numeric value for an integer parameter (for example `page=abc`) is also reported with this status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceError" }, "examples": { "typeMismatch": { "summary": "Non-numeric page", "value": { "message": "An error occurred: Method parameter 'page': Failed to convert value of type 'java.lang.String' to required type 'int'; For input string: \"abc\"", "code": "1" } } } } } } } } }, "/revenue/services/v1/reports/{reportId}": { "servers": [ { "url": "https://one.zuora.com", "description": "Zuora One production. Revenue Reporting paths start with /revenue/services/v1; Integration Reporting paths start with /api/integration/v1 or /api/integration/v2." } ], "get": { "tags": [ "Report Catalog" ], "security": [ { "OneIdOAuth": [] } ], "summary": "Retrieve a report", "description": "Returns one report definition by its identifier.\n\n**Purpose:** Confirm that a report exists and read its name, category and audit details before you list its layouts or run it.\n\n**When to use:** When you already have a report ID (from configuration or a previous call) and want to confirm it still exists before you list layouts or run it.\n\n### Request definition\n\n| Parameter | In | Type | Required | Default | Description |\n|---|---|---|---|---|---|\n| `reportId` | path | integer | Yes | | Identifier of the report (`id` from List reports). |\n| `Zuora-Track-Id` | header | string | No | | Optional correlation identifier (up to 64 characters) that you choose. The Zuora One gateway records it; quote it to Zuora Support when you report a problem. |\n| `Authorization` | header | string | Yes | | `Bearer ` (Zuora OneID OAuth). |\n\n**Request body:** none.\n\n### Response definition\n\n| HTTP status | Content type | Response schema |\n|---|---|---|\n| `200` | `application/json` | Report |\n| `400` | `application/json` | SpringError |\n| `401` | `application/json` | GatewayError |\n| `403` | `application/json` | GatewayError |\n| `404` | none | No body |\n| `429` | `application/json` | GatewayError |\n| `500` | `application/json` | ServiceError |\n\n*Report*: A report definition in the tenant's report catalog. A report describes a data set (for example revenue waterfall or deferred revenue balances). It does not contain row data.\n\n| Field | Type | Required | Description |\n|---|---|---|---|\n| `id` | integer | No | Unique numeric identifier of the report definition. Use it as `reportId` in every other Reports call. |\n| `name` | string | No | Display name of the report. List reports returns the translated name when a translation exists for the caller's language; other operations return the stored name. |\n| `description` | string | No | Business description of what the report contains. |\n| `category` | string | No | Catalog grouping the report belongs to, as configured in Zuora Revenue. |\n| `sequence` | integer | No | Display order of the report inside its category. Lower numbers are shown first. |\n| `createdBy` | string | No | User name that created the report definition. |\n| `createdAt` | string (date-time) | No | Date and time the report definition was created, formatted `yyyy-MM-dd'T'HH:mm:ss`. |\n| `updatedBy` | string | No | User name that last changed the report definition. |\n| `updatedAt` | string (date-time) | No | Date and time the report definition was last changed, formatted `yyyy-MM-dd'T'HH:mm:ss`. |\n\nError response schemas (GatewayError, ServiceError, SpringError, SimpleError, MissingFiltersError, RunStatusConflict, RiaError, SignedUrlError) are defined once under *Error response schemas* in the API overview and in `components/schemas`.\n\n\n**Response codes:** `200`, `400`, `401`, `403`, `404`, `429`, `500`. Each response with a body includes worked examples; responses without a body say so.", "operationId": "getReport", "parameters": [ { "name": "reportId", "in": "path", "required": true, "description": "Identifier of the report (`id` from List reports).", "schema": { "type": "integer", "format": "int32" }, "example": 10021 }, { "name": "Zuora-Track-Id", "in": "header", "required": false, "description": "Optional correlation identifier (up to 64 characters) that you choose. The Zuora One gateway records it; quote it to Zuora Support when you report a problem.", "schema": { "type": "string" }, "example": "close-run-2026-09-001" } ], "responses": { "200": { "description": "**Success.** The report.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Report" }, "examples": { "found": { "summary": "Report found", "value": { "id": 10021, "name": "Revenue Waterfall Report", "description": "Recognized and scheduled revenue by period for each revenue contract line", "category": "Revenue", "sequence": 3, "createdBy": "SYSADMIN", "createdAt": "2024-01-15T09:30:00", "updatedBy": "FIN.ADMIN", "updatedAt": "2026-08-02T14:05:11" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/ReportingUnauthorized" }, "403": { "$ref": "#/components/responses/ReportingForbidden" }, "404": { "description": "**Failure.** No report has this identifier. The response has no body." }, "429": { "$ref": "#/components/responses/ReportingTooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/revenue/services/v1/reports/{reportId}/layouts": { "servers": [ { "url": "https://one.zuora.com", "description": "Zuora One production. Revenue Reporting paths start with /revenue/services/v1; Integration Reporting paths start with /api/integration/v1 or /api/integration/v2." } ], "get": { "tags": [ "Report Catalog" ], "security": [ { "OneIdOAuth": [] } ], "summary": "List layouts of a report", "description": "Returns every layout of a report, sorted by layout name. Each layout includes its output columns (`fields`) and its filters with default values, required flags and allowed values.\n\n**Purpose:** Choose the `layoutId` you will run and learn which filters you must or may supply, without a separate call per layout.\n\n**When to use:** Before your first run of a report, or whenever a layout may have changed, to choose a `layoutId` and learn which filters are required and which values are allowed.\n\n**Notes:**\n\n- If the report does not exist or has no layouts, the response is `200` with an empty `layouts` array and `totalCount` 0.\n- `name` is an exact, case-insensitive match on the layout name.\n\n### Request definition\n\n| Parameter | In | Type | Required | Default | Description |\n|---|---|---|---|---|---|\n| `reportId` | path | integer | Yes | | Identifier of the report. |\n| `name` | query | string | No | | Return only the layout with this exact name (case-insensitive). |\n| `Accept-Language` | header | string | No | | Optional language for translated report names, labels and filter options, for example `en` or `ja`. Defaults to the user's profile language. |\n| `Zuora-Track-Id` | header | string | No | | Optional correlation identifier (up to 64 characters) that you choose. The Zuora One gateway records it; quote it to Zuora Support when you report a problem. |\n| `Authorization` | header | string | Yes | | `Bearer ` (Zuora OneID OAuth). |\n\n**Request body:** none.\n\n### Response definition\n\n| HTTP status | Content type | Response schema |\n|---|---|---|\n| `200` | `application/json` | LayoutList |\n| `400` | `application/json` | SpringError |\n| `401` | `application/json` | GatewayError |\n| `403` | `application/json` | GatewayError |\n| `429` | `application/json` | GatewayError |\n| `500` | `application/json` | ServiceError |\n\n*LayoutList*: Wrapper returned by the list-layouts operation.\n\n| Field | Type | Required | Description |\n|---|---|---|---|\n| `layouts` | array of ReportLayout | No | Layouts of the report, sorted by layout name. Each layout includes its fields and filters. |\n| `layouts[].id` | integer | No | Unique identifier of the layout. Send it as `layoutId` when you run the report. |\n| `layouts[].reportId` | integer | No | Identifier of the report the layout belongs to. |\n| `layouts[].name` | string | No | Layout name. |\n| `layouts[].description` | string | No | Layout description. |\n| `layouts[].filenamePrefix` | string | No | Prefix used for the generated output file name. |\n| `layouts[].createdBy` | string | No | User name that created the layout. |\n| `layouts[].createdAt` | string (date-time) | No | Creation date and time, formatted `yyyy-MM-dd'T'HH:mm:ss`. |\n| `layouts[].updatedBy` | string | No | User name that last changed the layout. |\n| `layouts[].updatedAt` | string (date-time) | No | Last change date and time, formatted `yyyy-MM-dd'T'HH:mm:ss`. |\n| `layouts[].fields` | array of LayoutField | No | Output columns of the layout, in output order. |\n| `layouts[].fields[].id` | integer | No | Unique identifier of this column assignment within the layout. |\n| `layouts[].fields[].layoutId` | integer | No | Identifier of the layout the column belongs to. |\n| `layouts[].fields[].fieldId` | integer | No | Identifier of the underlying report field (column definition). |\n| `layouts[].fields[].seq` | integer | No | Position of the column in the output file. Lower numbers appear further left. |\n| `layouts[].fields[].sortSeq` | integer | No | Sort priority of the column. `null` when the layout does not sort by this column. |\n| `layouts[].fields[].fieldName` | string | No | Technical field name in lowerCamelCase. Use this value as `fieldName` when you filter a report run. |\n| `layouts[].fields[].fieldLabel` | string | No | Column heading shown in the output file, translated to the caller's language when a translation exists. |\n| `layouts[].fields[].fieldType` | string | No | Database data type of the column, for example `VARCHAR2`, `NUMBER`, `DATE` or `DATE_TIME`. |\n| `layouts[].filters` | array of LayoutFilter | No | Filters defined on the layout, with required flags and allowed values. |\n| `layouts[].filters[].id` | integer | No | Unique identifier of the filter definition. |\n| `layouts[].filters[].layoutId` | integer | No | Identifier of the layout the filter belongs to. |\n| `layouts[].filters[].fieldId` | integer | No | Identifier of the report field the filter applies to. |\n| `layouts[].filters[].fieldName` | string | No | Technical field name in lowerCamelCase. Send this as `fieldName` in a run request to override the filter. |\n| `layouts[].filters[].fieldLabel` | string | No | Display label of the filter, translated when a translation exists. |\n| `layouts[].filters[].fieldType` | string | No | Database data type of the filtered field, for example `VARCHAR2`, `NUMBER`, `DATE` or `DATE_TIME`. |\n| `layouts[].filters[].type` | string | No | How the filter is presented and evaluated, for example `LOV` (pick from a list), `RANGE` (from/to) or `EQUALS` (single value). |\n| `layouts[].filters[].valueFrom` | string | No | Saved default value, or the lower bound of a range filter. |\n| `layouts[].filters[].valueTo` | string | No | Saved upper bound of a range filter. `null` for single-value filters. |\n| `layouts[].filters[].createdBy` | string | No | User name that created the filter. |\n| `layouts[].filters[].createdAt` | string (date-time) | No | Creation date and time, formatted `yyyy-MM-dd'T'HH:mm:ss`. |\n| `layouts[].filters[].updatedBy` | string | No | User name that last changed the filter. |\n| `layouts[].filters[].updatedAt` | string (date-time) | No | Last change date and time, formatted `yyyy-MM-dd'T'HH:mm:ss`. |\n| `layouts[].filters[].required` | boolean | No | `true` when the layout requires a value for this filter before a run is accepted; `null` when the filter is optional. |\n| `layouts[].filters[].options` | array of FilterOption | No | Allowed values for an `LOV` filter. Always an array; empty for other filter types or when no list is configured. |\n| `layouts[].filters[].options[].label` | string | No | Human-readable text of the option, already translated. |\n| `layouts[].filters[].options[].value` | string | No | Value to send as the filter `value` when you select this option. |\n| `totalCount` | integer | No | Number of layouts in `layouts`. |\n\nError response schemas (GatewayError, ServiceError, SpringError, SimpleError, MissingFiltersError, RunStatusConflict, RiaError, SignedUrlError) are defined once under *Error response schemas* in the API overview and in `components/schemas`.\n\n\n**Response codes:** `200`, `400`, `401`, `403`, `429`, `500`. Each response with a body includes worked examples; responses without a body say so.", "operationId": "listReportLayouts", "parameters": [ { "name": "reportId", "in": "path", "required": true, "description": "Identifier of the report.", "schema": { "type": "integer", "format": "int32" }, "example": 10021 }, { "name": "name", "in": "query", "required": false, "description": "Return only the layout with this exact name (case-insensitive).", "schema": { "type": "string" }, "example": "Monthly Close - Summary" }, { "name": "Accept-Language", "in": "header", "required": false, "description": "Optional language for translated report names, labels and filter options, for example `en` or `ja`. Defaults to the user's profile language.", "schema": { "type": "string" }, "example": "en" }, { "name": "Zuora-Track-Id", "in": "header", "required": false, "description": "Optional correlation identifier (up to 64 characters) that you choose. The Zuora One gateway records it; quote it to Zuora Support when you report a problem.", "schema": { "type": "string" }, "example": "close-run-2026-09-001" } ], "responses": { "200": { "description": "**Success.** The layouts of the report.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LayoutList" }, "examples": { "layouts": { "summary": "One layout with fields and filters", "value": { "layouts": [ { "id": 3105, "reportId": 10021, "name": "Monthly Close - Summary", "description": "Summary by period for month-end close", "filenamePrefix": "WF_SUMMARY", "createdBy": "FIN.ADMIN", "createdAt": "2025-03-01T10:00:00", "updatedBy": "FIN.ADMIN", "updatedAt": "2026-07-30T16:12:45", "fields": [ { "id": 55012, "layoutId": 3105, "fieldId": 8801, "seq": 1, "sortSeq": 1, "fieldName": "periodName", "fieldLabel": "Period Name", "fieldType": "VARCHAR2" }, { "id": 55013, "layoutId": 3105, "fieldId": 8802, "seq": 2, "sortSeq": null, "fieldName": "rcId", "fieldLabel": "Revenue Contract ID", "fieldType": "NUMBER" }, { "id": 55014, "layoutId": 3105, "fieldId": 8810, "seq": 3, "sortSeq": null, "fieldName": "recognizedAmount", "fieldLabel": "Recognized Amount", "fieldType": "NUMBER" } ], "filters": [ { "id": 70033, "layoutId": 3105, "fieldId": 8801, "fieldName": "periodName", "fieldLabel": "Period Name", "fieldType": "VARCHAR2", "type": "LOV", "valueFrom": "$revpro.CurrPrd", "valueTo": null, "createdBy": "SYSADMIN", "createdAt": "2025-03-01T10:00:00", "updatedBy": "SYSADMIN", "updatedAt": "2025-03-01T10:00:00", "required": true, "options": [ { "label": "AUG-2026", "value": "AUG-2026" }, { "label": "SEP-2026", "value": "SEP-2026" } ] }, { "id": 70034, "layoutId": 3105, "fieldId": 8820, "fieldName": "wfType", "fieldLabel": "Waterfall Type", "fieldType": "VARCHAR2", "type": "LOV", "valueFrom": "R", "valueTo": null, "createdBy": "SYSADMIN", "createdAt": "2025-03-01T10:00:00", "updatedBy": "SYSADMIN", "updatedAt": "2025-03-01T10:00:00", "required": null, "options": [ { "label": "Revenue", "value": "R" }, { "label": "Cost", "value": "C" } ] } ] } ], "totalCount": 1 } }, "none": { "summary": "Report has no layouts, or the report does not exist", "value": { "layouts": [], "totalCount": 0 } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/ReportingUnauthorized" }, "403": { "$ref": "#/components/responses/ReportingForbidden" }, "429": { "$ref": "#/components/responses/ReportingTooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/revenue/services/v1/reports/{reportId}/layouts/{layoutId}": { "servers": [ { "url": "https://one.zuora.com", "description": "Zuora One production. Revenue Reporting paths start with /revenue/services/v1; Integration Reporting paths start with /api/integration/v1 or /api/integration/v2." } ], "get": { "tags": [ "Report Catalog" ], "security": [ { "OneIdOAuth": [] } ], "summary": "Retrieve a report layout", "description": "Returns one layout of a report, including its output columns and filters.\n\n**Purpose:** Read the exact filters, defaults and allowed values of the layout you will run, so you can build a valid run request.\n\n**When to use:** When you run one known layout and need its current filters, defaults and allowed values to build or validate the run request.\n\n**Notes:**\n\n- The layout must belong to the report in the path; otherwise the response is `404`.\n\n### Request definition\n\n| Parameter | In | Type | Required | Default | Description |\n|---|---|---|---|---|---|\n| `reportId` | path | integer | Yes | | Identifier of the report. |\n| `layoutId` | path | integer | Yes | | Identifier of the layout. |\n| `Accept-Language` | header | string | No | | Optional language for translated report names, labels and filter options, for example `en` or `ja`. Defaults to the user's profile language. |\n| `Zuora-Track-Id` | header | string | No | | Optional correlation identifier (up to 64 characters) that you choose. The Zuora One gateway records it; quote it to Zuora Support when you report a problem. |\n| `Authorization` | header | string | Yes | | `Bearer ` (Zuora OneID OAuth). |\n\n**Request body:** none.\n\n### Response definition\n\n| HTTP status | Content type | Response schema |\n|---|---|---|\n| `200` | `application/json` | ReportLayout |\n| `400` | `application/json` | SpringError |\n| `401` | `application/json` | GatewayError |\n| `403` | `application/json` | GatewayError |\n| `404` | none | No body |\n| `429` | `application/json` | GatewayError |\n| `500` | `application/json` | ServiceError |\n\n*ReportLayout*: A saved layout of a report: the columns to output, the filters with their defaults, and the output file-name prefix. A report can have many layouts.\n\n| Field | Type | Required | Description |\n|---|---|---|---|\n| `id` | integer | No | Unique identifier of the layout. Send it as `layoutId` when you run the report. |\n| `reportId` | integer | No | Identifier of the report the layout belongs to. |\n| `name` | string | No | Layout name. |\n| `description` | string | No | Layout description. |\n| `filenamePrefix` | string | No | Prefix used for the generated output file name. |\n| `createdBy` | string | No | User name that created the layout. |\n| `createdAt` | string (date-time) | No | Creation date and time, formatted `yyyy-MM-dd'T'HH:mm:ss`. |\n| `updatedBy` | string | No | User name that last changed the layout. |\n| `updatedAt` | string (date-time) | No | Last change date and time, formatted `yyyy-MM-dd'T'HH:mm:ss`. |\n| `fields` | array of LayoutField | No | Output columns of the layout, in output order. |\n| `fields[].id` | integer | No | Unique identifier of this column assignment within the layout. |\n| `fields[].layoutId` | integer | No | Identifier of the layout the column belongs to. |\n| `fields[].fieldId` | integer | No | Identifier of the underlying report field (column definition). |\n| `fields[].seq` | integer | No | Position of the column in the output file. Lower numbers appear further left. |\n| `fields[].sortSeq` | integer | No | Sort priority of the column. `null` when the layout does not sort by this column. |\n| `fields[].fieldName` | string | No | Technical field name in lowerCamelCase. Use this value as `fieldName` when you filter a report run. |\n| `fields[].fieldLabel` | string | No | Column heading shown in the output file, translated to the caller's language when a translation exists. |\n| `fields[].fieldType` | string | No | Database data type of the column, for example `VARCHAR2`, `NUMBER`, `DATE` or `DATE_TIME`. |\n| `filters` | array of LayoutFilter | No | Filters defined on the layout, with required flags and allowed values. |\n| `filters[].id` | integer | No | Unique identifier of the filter definition. |\n| `filters[].layoutId` | integer | No | Identifier of the layout the filter belongs to. |\n| `filters[].fieldId` | integer | No | Identifier of the report field the filter applies to. |\n| `filters[].fieldName` | string | No | Technical field name in lowerCamelCase. Send this as `fieldName` in a run request to override the filter. |\n| `filters[].fieldLabel` | string | No | Display label of the filter, translated when a translation exists. |\n| `filters[].fieldType` | string | No | Database data type of the filtered field, for example `VARCHAR2`, `NUMBER`, `DATE` or `DATE_TIME`. |\n| `filters[].type` | string | No | How the filter is presented and evaluated, for example `LOV` (pick from a list), `RANGE` (from/to) or `EQUALS` (single value). |\n| `filters[].valueFrom` | string | No | Saved default value, or the lower bound of a range filter. |\n| `filters[].valueTo` | string | No | Saved upper bound of a range filter. `null` for single-value filters. |\n| `filters[].createdBy` | string | No | User name that created the filter. |\n| `filters[].createdAt` | string (date-time) | No | Creation date and time, formatted `yyyy-MM-dd'T'HH:mm:ss`. |\n| `filters[].updatedBy` | string | No | User name that last changed the filter. |\n| `filters[].updatedAt` | string (date-time) | No | Last change date and time, formatted `yyyy-MM-dd'T'HH:mm:ss`. |\n| `filters[].required` | boolean | No | `true` when the layout requires a value for this filter before a run is accepted; `null` when the filter is optional. |\n| `filters[].options` | array of FilterOption | No | Allowed values for an `LOV` filter. Always an array; empty for other filter types or when no list is configured. |\n| `filters[].options[].label` | string | No | Human-readable text of the option, already translated. |\n| `filters[].options[].value` | string | No | Value to send as the filter `value` when you select this option. |\n\nError response schemas (GatewayError, ServiceError, SpringError, SimpleError, MissingFiltersError, RunStatusConflict, RiaError, SignedUrlError) are defined once under *Error response schemas* in the API overview and in `components/schemas`.\n\n\n**Response codes:** `200`, `400`, `401`, `403`, `404`, `429`, `500`. Each response with a body includes worked examples; responses without a body say so.", "operationId": "getReportLayout", "parameters": [ { "name": "reportId", "in": "path", "required": true, "description": "Identifier of the report.", "schema": { "type": "integer", "format": "int32" }, "example": 10021 }, { "name": "layoutId", "in": "path", "required": true, "description": "Identifier of the layout.", "schema": { "type": "integer", "format": "int32" }, "example": 3105 }, { "name": "Accept-Language", "in": "header", "required": false, "description": "Optional language for translated report names, labels and filter options, for example `en` or `ja`. Defaults to the user's profile language.", "schema": { "type": "string" }, "example": "en" }, { "name": "Zuora-Track-Id", "in": "header", "required": false, "description": "Optional correlation identifier (up to 64 characters) that you choose. The Zuora One gateway records it; quote it to Zuora Support when you report a problem.", "schema": { "type": "string" }, "example": "close-run-2026-09-001" } ], "responses": { "200": { "description": "**Success.** The layout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportLayout" }, "examples": { "found": { "summary": "Layout with fields and filters", "value": { "id": 3105, "reportId": 10021, "name": "Monthly Close - Summary", "description": "Summary by period for month-end close", "filenamePrefix": "WF_SUMMARY", "createdBy": "FIN.ADMIN", "createdAt": "2025-03-01T10:00:00", "updatedBy": "FIN.ADMIN", "updatedAt": "2026-07-30T16:12:45", "fields": [ { "id": 55012, "layoutId": 3105, "fieldId": 8801, "seq": 1, "sortSeq": 1, "fieldName": "periodName", "fieldLabel": "Period Name", "fieldType": "VARCHAR2" }, { "id": 55013, "layoutId": 3105, "fieldId": 8802, "seq": 2, "sortSeq": null, "fieldName": "rcId", "fieldLabel": "Revenue Contract ID", "fieldType": "NUMBER" }, { "id": 55014, "layoutId": 3105, "fieldId": 8810, "seq": 3, "sortSeq": null, "fieldName": "recognizedAmount", "fieldLabel": "Recognized Amount", "fieldType": "NUMBER" } ], "filters": [ { "id": 70033, "layoutId": 3105, "fieldId": 8801, "fieldName": "periodName", "fieldLabel": "Period Name", "fieldType": "VARCHAR2", "type": "LOV", "valueFrom": "$revpro.CurrPrd", "valueTo": null, "createdBy": "SYSADMIN", "createdAt": "2025-03-01T10:00:00", "updatedBy": "SYSADMIN", "updatedAt": "2025-03-01T10:00:00", "required": true, "options": [ { "label": "AUG-2026", "value": "AUG-2026" }, { "label": "SEP-2026", "value": "SEP-2026" } ] }, { "id": 70034, "layoutId": 3105, "fieldId": 8820, "fieldName": "wfType", "fieldLabel": "Waterfall Type", "fieldType": "VARCHAR2", "type": "LOV", "valueFrom": "R", "valueTo": null, "createdBy": "SYSADMIN", "createdAt": "2025-03-01T10:00:00", "updatedBy": "SYSADMIN", "updatedAt": "2025-03-01T10:00:00", "required": null, "options": [ { "label": "Revenue", "value": "R" }, { "label": "Cost", "value": "C" } ] } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/ReportingUnauthorized" }, "403": { "$ref": "#/components/responses/ReportingForbidden" }, "404": { "$ref": "#/components/responses/ReportingNotFound" }, "429": { "$ref": "#/components/responses/ReportingTooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/revenue/services/v1/reports/{reportId}/layouts/{layoutId}/fields": { "servers": [ { "url": "https://one.zuora.com", "description": "Zuora One production. Revenue Reporting paths start with /revenue/services/v1; Integration Reporting paths start with /api/integration/v1 or /api/integration/v2." } ], "get": { "tags": [ "Report Catalog" ], "security": [ { "OneIdOAuth": [] } ], "summary": "List the columns of a layout", "description": "Returns only the output columns of a layout, in output order.\n\n**Purpose:** Map the columns of the output file to your target system (for example a data warehouse table) before you download it.\n\n**When to use:** When you load the output file into another system and need the column order, names and data types to map the file to a target table.\n\n**Notes:**\n\n- The layout must belong to the report in the path; otherwise the response is `404`.\n- This operation returns the column labels and data types stored on the layout columns. They are not translated and can differ from the values returned inside List layouts and Get a layout.\n\n### Request definition\n\n| Parameter | In | Type | Required | Default | Description |\n|---|---|---|---|---|---|\n| `reportId` | path | integer | Yes | | Identifier of the report. |\n| `layoutId` | path | integer | Yes | | Identifier of the layout. |\n| `Zuora-Track-Id` | header | string | No | | Optional correlation identifier (up to 64 characters) that you choose. The Zuora One gateway records it; quote it to Zuora Support when you report a problem. |\n| `Authorization` | header | string | Yes | | `Bearer ` (Zuora OneID OAuth). |\n\n**Request body:** none.\n\n### Response definition\n\n| HTTP status | Content type | Response schema |\n|---|---|---|\n| `200` | `application/json` | LayoutFieldList |\n| `400` | `application/json` | SpringError |\n| `401` | `application/json` | GatewayError |\n| `403` | `application/json` | GatewayError |\n| `404` | none | No body |\n| `429` | `application/json` | GatewayError |\n| `500` | `application/json` | ServiceError |\n\n*LayoutFieldList*: Wrapper returned by the list-layout-fields operation.\n\n| Field | Type | Required | Description |\n|---|---|---|---|\n| `layoutFields` | array of LayoutField | No | Output columns of the layout. |\n| `layoutFields[].id` | integer | No | Unique identifier of this column assignment within the layout. |\n| `layoutFields[].layoutId` | integer | No | Identifier of the layout the column belongs to. |\n| `layoutFields[].fieldId` | integer | No | Identifier of the underlying report field (column definition). |\n| `layoutFields[].seq` | integer | No | Position of the column in the output file. Lower numbers appear further left. |\n| `layoutFields[].sortSeq` | integer | No | Sort priority of the column. `null` when the layout does not sort by this column. |\n| `layoutFields[].fieldName` | string | No | Technical field name in lowerCamelCase. Use this value as `fieldName` when you filter a report run. |\n| `layoutFields[].fieldLabel` | string | No | Column heading shown in the output file, translated to the caller's language when a translation exists. |\n| `layoutFields[].fieldType` | string | No | Database data type of the column, for example `VARCHAR2`, `NUMBER`, `DATE` or `DATE_TIME`. |\n\nError response schemas (GatewayError, ServiceError, SpringError, SimpleError, MissingFiltersError, RunStatusConflict, RiaError, SignedUrlError) are defined once under *Error response schemas* in the API overview and in `components/schemas`.\n\n\n**Response codes:** `200`, `400`, `401`, `403`, `404`, `429`, `500`. Each response with a body includes worked examples; responses without a body say so.", "operationId": "listReportLayoutFields", "parameters": [ { "name": "reportId", "in": "path", "required": true, "description": "Identifier of the report.", "schema": { "type": "integer", "format": "int32" }, "example": 10021 }, { "name": "layoutId", "in": "path", "required": true, "description": "Identifier of the layout.", "schema": { "type": "integer", "format": "int32" }, "example": 3105 }, { "name": "Zuora-Track-Id", "in": "header", "required": false, "description": "Optional correlation identifier (up to 64 characters) that you choose. The Zuora One gateway records it; quote it to Zuora Support when you report a problem.", "schema": { "type": "string" }, "example": "close-run-2026-09-001" } ], "responses": { "200": { "description": "**Success.** The columns of the layout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LayoutFieldList" }, "examples": { "fields": { "summary": "Three columns", "value": { "layoutFields": [ { "id": 55012, "layoutId": 3105, "fieldId": 8801, "seq": 1, "sortSeq": 1, "fieldName": "periodName", "fieldLabel": "Period Name", "fieldType": "VARCHAR2" }, { "id": 55013, "layoutId": 3105, "fieldId": 8802, "seq": 2, "sortSeq": null, "fieldName": "rcId", "fieldLabel": "Revenue Contract ID", "fieldType": "NUMBER" }, { "id": 55014, "layoutId": 3105, "fieldId": 8810, "seq": 3, "sortSeq": null, "fieldName": "recognizedAmount", "fieldLabel": "Recognized Amount", "fieldType": "NUMBER" } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/ReportingUnauthorized" }, "403": { "$ref": "#/components/responses/ReportingForbidden" }, "404": { "$ref": "#/components/responses/ReportingNotFound" }, "429": { "$ref": "#/components/responses/ReportingTooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/revenue/services/v1/reports/{reportIdentifier}/metadata": { "servers": [ { "url": "https://one.zuora.com", "description": "Zuora One production. Revenue Reporting paths start with /revenue/services/v1; Integration Reporting paths start with /api/integration/v1 or /api/integration/v2." } ], "get": { "tags": [ "Report Catalog" ], "security": [ { "OneIdOAuth": [] } ], "summary": "Retrieve report metadata by ID or name", "description": "Returns a report's identity, whether it is a standard or custom report, every field it can output, and its layouts with the default layout flagged.\n\n**Purpose:** Resolve a report from a name you already know (for example from configuration) and find its default layout in a single call.\n\n**When to use:** When your configuration stores report names rather than IDs, or when you need the default layout of a report in a single call.\n\n**Notes:**\n\n- `reportIdentifier` is treated as a report ID when it is numeric; otherwise it is matched to the report name exactly, ignoring case and surrounding spaces. A report whose name is only digits can therefore be found only by its ID.\n- `metadata.parameters` and `metadata.filters` are reserved and currently empty. Use the layout operations to read filters.\n\n### Request definition\n\n| Parameter | In | Type | Required | Default | Description |\n|---|---|---|---|---|---|\n| `reportIdentifier` | path | string | Yes | | Report ID (numeric) or exact report name. URL-encode spaces as `%20`. |\n| `Zuora-Track-Id` | header | string | No | | Optional correlation identifier (up to 64 characters) that you choose. The Zuora One gateway records it; quote it to Zuora Support when you report a problem. |\n| `Authorization` | header | string | Yes | | `Bearer ` (Zuora OneID OAuth). |\n\n**Request body:** none.\n\n### Response definition\n\n| HTTP status | Content type | Response schema |\n|---|---|---|\n| `200` | `application/json` | ReportMetadata |\n| `400` | `application/json` | SpringError |\n| `401` | `application/json` | GatewayError |\n| `403` | `application/json` | GatewayError |\n| `404` | none | No body |\n| `429` | `application/json` | GatewayError |\n| `500` | `application/json` | ServiceError |\n\n*ReportMetadata*: Report metadata: identity, type, available columns and layouts.\n\n| Field | Type | Required | Description |\n|---|---|---|---|\n| `reportId` | integer | No | Identifier of the report. |\n| `reportName` | string | No | Name of the report. |\n| `reportType` | string | No | `STANDARD` for a report delivered by Zuora; `CUSTOM` for a report your organization created. Allowed: `STANDARD`, `CUSTOM`. |\n| `metadata` | ReportMetadataInfo | No | Description, columns and reserved arrays. |\n| `metadata.description` | string | No | Business description of the report. |\n| `metadata.parameters` | array of object | No | Reserved for future use. Currently always an empty array. |\n| `metadata.filters` | array of object | No | Reserved for future use. Currently always an empty array. Read filters from the layout operations instead. |\n| `metadata.columns` | array of ReportMetadataColumn | No | All fields the report can output. |\n| `metadata.columns[].id` | integer | No | Identifier of the report field. |\n| `metadata.columns[].fieldName` | string | No | Technical field name as stored in the report definition (UPPER_SNAKE_CASE). |\n| `metadata.columns[].alias` | string | No | Column alias used in the report output. |\n| `metadata.columns[].fieldType` | string | No | Data type of the field. |\n| `metadata.columns[].label` | string | No | Display label of the field. |\n| `layouts` | array of ReportMetadataLayout | No | Layouts available for the report. |\n| `layouts[].layoutId` | integer | No | Identifier of the layout. |\n| `layouts[].layoutName` | string | No | Name of the layout. |\n| `layouts[].isDefault` | boolean | No | `true` when this is the report's default layout. |\n\nError response schemas (GatewayError, ServiceError, SpringError, SimpleError, MissingFiltersError, RunStatusConflict, RiaError, SignedUrlError) are defined once under *Error response schemas* in the API overview and in `components/schemas`.\n\n\n**Response codes:** `200`, `400`, `401`, `403`, `404`, `429`, `500`. Each response with a body includes worked examples; responses without a body say so.", "operationId": "getReportMetadata", "parameters": [ { "name": "reportIdentifier", "in": "path", "required": true, "description": "Report ID (numeric) or exact report name. URL-encode spaces as `%20`.", "schema": { "type": "string" }, "example": "Revenue Waterfall Report" }, { "name": "Zuora-Track-Id", "in": "header", "required": false, "description": "Optional correlation identifier (up to 64 characters) that you choose. The Zuora One gateway records it; quote it to Zuora Support when you report a problem.", "schema": { "type": "string" }, "example": "close-run-2026-09-001" } ], "responses": { "200": { "description": "**Success.** The report metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportMetadata" }, "examples": { "byName": { "summary": "Metadata resolved by name", "value": { "reportId": 10021, "reportName": "Revenue Waterfall Report", "reportType": "STANDARD", "metadata": { "description": "Recognized and scheduled revenue by period for each revenue contract line", "parameters": [], "filters": [], "columns": [ { "id": 8801, "fieldName": "PERIOD_NAME", "alias": "PERIOD_NAME", "fieldType": "VARCHAR2", "label": "Period Name" }, { "id": 8802, "fieldName": "RC_ID", "alias": "RC_ID", "fieldType": "NUMBER", "label": "Revenue Contract ID" } ] }, "layouts": [ { "layoutId": 3105, "layoutName": "Monthly Close - Summary", "isDefault": true }, { "layoutId": 3106, "layoutName": "Auditor Extract", "isDefault": false } ] } } } } } }, "400": { "description": "**Failure.** The identifier is blank (for example `%20`). That case has no response body. The tenant could not be resolved for Zuora Revenue, or the database connection failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpringError" }, "examples": { "tenant": { "$ref": "#/components/examples/Tenant" } } } } }, "401": { "$ref": "#/components/responses/ReportingUnauthorized" }, "403": { "$ref": "#/components/responses/ReportingForbidden" }, "404": { "description": "**Failure.** No report matches the ID or name. The response has no body." }, "429": { "$ref": "#/components/responses/ReportingTooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/revenue/services/v1/reports/{reportId}/run": { "servers": [ { "url": "https://one.zuora.com", "description": "Zuora One production. Revenue Reporting paths start with /revenue/services/v1; Integration Reporting paths start with /api/integration/v1 or /api/integration/v2." } ], "post": { "tags": [ "Report Runs" ], "security": [ { "OneIdOAuth": [] } ], "summary": "Run a report", "description": "Submits a report layout for background execution and returns the new run. A `200` response means the run was accepted, not that the file is ready. Poll *Get a report run* until `status` is `Available`, then call *Get a download URL*.\n\n**Purpose:** Produce report files on demand from your own scheduler, for example at period close or for an auditor extract, without using the Zuora Revenue user interface.\n\n**When to use:** Each time you need a fresh report file: period close, an auditor request, a scheduled data feed, or an on-demand extract triggered by another system.\n\n**Notes:**\n\n- Filters are merged with the layout's saved defaults: omit `filters` to use all defaults; send some filters to override only those (your values win, defaults fill the rest); send `[]` to use no filters.\n- Required layout filters are checked after the merge. If any is still missing, the run is rejected with `400` and the labels of the missing filters.\n- `$revpro.CurrPrd` and `$revpro.PriorPrd` are replaced with the current or prior open period of the book and organization. If that cannot be resolved (for example several organizations with different open periods), the run is rejected with `errorCode` `INVALID_PERIOD_ORG`; send a concrete period name or organization instead.\n- Date values use `YYYY-MM-DD`. The value `-999` means *All* for book, period and organization filters.\n- Use a `layoutId` returned by List layouts for the same report. Operators outside the documented list are not supported and can make the run fail.\n\n### Request definition\n\n| Parameter | In | Type | Required | Default | Description |\n|---|---|---|---|---|---|\n| `reportId` | path | integer | Yes | | Identifier of the report to run. |\n| `Accept-Language` | header | string | No | | Optional language for translated report names, labels and filter options, for example `en` or `ja`. Defaults to the user's profile language. |\n| `Zuora-Track-Id` | header | string | No | | Optional correlation identifier (up to 64 characters) that you choose. The Zuora One gateway records it; quote it to Zuora Support when you report a problem. |\n| `Authorization` | header | string | Yes | | `Bearer ` (Zuora OneID OAuth). |\n\n**Request body** (required, `application/json`): RunReportRequest\n\n*RunReportRequest*: Request body that submits a report layout for execution.\n\n| Field | Type | Required | Description |\n|---|---|---|---|\n| `layoutId` | integer | Yes | Identifier of the layout to run. Use a layout returned by List layouts for the same report. |\n| `filters` | array of ReportFilterParam | No | Filter conditions. Omit the property (or send `null`) to apply all saved layout defaults. Send a partial list to override some filters; layout defaults fill in the rest. Send `[]` to run with no filters at all (required filters are still enforced). |\n| `filters[].fieldName` | string | Yes | Field to filter on, in lowerCamelCase as returned by the layout operations (for example `periodName`). The service converts it to the stored field key. |\n| `filters[].operator` | string | No | Comparison operator. When omitted, `=` is used. See *Filter operators* for the value rules of each operator. Allowed: `=`, `!=`, `<`, `<=`, `>`, `>=`, `LIKE`, `NOT LIKE`, `IS NULL`, `IS NOT NULL`, `BETWEEN`, `IN`, `VS`. |\n| `filters[].value` | string | No | Filter value. Dates use `YYYY-MM-DD`. For `IN`, a comma-separated list. For `VS`, the from-book. Omit for `IS NULL` and `IS NOT NULL`. The macros `$revpro.CurrPrd` and `$revpro.PriorPrd` are replaced with the current or prior open period name. |\n| `filters[].valueTo` | string | No | Upper bound for `BETWEEN` (date `YYYY-MM-DD`) or the to-book for `VS`. Not used by other operators. |\n\n### Response definition\n\n| HTTP status | Content type | Response schema |\n|---|---|---|\n| `200` | `application/json` | ReportRun |\n| `400` | `application/json` | MissingFiltersError or SimpleError or ServiceError or SpringError |\n| `401` | `application/json` | GatewayError |\n| `403` | `application/json` | GatewayError |\n| `429` | `application/json` | GatewayError |\n| `500` | `application/json` | SimpleError or ServiceError |\n\n*ReportRun*: One execution (submission) of a report layout.\n\n| Field | Type | Required | Description |\n|---|---|---|---|\n| `id` | integer | No | Submission identifier of the run. Use it as `submissionId` to poll status and download. |\n| `reportId` | integer | No | Identifier of the report that was run. |\n| `layoutId` | integer | No | Identifier of the layout that was run. |\n| `status` | string | No | Current run status. See *Report run status values*. Allowed: `Submitted`, `Upload Started`, `File Created`, `Available`, `Error`, `Terminated`, `Cancelled`. |\n| `fileName` | string | No | Name of the output file. Populated once the file is produced. |\n| `filterParameters` | string | No | JSON text of the filters stored for the run, after defaults and period macros were resolved. Filters are stored with internal filter keys (`key`), operator (`opr`, omitted for `=`) and values (`val1`, `val2`). Treat the content as informational; its format can change. |\n| `config` | string | No | JSON text of output options: `Show Filters` (Y/N, print the filters in the file) and `Enable Totals` (Y/N, add total rows). |\n| `createdBy` | string | No | User that submitted the run. |\n| `runDate` | string (date-time) | No | Date and time the run was submitted, formatted `yyyy-MM-dd'T'HH:mm:ss`. |\n| `updatedBy` | string | No | User or process that last updated the run. |\n| `updatedAt` | string (date-time) | No | Date and time of the last status change, formatted `yyyy-MM-dd'T'HH:mm:ss`. |\n\nError response schemas (GatewayError, ServiceError, SpringError, SimpleError, MissingFiltersError, RunStatusConflict, RiaError, SignedUrlError) are defined once under *Error response schemas* in the API overview and in `components/schemas`.\n\n\n**Response codes:** `200`, `400`, `401`, `403`, `429`, `500`. Each response with a body includes worked examples; responses without a body say so.", "operationId": "runReport", "parameters": [ { "name": "reportId", "in": "path", "required": true, "description": "Identifier of the report to run.", "schema": { "type": "integer", "format": "int32" }, "example": 10021 }, { "name": "Accept-Language", "in": "header", "required": false, "description": "Optional language for translated report names, labels and filter options, for example `en` or `ja`. Defaults to the user's profile language.", "schema": { "type": "string" }, "example": "en" }, { "name": "Zuora-Track-Id", "in": "header", "required": false, "description": "Optional correlation identifier (up to 64 characters) that you choose. The Zuora One gateway records it; quote it to Zuora Support when you report a problem.", "schema": { "type": "string" }, "example": "close-run-2026-09-001" } ], "requestBody": { "required": true, "description": "The layout to run and optional filter overrides.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunReportRequest" }, "examples": { "defaults": { "summary": "Run with the layout's saved filters", "value": { "layoutId": 3105 } }, "override": { "summary": "Override the period, keep other defaults", "value": { "layoutId": 3105, "filters": [ { "fieldName": "periodName", "operator": "=", "value": "SEP-2026" } ] } }, "dateRange": { "summary": "Date range and list filters", "value": { "layoutId": 3105, "filters": [ { "fieldName": "glDate", "operator": "BETWEEN", "value": "2026-09-01", "valueTo": "2026-09-30" }, { "fieldName": "rcId", "operator": "IN", "value": "120045,120046,120051" } ] } }, "macro": { "summary": "Current open period macro", "value": { "layoutId": 3105, "filters": [ { "fieldName": "periodName", "value": "$revpro.CurrPrd" } ] } } } } } }, "responses": { "200": { "description": "**Success.** The run was accepted. Save `id`; it is the `submissionId` for status and download.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportRun" }, "examples": { "accepted": { "summary": "Run accepted", "value": { "id": 482391, "reportId": 10021, "layoutId": 3105, "status": "Submitted", "fileName": null, "filterParameters": "{\"filters\":[{\"key\":\"A300\",\"val1\":\"SEP-2026\"},{\"key\":\"A101\",\"val1\":\"R\"}]}", "config": "{\"Show Filters\":\"Y\",\"Enable Totals\":\"N\"}", "createdBy": "INTEGRATION.USER", "runDate": "2026-10-09T07:15:02", "updatedBy": "INTEGRATION.USER", "updatedAt": "2026-10-09T07:15:02" } } } } } }, "400": { "description": "**Failure.** The request was rejected: `layoutId` missing, a required filter has no value, a period macro could not be resolved, or the body could not be processed. Also returned when the tenant could not be resolved for Zuora Revenue.", "content": { "application/json": { "schema": { "anyOf": [ { "anyOf": [ { "$ref": "#/components/schemas/MissingFiltersError" }, { "$ref": "#/components/schemas/SimpleError" }, { "$ref": "#/components/schemas/ServiceError" } ] }, { "$ref": "#/components/schemas/SpringError" } ] }, "examples": { "missingLayout": { "summary": "layoutId missing", "value": { "message": "Validation failed :layoutId is required", "code": "1" } }, "missingFilters": { "summary": "Required filter missing", "value": { "error": "Missing required filters", "missingFilters": [ "Period Name" ] } }, "periodMultiple": { "summary": "Period macro matches several open periods", "value": { "error": "Could not resolve $revpro.CurrPrd: multiple open periods were found; specify a concrete period name.", "errorCode": "INVALID_PERIOD_ORG" } }, "periodNone": { "summary": "No open period for the book and organization", "value": { "error": "Could not resolve $revpro.CurrPrd: no open period was found for the given book and organization.", "errorCode": "INVALID_PERIOD_ORG" } }, "periodBook": { "summary": "Book could not be determined", "value": { "error": "Current or prior period could not be resolved for the selected book and organization. Specify a concrete organization or period name instead of $revpro.CurrPrd / $revpro.PriorPrd.", "errorCode": "INVALID_PERIOD_ORG" } }, "invalidRequest": { "summary": "Request could not be serialized", "value": { "error": "Invalid report request" } }, "tenant": { "$ref": "#/components/examples/Tenant" } } } } }, "401": { "$ref": "#/components/responses/ReportingUnauthorized" }, "403": { "$ref": "#/components/responses/ReportingForbidden" }, "429": { "$ref": "#/components/responses/ReportingTooManyRequests" }, "500": { "description": "**Failure.** Unexpected error while submitting the run (for example an unknown `layoutId`, or a malformed JSON body). Check the request; if it is correct, retry later.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/SimpleError" }, { "$ref": "#/components/schemas/ServiceError" } ] }, "examples": { "internal": { "summary": "Submission failed", "value": { "error": "Internal server error" } }, "malformedJson": { "summary": "Malformed JSON body", "value": { "message": "An error occurred: JSON parse error: Unexpected character ('}' (code 125))", "code": "1" } } } } } } } } }, "/revenue/services/v1/reports/run/{submissionId}": { "servers": [ { "url": "https://one.zuora.com", "description": "Zuora One production. Revenue Reporting paths start with /revenue/services/v1; Integration Reporting paths start with /api/integration/v1 or /api/integration/v2." } ], "get": { "tags": [ "Report Runs" ], "security": [ { "OneIdOAuth": [] } ], "summary": "Retrieve a report run", "description": "Returns the current state of one report run.\n\n**Purpose:** Poll a run you submitted until it reaches a final status. Poll every 10 to 30 seconds and stop when `status` is `Available`, `Error`, `Terminated` or `Cancelled`.\n\n**When to use:** After Run a report, to poll until the run reaches a final status, or later to check the outcome of a known run.\n\n### Request definition\n\n| Parameter | In | Type | Required | Default | Description |\n|---|---|---|---|---|---|\n| `submissionId` | path | integer | Yes | | Run identifier (`id` returned by Run a report). |\n| `Zuora-Track-Id` | header | string | No | | Optional correlation identifier (up to 64 characters) that you choose. The Zuora One gateway records it; quote it to Zuora Support when you report a problem. |\n| `Authorization` | header | string | Yes | | `Bearer ` (Zuora OneID OAuth). |\n\n**Request body:** none.\n\n### Response definition\n\n| HTTP status | Content type | Response schema |\n|---|---|---|\n| `200` | `application/json` | ReportRun |\n| `400` | `application/json` | SpringError |\n| `401` | `application/json` | GatewayError |\n| `403` | `application/json` | GatewayError |\n| `404` | none | No body |\n| `429` | `application/json` | GatewayError |\n| `500` | `application/json` | ServiceError |\n\n*ReportRun*: One execution (submission) of a report layout.\n\n| Field | Type | Required | Description |\n|---|---|---|---|\n| `id` | integer | No | Submission identifier of the run. Use it as `submissionId` to poll status and download. |\n| `reportId` | integer | No | Identifier of the report that was run. |\n| `layoutId` | integer | No | Identifier of the layout that was run. |\n| `status` | string | No | Current run status. See *Report run status values*. Allowed: `Submitted`, `Upload Started`, `File Created`, `Available`, `Error`, `Terminated`, `Cancelled`. |\n| `fileName` | string | No | Name of the output file. Populated once the file is produced. |\n| `filterParameters` | string | No | JSON text of the filters stored for the run, after defaults and period macros were resolved. Filters are stored with internal filter keys (`key`), operator (`opr`, omitted for `=`) and values (`val1`, `val2`). Treat the content as informational; its format can change. |\n| `config` | string | No | JSON text of output options: `Show Filters` (Y/N, print the filters in the file) and `Enable Totals` (Y/N, add total rows). |\n| `createdBy` | string | No | User that submitted the run. |\n| `runDate` | string (date-time) | No | Date and time the run was submitted, formatted `yyyy-MM-dd'T'HH:mm:ss`. |\n| `updatedBy` | string | No | User or process that last updated the run. |\n| `updatedAt` | string (date-time) | No | Date and time of the last status change, formatted `yyyy-MM-dd'T'HH:mm:ss`. |\n\nError response schemas (GatewayError, ServiceError, SpringError, SimpleError, MissingFiltersError, RunStatusConflict, RiaError, SignedUrlError) are defined once under *Error response schemas* in the API overview and in `components/schemas`.\n\n\n**Response codes:** `200`, `400`, `401`, `403`, `404`, `429`, `500`. Each response with a body includes worked examples; responses without a body say so.", "operationId": "getReportRun", "parameters": [ { "name": "submissionId", "in": "path", "required": true, "description": "Run identifier (`id` returned by Run a report).", "schema": { "type": "integer", "format": "int64" }, "example": 482391 }, { "name": "Zuora-Track-Id", "in": "header", "required": false, "description": "Optional correlation identifier (up to 64 characters) that you choose. The Zuora One gateway records it; quote it to Zuora Support when you report a problem.", "schema": { "type": "string" }, "example": "close-run-2026-09-001" } ], "responses": { "200": { "description": "**Success.** The run.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportRun" }, "examples": { "inProgress": { "summary": "Still running", "value": { "id": 482391, "reportId": 10021, "layoutId": 3105, "status": "Submitted", "fileName": null, "filterParameters": "{\"filters\":[{\"key\":\"A300\",\"val1\":\"SEP-2026\"},{\"key\":\"A101\",\"val1\":\"R\"}]}", "config": "{\"Show Filters\":\"Y\",\"Enable Totals\":\"N\"}", "createdBy": "INTEGRATION.USER", "runDate": "2026-10-09T07:15:02", "updatedBy": "INTEGRATION.USER", "updatedAt": "2026-10-09T07:15:02" } }, "available": { "summary": "File ready", "value": { "id": 482391, "reportId": 10021, "layoutId": 3105, "status": "Available", "fileName": "WF_SUMMARY_482391.csv", "filterParameters": "{\"filters\":[{\"key\":\"A300\",\"val1\":\"SEP-2026\"},{\"key\":\"A101\",\"val1\":\"R\"}]}", "config": "{\"Show Filters\":\"Y\",\"Enable Totals\":\"N\"}", "createdBy": "INTEGRATION.USER", "runDate": "2026-10-09T07:15:02", "updatedBy": "INTEGRATION.USER", "updatedAt": "2026-10-09T07:16:40" } }, "failed": { "summary": "Run failed", "value": { "id": 482377, "reportId": 10021, "layoutId": 3105, "status": "Error", "fileName": null, "filterParameters": "{\"filters\":[{\"key\":\"A300\",\"val1\":\"SEP-2026\"},{\"key\":\"A101\",\"val1\":\"R\"}]}", "config": "{\"Show Filters\":\"Y\",\"Enable Totals\":\"N\"}", "createdBy": "INTEGRATION.USER", "runDate": "2026-10-09T07:15:02", "updatedBy": "INTEGRATION.USER", "updatedAt": "2026-10-09T06:58:12" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/ReportingUnauthorized" }, "403": { "$ref": "#/components/responses/ReportingForbidden" }, "404": { "$ref": "#/components/responses/NotFound2" }, "429": { "$ref": "#/components/responses/ReportingTooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/revenue/services/v1/reports/run/latest": { "servers": [ { "url": "https://one.zuora.com", "description": "Zuora One production. Revenue Reporting paths start with /revenue/services/v1; Integration Reporting paths start with /api/integration/v1 or /api/integration/v2." } ], "get": { "tags": [ "Report Runs" ], "security": [ { "OneIdOAuth": [] } ], "summary": "Retrieve the latest finished report run", "description": "Returns the most recent report run in the tenant, across all reports, that has reached a final status (`Available`, `Error`, `Terminated` or `Cancelled`).\n\n**Purpose:** Check the outcome of the last report produced in the tenant, for example in a monitoring job, without knowing its submission ID.\n\n**When to use:** In monitoring or health-check jobs that need the outcome of the most recent finished run without tracking submission IDs.\n\n**Notes:**\n\n- Runs that are still in progress are ignored.\n\n### Request definition\n\n| Parameter | In | Type | Required | Default | Description |\n|---|---|---|---|---|---|\n| `Zuora-Track-Id` | header | string | No | | Optional correlation identifier (up to 64 characters) that you choose. The Zuora One gateway records it; quote it to Zuora Support when you report a problem. |\n| `Authorization` | header | string | Yes | | `Bearer ` (Zuora OneID OAuth). |\n\n**Request body:** none.\n\n### Response definition\n\n| HTTP status | Content type | Response schema |\n|---|---|---|\n| `200` | `application/json` | ReportRun |\n| `400` | `application/json` | SpringError |\n| `401` | `application/json` | GatewayError |\n| `403` | `application/json` | GatewayError |\n| `404` | none | No body |\n| `429` | `application/json` | GatewayError |\n| `500` | `application/json` | ServiceError |\n\n*ReportRun*: One execution (submission) of a report layout.\n\n| Field | Type | Required | Description |\n|---|---|---|---|\n| `id` | integer | No | Submission identifier of the run. Use it as `submissionId` to poll status and download. |\n| `reportId` | integer | No | Identifier of the report that was run. |\n| `layoutId` | integer | No | Identifier of the layout that was run. |\n| `status` | string | No | Current run status. See *Report run status values*. Allowed: `Submitted`, `Upload Started`, `File Created`, `Available`, `Error`, `Terminated`, `Cancelled`. |\n| `fileName` | string | No | Name of the output file. Populated once the file is produced. |\n| `filterParameters` | string | No | JSON text of the filters stored for the run, after defaults and period macros were resolved. Filters are stored with internal filter keys (`key`), operator (`opr`, omitted for `=`) and values (`val1`, `val2`). Treat the content as informational; its format can change. |\n| `config` | string | No | JSON text of output options: `Show Filters` (Y/N, print the filters in the file) and `Enable Totals` (Y/N, add total rows). |\n| `createdBy` | string | No | User that submitted the run. |\n| `runDate` | string (date-time) | No | Date and time the run was submitted, formatted `yyyy-MM-dd'T'HH:mm:ss`. |\n| `updatedBy` | string | No | User or process that last updated the run. |\n| `updatedAt` | string (date-time) | No | Date and time of the last status change, formatted `yyyy-MM-dd'T'HH:mm:ss`. |\n\nError response schemas (GatewayError, ServiceError, SpringError, SimpleError, MissingFiltersError, RunStatusConflict, RiaError, SignedUrlError) are defined once under *Error response schemas* in the API overview and in `components/schemas`.\n\n\n**Response codes:** `200`, `400`, `401`, `403`, `404`, `429`, `500`. Each response with a body includes worked examples; responses without a body say so.", "operationId": "getLatestReportRun", "parameters": [ { "name": "Zuora-Track-Id", "in": "header", "required": false, "description": "Optional correlation identifier (up to 64 characters) that you choose. The Zuora One gateway records it; quote it to Zuora Support when you report a problem.", "schema": { "type": "string" }, "example": "close-run-2026-09-001" } ], "responses": { "200": { "description": "**Success.** The latest finished run.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportRun" }, "examples": { "latest": { "summary": "Latest finished run", "value": { "id": 482391, "reportId": 10021, "layoutId": 3105, "status": "Available", "fileName": "WF_SUMMARY_482391.csv", "filterParameters": "{\"filters\":[{\"key\":\"A300\",\"val1\":\"SEP-2026\"},{\"key\":\"A101\",\"val1\":\"R\"}]}", "config": "{\"Show Filters\":\"Y\",\"Enable Totals\":\"N\"}", "createdBy": "INTEGRATION.USER", "runDate": "2026-10-09T07:15:02", "updatedBy": "INTEGRATION.USER", "updatedAt": "2026-10-09T07:16:40" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/ReportingUnauthorized" }, "403": { "$ref": "#/components/responses/ReportingForbidden" }, "404": { "description": "**Failure.** No finished run exists in the tenant. The response has no body." }, "429": { "$ref": "#/components/responses/ReportingTooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/revenue/services/v1/reports/run/{submissionId}/download": { "servers": [ { "url": "https://one.zuora.com", "description": "Zuora One production. Revenue Reporting paths start with /revenue/services/v1; Integration Reporting paths start with /api/integration/v1 or /api/integration/v2." } ], "get": { "tags": [ "Report Runs" ], "security": [ { "OneIdOAuth": [] } ], "summary": "Retrieve a download URL", "description": "Returns a pre-signed HTTPS URL for the output file of an Available run. The URL is valid for 30 minutes. Download the file with a plain HTTP GET on that URL, without an Authorization header.\n\n**Purpose:** Retrieve large report files securely and directly from file storage, without streaming them through the API.\n\n**When to use:** As soon as a run is `Available`, to download its file. Call it again if a previous URL has expired.\n\n**Notes:**\n\n- Request the URL only when the run status is `Available`; otherwise the response is `409` with the current status code.\n- If the URL expires, call this operation again to get a new one.\n\n### Request definition\n\n| Parameter | In | Type | Required | Default | Description |\n|---|---|---|---|---|---|\n| `submissionId` | path | integer | Yes | | Run identifier. |\n| `Zuora-Track-Id` | header | string | No | | Optional correlation identifier (up to 64 characters) that you choose. The Zuora One gateway records it; quote it to Zuora Support when you report a problem. |\n| `Authorization` | header | string | Yes | | `Bearer ` (Zuora OneID OAuth). |\n\n**Request body:** none.\n\n### Response definition\n\n| HTTP status | Content type | Response schema |\n|---|---|---|\n| `200` | `application/json` | ReportDownload |\n| `400` | `application/json` | SimpleError or SpringError |\n| `401` | `application/json` | GatewayError |\n| `403` | `application/json` | GatewayError |\n| `404` | none | No body |\n| `409` | `application/json` | RunStatusConflict |\n| `429` | `application/json` | GatewayError |\n| `500` | `application/json` | ServiceError |\n| `503` | `application/json` | SimpleError |\n\n*ReportDownload*: Time-limited download link for a completed report file.\n\n| Field | Type | Required | Description |\n|---|---|---|---|\n| `presignedUrl` | string (uri) | No | HTTPS URL of the report file. Download it with a plain HTTP GET and no Authorization header. Valid for 30 minutes. |\n| `expiresAt` | string (date-time) | No | UTC date and time after which the URL stops working, formatted `yyyy-MM-dd'T'HH:mm:ss`. |\n\nError response schemas (GatewayError, ServiceError, SpringError, SimpleError, MissingFiltersError, RunStatusConflict, RiaError, SignedUrlError) are defined once under *Error response schemas* in the API overview and in `components/schemas`.\n\n\n**Response codes:** `200`, `400`, `401`, `403`, `404`, `409`, `429`, `500`, `503`. Each response with a body includes worked examples; responses without a body say so.", "operationId": "getReportRunDownloadUrl", "parameters": [ { "name": "submissionId", "in": "path", "required": true, "description": "Run identifier.", "schema": { "type": "integer", "format": "int64" }, "example": 482391 }, { "name": "Zuora-Track-Id", "in": "header", "required": false, "description": "Optional correlation identifier (up to 64 characters) that you choose. The Zuora One gateway records it; quote it to Zuora Support when you report a problem.", "schema": { "type": "string" }, "example": "close-run-2026-09-001" } ], "responses": { "200": { "description": "**Success.** The download URL.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportDownload" }, "examples": { "url": { "summary": "URL issued", "value": { "presignedUrl": "https://files.zuora.com/rev/1234567/reports/WF_SUMMARY_482391.csv?X-Amz-Expires=1800&X-Amz-Signature=3b1f...", "expiresAt": "2026-10-09T07:47:10" } } } } } }, "400": { "description": "**Failure.** The run's file reference is invalid, so no URL can be generated. Also returned when the tenant could not be resolved for Zuora Revenue.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/SimpleError" }, { "$ref": "#/components/schemas/SpringError" } ] }, "examples": { "badRef": { "summary": "Invalid file reference", "value": { "error": "Invalid report reference" } }, "tenant": { "$ref": "#/components/examples/Tenant" } } } } }, "401": { "$ref": "#/components/responses/ReportingUnauthorized" }, "403": { "$ref": "#/components/responses/ReportingForbidden" }, "404": { "$ref": "#/components/responses/NotFound2" }, "409": { "description": "**Failure.** The run is not Available yet (or failed). `status` holds the one-letter status code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunStatusConflict" }, "examples": { "notReady": { "summary": "Run still submitted", "value": { "status": "S" } }, "failed": { "summary": "Run ended in error", "value": { "status": "E" } } } } } }, "429": { "$ref": "#/components/responses/ReportingTooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "description": "**Failure.** The URL could not be signed because file storage was temporarily unavailable. Retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimpleError" }, "examples": { "presign": { "summary": "Signing failed", "value": { "error": "Unable to generate download URL, please retry" } } } } } } } } }, "/api/integration/v1/reports/list": { "servers": [ { "url": "https://one.zuora.com", "description": "Zuora One production. Revenue Reporting paths start with /revenue/services/v1; Integration Reporting paths start with /api/integration/v1 or /api/integration/v2." } ], "get": { "tags": [ "Report Files" ], "security": [ { "OneIdOAuth": [] } ], "summary": "List report files by date", "description": "Returns the Available report files created on one calendar day, limited to the organizations your role can access. Runs that are still in progress or failed are not returned.\n\n**Purpose:** Collect every report produced on a given day (for example by schedules in Zuora Revenue) so a nightly job can download them.\n\n**When to use:** In a daily job that collects every report file produced on a given day, for example by report schedules set up in Zuora Revenue.\n\n**Notes:**\n\n- `createddate` uses the format `DD-Mon-YYYY` with an English month abbreviation, for example `09-Oct-2026`. The month is not case-sensitive.\n- When nothing matches, the response is `200` with an empty `Result` array.\n\n### Request definition\n\n| Parameter | In | Type | Required | Default | Description |\n|---|---|---|---|---|---|\n| `createddate` | query | string | Yes | | Creation date of the report files, formatted `DD-Mon-YYYY`. |\n| `Zuora-Track-Id` | header | string | No | | Optional correlation identifier (up to 64 characters) that you choose. The Zuora One gateway records it; quote it to Zuora Support when you report a problem. |\n| `Authorization` | header | string | Yes | | `Bearer ` (Zuora OneID OAuth). |\n\n**Request body:** none.\n\n### Response definition\n\n| HTTP status | Content type | Response schema |\n|---|---|---|\n| `200` | `application/json` | ReportFileListResponse |\n| `400` | `application/json` | RiaError |\n| `401` | `application/json` | GatewayError or RiaError |\n| `403` | `application/json` | RiaError |\n| `404` | `application/json` | RiaError |\n| `429` | `application/json` | GatewayError |\n| `500` | `application/json` | RiaError |\n| `502` | `application/json` | RiaError |\n\n*ReportFileListResponse*: Success envelope for the report-file operations.\n\n| Field | Type | Required | Description |\n|---|---|---|---|\n| `Status` | string | No | `Success` when the call completed. |\n| `Message` | string | No | Additional message. Empty on success. |\n| `Result` | array of ReportFile | No | Matching Available report files. An empty array means nothing matched. |\n| `Result[].id` | integer | No | Submission identifier of the run that produced the file. Use it with `GET /reports/{report_id}` and the v2 signed-URL operation. |\n| `Result[].file_name` | string | No | Name of the generated file. Use it with `GET /reports/download/{filename}`. |\n| `Result[].rep_name` | string | No | Name of the report definition that produced the file. |\n| `Result[].category` | string | No | Report category. |\n| `Result[].rep_desc` | string | No | Report description. |\n| `Result[].layout_name` | string | No | Name of the layout that was run. |\n| `Result[].report_date` | string | No | Date and time the run was created, formatted `DD-MM-YYYY HH24:MI:SS`. |\n| `Result[].status` | string | No | Run status. These operations only return Available runs, so the value is `A` (or `Available` on some tenant database platforms). Allowed: `A`, `Available`. |\n| `Result[].org_id` | string | No | Organization security value of the run. Returned on some tenant database platforms only. |\n\nError response schemas (GatewayError, ServiceError, SpringError, SimpleError, MissingFiltersError, RunStatusConflict, RiaError, SignedUrlError) are defined once under *Error response schemas* in the API overview and in `components/schemas`.\n\n\n**Response codes:** `200`, `400`, `401`, `403`, `404`, `429`, `500`, `502`. Each response with a body includes worked examples; responses without a body say so.", "operationId": "listReportFilesByDate", "parameters": [ { "name": "createddate", "in": "query", "required": true, "description": "Creation date of the report files, formatted `DD-Mon-YYYY`.", "schema": { "type": "string" }, "example": "09-Oct-2026" }, { "name": "Zuora-Track-Id", "in": "header", "required": false, "description": "Optional correlation identifier (up to 64 characters) that you choose. The Zuora One gateway records it; quote it to Zuora Support when you report a problem.", "schema": { "type": "string" }, "example": "close-run-2026-09-001" } ], "responses": { "200": { "description": "**Success.** Matching report files.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportFileListResponse" }, "examples": { "files": { "summary": "Two files", "value": { "Status": "Success", "Message": "", "Result": [ { "id": 482391, "file_name": "WF_SUMMARY_482391.csv", "rep_name": "Revenue Waterfall Report", "category": "Revenue", "rep_desc": "Recognized and scheduled revenue by period for each revenue contract line", "layout_name": "Monthly Close - Summary", "report_date": "09-10-2026 07:15:02", "status": "A" }, { "id": 482402, "file_name": "DEF_ROLL_482402.csv", "rep_name": "Deferred Revenue Roll Forward", "category": "Revenue", "rep_desc": "Opening balance, additions, recognition and closing deferred revenue by period", "layout_name": "Auditor Extract", "report_date": "09-10-2026 08:02:44", "status": "A" } ] } }, "none": { "summary": "No files that day", "value": { "Status": "Success", "Message": "", "Result": [] } } } } } }, "400": { "description": "**Failure.** `createddate` is missing or not in `DD-Mon-YYYY` format, or the OAuth client is not linked to a Zuora user. Also returned when the database connection fails (retry with backoff).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportingRiaError" }, "examples": { "missing": { "summary": "createddate missing", "value": { "Status": "Error", "Message": "Mandatory field createddate is missing in path" } }, "badDate": { "summary": "Wrong date format", "value": { "Status": "Error", "Message": "Invalid date format 2026-10-09 for createddate" } }, "noUser": { "$ref": "#/components/examples/NoUser" }, "dbConnect": { "$ref": "#/components/examples/DbConnect" } } } } }, "401": { "$ref": "#/components/responses/ReportingUnauthorized2" }, "403": { "$ref": "#/components/responses/ReportingForbidden2" }, "404": { "description": "**Failure.** The file list could not be read. Returned on some tenant database platforms; on others the same condition returns `500`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportingRiaError" }, "examples": { "notFound": { "$ref": "#/components/examples/NotFound" } } } } }, "429": { "$ref": "#/components/responses/ReportingTooManyRequests" }, "500": { "$ref": "#/components/responses/ReportingServerError2" }, "502": { "$ref": "#/components/responses/ReportingBadGateway" } } } }, "/api/integration/v1/reports/{report_id}": { "servers": [ { "url": "https://one.zuora.com", "description": "Zuora One production. Revenue Reporting paths start with /revenue/services/v1; Integration Reporting paths start with /api/integration/v1 or /api/integration/v2." } ], "get": { "tags": [ "Report Files" ], "security": [ { "OneIdOAuth": [] } ], "summary": "Retrieve a report file by submission ID", "description": "Returns the report file of one run when that run is Available and belongs to an organization your role can access.\n\n**Purpose:** Confirm that a run (for example one produced by a report schedule) is ready, and get its `file_name` for download.\n\n**When to use:** When you have a submission ID (for example from a schedule notification) and want to check that its file is ready and get its file name.\n\n**Notes:**\n\n- `report_id` is the submission (run) ID, not the report definition ID.\n- When the run does not exist, is not Available yet, or is outside your organizations, the response is `200` with an empty `Result` array. Poll until the array contains the file.\n\n### Request definition\n\n| Parameter | In | Type | Required | Default | Description |\n|---|---|---|---|---|---|\n| `report_id` | path | integer | Yes | | Submission (run) identifier. |\n| `Zuora-Track-Id` | header | string | No | | Optional correlation identifier (up to 64 characters) that you choose. The Zuora One gateway records it; quote it to Zuora Support when you report a problem. |\n| `Authorization` | header | string | Yes | | `Bearer ` (Zuora OneID OAuth). |\n\n**Request body:** none.\n\n### Response definition\n\n| HTTP status | Content type | Response schema |\n|---|---|---|\n| `200` | `application/json` | ReportFileListResponse |\n| `400` | `application/json` | RiaError |\n| `401` | `application/json` | GatewayError or RiaError |\n| `403` | `application/json` | RiaError |\n| `404` | `application/json` | RiaError |\n| `429` | `application/json` | GatewayError |\n| `500` | `application/json` | RiaError |\n| `502` | `application/json` | RiaError |\n\n*ReportFileListResponse*: Success envelope for the report-file operations.\n\n| Field | Type | Required | Description |\n|---|---|---|---|\n| `Status` | string | No | `Success` when the call completed. |\n| `Message` | string | No | Additional message. Empty on success. |\n| `Result` | array of ReportFile | No | Matching Available report files. An empty array means nothing matched. |\n| `Result[].id` | integer | No | Submission identifier of the run that produced the file. Use it with `GET /reports/{report_id}` and the v2 signed-URL operation. |\n| `Result[].file_name` | string | No | Name of the generated file. Use it with `GET /reports/download/{filename}`. |\n| `Result[].rep_name` | string | No | Name of the report definition that produced the file. |\n| `Result[].category` | string | No | Report category. |\n| `Result[].rep_desc` | string | No | Report description. |\n| `Result[].layout_name` | string | No | Name of the layout that was run. |\n| `Result[].report_date` | string | No | Date and time the run was created, formatted `DD-MM-YYYY HH24:MI:SS`. |\n| `Result[].status` | string | No | Run status. These operations only return Available runs, so the value is `A` (or `Available` on some tenant database platforms). Allowed: `A`, `Available`. |\n| `Result[].org_id` | string | No | Organization security value of the run. Returned on some tenant database platforms only. |\n\nError response schemas (GatewayError, ServiceError, SpringError, SimpleError, MissingFiltersError, RunStatusConflict, RiaError, SignedUrlError) are defined once under *Error response schemas* in the API overview and in `components/schemas`.\n\n\n**Response codes:** `200`, `400`, `401`, `403`, `404`, `429`, `500`, `502`. Each response with a body includes worked examples; responses without a body say so.", "operationId": "getReportFile", "parameters": [ { "name": "report_id", "in": "path", "required": true, "description": "Submission (run) identifier.", "schema": { "type": "integer" }, "example": 482391 }, { "name": "Zuora-Track-Id", "in": "header", "required": false, "description": "Optional correlation identifier (up to 64 characters) that you choose. The Zuora One gateway records it; quote it to Zuora Support when you report a problem.", "schema": { "type": "string" }, "example": "close-run-2026-09-001" } ], "responses": { "200": { "description": "**Success.** The report file, or an empty array.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportFileListResponse" }, "examples": { "ready": { "summary": "File ready", "value": { "Status": "Success", "Message": "", "Result": [ { "id": 482391, "file_name": "WF_SUMMARY_482391.csv", "rep_name": "Revenue Waterfall Report", "category": "Revenue", "rep_desc": "Recognized and scheduled revenue by period for each revenue contract line", "layout_name": "Monthly Close - Summary", "report_date": "09-10-2026 07:15:02", "status": "A" } ] } }, "notReady": { "summary": "Not Available yet, or not visible", "value": { "Status": "Success", "Message": "", "Result": [] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest2" }, "401": { "$ref": "#/components/responses/ReportingUnauthorized2" }, "403": { "$ref": "#/components/responses/ReportingForbidden2" }, "404": { "description": "**Failure.** `report_id` is not a non-negative integer (the route does not match and a plain HTML \"Not Found\" page is returned), or, on some tenant database platforms, the data could not be read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportingRiaError" }, "examples": { "notFound": { "$ref": "#/components/examples/NotFound" } } } } }, "429": { "$ref": "#/components/responses/ReportingTooManyRequests" }, "500": { "$ref": "#/components/responses/ReportingServerError2" }, "502": { "$ref": "#/components/responses/ReportingBadGateway" } } } }, "/api/integration/v1/reports/recent-n/{number_of_records}": { "servers": [ { "url": "https://one.zuora.com", "description": "Zuora One production. Revenue Reporting paths start with /revenue/services/v1; Integration Reporting paths start with /api/integration/v1 or /api/integration/v2." } ], "get": { "tags": [ "Report Files" ], "security": [ { "OneIdOAuth": [] } ], "summary": "List recent report files", "description": "Returns up to `number_of_records` Available report files, sorted by creation time with the newest first.\n\n**Purpose:** Pick up recently produced files without tracking dates or submission IDs.\n\n**When to use:** When you want the latest completed files without tracking dates or submission IDs, for example in a frequent polling job.\n\n**Notes:**\n\n- Keep `number_of_records` small (for example 10 to 50) to keep responses fast.\n\n### Request definition\n\n| Parameter | In | Type | Required | Default | Description |\n|---|---|---|---|---|---|\n| `number_of_records` | path | integer | Yes | | Maximum number of files to return. |\n| `Zuora-Track-Id` | header | string | No | | Optional correlation identifier (up to 64 characters) that you choose. The Zuora One gateway records it; quote it to Zuora Support when you report a problem. |\n| `Authorization` | header | string | Yes | | `Bearer ` (Zuora OneID OAuth). |\n\n**Request body:** none.\n\n### Response definition\n\n| HTTP status | Content type | Response schema |\n|---|---|---|\n| `200` | `application/json` | ReportFileListResponse |\n| `400` | `application/json` | RiaError |\n| `401` | `application/json` | GatewayError or RiaError |\n| `403` | `application/json` | RiaError |\n| `404` | `application/json` | RiaError |\n| `429` | `application/json` | GatewayError |\n| `500` | `application/json` | RiaError |\n| `502` | `application/json` | RiaError |\n\n*ReportFileListResponse*: Success envelope for the report-file operations.\n\n| Field | Type | Required | Description |\n|---|---|---|---|\n| `Status` | string | No | `Success` when the call completed. |\n| `Message` | string | No | Additional message. Empty on success. |\n| `Result` | array of ReportFile | No | Matching Available report files. An empty array means nothing matched. |\n| `Result[].id` | integer | No | Submission identifier of the run that produced the file. Use it with `GET /reports/{report_id}` and the v2 signed-URL operation. |\n| `Result[].file_name` | string | No | Name of the generated file. Use it with `GET /reports/download/{filename}`. |\n| `Result[].rep_name` | string | No | Name of the report definition that produced the file. |\n| `Result[].category` | string | No | Report category. |\n| `Result[].rep_desc` | string | No | Report description. |\n| `Result[].layout_name` | string | No | Name of the layout that was run. |\n| `Result[].report_date` | string | No | Date and time the run was created, formatted `DD-MM-YYYY HH24:MI:SS`. |\n| `Result[].status` | string | No | Run status. These operations only return Available runs, so the value is `A` (or `Available` on some tenant database platforms). Allowed: `A`, `Available`. |\n| `Result[].org_id` | string | No | Organization security value of the run. Returned on some tenant database platforms only. |\n\nError response schemas (GatewayError, ServiceError, SpringError, SimpleError, MissingFiltersError, RunStatusConflict, RiaError, SignedUrlError) are defined once under *Error response schemas* in the API overview and in `components/schemas`.\n\n\n**Response codes:** `200`, `400`, `401`, `403`, `404`, `429`, `500`, `502`. Each response with a body includes worked examples; responses without a body say so.", "operationId": "listRecentReportFiles", "parameters": [ { "name": "number_of_records", "in": "path", "required": true, "description": "Maximum number of files to return.", "schema": { "type": "integer" }, "example": 10 }, { "name": "Zuora-Track-Id", "in": "header", "required": false, "description": "Optional correlation identifier (up to 64 characters) that you choose. The Zuora One gateway records it; quote it to Zuora Support when you report a problem.", "schema": { "type": "string" }, "example": "close-run-2026-09-001" } ], "responses": { "200": { "description": "**Success.** Recent report files.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportFileListResponse" }, "examples": { "recent": { "summary": "Two most recent files", "value": { "Status": "Success", "Message": "", "Result": [ { "id": 482402, "file_name": "DEF_ROLL_482402.csv", "rep_name": "Deferred Revenue Roll Forward", "category": "Revenue", "rep_desc": "Opening balance, additions, recognition and closing deferred revenue by period", "layout_name": "Auditor Extract", "report_date": "09-10-2026 08:02:44", "status": "A" }, { "id": 482391, "file_name": "WF_SUMMARY_482391.csv", "rep_name": "Revenue Waterfall Report", "category": "Revenue", "rep_desc": "Recognized and scheduled revenue by period for each revenue contract line", "layout_name": "Monthly Close - Summary", "report_date": "09-10-2026 07:15:02", "status": "A" } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest2" }, "401": { "$ref": "#/components/responses/ReportingUnauthorized2" }, "403": { "$ref": "#/components/responses/ReportingForbidden2" }, "404": { "description": "**Failure.** `number_of_records` is missing or not a non-negative integer (a plain HTML \"Not Found\" page is returned), or, on some tenant database platforms, the data could not be read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportingRiaError" }, "examples": { "notFound": { "$ref": "#/components/examples/NotFound" } } } } }, "429": { "$ref": "#/components/responses/ReportingTooManyRequests" }, "500": { "$ref": "#/components/responses/ReportingServerError2" }, "502": { "$ref": "#/components/responses/ReportingBadGateway" } } } }, "/api/integration/v1/reports/download/{filename}": { "servers": [ { "url": "https://one.zuora.com", "description": "Zuora One production. Revenue Reporting paths start with /revenue/services/v1; Integration Reporting paths start with /api/integration/v1 or /api/integration/v2." } ], "get": { "tags": [ "Report Files" ], "security": [ { "OneIdOAuth": [] } ], "summary": "Download a report file", "description": "Streams the bytes of a report file stored in your tenant's Revenue file store. Supports `.csv` and `.zip` files.\n\n**Purpose:** Download a file listed by the report-file operations when your tenant stores reports on the Revenue file store. For files in cloud storage, use *Get a signed URL* instead.\n\n**When to use:** When your tenant stores report files on the Revenue file store and you have the `file_name` from a list operation.\n\n**Notes:**\n\n- `filename` is the `file_name` value from the list operations, including its extension.\n- `204 No Content` means the file is not in the file store, or its extension is not `.csv` or `.zip`.\n\n### Request definition\n\n| Parameter | In | Type | Required | Default | Description |\n|---|---|---|---|---|---|\n| `filename` | path | string | Yes | | File name including extension. |\n| `Zuora-Track-Id` | header | string | No | | Optional correlation identifier (up to 64 characters) that you choose. The Zuora One gateway records it; quote it to Zuora Support when you report a problem. |\n| `Authorization` | header | string | Yes | | `Bearer ` (Zuora OneID OAuth). |\n\n**Request body:** none.\n\n### Response definition\n\n| HTTP status | Content type | Response schema |\n|---|---|---|\n| `200` | `application/octet-stream` | string (binary) |\n| `204` | none | No body |\n| `400` | `application/json` | RiaError |\n| `401` | `application/json` | GatewayError or RiaError |\n| `403` | `application/json` | RiaError |\n| `429` | `application/json` | GatewayError |\n| `500` | `application/json` | RiaError |\n| `502` | `application/json` | RiaError |\n\nError response schemas (GatewayError, ServiceError, SpringError, SimpleError, MissingFiltersError, RunStatusConflict, RiaError, SignedUrlError) are defined once under *Error response schemas* in the API overview and in `components/schemas`.\n\n\n**Response codes:** `200`, `204`, `400`, `401`, `403`, `429`, `500`, `502`. Each response with a body includes worked examples; responses without a body say so.", "operationId": "downloadReportFile", "parameters": [ { "name": "filename", "in": "path", "required": true, "description": "File name including extension.", "schema": { "type": "string" }, "example": "WF_SUMMARY_482391.csv" }, { "name": "Zuora-Track-Id", "in": "header", "required": false, "description": "Optional correlation identifier (up to 64 characters) that you choose. The Zuora One gateway records it; quote it to Zuora Support when you report a problem.", "schema": { "type": "string" }, "example": "close-run-2026-09-001" } ], "responses": { "200": { "description": "**Success.** The file contents.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" }, "examples": { "csv": { "summary": "CSV file bytes", "value": "\"Period Name\",\"Revenue Contract ID\",\"Recognized Amount\"\n\"SEP-2026\",\"120045\",\"1000.00\"\n" } } } } }, "204": { "description": "**Success.** The file does not exist in the file store, or it is not a `.csv` or `.zip` file. No body." }, "400": { "description": "**Failure.** The tenant's file store could not be resolved or read, or the OAuth client is not linked to a Zuora user. Also returned when the database connection fails (retry with backoff).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportingRiaError" }, "examples": { "noPath": { "summary": "File store not available", "value": { "Status": "Error", "Result": null, "Message": "Failed to derive Report FilePath" } }, "noUser": { "$ref": "#/components/examples/NoUser" }, "dbConnect": { "$ref": "#/components/examples/DbConnect" } } } } }, "401": { "$ref": "#/components/responses/ReportingUnauthorized2" }, "403": { "$ref": "#/components/responses/ReportingForbidden2" }, "429": { "$ref": "#/components/responses/ReportingTooManyRequests" }, "500": { "$ref": "#/components/responses/ReportingServerError2" }, "502": { "$ref": "#/components/responses/ReportingBadGateway" } } } }, "/api/integration/v2/reports/signedurl/{report_id}": { "servers": [ { "url": "https://one.zuora.com", "description": "Zuora One production. Revenue Reporting paths start with /revenue/services/v1; Integration Reporting paths start with /api/integration/v1 or /api/integration/v2." } ], "get": { "tags": [ "Report Files" ], "security": [ { "OneIdOAuth": [] } ], "summary": "Retrieve a signed URL", "description": "Returns a signed HTTPS URL, valid for 30 minutes, for the file of an Available run stored in cloud storage. Download the file with a plain HTTP GET on the URL. GET and POST behave the same; POST takes no body.\n\n**Purpose:** The recommended way to download report files: large files do not pass through the API and the URL expires quickly if it is leaked.\n\n**When to use:** To download a completed report file that is stored in cloud storage. This is the preferred download method for the Integration Reporting APIs.\n\n**Notes:**\n\n- `report_id` is the submission (run) ID.\n- Some tenants disable HTTP GET on this operation. In that case GET returns `403` and you must use POST on the same path. POST always works, so prefer POST in new integrations.\n\n### Request definition\n\n| Parameter | In | Type | Required | Default | Description |\n|---|---|---|---|---|---|\n| `report_id` | path | integer | Yes | | Submission (run) identifier. |\n| `Zuora-Track-Id` | header | string | No | | Optional correlation identifier (up to 64 characters) that you choose. The Zuora One gateway records it; quote it to Zuora Support when you report a problem. |\n| `Authorization` | header | string | Yes | | `Bearer ` (Zuora OneID OAuth). |\n\n**Request body:** none.\n\n### Response definition\n\n| HTTP status | Content type | Response schema |\n|---|---|---|\n| `200` | `application/json` | SignedUrlResponse |\n| `400` | `application/json` | RiaError |\n| `401` | `application/json` | GatewayError or RiaError |\n| `403` | `application/json` | RiaError |\n| `404` | `application/json` | SignedUrlError |\n| `429` | `application/json` | GatewayError |\n| `500` | `application/json` | RiaError |\n| `502` | `application/json` | RiaError |\n\n*SignedUrlResponse*: Signed download URL for a completed report.\n\n| Field | Type | Required | Description |\n|---|---|---|---|\n| `success` | boolean | No | `true` when the URL was generated. |\n| `signed_url` | string (uri) | No | HTTPS URL of the report file. Download it with a plain HTTP GET; it is valid for 30 minutes (1,800 seconds). |\n\nError response schemas (GatewayError, ServiceError, SpringError, SimpleError, MissingFiltersError, RunStatusConflict, RiaError, SignedUrlError) are defined once under *Error response schemas* in the API overview and in `components/schemas`.\n\n\n**Response codes:** `200`, `400`, `401`, `403`, `404`, `429`, `500`, `502`. Each response with a body includes worked examples; responses without a body say so.", "operationId": "getReportSignedUrl", "parameters": [ { "name": "report_id", "in": "path", "required": true, "description": "Submission (run) identifier.", "schema": { "type": "integer" }, "example": 482391 }, { "name": "Zuora-Track-Id", "in": "header", "required": false, "description": "Optional correlation identifier (up to 64 characters) that you choose. The Zuora One gateway records it; quote it to Zuora Support when you report a problem.", "schema": { "type": "string" }, "example": "close-run-2026-09-001" } ], "responses": { "200": { "$ref": "#/components/responses/Response200" }, "400": { "$ref": "#/components/responses/BadRequest3" }, "401": { "$ref": "#/components/responses/ReportingUnauthorized2" }, "403": { "$ref": "#/components/responses/Forbidden3" }, "404": { "$ref": "#/components/responses/NotFound3" }, "429": { "$ref": "#/components/responses/ReportingTooManyRequests" }, "500": { "$ref": "#/components/responses/ReportingServerError2" }, "502": { "$ref": "#/components/responses/ReportingBadGateway" } } }, "post": { "tags": [ "Report Files" ], "security": [ { "OneIdOAuth": [] } ], "summary": "Get a signed URL (POST)", "description": "Returns a signed HTTPS URL, valid for 30 minutes, for the file of an Available run stored in cloud storage. Download the file with a plain HTTP GET on the URL. GET and POST behave the same; POST takes no body.\n\n**Purpose:** The recommended way to download report files: large files do not pass through the API and the URL expires quickly if it is leaked.\n\n**When to use:** To download a completed report file that is stored in cloud storage. This is the preferred download method for the Integration Reporting APIs.\n\n**Notes:**\n\n- `report_id` is the submission (run) ID.\n- Some tenants disable HTTP GET on this operation. In that case GET returns `403` and you must use POST on the same path. POST always works, so prefer POST in new integrations.\n\n### Request definition\n\n| Parameter | In | Type | Required | Default | Description |\n|---|---|---|---|---|---|\n| `report_id` | path | integer | Yes | | Submission (run) identifier. |\n| `Zuora-Track-Id` | header | string | No | | Optional correlation identifier (up to 64 characters) that you choose. The Zuora One gateway records it; quote it to Zuora Support when you report a problem. |\n| `Authorization` | header | string | Yes | | `Bearer ` (Zuora OneID OAuth). |\n\n**Request body:** none.\n\n### Response definition\n\n| HTTP status | Content type | Response schema |\n|---|---|---|\n| `200` | `application/json` | SignedUrlResponse |\n| `400` | `application/json` | RiaError |\n| `401` | `application/json` | GatewayError or RiaError |\n| `403` | `application/json` | RiaError |\n| `404` | `application/json` | SignedUrlError |\n| `429` | `application/json` | GatewayError |\n| `500` | `application/json` | RiaError |\n| `502` | `application/json` | RiaError |\n\n*SignedUrlResponse*: Signed download URL for a completed report.\n\n| Field | Type | Required | Description |\n|---|---|---|---|\n| `success` | boolean | No | `true` when the URL was generated. |\n| `signed_url` | string (uri) | No | HTTPS URL of the report file. Download it with a plain HTTP GET; it is valid for 30 minutes (1,800 seconds). |\n\nError response schemas (GatewayError, ServiceError, SpringError, SimpleError, MissingFiltersError, RunStatusConflict, RiaError, SignedUrlError) are defined once under *Error response schemas* in the API overview and in `components/schemas`.\n\n\n**Response codes:** `200`, `400`, `401`, `403`, `404`, `429`, `500`, `502`. Each response with a body includes worked examples; responses without a body say so.", "operationId": "getReportSignedUrlPost", "parameters": [ { "name": "report_id", "in": "path", "required": true, "description": "Submission (run) identifier.", "schema": { "type": "integer" }, "example": 482391 }, { "name": "Zuora-Track-Id", "in": "header", "required": false, "description": "Optional correlation identifier (up to 64 characters) that you choose. The Zuora One gateway records it; quote it to Zuora Support when you report a problem.", "schema": { "type": "string" }, "example": "close-run-2026-09-001" } ], "responses": { "200": { "$ref": "#/components/responses/Response200" }, "400": { "$ref": "#/components/responses/BadRequest3" }, "401": { "$ref": "#/components/responses/ReportingUnauthorized2" }, "403": { "$ref": "#/components/responses/Forbidden3" }, "404": { "$ref": "#/components/responses/NotFound3" }, "429": { "$ref": "#/components/responses/ReportingTooManyRequests" }, "500": { "$ref": "#/components/responses/ReportingServerError2" }, "502": { "$ref": "#/components/responses/ReportingBadGateway" } } } } }, "x-tagGroups": [ { "name": "Authentication", "tags": [ "Authentication" ] }, { "name": "Data Ingestion File Uploads", "tags": [ "Adapter", "File Upload", "Inbound" ] }, { "name": "Staging Errors", "tags": [ "Stage Error" ] }, { "name": "Revenue Transfer Accounting", "tags": [ "Transfer Accounting", "Transfer Accounting Files" ] }, { "name": "Revenue Jobs and Programs", "tags": [ "Revenue Jobs", "Data Collection" ] }, { "name": "Revenue Reporting", "tags": [ "Report Catalog", "Report Runs", "Report Files" ] }, { "name": "BI Views", "tags": [ "BI Views", "BI View Tasks" ] }, { "name": "Revenue Manual Journals", "tags": [ "Journal Entries", "Service Health", "Journal Entry Lines", "Schedules and Waterfall", "Approval Workflow", "Reference Data", "Attachments", "Templates and Exports" ] }, { "name": "Revenue Contract Management and Workbench Operations", "tags": [ "Revenue Contracts", "Revenue Contract Lines", "Revenue Holds", "Contract Status", "Apply and Release Holds", "Revenue Deferral and Release", "Cost Deferral and Release", "Allocation", "Lines and POBs", "Contract Grouping", "Variable Consideration", "Impairment", "Usage", "Billing", "Forecast" ] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Use `Bearer {{token}}` in the `Authorization` header for authentication.\n" }, "basicAuth": { "type": "http", "scheme": "basic", "description": "The user name is the email address that you use for logging in Zuora. The password is the API token that is shown in the settings of Configurable Payment Retry.\n" }, "OneIdOAuth": { "type": "oauth2", "description": "Zuora OneID OAuth 2.0 client credentials. Send the access token as `Authorization: Bearer `.", "flows": { "clientCredentials": { "tokenUrl": "https://one.zuora.com/oauth2/token", "scopes": {} } } } }, "schemas": { "JobStatusResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/JobStatus" }, "success": { "type": "boolean" } } }, "JobStatus": { "type": "object", "properties": { "actual_start_date": { "type": "string", "format": "datetime" }, "crtd_by": { "type": "string" }, "crtd_dt": { "type": "string", "format": "datetime" }, "error_message": { "type": "string" }, "id": { "type": "integer" }, "sec_atr_val": { "type": "integer" }, "status": { "type": "string" }, "updt_dt": { "type": "string", "format": "datetime" } } }, "SubmitJobFailureResponse": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "OrgId does not match the Org assigned to the role", "This Program is not supported at the moment" ] }, "success": { "type": "boolean" } } }, "SubmitJobRequest": { "type": "object", "properties": { "parameters": { "type": "array", "items": { "$ref": "#/components/schemas/ParameterList" } } } }, "ParameterList": { "type": "object", "properties": { "parameter_id": { "type": "integer" }, "sequence": { "type": "integer" }, "parameter_value": { "type": "string" } } }, "ProgramDetailsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProgramDetail" } } } }, "ProgramDetail": { "type": "object", "properties": { "program_name": { "type": "string" }, "program_id": { "type": "string" }, "parameters": { "type": "array", "items": { "$ref": "#/components/schemas/ProgramParameter" } } } }, "ProgramParameter": { "type": "object", "properties": { "id": { "type": "integer" }, "mandatory": { "type": "string" }, "sequence": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" } } }, "RevenueJobDetail": { "type": "object", "properties": { "data": { "type": "object", "properties": { "actual_start_date": { "type": "string" }, "crtd_by": { "type": "string" }, "crtd_dt": { "type": "string" }, "id": { "type": "integer" }, "status": { "type": "string", "enum": [ "Running", "Error", "Pending", "Completed", "Warning", "Failed", "Cancelled", "Terminated", "Incompatible" ] }, "updt_dt": { "type": "string" } } }, "success": { "type": "boolean" } } }, "RevenueJobRequest": { "type": "object", "properties": { "rc_template_name": { "type": "string", "description": "Name of the RC template that is defined in Zuora Revenue (**Policies > RC Grouping Template**)." }, "org_id": { "type": "integer", "description": "The organization ID that can be found in Zuora Revenue (**Setups > Application > Organization**). This field is required only for multi-organization tenants." } } }, "RevenueJobResponse": { "type": "object", "properties": { "message": { "type": "string" }, "success": { "type": "boolean" } } }, "Journal": { "type": "object", "properties": { "client_id": { "type": "integer" }, "crtd_by": { "type": "string" }, "crtd_dt": { "type": "string", "format": "date-time" }, "id": { "type": "integer", "format": "int32" }, "name": { "type": "string" }, "status": { "type": "string" }, "updt_by": { "type": "string" }, "updt_dt": { "type": "string", "format": "date-time" }, "report_id": { "type": "integer", "format": "int32" } } }, "stageError": { "type": "object", "properties": { "client_id": { "type": "integer" }, "crtd_by": { "type": "string" }, "crtd_dt": { "type": "string", "format": "date-time" }, "err_msg": { "type": "string" }, "id": { "type": "integer" }, "inv_line_id": { "type": "string" }, "inv_line_num": { "type": "string" }, "processed_flag": { "type": "string" }, "sec_atr_val": { "type": "string" }, "so_line_id": { "type": "string" }, "so_line_num": { "type": "string" }, "so_num": { "type": "string" }, "type": { "type": "string" }, "updt_by": { "type": "string" }, "updt_dt": { "type": "string", "format": "date-time" }, "upload_id": { "type": "string" } } }, "uploadMapping": { "type": "object", "properties": { "client_id": { "type": "integer" }, "col_name": { "type": "string" }, "data_type": { "type": "string" }, "id": { "type": "integer" }, "label": { "type": "string" }, "seq": { "type": "integer" }, "upload_id": { "type": "integer" } } }, "uploadStatus": { "type": "object", "properties": { "file_log": { "type": "string" }, "file_request_id": { "type": "integer" } } }, "Report": { "type": "object", "description": "A report definition in the tenant's report catalog. A report describes a data set (for example revenue waterfall or deferred revenue balances). It does not contain row data.", "properties": { "id": { "type": "integer", "description": "Unique numeric identifier of the report definition. Use it as `reportId` in every other Reports call.", "example": 10021, "format": "int32" }, "name": { "type": "string", "description": "Display name of the report. List reports returns the translated name when a translation exists for the caller's language; other operations return the stored name.", "example": "Revenue Waterfall Report" }, "description": { "type": "string", "description": "Business description of what the report contains.", "example": "Recognized and scheduled revenue by period for each revenue contract line", "nullable": true }, "category": { "type": "string", "description": "Catalog grouping the report belongs to, as configured in Zuora Revenue.", "example": "Revenue", "nullable": true }, "sequence": { "type": "integer", "description": "Display order of the report inside its category. Lower numbers are shown first.", "example": 3, "format": "int32", "nullable": true }, "createdBy": { "type": "string", "description": "User name that created the report definition.", "example": "SYSADMIN", "nullable": true }, "createdAt": { "type": "string", "description": "Date and time the report definition was created, formatted `yyyy-MM-dd'T'HH:mm:ss`.", "example": "2024-01-15T09:30:00", "format": "date-time", "nullable": true }, "updatedBy": { "type": "string", "description": "User name that last changed the report definition.", "example": "FIN.ADMIN", "nullable": true }, "updatedAt": { "type": "string", "description": "Date and time the report definition was last changed, formatted `yyyy-MM-dd'T'HH:mm:ss`.", "example": "2026-08-02T14:05:11", "format": "date-time", "nullable": true } } }, "LayoutField": { "type": "object", "description": "One output column of a report layout.", "properties": { "id": { "type": "integer", "description": "Unique identifier of this column assignment within the layout.", "example": 55012, "format": "int32" }, "layoutId": { "type": "integer", "description": "Identifier of the layout the column belongs to.", "example": 3105, "format": "int32" }, "fieldId": { "type": "integer", "description": "Identifier of the underlying report field (column definition).", "example": 8801, "format": "int32" }, "seq": { "type": "integer", "description": "Position of the column in the output file. Lower numbers appear further left.", "example": 1, "format": "int32", "nullable": true }, "sortSeq": { "type": "integer", "description": "Sort priority of the column. `null` when the layout does not sort by this column.", "example": 1, "format": "int32", "nullable": true }, "fieldName": { "type": "string", "description": "Technical field name in lowerCamelCase. Use this value as `fieldName` when you filter a report run.", "example": "periodName", "nullable": true }, "fieldLabel": { "type": "string", "description": "Column heading shown in the output file, translated to the caller's language when a translation exists.", "example": "Period Name", "nullable": true }, "fieldType": { "type": "string", "description": "Database data type of the column, for example `VARCHAR2`, `NUMBER`, `DATE` or `DATE_TIME`.", "example": "VARCHAR2", "nullable": true } } }, "FilterOption": { "type": "object", "description": "One allowed value of a list-of-values (LOV) filter.", "properties": { "label": { "type": "string", "description": "Human-readable text of the option, already translated.", "example": "Revenue" }, "value": { "type": "string", "description": "Value to send as the filter `value` when you select this option.", "example": "R" } } }, "LayoutFilter": { "type": "object", "description": "A filter that is defined on a report layout. Filters restrict the rows the report returns.", "properties": { "id": { "type": "integer", "description": "Unique identifier of the filter definition.", "example": 70033, "format": "int32" }, "layoutId": { "type": "integer", "description": "Identifier of the layout the filter belongs to.", "example": 3105, "format": "int32" }, "fieldId": { "type": "integer", "description": "Identifier of the report field the filter applies to.", "example": 8801, "format": "int32" }, "fieldName": { "type": "string", "description": "Technical field name in lowerCamelCase. Send this as `fieldName` in a run request to override the filter.", "example": "periodName", "nullable": true }, "fieldLabel": { "type": "string", "description": "Display label of the filter, translated when a translation exists.", "example": "Period Name", "nullable": true }, "fieldType": { "type": "string", "description": "Database data type of the filtered field, for example `VARCHAR2`, `NUMBER`, `DATE` or `DATE_TIME`.", "example": "VARCHAR2", "nullable": true }, "type": { "type": "string", "description": "How the filter is presented and evaluated, for example `LOV` (pick from a list), `RANGE` (from/to) or `EQUALS` (single value).", "example": "LOV", "nullable": true }, "valueFrom": { "type": "string", "description": "Saved default value, or the lower bound of a range filter.", "example": "$revpro.CurrPrd", "nullable": true }, "valueTo": { "type": "string", "description": "Saved upper bound of a range filter. `null` for single-value filters.", "nullable": true }, "createdBy": { "type": "string", "description": "User name that created the filter.", "example": "SYSADMIN", "nullable": true }, "createdAt": { "type": "string", "description": "Creation date and time, formatted `yyyy-MM-dd'T'HH:mm:ss`.", "example": "2024-01-15T09:30:00", "format": "date-time", "nullable": true }, "updatedBy": { "type": "string", "description": "User name that last changed the filter.", "example": "SYSADMIN", "nullable": true }, "updatedAt": { "type": "string", "description": "Last change date and time, formatted `yyyy-MM-dd'T'HH:mm:ss`.", "example": "2024-01-15T09:30:00", "format": "date-time", "nullable": true }, "required": { "type": "boolean", "description": "`true` when the layout requires a value for this filter before a run is accepted; `null` when the filter is optional.", "example": true, "nullable": true }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/FilterOption" }, "description": "Allowed values for an `LOV` filter. Always an array; empty for other filter types or when no list is configured." } } }, "ReportLayout": { "type": "object", "description": "A saved layout of a report: the columns to output, the filters with their defaults, and the output file-name prefix. A report can have many layouts.", "properties": { "id": { "type": "integer", "description": "Unique identifier of the layout. Send it as `layoutId` when you run the report.", "example": 3105, "format": "int32" }, "reportId": { "type": "integer", "description": "Identifier of the report the layout belongs to.", "example": 10021, "format": "int32" }, "name": { "type": "string", "description": "Layout name.", "example": "Monthly Close - Summary" }, "description": { "type": "string", "description": "Layout description.", "example": "Summary by period for month-end close", "nullable": true }, "filenamePrefix": { "type": "string", "description": "Prefix used for the generated output file name.", "example": "WF_SUMMARY", "nullable": true }, "createdBy": { "type": "string", "description": "User name that created the layout.", "example": "FIN.ADMIN", "nullable": true }, "createdAt": { "type": "string", "description": "Creation date and time, formatted `yyyy-MM-dd'T'HH:mm:ss`.", "example": "2025-03-01T10:00:00", "format": "date-time", "nullable": true }, "updatedBy": { "type": "string", "description": "User name that last changed the layout.", "example": "FIN.ADMIN", "nullable": true }, "updatedAt": { "type": "string", "description": "Last change date and time, formatted `yyyy-MM-dd'T'HH:mm:ss`.", "example": "2026-07-30T16:12:45", "format": "date-time", "nullable": true }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/LayoutField" }, "description": "Output columns of the layout, in output order." }, "filters": { "type": "array", "items": { "$ref": "#/components/schemas/LayoutFilter" }, "description": "Filters defined on the layout, with required flags and allowed values." } } }, "LayoutList": { "type": "object", "description": "Wrapper returned by the list-layouts operation.", "properties": { "layouts": { "type": "array", "items": { "$ref": "#/components/schemas/ReportLayout" }, "description": "Layouts of the report, sorted by layout name. Each layout includes its fields and filters." }, "totalCount": { "type": "integer", "description": "Number of layouts in `layouts`.", "example": 1, "format": "int32" } } }, "LayoutFieldList": { "type": "object", "description": "Wrapper returned by the list-layout-fields operation.", "properties": { "layoutFields": { "type": "array", "items": { "$ref": "#/components/schemas/LayoutField" }, "description": "Output columns of the layout." } } }, "ReportMetadataColumn": { "type": "object", "description": "One field that the report can output.", "properties": { "id": { "type": "integer", "description": "Identifier of the report field.", "example": 8801, "format": "int32" }, "fieldName": { "type": "string", "description": "Technical field name as stored in the report definition (UPPER_SNAKE_CASE).", "example": "PERIOD_NAME" }, "alias": { "type": "string", "description": "Column alias used in the report output.", "example": "PERIOD_NAME", "nullable": true }, "fieldType": { "type": "string", "description": "Data type of the field.", "example": "VARCHAR2", "nullable": true }, "label": { "type": "string", "description": "Display label of the field.", "example": "Period Name", "nullable": true } } }, "ReportMetadataInfo": { "type": "object", "description": "Structural information about a report.", "properties": { "description": { "type": "string", "description": "Business description of the report.", "example": "Recognized and scheduled revenue by period for each revenue contract line", "nullable": true }, "parameters": { "type": "array", "items": { "type": "object" }, "description": "Reserved for future use. Currently always an empty array." }, "filters": { "type": "array", "items": { "type": "object" }, "description": "Reserved for future use. Currently always an empty array. Read filters from the layout operations instead." }, "columns": { "type": "array", "items": { "$ref": "#/components/schemas/ReportMetadataColumn" }, "description": "All fields the report can output." } } }, "ReportMetadataLayout": { "type": "object", "description": "Short reference to a layout of the report.", "properties": { "layoutId": { "type": "integer", "description": "Identifier of the layout.", "example": 3105, "format": "int32" }, "layoutName": { "type": "string", "description": "Name of the layout.", "example": "Monthly Close - Summary" }, "isDefault": { "type": "boolean", "description": "`true` when this is the report's default layout.", "example": true } } }, "ReportMetadata": { "type": "object", "description": "Report metadata: identity, type, available columns and layouts.", "properties": { "reportId": { "type": "integer", "description": "Identifier of the report.", "example": 10021, "format": "int32" }, "reportName": { "type": "string", "description": "Name of the report.", "example": "Revenue Waterfall Report" }, "reportType": { "type": "string", "description": "`STANDARD` for a report delivered by Zuora; `CUSTOM` for a report your organization created.", "example": "STANDARD", "enum": [ "STANDARD", "CUSTOM" ] }, "metadata": { "allOf": [ { "$ref": "#/components/schemas/ReportMetadataInfo" } ], "description": "Description, columns and reserved arrays." }, "layouts": { "type": "array", "items": { "$ref": "#/components/schemas/ReportMetadataLayout" }, "description": "Layouts available for the report." } } }, "ReportFilterParam": { "type": "object", "description": "One filter condition applied to a report run.", "properties": { "fieldName": { "type": "string", "description": "Field to filter on, in lowerCamelCase as returned by the layout operations (for example `periodName`). The service converts it to the stored field key.", "example": "periodName" }, "operator": { "type": "string", "description": "Comparison operator. When omitted, `=` is used. See *Filter operators* for the value rules of each operator.", "example": "=", "enum": [ "=", "!=", "<", "<=", ">", ">=", "LIKE", "NOT LIKE", "IS NULL", "IS NOT NULL", "BETWEEN", "IN", "VS" ] }, "value": { "type": "string", "description": "Filter value. Dates use `YYYY-MM-DD`. For `IN`, a comma-separated list. For `VS`, the from-book. Omit for `IS NULL` and `IS NOT NULL`. The macros `$revpro.CurrPrd` and `$revpro.PriorPrd` are replaced with the current or prior open period name.", "example": "$revpro.CurrPrd" }, "valueTo": { "type": "string", "description": "Upper bound for `BETWEEN` (date `YYYY-MM-DD`) or the to-book for `VS`. Not used by other operators." } }, "required": [ "fieldName" ] }, "RunReportRequest": { "type": "object", "description": "Request body that submits a report layout for execution.", "properties": { "layoutId": { "type": "integer", "description": "Identifier of the layout to run. Use a layout returned by List layouts for the same report.", "example": 3105, "format": "int32" }, "filters": { "type": "array", "items": { "$ref": "#/components/schemas/ReportFilterParam" }, "nullable": true, "description": "Filter conditions. Omit the property (or send `null`) to apply all saved layout defaults. Send a partial list to override some filters; layout defaults fill in the rest. Send `[]` to run with no filters at all (required filters are still enforced)." } }, "required": [ "layoutId" ] }, "ReportRun": { "type": "object", "description": "One execution (submission) of a report layout.", "properties": { "id": { "type": "integer", "description": "Submission identifier of the run. Use it as `submissionId` to poll status and download.", "example": 482391, "format": "int64" }, "reportId": { "type": "integer", "description": "Identifier of the report that was run.", "example": 10021, "format": "int32" }, "layoutId": { "type": "integer", "description": "Identifier of the layout that was run.", "example": 3105, "format": "int32" }, "status": { "type": "string", "description": "Current run status. See *Report run status values*.", "example": "Available", "enum": [ "Submitted", "Upload Started", "File Created", "Available", "Error", "Terminated", "Cancelled" ] }, "fileName": { "type": "string", "description": "Name of the output file. Populated once the file is produced.", "example": "WF_SUMMARY_482391.csv", "nullable": true }, "filterParameters": { "type": "string", "description": "JSON text of the filters stored for the run, after defaults and period macros were resolved. Filters are stored with internal filter keys (`key`), operator (`opr`, omitted for `=`) and values (`val1`, `val2`). Treat the content as informational; its format can change.", "example": "{\"filters\":[{\"key\":\"A300\",\"val1\":\"SEP-2026\"},{\"key\":\"A101\",\"val1\":\"R\"}]}", "nullable": true }, "config": { "type": "string", "description": "JSON text of output options: `Show Filters` (Y/N, print the filters in the file) and `Enable Totals` (Y/N, add total rows).", "example": "{\"Show Filters\":\"Y\",\"Enable Totals\":\"N\"}", "nullable": true }, "createdBy": { "type": "string", "description": "User that submitted the run.", "example": "INTEGRATION.USER", "nullable": true }, "runDate": { "type": "string", "description": "Date and time the run was submitted, formatted `yyyy-MM-dd'T'HH:mm:ss`.", "example": "2026-10-09T07:15:02", "format": "date-time", "nullable": true }, "updatedBy": { "type": "string", "description": "User or process that last updated the run.", "example": "INTEGRATION.USER", "nullable": true }, "updatedAt": { "type": "string", "description": "Date and time of the last status change, formatted `yyyy-MM-dd'T'HH:mm:ss`.", "example": "2026-10-09T07:16:40", "format": "date-time", "nullable": true } } }, "ReportDownload": { "type": "object", "description": "Time-limited download link for a completed report file.", "properties": { "presignedUrl": { "type": "string", "description": "HTTPS URL of the report file. Download it with a plain HTTP GET and no Authorization header. Valid for 30 minutes.", "example": "https://files.zuora.com/rev/1234567/reports/WF_SUMMARY_482391.csv?X-Amz-Expires=1800&X-Amz-Signature=3b1f...", "format": "uri" }, "expiresAt": { "type": "string", "description": "UTC date and time after which the URL stops working, formatted `yyyy-MM-dd'T'HH:mm:ss`.", "example": "2026-10-09T07:47:10", "format": "date-time" } } }, "MissingFiltersError": { "type": "object", "description": "Returned when a run is missing values for required layout filters.", "properties": { "error": { "type": "string", "description": "Fixed text `Missing required filters`.", "example": "Missing required filters" }, "missingFilters": { "type": "array", "items": { "type": "string" }, "description": "Labels of the required filters that had no value after defaults were applied.", "example": [ "Period Name" ] } } }, "SimpleError": { "type": "object", "description": "Error returned by the report run and download operations.", "properties": { "error": { "type": "string", "description": "Human-readable description of the problem.", "example": "Invalid report reference" }, "errorCode": { "type": "string", "description": "Machine-readable code, present for specific errors such as `INVALID_PERIOD_ORG`.", "example": "INVALID_PERIOD_ORG" } } }, "RunStatusConflict": { "type": "object", "description": "Returned when a download is requested before the run is Available.", "properties": { "status": { "type": "string", "description": "Current one-letter status code of the run: `S` Submitted, `U` Upload Started, `C` File Created, `E` Error, `T` Terminated, `X` Cancelled.", "example": "S", "enum": [ "S", "U", "C", "E", "T", "X", "" ] } } }, "ServiceError": { "type": "object", "description": "General error envelope used by the Revenue service for validation and unexpected errors.", "properties": { "message": { "type": "string", "description": "Description of the error.", "example": "An error occurred: Invalid pagination parameters: page=-1, size=20" }, "code": { "type": "string", "description": "Error indicator. Always `1` for errors.", "example": "1" } } }, "SpringError": { "type": "object", "description": "Standard error body returned when a request is rejected before it reaches the operation.", "properties": { "timestamp": { "type": "string", "description": "When the error occurred.", "example": "2026-10-09T07:15:02.123+00:00", "format": "date-time" }, "status": { "type": "integer", "description": "HTTP status code.", "example": 400 }, "error": { "type": "string", "description": "HTTP reason phrase.", "example": "Bad Request" } } }, "GatewayError": { "type": "object", "description": "Error returned by the Zuora One API gateway before the request reaches a Revenue service (authentication, authorization and rate limiting).", "properties": { "message": { "type": "string", "description": "Description of the gateway error.", "example": "Authentication error" } } }, "ReportFile": { "type": "object", "description": "A completed (Available) report file produced by a report run.", "properties": { "id": { "type": "integer", "description": "Submission identifier of the run that produced the file. Use it with `GET /reports/{report_id}` and the v2 signed-URL operation.", "example": 482391 }, "file_name": { "type": "string", "description": "Name of the generated file. Use it with `GET /reports/download/{filename}`.", "example": "WF_SUMMARY_482391.csv" }, "rep_name": { "type": "string", "description": "Name of the report definition that produced the file.", "example": "Revenue Waterfall Report" }, "category": { "type": "string", "description": "Report category.", "example": "Revenue", "nullable": true }, "rep_desc": { "type": "string", "description": "Report description.", "example": "Recognized and scheduled revenue by period for each revenue contract line", "nullable": true }, "layout_name": { "type": "string", "description": "Name of the layout that was run.", "example": "Monthly Close - Summary" }, "report_date": { "type": "string", "description": "Date and time the run was created, formatted `DD-MM-YYYY HH24:MI:SS`.", "example": "09-10-2026 07:15:02" }, "status": { "type": "string", "description": "Run status. These operations only return Available runs, so the value is `A` (or `Available` on some tenant database platforms).", "example": "A", "enum": [ "A", "Available" ] }, "org_id": { "type": "string", "description": "Organization security value of the run. Returned on some tenant database platforms only.", "example": "101", "nullable": true } } }, "ReportFileListResponse": { "type": "object", "description": "Success envelope for the report-file operations.", "properties": { "Status": { "type": "string", "description": "`Success` when the call completed.", "example": "Success" }, "Message": { "type": "string", "description": "Additional message. Empty on success.", "example": "" }, "Result": { "type": "array", "items": { "$ref": "#/components/schemas/ReportFile" }, "description": "Matching Available report files. An empty array means nothing matched." } } }, "RiaError": { "type": "object", "description": "Error envelope used by the Integration service. `Status` is `Error` (or, on a few operations, the error text itself), and `Message` or `Result` carries the detail.", "properties": { "Status": { "description": "`Error` for most failures. Some BI View operations put the error text (or, for the v1 column list, the columns) here.", "example": "Error" }, "Message": { "description": "Human-readable error detail. A string on most errors; an object such as `{\"Invalid_fields\": [...]}` on field validation errors.", "example": "Invalid date format 2026-09-22 for createddate" }, "Result": { "description": "Additional error detail or `null`. Some BI View operations return the message text or the list of supported views here." } } }, "SignedUrlResponse": { "type": "object", "description": "Signed download URL for a completed report.", "properties": { "success": { "type": "boolean", "description": "`true` when the URL was generated.", "example": true }, "signed_url": { "type": "string", "description": "HTTPS URL of the report file. Download it with a plain HTTP GET; it is valid for 30 minutes (1,800 seconds).", "example": "https://files.zuora.com/rev/1234567/reports/WF_SUMMARY_482391.csv?X-Amz-Expires=1800&X-Amz-Signature=9ac2...", "format": "uri" } } }, "SignedUrlError": { "type": "object", "description": "Returned when no signed URL can be generated.", "properties": { "success": { "type": "boolean", "description": "Always `false`.", "example": false }, "error": { "type": "string", "description": "Reason the URL could not be generated.", "example": "Report not found for Submission Id: 482391" } } }, "BiViewColumn": { "type": "object", "description": "One column of a BI View.", "properties": { "column_name": { "type": "string", "description": "Column name. Use it in the `Fields` list to select columns.", "example": "RC_ID" }, "data_type": { "type": "string", "description": "Database data type of the column.", "example": "NUMBER" }, "data_length": { "type": "integer", "description": "Maximum length of the column in bytes.", "example": 22 }, "data_precision": { "type": "integer", "description": "Numeric precision, when applicable.", "example": 38, "nullable": true }, "data_scale": { "type": "integer", "description": "Numeric scale, when applicable.", "example": 0, "nullable": true } } }, "BiViewFieldsRequest": { "type": "object", "description": "Optional body that selects which BI View columns to return. You can also send a plain JSON array of column names.", "properties": { "Fields": { "type": "array", "items": { "type": "string" }, "description": "Column names to return. Names are matched case-insensitively against the describe-columns output.", "example": [ "RC_ID", "RC_NUM", "UPDT_DT" ] } } }, "BiViewCount": { "type": "object", "description": "Row count of a BI View for a date range.", "properties": { "count": { "type": "integer", "description": "Number of rows in the view for the requested date range, limited to the organizations the caller can access.", "example": 25430 } } }, "BiViewCountV1": { "type": "object", "description": "Row count envelope returned by the v1 BI Views operation when `count=true`.", "properties": { "Status": { "type": "string", "description": "`Success` when the count was computed.", "example": "Success" }, "Result": { "allOf": [ { "$ref": "#/components/schemas/BiViewCount" } ], "description": "The count." } } }, "BiViewReportSubmitResponse": { "type": "object", "description": "Result of submitting a BI View as a background report.", "properties": { "success": { "type": "boolean", "description": "`true` when the report job was accepted.", "example": true }, "report_id": { "type": "integer", "description": "Submission identifier of the report job. Use it with `GET /api/integration/v1/reports/{report_id}` and `GET /api/integration/v2/reports/signedurl/{report_id}`.", "example": 482455 }, "message": { "type": "string", "description": "Reason the job was not accepted (present only when `success` is `false`).", "example": "Unable to submit" } } }, "BiViewTaskFilterParams": { "type": "object", "description": "Date filters of the BI View query.", "properties": { "fromDate": { "type": "string", "description": "Start of the query date range.", "example": "2026-09-01 00:00:00" }, "toDate": { "type": "string", "description": "End of the query date range.", "example": "2026-09-30 23:59:59" } } }, "BiViewTaskQueryConfig": { "type": "object", "description": "What the task is querying.", "properties": { "object_name": { "type": "string", "description": "BI View database object being read.", "example": "RPRO_BI3_RC_LNS_V" }, "filter_params": { "allOf": [ { "$ref": "#/components/schemas/BiViewTaskFilterParams" } ], "description": "Date range of the query." } } }, "BiViewTaskTime": { "type": "object", "description": "Timing information of a BI View task.", "properties": { "initated_time": { "type": "string", "description": "When the task started, ISO 8601 date and time. (The property name is spelled `initated_time`.)", "example": "2026-10-09T07:20:01.512000" }, "last_activity": { "type": "string", "description": "When the task last reported progress, ISO 8601 date and time.", "example": "2026-10-09T07:21:44.008000" }, "elapsed_time": { "type": "string", "description": "Time since the task last reported progress, formatted `H:MM:SS.ffffff`. A large value means the task may be stuck.", "example": "0:00:12.405000", "nullable": true } } }, "BiViewTask": { "type": "object", "description": "State of a background BI View extraction task. The task identifier is the `continuation-token` returned on page 1.", "properties": { "task_id": { "type": "string", "description": "Task identifier (same value as the `continuation-token`).", "example": "3f6c2d0a-8b1e-4f7a-9d2c-55e1a7b0c9f4" }, "status": { "type": "string", "description": "Task status. `ADDED-TO-QUEUE`, `META-DATA-SCANNED`, `SCANNING-PAGE-n`, `COMMITING-PAGE-n`, `MAX-REQUESTED-PAGE-REACHED`, `NO-RECORD-FOUND` and `END-OF-QUERY-DATA` are in-progress states; `COMPLETED`, `CANCELLED` and `FAILED` are final.", "example": "COMMITING-PAGE-3" }, "message": { "type": "string", "description": "Latest progress or error message.", "nullable": true }, "metric": { "type": "integer", "description": "Rows written by the latest step.", "example": 1000, "nullable": true }, "accumulate": { "type": "integer", "description": "Total rows written so far.", "example": 3000, "nullable": true }, "query_config": { "allOf": [ { "$ref": "#/components/schemas/BiViewTaskQueryConfig" } ], "description": "View and date range being queried." }, "activity_tracker": { "allOf": [ { "$ref": "#/components/schemas/BiViewTaskTime" } ], "description": "Timing information." } } }, "BiViewTaskQueues": { "type": "object", "description": "BI View tasks of the tenant grouped by state.", "properties": { "active": { "type": "array", "items": { "$ref": "#/components/schemas/BiViewTask" }, "description": "Tasks that are running and reported progress recently." }, "completed": { "type": "array", "items": { "$ref": "#/components/schemas/BiViewTask" }, "description": "Tasks that finished (`COMPLETED`, `CANCELLED` or `FAILED`)." }, "stale": { "type": "array", "items": { "$ref": "#/components/schemas/BiViewTask" }, "description": "Running tasks with no progress within the staleness threshold (240 seconds by default)." }, "draining": { "type": "array", "items": { "type": "string" }, "description": "Identifiers of tasks whose details have expired and are being removed." } } }, "JournalEntryListPage": { "type": "object", "description": "A page of journal entries.", "properties": { "pageNumber": { "type": "integer", "format": "int32", "description": "1-based number of the page returned.", "example": 1, "nullable": true }, "pageSize": { "type": "integer", "format": "int32", "description": "Maximum number of records per page (capped at 40).", "example": 20, "nullable": true }, "totalRecords": { "type": "integer", "format": "int64", "description": "Total number of records that match the query across all pages.", "example": 1, "nullable": true }, "result": { "type": "array", "items": { "$ref": "#/components/schemas/JournalEntryListItem" }, "description": "Records on this page.", "nullable": true } } }, "JournalEntryListItem": { "type": "object", "description": "Summary row for a journal entry in list and search results.", "properties": { "id": { "type": "integer", "format": "int64", "description": "Unique system-generated identifier of the journal entry (JE header ID).", "example": 10045, "nullable": true }, "name": { "type": "string", "description": "Name of the journal entry. Shown in the Zuora Revenue UI and in GL interfaces. Must be meaningful to approvers, for example `SEP-2026 Revenue Reclass`.", "example": "SEP-2026 Revenue Reclass", "nullable": true }, "description": { "type": "string", "description": "Free-text description of the journal entry's business purpose.", "example": "Reclass deferred revenue for contract RC-1001", "nullable": true }, "reversalStatus": { "type": "string", "description": "Approval status of the reversal of this entry, when a reversal was requested. Empty when the entry has not been reversed.", "example": "", "nullable": true }, "categoryCode": { "type": "string", "description": "Journal entry category code. Classifies why the entry is posted (for example an accrual, reclass or adjustment). Valid values are configured in your tenant's MANUAL_JOURNAL lookup; retrieve them from `categoryId` in GET /journal-entries/metadata.", "example": "RECLASS", "nullable": true }, "exRateType": { "type": "string", "description": "Exchange rate type used to convert transaction currency to functional and reporting currency (for example `User` or `Corporate`). Valid values come from `exchangeRates` in GET /journal-entries/metadata. (Filter and sort on this property using the name `exchangeRateType`.)", "example": "User", "nullable": true }, "periodId": { "type": "string", "description": "Name of the posting period, for example `SEP-2026` (in list results this property holds the period name, not the numeric ID; filters compare against the name).", "example": "SEP-2026", "nullable": true }, "status": { "type": "string", "description": "Journal entry status. One of `New`, `Draft`, `Validated`, `Approval Pending`, `Approved`, `Rejected`, `Approval Cancelled`, `Error`, `Approval Rule not Defined`.", "example": "New", "nullable": true }, "reversalPeriodId": { "type": "string", "description": "Name of the reversal period, for example `OCT-2026` (period name, not the numeric ID).", "example": "OCT-2026", "nullable": true }, "hashTotal": { "type": "number", "format": "double", "description": "Hash total of the entry: the sum of all line amounts. Useful as a control total when reconciling uploads.", "example": 3000, "nullable": true }, "sobName": { "type": "string", "description": "Name of the Set of Books. On create and update the service derives this from `sobId`; any value you send is overwritten.", "example": "US Primary SOB", "nullable": true }, "sobId": { "type": "integer", "format": "int64", "description": "Identifier of the Set of Books (SOB) the entry posts to. A Set of Books groups the ledger, functional currency and calendar used for accounting.", "example": 1, "nullable": true }, "functionalCurrency": { "type": "string", "description": "ISO 4217 currency code of the functional (ledger) currency of the Set of Books, for example `USD`.", "example": "USD", "nullable": true }, "createdBy": { "type": "string", "description": "User who created the record.", "example": "jane.doe@example.com", "nullable": true }, "createdDate": { "type": "string", "description": "Timestamp when the record was created (ISO 8601).", "example": "2026-09-28 10:21:04", "nullable": true }, "updatedBy": { "type": "string", "description": "User who last updated the record.", "example": "jane.doe@example.com", "nullable": true }, "updatedDate": { "type": "string", "description": "Timestamp when the record was last updated (ISO 8601).", "example": "2026-09-28 10:21:04", "nullable": true }, "approverName": { "type": "string", "description": "Name of the approver currently assigned to the entry by the approval rule. Read-only on most flows.", "nullable": true }, "bookId": { "type": "integer", "format": "int32", "description": "Identifier of the accounting book (for example the primary book or a secondary/parallel book) the entry belongs to.", "example": 1, "nullable": true }, "secAtrVal": { "type": "string", "description": "Organization (security attribute value) of the entry. Same meaning as `orgId`.", "example": "101", "nullable": true } } }, "JournalEntryUpdateResponse": { "type": "object", "description": "Result of an update.", "properties": { "id": { "type": "integer", "format": "int64", "description": "Unique system-generated identifier of the journal entry (JE header ID).", "example": 10045, "nullable": true }, "status": { "type": "string", "description": "Journal entry status. One of `New`, `Draft`, `Validated`, `Approval Pending`, `Approved`, `Rejected`, `Approval Cancelled`, `Error`, `Approval Rule not Defined`.", "example": "New", "nullable": true }, "waterfallStatus": { "type": "string", "description": "Status of revenue waterfall (schedule) generation for the entry. One of `NEW`, `IN PROGRESS`, `SUCCESS`, `ERROR`. For approved entries this reflects the final waterfall; otherwise the preview waterfall.", "example": "NEW", "nullable": true } } }, "CreateJournalEntryRequest": { "type": "object", "description": "JSON body for creating a journal entry with its lines in one call.", "required": [ "jeHeader", "lines" ], "properties": { "jeHeader": { "allOf": [ { "$ref": "#/components/schemas/JournalEntryHeaderInput" } ], "description": "Journal entry header." }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/JournalEntryLineInput" }, "description": "Journal entry lines. At least one line is required." } } }, "JournalEntryLineDataset": { "type": "object", "description": "A journal entry line returned by the copy-lines operation.", "properties": { "id": { "type": "integer", "format": "int64", "description": "Unique system-generated identifier of the journal entry line.", "example": 70001, "nullable": true }, "headerId": { "type": "integer", "format": "int64", "description": "Identifier of the journal entry (header) this record belongs to.", "example": 10045, "nullable": true }, "clientId": { "type": "integer", "format": "int32", "description": "Identifier of your Zuora Revenue client (tenant partition). Informational.", "example": 1, "nullable": true }, "orgId": { "type": "string", "description": "Organization (operating unit) identifier the entry belongs to, also called the security attribute value (`secAtrVal`). Valid values come from `orgId` in GET /journal-entries/metadata.", "example": "101", "nullable": true }, "createdBy": { "type": "string", "description": "User who created the record.", "example": "jane.doe@example.com", "nullable": true }, "createdDate": { "type": "string", "format": "date-time", "description": "Timestamp when the record was created (ISO 8601).", "example": "2026-09-28T10:21:04.000+00:00", "nullable": true }, "updatedBy": { "type": "string", "description": "User who last updated the record.", "example": "jane.doe@example.com", "nullable": true }, "updatedDate": { "type": "string", "format": "date-time", "description": "Timestamp when the record was last updated (ISO 8601).", "example": "2026-09-28T10:21:04.000+00:00", "nullable": true }, "bookId": { "type": "integer", "format": "int32", "description": "Identifier of the accounting book (for example the primary book or a secondary/parallel book) the entry belongs to.", "example": 1, "nullable": true }, "rcId": { "type": "integer", "format": "int64", "description": "Revenue contract (RC) identifier the line relates to.", "example": 1001, "nullable": true }, "rcLineId": { "type": "integer", "format": "int64", "description": "Revenue contract line identifier the line relates to.", "example": 50001, "nullable": true }, "currency": { "type": "string", "description": "ISO 4217 transaction currency of the line amount.", "example": "USD", "nullable": true }, "debit": { "type": "number", "format": "double", "description": "Debit amount in transaction currency.", "example": 1500, "nullable": true }, "credit": { "type": "number", "format": "double", "description": "Credit amount in transaction currency.", "nullable": true }, "exchangeRateDate": { "type": "string", "format": "date-time", "description": "Date the exchange rates apply to.", "example": "2026-09-30T00:00:00.000+00:00", "nullable": true }, "exchangeRate": { "type": "number", "format": "double", "description": "Functional exchange rate: converts transaction currency to functional currency.", "example": 1, "nullable": true }, "gexchangeRate": { "type": "number", "format": "double", "description": "Global (reporting) exchange rate: converts functional currency to the reporting currency.", "example": 1, "nullable": true }, "startDate": { "type": "string", "format": "date-time", "description": "Start date of the revenue recognition period for the line.", "example": "2026-09-01T00:00:00.000+00:00", "nullable": true }, "endDate": { "type": "string", "format": "date-time", "description": "End date of the revenue recognition period for the line.", "example": "2026-09-30T00:00:00.000+00:00", "nullable": true }, "reason": { "type": "string", "description": "Reason code explaining the adjustment.", "example": "RECLASS", "nullable": true }, "errorMessage": { "type": "string", "description": "Validation error recorded on the line by the service, if any.", "nullable": true }, "description": { "type": "string", "description": "Free-text description of the line.", "example": "Move deferred revenue to revenue", "nullable": true }, "comments": { "type": "string", "description": "Free-text comments on the line.", "nullable": true }, "accountType": { "type": "string", "description": "Revenue activity (account) type of the line, for example `Revenue`, `Contract Liability`, `Adjustment Revenue`. Valid values come from `accountTypes` in GET /journal-entries/metadata.", "example": "Contract Liability", "nullable": true }, "soLineId": { "type": "string", "description": "Sales order (document) line identifier the line relates to.", "example": "SO-50012-1", "nullable": true }, "soNum": { "type": "string", "description": "Sales order (document) number the line relates to.", "example": "SO-50012", "nullable": true }, "costOrVcType": { "type": "string", "description": "Indicates whether `typeName` is a cost type or a variable consideration type.", "nullable": true }, "jeSetNo": { "type": "integer", "format": "int64", "description": "Set number that groups lines into a balanced set. Debits and credits within the same set number must net to zero. Use 1, 2, 3 ... to post several independent balanced sets in one entry.", "example": 1, "nullable": true }, "unbillAccounting": { "type": "string", "description": "Unbilled accounting flag (`Y`/`N`). `Y` posts the line to unbilled (contract asset/unbilled receivable) accounts.", "example": "N", "nullable": true }, "accountCode": { "type": "string", "description": "General ledger account code (accounting segments joined by your configured delimiter), for example `1000-200-4000`.", "example": "1000-200-4000", "nullable": true }, "typeName": { "type": "string", "description": "Name of the cost type or variable consideration (VC) type when `accountType` is a cost or VC account.", "nullable": true }, "reference1": { "type": "string", "description": "Customer-defined reference field. Use for your own identifiers (for example a ticket number or source-system key). `reference1` is one of 15 reference fields; your tenant may assign it a custom label (see GET /journal-entries/configurations).", "nullable": true }, "reference2": { "type": "string", "description": "Customer-defined reference field. Use for your own identifiers (for example a ticket number or source-system key). `reference2` is one of 15 reference fields; your tenant may assign it a custom label (see GET /journal-entries/configurations).", "nullable": true }, "reference3": { "type": "string", "description": "Customer-defined reference field. Use for your own identifiers (for example a ticket number or source-system key). `reference3` is one of 15 reference fields; your tenant may assign it a custom label (see GET /journal-entries/configurations).", "nullable": true }, "reference4": { "type": "string", "description": "Customer-defined reference field. Use for your own identifiers (for example a ticket number or source-system key). `reference4` is one of 15 reference fields; your tenant may assign it a custom label (see GET /journal-entries/configurations).", "nullable": true }, "reference5": { "type": "string", "description": "Customer-defined reference field. Use for your own identifiers (for example a ticket number or source-system key). `reference5` is one of 15 reference fields; your tenant may assign it a custom label (see GET /journal-entries/configurations).", "nullable": true }, "reference6": { "type": "string", "description": "Customer-defined reference field. Use for your own identifiers (for example a ticket number or source-system key). `reference6` is one of 15 reference fields; your tenant may assign it a custom label (see GET /journal-entries/configurations).", "nullable": true }, "reference7": { "type": "string", "description": "Customer-defined reference field. Use for your own identifiers (for example a ticket number or source-system key). `reference7` is one of 15 reference fields; your tenant may assign it a custom label (see GET /journal-entries/configurations).", "nullable": true }, "reference8": { "type": "string", "description": "Customer-defined reference field. Use for your own identifiers (for example a ticket number or source-system key). `reference8` is one of 15 reference fields; your tenant may assign it a custom label (see GET /journal-entries/configurations).", "nullable": true }, "reference9": { "type": "string", "description": "Customer-defined reference field. Use for your own identifiers (for example a ticket number or source-system key). `reference9` is one of 15 reference fields; your tenant may assign it a custom label (see GET /journal-entries/configurations).", "nullable": true }, "reference10": { "type": "string", "description": "Customer-defined reference field. Use for your own identifiers (for example a ticket number or source-system key). `reference10` is one of 15 reference fields; your tenant may assign it a custom label (see GET /journal-entries/configurations).", "nullable": true }, "reference11": { "type": "string", "description": "Customer-defined reference field. Use for your own identifiers (for example a ticket number or source-system key). `reference11` is one of 15 reference fields; your tenant may assign it a custom label (see GET /journal-entries/configurations).", "nullable": true }, "reference12": { "type": "string", "description": "Customer-defined reference field. Use for your own identifiers (for example a ticket number or source-system key). `reference12` is one of 15 reference fields; your tenant may assign it a custom label (see GET /journal-entries/configurations).", "nullable": true }, "reference13": { "type": "string", "description": "Customer-defined reference field. Use for your own identifiers (for example a ticket number or source-system key). `reference13` is one of 15 reference fields; your tenant may assign it a custom label (see GET /journal-entries/configurations).", "nullable": true }, "reference14": { "type": "string", "description": "Customer-defined reference field. Use for your own identifiers (for example a ticket number or source-system key). `reference14` is one of 15 reference fields; your tenant may assign it a custom label (see GET /journal-entries/configurations).", "nullable": true }, "reference15": { "type": "string", "description": "Customer-defined reference field. Use for your own identifiers (for example a ticket number or source-system key). `reference15` is one of 15 reference fields; your tenant may assign it a custom label (see GET /journal-entries/configurations).", "nullable": true }, "creditAccountType": { "type": "string", "description": "Account type used for the credit side when a single line carries both sides.", "nullable": true }, "debitAccountType": { "type": "string", "description": "Account type used for the debit side when a single line carries both sides.", "nullable": true }, "createPeriodId": { "type": "string", "description": "Identifier of the period in which the record was created.", "example": "202609", "nullable": true } } }, "CopyJournalEntryRequest": { "type": "object", "description": "Optional overrides for the copied journal entry.", "properties": { "name": { "type": "string", "description": "Name for the copy. Defaults to `Copy of `.", "example": "OCT-2026 Revenue Reclass", "nullable": true }, "periodId": { "type": "integer", "format": "int32", "description": "Posting period for the copy. Defaults to the current open period.", "example": 202610, "nullable": true } } }, "JournalEntryResponse": { "type": "object", "description": "A journal entry with its header and, depending on the operation, a page of lines or schedules.", "properties": { "success": { "type": "boolean", "description": "`true` when the operation succeeded.", "example": true }, "id": { "type": "integer", "format": "int64", "description": "Unique system-generated identifier of the journal entry (JE header ID).", "example": 10045, "nullable": true }, "name": { "type": "string", "description": "Name of the journal entry. Shown in the Zuora Revenue UI and in GL interfaces. Must be meaningful to approvers, for example `SEP-2026 Revenue Reclass`.", "example": "SEP-2026 Revenue Reclass", "nullable": true }, "status": { "type": "string", "description": "Journal entry status. One of `New`, `Draft`, `Validated`, `Approval Pending`, `Approved`, `Rejected`, `Approval Cancelled`, `Error`, `Approval Rule not Defined`.", "example": "New", "nullable": true }, "description": { "type": "string", "description": "Free-text description of the journal entry's business purpose.", "example": "Reclass deferred revenue for contract RC-1001", "nullable": true }, "waterfallStatus": { "type": "string", "description": "Status of revenue waterfall (schedule) generation for the entry. One of `NEW`, `IN PROGRESS`, `SUCCESS`, `ERROR`. For approved entries this reflects the final waterfall; otherwise the preview waterfall.", "example": "NEW", "nullable": true }, "jeHeader": { "allOf": [ { "$ref": "#/components/schemas/JournalEntryHeader" } ], "description": "Full header. Returned by create, get and copy." }, "lines": { "allOf": [ { "$ref": "#/components/schemas/JournalEntryLinesPage" } ], "description": "Page of lines. Returned by GET /journal-entries/{jeId}/lines." }, "schedules": { "allOf": [ { "$ref": "#/components/schemas/JournalEntrySchedulesPage" } ], "description": "Page of schedules. Returned by GET /journal-entries/{jeId}/schedules." } } }, "UpdateJournalEntryRequest": { "type": "object", "description": "Partial update of a journal entry header. Send only the fields you want to change; omitted fields are left unchanged. `revRecType` and `approvalCurrency` cannot be changed after create.", "properties": { "name": { "type": "string", "description": "Name of the journal entry. Shown in the Zuora Revenue UI and in GL interfaces. Must be meaningful to approvers, for example `SEP-2026 Revenue Reclass`.", "example": "SEP-2026 Revenue Reclass v2", "nullable": true }, "description": { "type": "string", "description": "Free-text description of the journal entry's business purpose.", "example": "Updated description", "nullable": true }, "periodId": { "type": "integer", "format": "int64", "description": "Identifier of the accounting (posting) period the journal entry is posted to. The period must be open. Retrieve valid IDs from GET /journal-entries/metadata/periods or GET /journal-entries/current-period.", "example": 202609, "nullable": true }, "reversalPeriodId": { "type": "integer", "format": "int64", "description": "Identifier of the accounting period in which an automatic reversal of this entry is posted. Leave empty when the entry should not reverse.", "example": 202610, "nullable": true }, "categoryCode": { "type": "string", "description": "Journal entry category code. Classifies why the entry is posted (for example an accrual, reclass or adjustment). Valid values are configured in your tenant's MANUAL_JOURNAL lookup; retrieve them from `categoryId` in GET /journal-entries/metadata.", "example": "RECLASS", "nullable": true }, "exchangeRateType": { "type": "string", "description": "Exchange rate type used to convert transaction currency to functional and reporting currency (for example `User` or `Corporate`). Valid values come from `exchangeRates` in GET /journal-entries/metadata.", "example": "User", "nullable": true }, "sobName": { "type": "string", "description": "Name of the Set of Books. On create and update the service derives this from `sobId`; any value you send is overwritten.", "nullable": true }, "sobId": { "type": "integer", "format": "int64", "description": "Identifier of the Set of Books (SOB) the entry posts to. A Set of Books groups the ledger, functional currency and calendar used for accounting. When supplied it must match an existing Set of Books.", "example": 1, "nullable": true }, "functionalCurrency": { "type": "string", "description": "ISO 4217 currency code of the functional (ledger) currency of the Set of Books, for example `USD`.", "example": "USD", "nullable": true }, "accountMethod": { "type": "string", "description": "Accounting method used to post the entry. Valid values come from `accountingMethod` in GET /journal-entries/metadata.", "example": "Standard", "nullable": true }, "bookId": { "type": "integer", "format": "int64", "description": "Identifier of the accounting book (for example the primary book or a secondary/parallel book) the entry belongs to.", "example": 1, "nullable": true }, "orgId": { "type": "string", "description": "Organization (operating unit) identifier the entry belongs to, also called the security attribute value (`secAtrVal`). Valid values come from `orgId` in GET /journal-entries/metadata.", "example": "101", "nullable": true }, "glTransfer": { "type": "string", "description": "Whether the entry is transferred to the general ledger. Accepted values on input: `Yes` or `No` (the service reports `Yes` when not set).", "enum": [ "Yes", "No" ], "example": "Yes", "nullable": true }, "approverName": { "type": "string", "description": "Name of the approver currently assigned to the entry by the approval rule. Read-only on most flows.", "nullable": true } } }, "JournalEntryLine": { "type": "object", "description": "A journal entry line as returned by the service.", "properties": { "id": { "type": "integer", "format": "int64", "description": "Unique system-generated identifier of the journal entry line.", "example": 70001, "nullable": true }, "headerId": { "type": "integer", "format": "int64", "description": "Identifier of the journal entry (header) this record belongs to.", "example": 10045, "nullable": true }, "clientId": { "type": "integer", "format": "int32", "description": "Identifier of your Zuora Revenue client (tenant partition). Informational.", "example": 1, "nullable": true }, "orgId": { "type": "string", "description": "Organization (operating unit) identifier the entry belongs to, also called the security attribute value (`secAtrVal`). Valid values come from `orgId` in GET /journal-entries/metadata.", "example": "101", "nullable": true }, "createdBy": { "type": "string", "description": "User who created the record.", "example": "jane.doe@example.com", "nullable": true }, "createdDate": { "type": "string", "format": "date-time", "description": "Timestamp when the record was created (ISO 8601).", "example": "2026-09-28T10:21:04.000+00:00", "nullable": true }, "updatedBy": { "type": "string", "description": "User who last updated the record.", "example": "jane.doe@example.com", "nullable": true }, "updatedDate": { "type": "string", "format": "date-time", "description": "Timestamp when the record was last updated (ISO 8601).", "example": "2026-09-28T10:21:04.000+00:00", "nullable": true }, "bookId": { "type": "integer", "format": "int32", "description": "Identifier of the accounting book (for example the primary book or a secondary/parallel book) the entry belongs to.", "example": 1, "nullable": true }, "rcId": { "type": "integer", "format": "int64", "description": "Revenue contract (RC) identifier the line relates to.", "example": 1001, "nullable": true }, "rcLineId": { "type": "integer", "format": "int64", "description": "Revenue contract line identifier the line relates to.", "example": 50001, "nullable": true }, "currency": { "type": "string", "description": "ISO 4217 transaction currency of the line amount.", "example": "USD", "nullable": true }, "debit": { "type": "number", "format": "double", "description": "Debit amount in transaction currency.", "example": 1500, "nullable": true }, "credit": { "type": "number", "format": "double", "description": "Credit amount in transaction currency.", "nullable": true }, "exchangeRateDate": { "type": "string", "format": "date-time", "description": "Date the exchange rates apply to.", "example": "2026-09-30T00:00:00.000+00:00", "nullable": true }, "exchangeRate": { "type": "number", "format": "double", "description": "Functional exchange rate: converts transaction currency to functional currency.", "example": 1, "nullable": true }, "gexchangeRate": { "type": "number", "format": "double", "description": "Global (reporting) exchange rate: converts functional currency to the reporting currency.", "example": 1, "nullable": true }, "startDate": { "type": "string", "format": "date-time", "description": "Start date of the revenue recognition period for the line.", "example": "2026-09-01T00:00:00.000+00:00", "nullable": true }, "endDate": { "type": "string", "format": "date-time", "description": "End date of the revenue recognition period for the line.", "example": "2026-09-30T00:00:00.000+00:00", "nullable": true }, "reason": { "type": "string", "description": "Reason code explaining the adjustment.", "example": "RECLASS", "nullable": true }, "errorMessage": { "type": "string", "description": "Validation error recorded on the line by the service, if any.", "nullable": true }, "description": { "type": "string", "description": "Free-text description of the line.", "example": "Move deferred revenue to revenue", "nullable": true }, "comments": { "type": "string", "description": "Free-text comments on the line.", "nullable": true }, "accountType": { "type": "string", "description": "Revenue activity (account) type of the line, for example `Revenue`, `Contract Liability`, `Adjustment Revenue`. Valid values come from `accountTypes` in GET /journal-entries/metadata.", "example": "Contract Liability", "nullable": true }, "soLineId": { "type": "string", "description": "Sales order (document) line identifier the line relates to.", "example": "SO-50012-1", "nullable": true }, "soNum": { "type": "string", "description": "Sales order (document) number the line relates to.", "example": "SO-50012", "nullable": true }, "costOrVcType": { "type": "string", "description": "Indicates whether `typeName` is a cost type or a variable consideration type.", "nullable": true }, "jeSetNo": { "type": "integer", "format": "int64", "description": "Set number that groups lines into a balanced set. Debits and credits within the same set number must net to zero. Use 1, 2, 3 ... to post several independent balanced sets in one entry.", "example": 1, "nullable": true }, "unbillAccounting": { "type": "string", "description": "Unbilled accounting flag (`Y`/`N`). `Y` posts the line to unbilled (contract asset/unbilled receivable) accounts.", "example": "N", "nullable": true }, "accountCode": { "type": "string", "description": "General ledger account code (accounting segments joined by your configured delimiter), for example `1000-200-4000`.", "example": "1000-200-4000", "nullable": true }, "typeName": { "type": "string", "description": "Name of the cost type or variable consideration (VC) type when `accountType` is a cost or VC account.", "nullable": true }, "reference1": { "type": "string", "description": "Customer-defined reference field. Use for your own identifiers (for example a ticket number or source-system key). `reference1` is one of 15 reference fields; your tenant may assign it a custom label (see GET /journal-entries/configurations).", "nullable": true }, "reference2": { "type": "string", "description": "Customer-defined reference field. Use for your own identifiers (for example a ticket number or source-system key). `reference2` is one of 15 reference fields; your tenant may assign it a custom label (see GET /journal-entries/configurations).", "nullable": true }, "reference3": { "type": "string", "description": "Customer-defined reference field. Use for your own identifiers (for example a ticket number or source-system key). `reference3` is one of 15 reference fields; your tenant may assign it a custom label (see GET /journal-entries/configurations).", "nullable": true }, "reference4": { "type": "string", "description": "Customer-defined reference field. Use for your own identifiers (for example a ticket number or source-system key). `reference4` is one of 15 reference fields; your tenant may assign it a custom label (see GET /journal-entries/configurations).", "nullable": true }, "reference5": { "type": "string", "description": "Customer-defined reference field. Use for your own identifiers (for example a ticket number or source-system key). `reference5` is one of 15 reference fields; your tenant may assign it a custom label (see GET /journal-entries/configurations).", "nullable": true }, "reference6": { "type": "string", "description": "Customer-defined reference field. Use for your own identifiers (for example a ticket number or source-system key). `reference6` is one of 15 reference fields; your tenant may assign it a custom label (see GET /journal-entries/configurations).", "nullable": true }, "reference7": { "type": "string", "description": "Customer-defined reference field. Use for your own identifiers (for example a ticket number or source-system key). `reference7` is one of 15 reference fields; your tenant may assign it a custom label (see GET /journal-entries/configurations).", "nullable": true }, "reference8": { "type": "string", "description": "Customer-defined reference field. Use for your own identifiers (for example a ticket number or source-system key). `reference8` is one of 15 reference fields; your tenant may assign it a custom label (see GET /journal-entries/configurations).", "nullable": true }, "reference9": { "type": "string", "description": "Customer-defined reference field. Use for your own identifiers (for example a ticket number or source-system key). `reference9` is one of 15 reference fields; your tenant may assign it a custom label (see GET /journal-entries/configurations).", "nullable": true }, "reference10": { "type": "string", "description": "Customer-defined reference field. Use for your own identifiers (for example a ticket number or source-system key). `reference10` is one of 15 reference fields; your tenant may assign it a custom label (see GET /journal-entries/configurations).", "nullable": true }, "reference11": { "type": "string", "description": "Customer-defined reference field. Use for your own identifiers (for example a ticket number or source-system key). `reference11` is one of 15 reference fields; your tenant may assign it a custom label (see GET /journal-entries/configurations).", "nullable": true }, "reference12": { "type": "string", "description": "Customer-defined reference field. Use for your own identifiers (for example a ticket number or source-system key). `reference12` is one of 15 reference fields; your tenant may assign it a custom label (see GET /journal-entries/configurations).", "nullable": true }, "reference13": { "type": "string", "description": "Customer-defined reference field. Use for your own identifiers (for example a ticket number or source-system key). `reference13` is one of 15 reference fields; your tenant may assign it a custom label (see GET /journal-entries/configurations).", "nullable": true }, "reference14": { "type": "string", "description": "Customer-defined reference field. Use for your own identifiers (for example a ticket number or source-system key). `reference14` is one of 15 reference fields; your tenant may assign it a custom label (see GET /journal-entries/configurations).", "nullable": true }, "reference15": { "type": "string", "description": "Customer-defined reference field. Use for your own identifiers (for example a ticket number or source-system key). `reference15` is one of 15 reference fields; your tenant may assign it a custom label (see GET /journal-entries/configurations).", "nullable": true } } }, "JournalEntrySchedulesPage": { "type": "object", "description": "A page of revenue schedules generated by a journal entry.", "properties": { "pageNumber": { "type": "integer", "format": "int32", "description": "1-based number of the page returned.", "example": 1, "nullable": true }, "pageSize": { "type": "integer", "format": "int32", "description": "Maximum number of records per page (capped at 40).", "example": 20, "nullable": true }, "totalRecords": { "type": "integer", "format": "int64", "description": "Total number of records that match the query across all pages.", "example": 1, "nullable": true }, "result": { "type": "array", "items": { "$ref": "#/components/schemas/JournalEntrySchedule" }, "description": "Records on this page.", "nullable": true } } }, "JournalEntryLinesPage": { "type": "object", "description": "A page of journal entry lines.", "properties": { "pageNumber": { "type": "integer", "format": "int32", "description": "1-based number of the page returned.", "example": 1, "nullable": true }, "pageSize": { "type": "integer", "format": "int32", "description": "Maximum number of records per page (capped at 40).", "example": 20, "nullable": true }, "totalRecords": { "type": "integer", "format": "int64", "description": "Total number of records that match the query across all pages.", "example": 1, "nullable": true }, "result": { "type": "array", "items": { "$ref": "#/components/schemas/JournalEntryLine" }, "description": "Records on this page.", "nullable": true } } }, "CopyJournalEntryLinesRequest": { "type": "object", "description": "Lines to copy and the destination entry.", "required": [ "lineIds" ], "properties": { "targetJeId": { "type": "integer", "format": "int64", "description": "Journal entry that receives the copied lines. Defaults to the source entry (`jeId` in the path).", "example": 10046, "nullable": true }, "lineIds": { "type": "array", "items": { "type": "integer", "format": "int64" }, "description": "IDs of the lines to copy.", "example": [ 70001, 70002 ] } } }, "UpdateJournalEntryMultipartRequest": { "type": "object", "description": "Multipart form for a full-file update of a journal entry's lines from CSV.", "required": [ "lines" ], "properties": { "lines": { "type": "string", "format": "binary", "description": "CSV file containing the **complete** set of lines for the entry (at least one). Rows whose `ID` column matches an existing line are updated, other rows are inserted, and existing lines that are absent from the file are deleted. May include an optional header section." }, "jeHeader": { "allOf": [ { "$ref": "#/components/schemas/UpdateJournalEntryRequest" } ], "description": "Optional header changes as a JSON part. Must be omitted when the CSV contains a header section." } } }, "CreateJournalEntryMultipartRequest": { "type": "object", "description": "Multipart form for creating a journal entry from a CSV file.", "required": [ "lines" ], "properties": { "lines": { "type": "string", "format": "binary", "description": "CSV file (UTF-8). Either a **combined** file (header titles row, one header values row, a blank line, then line titles and line rows) or a **lines-only** file. Download the template from GET /journal-entries/template." }, "jeHeader": { "allOf": [ { "$ref": "#/components/schemas/JournalEntryHeaderInput" } ], "description": "Header as a JSON part (`Content-Type: application/json`). Required with a lines-only CSV; must be omitted when the CSV contains a header section." } } }, "JournalEntryHeader": { "type": "object", "description": "Full journal entry header as stored by Zuora Revenue.", "properties": { "id": { "type": "integer", "format": "int64", "description": "Unique system-generated identifier of the journal entry (JE header ID).", "example": 10045, "nullable": true }, "name": { "type": "string", "description": "Name of the journal entry. Shown in the Zuora Revenue UI and in GL interfaces. Must be meaningful to approvers, for example `SEP-2026 Revenue Reclass`.", "example": "SEP-2026 Revenue Reclass", "nullable": true }, "description": { "type": "string", "description": "Free-text description of the journal entry's business purpose.", "example": "Reclass deferred revenue for contract RC-1001", "nullable": true }, "categoryCode": { "type": "string", "description": "Journal entry category code. Classifies why the entry is posted (for example an accrual, reclass or adjustment). Valid values are configured in your tenant's MANUAL_JOURNAL lookup; retrieve them from `categoryId` in GET /journal-entries/metadata.", "example": "RECLASS", "nullable": true }, "exchangeRateType": { "type": "string", "description": "Exchange rate type used to convert transaction currency to functional and reporting currency (for example `User` or `Corporate`). Valid values come from `exchangeRates` in GET /journal-entries/metadata.", "example": "User", "nullable": true }, "sobId": { "type": "integer", "format": "int64", "description": "Identifier of the Set of Books (SOB) the entry posts to. A Set of Books groups the ledger, functional currency and calendar used for accounting.", "example": 1, "nullable": true }, "sobName": { "type": "string", "description": "Name of the Set of Books. On create and update the service derives this from `sobId`; any value you send is overwritten.", "example": "US Primary SOB", "nullable": true }, "functionalCurrency": { "type": "string", "description": "ISO 4217 currency code of the functional (ledger) currency of the Set of Books, for example `USD`.", "example": "USD", "nullable": true }, "periodId": { "type": "integer", "format": "int32", "description": "Identifier of the accounting (posting) period the journal entry is posted to. The period must be open. Retrieve valid IDs from GET /journal-entries/metadata/periods or GET /journal-entries/current-period.", "example": 202609, "nullable": true }, "reversalPeriodId": { "type": "integer", "format": "int32", "description": "Identifier of the accounting period in which an automatic reversal of this entry is posted. Leave empty when the entry should not reverse.", "example": 202610, "nullable": true }, "reversalStatus": { "type": "string", "description": "Approval status of the reversal of this entry, when a reversal was requested. Empty when the entry has not been reversed.", "example": "", "nullable": true }, "clientId": { "type": "integer", "format": "int32", "description": "Identifier of your Zuora Revenue client (tenant partition). Informational.", "example": 1, "nullable": true }, "orgId": { "type": "string", "description": "Organization (operating unit) identifier the entry belongs to, also called the security attribute value (`secAtrVal`). Valid values come from `orgId` in GET /journal-entries/metadata.", "example": "101", "nullable": true }, "createdBy": { "type": "string", "description": "User who created the record.", "example": "jane.doe@example.com", "nullable": true }, "createdDate": { "type": "string", "format": "date-time", "description": "Timestamp when the record was created (ISO 8601).", "example": "2026-09-28T10:21:04.000+00:00", "nullable": true }, "updatedBy": { "type": "string", "description": "User who last updated the record.", "example": "jane.doe@example.com", "nullable": true }, "updatedDate": { "type": "string", "format": "date-time", "description": "Timestamp when the record was last updated (ISO 8601).", "example": "2026-09-28T10:21:04.000+00:00", "nullable": true }, "bookId": { "type": "integer", "format": "int32", "description": "Identifier of the accounting book (for example the primary book or a secondary/parallel book) the entry belongs to.", "example": 1, "nullable": true }, "approverName": { "type": "string", "description": "Name of the approver currently assigned to the entry by the approval rule. Read-only on most flows.", "nullable": true }, "approvalRuleName": { "type": "string", "description": "Name of the approval rule that matched this entry.", "nullable": true }, "revRecType": { "type": "string", "description": "Revenue recognition type that drives the accounting method applied to the entry. Set on create only.", "example": "STANDARD", "nullable": true }, "accountMethod": { "type": "string", "description": "Accounting method used to post the entry. Valid values come from `accountingMethod` in GET /journal-entries/metadata.", "example": "Standard", "nullable": true }, "status": { "type": "string", "description": "Journal entry status. One of `New`, `Draft`, `Validated`, `Approval Pending`, `Approved`, `Rejected`, `Approval Cancelled`, `Error`, `Approval Rule not Defined`.", "example": "New", "nullable": true }, "approvalCurrency": { "type": "string", "description": "ISO 4217 currency used to evaluate approval rules (thresholds) for this entry. Optional; valid values come from `approvalCurrency` in GET /journal-entries/metadata.", "example": "USD", "nullable": true }, "periodDisplayValue": { "type": "string", "description": "Display name of the posting period, for example `SEP-2026`.", "example": "SEP-2026", "nullable": true }, "reversalDisplayValue": { "type": "string", "description": "Display name of the reversal period, for example `OCT-2026`.", "example": "OCT-2026", "nullable": true }, "waterfallStatus": { "type": "string", "description": "Status of revenue waterfall (schedule) generation for the entry. One of `NEW`, `IN PROGRESS`, `SUCCESS`, `ERROR`. For approved entries this reflects the final waterfall; otherwise the preview waterfall.", "example": "NEW", "nullable": true }, "errorCount": { "type": "integer", "format": "int32", "description": "Number of lines on the entry that currently have validation errors.", "example": 0, "nullable": true }, "errorMessages": { "type": "array", "items": { "type": "string" }, "description": "Distinct validation error messages found on the entry's lines.", "example": [], "nullable": true }, "jeLines": { "type": "array", "items": { "$ref": "#/components/schemas/JournalEntryLine" }, "description": "Lines of the entry, when included by the service. Use GET /journal-entries/{jeId}/lines for paginated access.", "nullable": true }, "glTransfer": { "type": "string", "description": "Whether the entry is transferred to the general ledger. Accepted values on input: `Yes` or `No` (the service reports `Yes` when not set).", "example": "Yes", "nullable": true }, "orgName": { "type": "string", "description": "Display name of the organization.", "example": "US Operations", "nullable": true }, "bookName": { "type": "string", "description": "Display name of the accounting book.", "example": "Primary Book", "nullable": true }, "processType": { "type": "string", "description": "Single-character code describing how the entry was created (for example from the UI or by upload). Informational.", "example": "M", "nullable": true }, "jeStatus": { "type": "string", "description": "Raw journal entry status as stored on the header. Same value set as `status`.", "example": "New", "nullable": true }, "jeWaterfallStatus": { "type": "string", "description": "Status of the final waterfall generated after approval (`NEW`, `IN PROGRESS`, `SUCCESS`, `ERROR`).", "example": "NEW", "nullable": true }, "jeTempWaterfallStatus": { "type": "string", "description": "Status of the preview (temporary) waterfall generated before approval (`NEW`, `IN PROGRESS`, `SUCCESS`, `ERROR`).", "example": "NEW", "nullable": true }, "indicators": { "type": "string", "description": "Internal flag string that stores header options such as GL transfer. Informational; do not parse.", "nullable": true } } }, "JournalEntrySchedule": { "type": "object", "description": "One revenue schedule (accounting entry by period) generated from a journal entry.", "properties": { "periodName": { "type": "string", "description": "Accounting period the schedule posts to, for example `SEP-2026`.", "example": "SEP-2026", "nullable": true }, "accountType": { "type": "string", "description": "Revenue activity (account) type of the line, for example `Revenue`, `Contract Liability`, `Adjustment Revenue`. Valid values come from `accountTypes` in GET /journal-entries/metadata.", "example": "Revenue", "nullable": true }, "acountCode": { "type": "string", "description": "General ledger account code of the schedule. (The property name is spelled `acountCode` in responses; filters accept `accountCode` or `acountCode`.)", "example": "1000-200-4000", "nullable": true }, "currencyCode": { "type": "string", "description": "Transaction currency of the schedule.", "example": "USD", "nullable": true }, "drAmount": { "type": "number", "format": "double", "description": "Debit amount in transaction currency.", "example": 1500, "nullable": true }, "crAmount": { "type": "number", "format": "double", "description": "Credit amount in transaction currency.", "example": 0, "nullable": true }, "funcDrAmount": { "type": "number", "format": "double", "description": "Debit amount in functional currency.", "example": 1500, "nullable": true }, "funcCrAmount": { "type": "number", "format": "double", "description": "Credit amount in functional currency.", "example": 0, "nullable": true }, "rcurrDrAmount": { "type": "number", "format": "double", "description": "Debit amount in reporting currency.", "example": 1500, "nullable": true }, "rcurrCrAmount": { "type": "number", "format": "double", "description": "Credit amount in reporting currency.", "example": 0, "nullable": true }, "schdRcId": { "type": "integer", "format": "int64", "description": "Revenue contract ID the schedule belongs to.", "example": 1001, "nullable": true }, "interfaceFlag": { "type": "string", "description": "Whether the schedule has been interfaced (transferred) to the GL (`Y`/`N`).", "example": "N", "nullable": true } } }, "ErrorReason": { "type": "object", "description": "One reason why the request failed.", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Machine-readable error code. See *Error codes* for the complete list.", "example": "INVALID_VALUE" }, "message": { "type": "string", "description": "Human-readable explanation of the failure. Safe to log; do not parse.", "example": "Unknown field 'foo'. Allowed fields: categoryCode, createdBy, ..." }, "field": { "type": "string", "description": "Name of the request field that caused the error, when applicable.", "example": "periodId", "nullable": true } } }, "ErrorResponse": { "type": "object", "description": "Standard error envelope returned by the Manual Journal Entry API.", "required": [ "success", "reasons" ], "properties": { "success": { "type": "boolean", "description": "Always `false` for errors.", "example": false }, "reasons": { "type": "array", "items": { "$ref": "#/components/schemas/ErrorReason" }, "description": "One or more reasons for the failure." } } }, "PlatformErrorResponse": { "type": "object", "description": "Error body returned when a request is rejected before it reaches journal entry processing (for example access checks).", "properties": { "timestamp": { "type": "string", "format": "date-time", "description": "Time the error occurred.", "example": "2026-10-07T10:15:30.123+00:00", "nullable": true }, "status": { "type": "integer", "format": "int32", "description": "HTTP status code.", "example": 403, "nullable": true }, "error": { "type": "string", "description": "HTTP reason phrase.", "example": "Forbidden", "nullable": true }, "message": { "type": "string", "description": "Explanation of the failure.", "example": "No message available", "nullable": true }, "path": { "type": "string", "description": "Request path.", "example": "/journal-entries", "nullable": true } } }, "HealthCheckResponse": { "type": "object", "description": "Result of the availability check.", "required": [ "success", "status" ], "properties": { "success": { "type": "boolean", "description": "`true` when the service is available.", "example": true }, "status": { "type": "string", "description": "`UP` when the journal entry processing service responded. (When it does not respond the API returns HTTP 502.)", "enum": [ "UP" ], "example": "UP" }, "target": { "type": "string", "description": "Identifier of the component that was checked.", "example": "mje-backend", "nullable": true }, "details": { "type": "string", "description": "Optional detail, for example a failure summary.", "nullable": true } } }, "JournalEntryHeaderInput": { "type": "object", "description": "Journal entry header supplied when creating an entry. Required fields: `name`, `orgId`, `bookId`, `periodId`, `categoryCode`, `sobId`, `functionalCurrency`, `exchangeRateType`, `accountMethod`, `glTransfer`.", "required": [ "name", "orgId", "bookId", "periodId", "categoryCode", "sobId", "functionalCurrency", "exchangeRateType", "accountMethod", "glTransfer" ], "properties": { "name": { "type": "string", "description": "Name of the journal entry. Shown in the Zuora Revenue UI and in GL interfaces. Must be meaningful to approvers, for example `SEP-2026 Revenue Reclass`. **Required on create.**", "example": "SEP-2026 Revenue Reclass" }, "bookId": { "type": "integer", "format": "int64", "description": "Identifier of the accounting book (for example the primary book or a secondary/parallel book) the entry belongs to. **Required on create.**", "example": 1 }, "periodId": { "type": "integer", "format": "int64", "description": "Identifier of the accounting (posting) period the journal entry is posted to. The period must be open. Retrieve valid IDs from GET /journal-entries/metadata/periods or GET /journal-entries/current-period. **Required on create.**", "example": 202609 }, "description": { "type": "string", "description": "Free-text description of the journal entry's business purpose.", "example": "Reclass deferred revenue for contract RC-1001", "nullable": true }, "categoryCode": { "type": "string", "description": "Journal entry category code. Classifies why the entry is posted (for example an accrual, reclass or adjustment). Valid values are configured in your tenant's MANUAL_JOURNAL lookup; retrieve them from `categoryId` in GET /journal-entries/metadata. **Required on create.**", "example": "RECLASS" }, "exchangeRateType": { "type": "string", "description": "Exchange rate type used to convert transaction currency to functional and reporting currency (for example `User` or `Corporate`). Valid values come from `exchangeRates` in GET /journal-entries/metadata. **Required on create.**", "example": "User" }, "orgId": { "type": "string", "description": "Organization (operating unit) identifier the entry belongs to, also called the security attribute value (`secAtrVal`). Valid values come from `orgId` in GET /journal-entries/metadata. **Required on create.**", "example": "101" }, "sobName": { "type": "string", "description": "Name of the Set of Books. On create and update the service derives this from `sobId`; any value you send is overwritten.", "example": "US Primary SOB", "nullable": true }, "sobId": { "type": "integer", "format": "int64", "description": "Identifier of the Set of Books (SOB) the entry posts to. A Set of Books groups the ledger, functional currency and calendar used for accounting. **Required on create.** Must match an existing Set of Books, otherwise the request fails with `INVALID_VALUE` on `sobId`.", "example": 1 }, "functionalCurrency": { "type": "string", "description": "ISO 4217 currency code of the functional (ledger) currency of the Set of Books, for example `USD`. **Required on create.**", "example": "USD" }, "reversalPeriodId": { "type": "integer", "format": "int64", "description": "Identifier of the accounting period in which an automatic reversal of this entry is posted. Leave empty when the entry should not reverse.", "example": 202610, "nullable": true }, "approvalCurrency": { "type": "string", "description": "ISO 4217 currency used to evaluate approval rules (thresholds) for this entry. Optional; valid values come from `approvalCurrency` in GET /journal-entries/metadata.", "example": "USD", "nullable": true }, "glTransfer": { "type": "string", "description": "Whether the entry is transferred to the general ledger. Accepted values on input: `Yes` or `No` (the service reports `Yes` when not set). **Required on create.**", "enum": [ "Yes", "No" ], "example": "Yes" }, "revRecType": { "type": "string", "description": "Revenue recognition type that drives the accounting method applied to the entry. Set on create only.", "example": "STANDARD", "nullable": true }, "accountMethod": { "type": "string", "description": "Accounting method used to post the entry. Valid values come from `accountingMethod` in GET /journal-entries/metadata. **Required on create.**", "example": "Standard" } } }, "JournalEntryLineInput": { "type": "object", "description": "One journal entry line supplied on create or full-file update. Required on every line: `jeSetNo`, `accountType`, `accountCode`, `currency`, `exchangeRateDate`, `exchangeRate` (> 0), `gexchangeRate` (> 0) and at least one of `drAmount` / `crAmount`.", "required": [ "jeSetNo", "accountType", "accountCode", "currency", "exchangeRateDate", "exchangeRate", "gexchangeRate" ], "properties": { "id": { "type": "integer", "format": "int64", "description": "Existing line ID. Leave empty for new lines. On a full-file CSV update, lines with an `id` that matches an existing line are updated; lines without an `id` are inserted.", "nullable": true }, "jeSetNo": { "type": "integer", "format": "int64", "description": "Set number that groups lines into a balanced set. Debits and credits within the same set number must net to zero. Use 1, 2, 3 ... to post several independent balanced sets in one entry. **Required.**", "example": 1 }, "accountCode": { "type": "string", "description": "General ledger account code (accounting segments joined by your configured delimiter), for example `1000-200-4000`. **Required.**", "example": "1000-200-4000" }, "drAmount": { "type": "number", "description": "Debit amount in transaction currency. Enter zero or a positive amount (negative values are rejected in CSV uploads). Provide either `drAmount` or `crAmount` (or both) on every line.", "example": 1500, "nullable": true }, "crAmount": { "type": "number", "description": "Credit amount in transaction currency. Enter zero or a positive amount (negative values are rejected in CSV uploads). Provide either `drAmount` or `crAmount` (or both) on every line.", "nullable": true }, "currency": { "type": "string", "description": "ISO 4217 transaction currency of the line amount. **Required.**", "example": "USD" }, "accountType": { "type": "string", "description": "Revenue activity (account) type of the line, for example `Revenue`, `Contract Liability`, `Adjustment Revenue`. Valid values come from `accountTypes` in GET /journal-entries/metadata. **Required.**", "example": "Contract Liability" }, "startDate": { "type": "string", "description": "Start date of the revenue recognition period for the line. Accepted formats: `yyyy-MM-dd`, `yyyy-MMM-dd`, `dd-MMM-yyyy`, `MM/dd/yyyy`.", "example": "2026-09-01", "nullable": true }, "endDate": { "type": "string", "description": "End date of the revenue recognition period for the line. Must be on or after `startDate`.", "example": "2026-09-30", "nullable": true }, "reason": { "type": "string", "description": "Reason code explaining the adjustment.", "example": "RECLASS", "nullable": true }, "description": { "type": "string", "description": "Free-text description of the line.", "example": "Move deferred revenue to revenue", "nullable": true }, "exchangeRate": { "type": "number", "description": "Functional exchange rate: converts transaction currency to functional currency. Must be greater than 0. Use `1` when the currencies are the same. **Required.**", "example": 1 }, "gexchangeRate": { "type": "number", "description": "Global (reporting) exchange rate: converts functional currency to the reporting currency. Must be greater than 0. **Required.**", "example": 1 }, "exchangeRateDate": { "type": "string", "description": "Date the exchange rates apply to. Accepted formats: `yyyy-MM-dd`, `yyyy-MMM-dd`, `dd-MMM-yyyy`, `MM/dd/yyyy`. **Required.**", "example": "2026-09-30" }, "soNum": { "type": "string", "description": "Sales order (document) number the line relates to.", "example": "SO-50012", "nullable": true }, "soLineId": { "type": "string", "description": "Sales order (document) line identifier the line relates to.", "example": "SO-50012-1", "nullable": true }, "rcId": { "type": "integer", "format": "int64", "description": "Revenue contract (RC) identifier the line relates to.", "example": 1001, "nullable": true }, "rcLineId": { "type": "integer", "format": "int64", "description": "Revenue contract line identifier the line relates to.", "example": 50001, "nullable": true }, "debitAccountType": { "type": "string", "description": "Account type used for the debit side when a single line carries both sides.", "nullable": true }, "creditAccountType": { "type": "string", "description": "Account type used for the credit side when a single line carries both sides.", "nullable": true }, "unbillAccounting": { "type": "string", "description": "Unbilled accounting flag (`Y`/`N`). `Y` posts the line to unbilled (contract asset/unbilled receivable) accounts.", "enum": [ "Y", "N" ], "example": "N", "nullable": true }, "typeName": { "type": "string", "description": "Name of the cost type or variable consideration (VC) type when `accountType` is a cost or VC account.", "nullable": true }, "costOrVcType": { "type": "string", "description": "Indicates whether `typeName` is a cost type or a variable consideration type.", "nullable": true }, "comments": { "type": "string", "description": "Free-text comments on the line.", "nullable": true }, "reference1": { "type": "string", "description": "Customer-defined reference field. Use for your own identifiers (for example a ticket number or source-system key). `reference1` is one of 15 reference fields; your tenant may assign it a custom label (see GET /journal-entries/configurations).", "nullable": true }, "reference2": { "type": "string", "description": "Customer-defined reference field. Use for your own identifiers (for example a ticket number or source-system key). `reference2` is one of 15 reference fields; your tenant may assign it a custom label (see GET /journal-entries/configurations).", "nullable": true }, "reference3": { "type": "string", "description": "Customer-defined reference field. Use for your own identifiers (for example a ticket number or source-system key). `reference3` is one of 15 reference fields; your tenant may assign it a custom label (see GET /journal-entries/configurations).", "nullable": true }, "reference4": { "type": "string", "description": "Customer-defined reference field. Use for your own identifiers (for example a ticket number or source-system key). `reference4` is one of 15 reference fields; your tenant may assign it a custom label (see GET /journal-entries/configurations).", "nullable": true }, "reference5": { "type": "string", "description": "Customer-defined reference field. Use for your own identifiers (for example a ticket number or source-system key). `reference5` is one of 15 reference fields; your tenant may assign it a custom label (see GET /journal-entries/configurations).", "nullable": true }, "reference6": { "type": "string", "description": "Customer-defined reference field. Use for your own identifiers (for example a ticket number or source-system key). `reference6` is one of 15 reference fields; your tenant may assign it a custom label (see GET /journal-entries/configurations).", "nullable": true }, "reference7": { "type": "string", "description": "Customer-defined reference field. Use for your own identifiers (for example a ticket number or source-system key). `reference7` is one of 15 reference fields; your tenant may assign it a custom label (see GET /journal-entries/configurations).", "nullable": true }, "reference8": { "type": "string", "description": "Customer-defined reference field. Use for your own identifiers (for example a ticket number or source-system key). `reference8` is one of 15 reference fields; your tenant may assign it a custom label (see GET /journal-entries/configurations).", "nullable": true }, "reference9": { "type": "string", "description": "Customer-defined reference field. Use for your own identifiers (for example a ticket number or source-system key). `reference9` is one of 15 reference fields; your tenant may assign it a custom label (see GET /journal-entries/configurations).", "nullable": true }, "reference10": { "type": "string", "description": "Customer-defined reference field. Use for your own identifiers (for example a ticket number or source-system key). `reference10` is one of 15 reference fields; your tenant may assign it a custom label (see GET /journal-entries/configurations).", "nullable": true }, "reference11": { "type": "string", "description": "Customer-defined reference field. Use for your own identifiers (for example a ticket number or source-system key). `reference11` is one of 15 reference fields; your tenant may assign it a custom label (see GET /journal-entries/configurations).", "nullable": true }, "reference12": { "type": "string", "description": "Customer-defined reference field. Use for your own identifiers (for example a ticket number or source-system key). `reference12` is one of 15 reference fields; your tenant may assign it a custom label (see GET /journal-entries/configurations).", "nullable": true }, "reference13": { "type": "string", "description": "Customer-defined reference field. Use for your own identifiers (for example a ticket number or source-system key). `reference13` is one of 15 reference fields; your tenant may assign it a custom label (see GET /journal-entries/configurations).", "nullable": true }, "reference14": { "type": "string", "description": "Customer-defined reference field. Use for your own identifiers (for example a ticket number or source-system key). `reference14` is one of 15 reference fields; your tenant may assign it a custom label (see GET /journal-entries/configurations).", "nullable": true }, "reference15": { "type": "string", "description": "Customer-defined reference field. Use for your own identifiers (for example a ticket number or source-system key). `reference15` is one of 15 reference fields; your tenant may assign it a custom label (see GET /journal-entries/configurations).", "nullable": true } } }, "WaterfallEntriesPage": { "type": "object", "description": "A page of revenue waterfall entries.", "properties": { "pageNumber": { "type": "integer", "format": "int32", "description": "1-based number of the page returned.", "example": 1, "nullable": true }, "pageSize": { "type": "integer", "format": "int32", "description": "Maximum number of records per page (capped at 40).", "example": 20, "nullable": true }, "totalRecords": { "type": "integer", "format": "int64", "description": "Total number of records that match the query across all pages.", "example": 1, "nullable": true }, "result": { "type": "array", "items": { "$ref": "#/components/schemas/WaterfallEntry" }, "description": "Records on this page.", "nullable": true } } }, "QueryFilter": { "type": "object", "description": "One filter condition in a request body (POST /query and export endpoints).", "required": [ "fieldName", "operator" ], "properties": { "fieldName": { "type": "string", "description": "Field to filter on. See the allowed field list of the endpoint.", "example": "status" }, "operator": { "type": "string", "description": "Comparison operator. Use `IN` / `NOT IN` for text values (values are quoted automatically). `LIKE` accepts `%` wildcards.", "enum": [ "IN", "NOT IN", "=", "<>", "<", "<=", ">", ">=", "LIKE", "NOT LIKE", "IS NULL", "IS NOT NULL" ], "example": "IN" }, "values": { "type": "array", "items": { "type": "string" }, "description": "Values to compare against. Supply one value for scalar operators and one or more for `IN` / `NOT IN`. Must contain at least one element for every operator.", "example": [ "New", "Validated" ], "nullable": true } } }, "QueryOrder": { "type": "object", "description": "Sort order in a request body.", "required": [ "fieldName", "orderBy" ], "properties": { "fieldName": { "type": "string", "description": "Field to sort by.", "example": "createdDate" }, "orderBy": { "type": "string", "description": "Sort direction.", "enum": [ "ASC", "DESC" ], "example": "DESC" } } }, "QueryRequest": { "type": "object", "description": "Filter, sort and paging criteria sent in a request body.", "properties": { "pageNumber": { "type": "integer", "format": "int32", "description": "1-based page number. Defaults to 1.", "example": 1, "nullable": true }, "pageSize": { "type": "integer", "format": "int32", "description": "Records per page. Defaults to 20; values above 40 are reduced to 40. Not applied by export endpoints, which return all rows.", "example": 20, "nullable": true }, "filters": { "type": "array", "items": { "$ref": "#/components/schemas/QueryFilter" }, "description": "Filter conditions, combined with AND.", "nullable": true }, "ordering": { "allOf": [ { "$ref": "#/components/schemas/QueryOrder" } ], "description": "Single sort order." } } }, "WaterfallEntry": { "type": "object", "description": "One row of the revenue waterfall produced by a journal entry: the amount scheduled to each period for a line.", "properties": { "jeSetNo": { "type": "string", "description": "Set number that groups lines into a balanced set. Debits and credits within the same set number must net to zero. Use 1, 2, 3 ... to post several independent balanced sets in one entry.", "example": "1", "nullable": true }, "soNumber": { "type": "string", "description": "Sales order (document) number the line relates to.", "example": "SO-50012", "nullable": true }, "soLineId": { "type": "string", "description": "Sales order (document) line identifier the line relates to.", "example": "SO-50012-1", "nullable": true }, "accountCode": { "type": "string", "description": "General ledger account code (accounting segments joined by your configured delimiter), for example `1000-200-4000`.", "example": "1000-200-4000", "nullable": true }, "jeAmount": { "type": "number", "format": "double", "description": "Journal entry amount of the line being spread.", "example": 1500, "nullable": true }, "startDate": { "type": "string", "format": "date-time", "description": "Recognition start date.", "example": "2026-09-01T00:00:00.000+00:00", "nullable": true }, "endDate": { "type": "string", "format": "date-time", "description": "Recognition end date.", "example": "2026-11-30T00:00:00.000+00:00", "nullable": true }, "accountType": { "type": "string", "description": "Revenue activity (account) type of the line, for example `Revenue`, `Contract Liability`, `Adjustment Revenue`. Valid values come from `accountTypes` in GET /journal-entries/metadata.", "example": "Revenue", "nullable": true }, "entries": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Amount per period, keyed by period name (for example `SEP-2026`). Values are returned as strings.", "example": { "SEP-2026": "500.00", "OCT-2026": "500.00", "NOV-2026": "500.00" }, "nullable": true } } }, "WaterfallStatusResponse": { "type": "object", "description": "Waterfall generation status of a journal entry.", "properties": { "id": { "type": "integer", "format": "int64", "description": "Unique system-generated identifier of the journal entry (JE header ID).", "example": 10045, "nullable": true }, "waterfallStatus": { "type": "string", "description": "Status of revenue waterfall (schedule) generation for the entry. One of `NEW`, `IN PROGRESS`, `SUCCESS`, `ERROR`. For approved entries this reflects the final waterfall; otherwise the preview waterfall.", "enum": [ "NEW", "IN PROGRESS", "SUCCESS", "ERROR" ], "example": "SUCCESS", "nullable": true } } }, "ValidationStatusResponse": { "type": "object", "description": "Validation status of a journal entry.", "properties": { "id": { "type": "integer", "format": "int64", "description": "Unique system-generated identifier of the journal entry (JE header ID).", "example": 10045, "nullable": true }, "validationStatus": { "type": "string", "description": "Progress of line validation. One of `New`, `Validation In Progress`, `Validated`, `Error`.", "example": "Validated", "nullable": true } } }, "StatusRequest": { "type": "object", "description": "Request body for workflow actions (approve, reject, recall, reverse, bulk delete) and submit.", "properties": { "jeIds": { "type": "array", "items": { "type": "integer", "format": "int64" }, "description": "IDs of the journal entries to act on. **Required** for approve, reject, recall, reverse and bulk-delete. Reverse accepts exactly one ID. Ignored by submit (the ID comes from the path).", "example": [ 10045, 10046 ], "nullable": true }, "comment": { "type": "string", "description": "Comment recorded in the audit trail with the action.", "example": "Approved for September close", "nullable": true }, "bookId": { "type": "integer", "format": "int32", "description": "Identifier of the accounting book (for example the primary book or a secondary/parallel book) the entry belongs to. Optional.", "example": 1, "nullable": true }, "reversalPeriod": { "type": "integer", "format": "int32", "description": "Period ID in which the reversal is posted. **Required for reverse**; ignored by other actions.", "example": 202610, "nullable": true } } }, "BulkActionItem": { "type": "object", "description": "Outcome for one journal entry in a workflow action.", "properties": { "id": { "type": "string", "description": "Journal entry ID, when reported by the service. Workflow actions currently identify the entry inside `message`.", "example": "10045", "nullable": true }, "success": { "type": "boolean", "description": "`true` when the action succeeded for this entry.", "example": true }, "code": { "type": "string", "description": "`BUSINESS_RULE_VIOLATION` when the action was refused for this entry; omitted on success.", "nullable": true }, "message": { "type": "string", "description": "Result message for the entry.", "example": "Journal entry 10045 approved successfully", "nullable": true } } }, "BulkActionResponse": { "type": "object", "description": "Outcome of a workflow action. Returned with HTTP 200 when every entry has the same outcome and HTTP 207 when some entries succeeded and others failed.", "properties": { "success": { "type": "boolean", "description": "`true` only when the action succeeded for every entry.", "example": true }, "status": { "type": "string", "description": "Journal entry status after the action as reported by the service (for example `Approved` after approve, `Rejected` after reject, `Approval Pending` after submit); for reverse, the reversal status. May be omitted (for example bulk delete).", "example": "Approved", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/BulkActionItem" }, "description": "Per-entry outcomes.", "nullable": true } } }, "PrivilegesRequest": { "type": "object", "description": "Entries to evaluate privileges for.", "required": [ "jeIds" ], "properties": { "jeIds": { "type": "array", "items": { "type": "integer", "format": "int64" }, "description": "Journal entry IDs to evaluate. Privileges are returned for the combined selection.", "example": [ 10045 ] }, "bookId": { "type": "integer", "format": "int32", "description": "Identifier of the accounting book (for example the primary book or a secondary/parallel book) the entry belongs to.", "example": 1, "nullable": true } } }, "Privileges": { "type": "object", "description": "Which actions the caller may currently perform on the selected entries, considering entry status, approval rules, soft freeze and the caller's role.", "properties": { "submitAllowed": { "type": "boolean", "description": "Caller can submit the entries for approval.", "example": true, "nullable": true }, "approveAllowed": { "type": "boolean", "description": "Caller can approve the entries.", "example": false, "nullable": true }, "rejectAllowed": { "type": "boolean", "description": "Caller can reject the entries.", "example": false, "nullable": true }, "recallAllowed": { "type": "boolean", "description": "Caller can recall the entries from approval.", "example": false, "nullable": true }, "deleteAllowed": { "type": "boolean", "description": "Caller can delete the entries.", "example": true, "nullable": true }, "updateAllowed": { "type": "boolean", "description": "Caller can edit the entries.", "example": true, "nullable": true }, "revertAllowed": { "type": "boolean", "description": "Caller can reverse the entries.", "example": false, "nullable": true } } }, "AuditEvent": { "type": "object", "description": "One audit-trail event for a journal entry.", "properties": { "id": { "type": "integer", "format": "int64", "description": "Audit event ID.", "example": 900001, "nullable": true }, "action": { "type": "string", "description": "Action recorded. One of `SAVE`, `UPDATE`, `SUBMIT`, `DELETE`, `APPROVE`, `REJECT`, `RECALL`.", "example": "SUBMIT", "nullable": true }, "headerId": { "type": "integer", "format": "int64", "description": "Identifier of the journal entry (header) this record belongs to.", "example": 10045, "nullable": true }, "lineId": { "type": "integer", "format": "int64", "description": "Line ID when the event concerns a single line.", "nullable": true }, "comments": { "type": "string", "description": "Comment entered with the action.", "example": "Ready for review", "nullable": true }, "bookId": { "type": "integer", "format": "int32", "description": "Identifier of the accounting book (for example the primary book or a secondary/parallel book) the entry belongs to.", "example": 1, "nullable": true }, "clientId": { "type": "integer", "format": "int32", "description": "Identifier of your Zuora Revenue client (tenant partition). Informational.", "example": 1, "nullable": true }, "createdPeriodId": { "type": "integer", "format": "int32", "description": "Period ID that was open when the event was recorded.", "example": 202609, "nullable": true }, "createdBy": { "type": "string", "description": "User who performed the action.", "example": "jane.doe@example.com", "nullable": true }, "createdDate": { "type": "string", "description": "When the action was performed.", "example": "2026-09-28 11:02:44", "nullable": true }, "updatedBy": { "type": "string", "description": "User who last updated the record.", "example": "jane.doe@example.com", "nullable": true }, "updatedDate": { "type": "string", "description": "Timestamp when the record was last updated (ISO 8601).", "example": "2026-09-28 11:02:44", "nullable": true }, "secAtrValue": { "type": "string", "description": "Organization (security attribute value) of the entry.", "example": "101", "nullable": true } } }, "MetadataOption": { "type": "object", "description": "An ID/name option.", "properties": { "id": { "type": "integer", "format": "int32", "description": "Option identifier (for example a period ID, book ID or org ID).", "example": 202609, "nullable": true }, "name": { "type": "string", "description": "Display name.", "example": "SEP-2026", "nullable": true } } }, "MetadataKeyValue": { "type": "object", "description": "A code/display-value option.", "properties": { "key": { "type": "string", "description": "Code to send in requests.", "example": "RECLASS", "nullable": true }, "value": { "type": "string", "description": "Display value.", "example": "Reclassification", "nullable": true } } }, "Metadata": { "type": "object", "description": "Lists of valid values used to build journal entries. GET /metadata returns tenant-wide lists; GET /metadata/periods returns the period lists for a book and organization.", "properties": { "postingPeriod": { "type": "array", "items": { "$ref": "#/components/schemas/MetadataOption" }, "description": "Open periods an entry can be posted to (`id` is the `periodId`).", "nullable": true }, "reversalPeriod": { "type": "array", "items": { "$ref": "#/components/schemas/MetadataOption" }, "description": "Periods that can be used as `reversalPeriodId`.", "nullable": true }, "createDate": { "type": "string", "description": "Current date in the service time zone.", "example": "2026-10-07", "nullable": true }, "bookId": { "type": "array", "items": { "$ref": "#/components/schemas/MetadataOption" }, "description": "Accounting books available to the caller.", "nullable": true }, "categoryId": { "type": "array", "items": { "$ref": "#/components/schemas/MetadataKeyValue" }, "description": "Valid `categoryCode` values.", "nullable": true }, "exchangeRates": { "type": "array", "items": { "$ref": "#/components/schemas/MetadataKeyValue" }, "description": "Valid `exchangeRateType` values.", "nullable": true }, "approvalCurrency": { "type": "array", "items": { "type": "string" }, "description": "Valid `approvalCurrency` values.", "example": [ "USD", "EUR" ], "nullable": true }, "sobName": { "type": "array", "items": { "type": "string" }, "description": "Set of Books names.", "example": [ "US Primary SOB" ], "nullable": true }, "orgId": { "type": "array", "items": { "$ref": "#/components/schemas/MetadataOption" }, "description": "Organizations available to the caller.", "nullable": true }, "functionalCurrency": { "type": "array", "items": { "type": "string" }, "description": "Functional currencies.", "example": [ "USD" ], "nullable": true }, "glTransfer": { "type": "array", "items": { "type": "string" }, "description": "Valid `glTransfer` values.", "example": [ "YES", "NO" ], "nullable": true }, "accountingMethod": { "type": "array", "items": { "$ref": "#/components/schemas/MetadataKeyValue" }, "description": "Valid `accountMethod` values.", "nullable": true }, "accountTypes": { "type": "array", "items": { "$ref": "#/components/schemas/MetadataKeyValue" }, "description": "Valid line `accountType` values.", "nullable": true }, "accountingSegments": { "type": "array", "items": { "$ref": "#/components/schemas/MetadataKeyValue" }, "description": "Accounting segment definitions used to build `accountCode`.", "nullable": true }, "vcTypes": { "type": "array", "items": { "$ref": "#/components/schemas/MetadataKeyValue" }, "description": "Variable consideration types (for `typeName` when the account type is a VC account).", "nullable": true }, "costTypes": { "type": "array", "items": { "$ref": "#/components/schemas/MetadataKeyValue" }, "description": "Cost types (for `typeName` when the account type is a cost account).", "nullable": true } } }, "ConfigurationField": { "type": "object", "description": "One configurable journal entry field.", "properties": { "code": { "type": "string", "description": "Field code.", "example": "REFERENCE1", "nullable": true }, "value": { "type": "string", "description": "Label configured for the field in your tenant.", "example": "Ticket Number", "nullable": true }, "sequence": { "type": "integer", "format": "int32", "description": "Display order.", "example": 29, "nullable": true } } }, "Configurations": { "type": "object", "description": "Tenant-specific field configuration (for example custom labels for reference fields).", "properties": { "fields": { "type": "array", "items": { "$ref": "#/components/schemas/ConfigurationField" }, "description": "Configured fields.", "nullable": true } } }, "CurrentPeriod": { "type": "object", "description": "The current open accounting period.", "properties": { "periodId": { "type": "integer", "format": "int32", "description": "Period ID to use as `periodId`.", "example": 202610, "nullable": true }, "periodDisplayValue": { "type": "string", "description": "Period display name.", "example": "OCT-2026", "nullable": true } } }, "SummaryValue": { "type": "object", "description": "Debit/credit totals of a journal entry for one currency type.", "properties": { "currencyType": { "type": "string", "description": "Which currency the totals are in: transaction, functional or reporting.", "example": "Transaction", "nullable": true }, "currency": { "type": "string", "description": "ISO 4217 currency code.", "example": "USD", "nullable": true }, "drAmt": { "type": "string", "description": "Total debits (formatted string).", "example": "1500.00", "nullable": true }, "crAmt": { "type": "string", "description": "Total credits (formatted string).", "example": "1500.00", "nullable": true }, "netAmt": { "type": "string", "description": "Debits minus credits. `0.00` for a balanced entry.", "example": "0.00", "nullable": true } } }, "SoftFreeze": { "type": "object", "description": "Soft-freeze state for a book and organization. While a soft freeze is applied (typically during period close), journal entry changes are restricted.", "properties": { "bookId": { "type": "integer", "format": "int32", "description": "Identifier of the accounting book (for example the primary book or a secondary/parallel book) the entry belongs to.", "example": 1, "nullable": true }, "secAtrVal": { "type": "string", "description": "Organization (security attribute value).", "example": "101", "nullable": true }, "softFreezeApplied": { "type": "boolean", "description": "`true` when a soft freeze is in effect.", "example": false, "nullable": true } } }, "UserRole": { "type": "object", "description": "The caller's level of access to manual journal entries.", "properties": { "role": { "type": "string", "description": "`FULL_ACCESS` (create, edit and act on entries), `READ_ONLY` (view only) or `NONE`.", "enum": [ "FULL_ACCESS", "READ_ONLY", "NONE" ], "example": "FULL_ACCESS", "nullable": true } } }, "DescribeColumn": { "type": "object", "description": "Description of one column of a journal entry object.", "properties": { "name": { "type": "string", "description": "Column name. For `jeHead` and `rcSchedule` this is the API property name; for `jeLine` it is the CSV template column code.", "example": "DR_SEGMENTS", "nullable": true }, "label": { "type": "string", "description": "Display label (tenant overrides applied for configurable line fields).", "example": "Account Code", "nullable": true }, "dataType": { "type": "string", "description": "Data type: `string`, `number`, `date` or `id`.", "enum": [ "string", "number", "date", "id" ], "example": "string", "nullable": true }, "sequence": { "type": "integer", "format": "int32", "description": "Display/template order.", "example": 3, "nullable": true } } }, "DescribeObject": { "type": "object", "description": "Column list of one object.", "properties": { "columns": { "type": "array", "items": { "$ref": "#/components/schemas/DescribeColumn" }, "description": "Columns in display order.", "nullable": true } } }, "DescribeResponse": { "type": "object", "description": "Column catalog of the journal entry objects.", "properties": { "objects": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/DescribeObject" }, "description": "Map keyed by object name: `jeHead` (header), `jeLine` (line) and `rcSchedule` (schedule).", "nullable": true } } }, "Attachment": { "type": "object", "description": "A note or file attached to a journal entry.", "properties": { "id": { "type": "integer", "format": "int32", "description": "Attachment ID.", "example": 501, "nullable": true }, "fileName": { "type": "string", "description": "Original file name.", "example": "support.xlsx", "nullable": true }, "comments": { "type": "string", "description": "Note entered with the attachment.", "example": "Supporting calculation", "nullable": true }, "addLink": { "type": "string", "description": "Optional URL stored with the attachment (for example a link to a document system).", "example": "https://example.com/docs/123", "nullable": true }, "jeId": { "type": "integer", "format": "int32", "description": "Identifier of the journal entry (header) this record belongs to.", "example": 10045, "nullable": true }, "bookId": { "type": "integer", "format": "int32", "description": "Identifier of the accounting book (for example the primary book or a secondary/parallel book) the entry belongs to.", "example": 1, "nullable": true }, "contentType": { "type": "string", "description": "MIME type of the file.", "example": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", "nullable": true }, "fileSize": { "type": "integer", "format": "int64", "description": "File size in bytes.", "example": 18432, "nullable": true }, "body": { "type": "string", "format": "byte", "description": "File content (Base64). Normally empty in list responses; use the download endpoint.", "nullable": true }, "crtdBy": { "type": "string", "description": "User who uploaded the attachment.", "example": "jane.doe@example.com", "nullable": true }, "crtdDt": { "type": "string", "description": "Upload time (`yyyy-MM-ddTHH:mm:ss`).", "example": "2026-09-28T11:05:00", "nullable": true } } }, "AttachmentUploadRequest": { "type": "object", "description": "Multipart form for uploading an attachment.", "properties": { "file": { "type": "string", "format": "binary", "description": "File to attach (up to 100 MB).", "nullable": true } } }, "AttachmentUploadResponse": { "type": "object", "description": "Result of an attachment upload.", "properties": { "status": { "type": "string", "description": "`success` or `failure`.", "enum": [ "success", "failure" ], "example": "success", "nullable": true }, "message": { "type": "string", "description": "Result message.", "example": "Notes/Attachments are successfully uploaded", "nullable": true } } }, "AttachmentDownloadUrl": { "type": "object", "description": "Short-lived presigned URL for downloading the attachment.", "properties": { "url": { "type": "string", "format": "uri", "description": "Presigned HTTPS URL. Download with a plain GET without the Authorization header. The URL expires after a short time; request a new one if it has expired.", "example": "https://zr-attachments.s3.amazonaws.com/...&X-Amz-Signature=...", "nullable": true } } }, "RcRedirection": { "type": "object", "description": "Revenue contract lookup result.", "properties": { "rcId": { "type": "integer", "format": "int32", "description": "Revenue contract ID that contains the given RC, sales order or line.", "example": 1001, "nullable": true }, "retCode": { "type": "string", "description": "Return code from the lookup. `0` (or empty) indicates success.", "example": "0", "nullable": true }, "errMsg": { "type": "string", "description": "Error message when the lookup failed.", "nullable": true } } }, "MjeGatewayError": { "type": "object", "description": "Error body produced by the Zuora API gateway (authentication and rate limiting). The exact body is set by the gateway.", "properties": { "message": { "type": "string", "description": "Explanation of the failure.", "example": "Authentication error" } } }, "ManualActionResponse": { "type": "object", "description": "Result of a manual action.", "required": [ "success", "processId" ], "properties": { "success": { "type": "boolean", "description": "`true` when the action completed. `false` when the revenue engine rejected it under a business rule; see `message`." }, "processId": { "type": "string", "description": "Unique ID generated for this request. Quote it when you contact Zuora Global Support." }, "message": { "type": "string", "description": "Result message from the revenue engine. May be empty on success." }, "changeIds": { "type": "string", "description": "Comma-separated IDs of records changed by the action, when the action reports them. Omitted otherwise." } } }, "HoldRecord": { "type": "object", "description": "A hold record created by the apply-hold action.", "properties": { "id": { "type": "integer", "format": "int64", "description": "ID of the applied-hold record." }, "rcId": { "type": "integer", "format": "int64", "description": "Revenue contract ID." }, "lineId": { "type": "integer", "format": "int64", "description": "Line the hold was applied to. `0` when the hold is not line-level." }, "rcPobId": { "type": "integer", "format": "int64", "description": "POB the hold was applied to. `0` when the hold is not POB-level." }, "revHoldId": { "type": "integer", "format": "int64", "description": "Hold definition ID (the `holdId` from the path)." }, "bookId": { "type": "integer", "format": "int64", "description": "Revenue book." }, "comments": { "type": "string", "description": "Hold comment." } } }, "ApplyHoldResponse": { "allOf": [ { "$ref": "#/components/schemas/ManualActionResponse" }, { "type": "object", "properties": { "holdRecords": { "type": "array", "items": { "$ref": "#/components/schemas/HoldRecord" }, "description": "Hold records created by the action. Omitted when none were created." } } } ] }, "RcLineAdjustmentRecord": { "type": "object", "description": "Line price adjustment created by applying variable consideration.", "properties": { "id": { "type": "integer", "format": "int64", "description": "Line price adjustment ID. Pass it as `rcLinePriceAdjustmentId` to expire the variable consideration." }, "lineId": { "type": "integer", "format": "int64", "description": "Revenue contract line ID." }, "rcId": { "type": "integer", "format": "int64", "description": "Revenue contract ID." }, "bookId": { "type": "integer", "format": "int64", "description": "Revenue book." }, "vcTypeId": { "type": "integer", "format": "int64", "description": "Variable consideration type ID." } } }, "ApplyVcResponse": { "allOf": [ { "$ref": "#/components/schemas/ManualActionResponse" }, { "type": "object", "properties": { "rcLineAdjustmentRecords": { "type": "array", "items": { "$ref": "#/components/schemas/RcLineAdjustmentRecord" }, "description": "Price adjustments created. Omitted when none were created (for example on a dry run)." }, "previewData": { "type": "string", "description": "Preview of the adjustment returned on a dry run. Omitted when the engine returns none." } } } ] }, "VcType": { "type": "object", "description": "A variable consideration type that can be applied to the line.", "properties": { "id": { "type": "integer", "format": "int32", "description": "Variable consideration type ID. Pass it as `vcTypeId` to apply variable consideration." }, "value": { "type": "string", "description": "Variable consideration type name." } } }, "RcErrorReason": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Error code. `ValidationError`, `InvalidRequest`, and `NotFound` come from request checks. Upper-case codes such as `FAILED_PRECONDITION`, `ABORTED`, or `UNAVAILABLE` come from the revenue engine. `SystemError` is an unexpected failure." }, "message": { "type": "string", "description": "Human-readable description of the problem." } } }, "ClientErrorResponse": { "type": "object", "description": "Error returned for 4xx responses.", "required": [ "success", "reasons" ], "properties": { "success": { "type": "boolean", "description": "Always `false`." }, "processId": { "type": "string", "description": "Unique ID generated for this request." }, "requestId": { "type": "string", "description": "Unique ID of the failed request. Quote it when you contact Zuora Global Support." }, "reasons": { "type": "array", "items": { "$ref": "#/components/schemas/RcErrorReason" }, "description": "One entry per problem." } } }, "ServerErrorResponse": { "type": "object", "description": "Error returned for 5xx responses.", "required": [ "reasons" ], "properties": { "reasons": { "type": "array", "items": { "$ref": "#/components/schemas/RcErrorReason" } } } }, "OpenCloseRcRequest": { "type": "object", "description": "Body for opening or closing a contract. Send `{}` to use the current contract version.", "properties": { "objectVersion": { "type": "integer", "format": "int64", "description": "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 } } }, "UnfreezeRcRequest": { "type": "object", "required": [ "action" ], "properties": { "action": { "type": "string", "description": "Unfreeze action to perform. Use `UNFREEZE`.", "example": "UNFREEZE" }, "changeModDate": { "type": "string", "description": "Whether to update the contract modification date as part of the unfreeze.", "enum": [ "Y", "N" ], "default": "Y" }, "objectVersion": { "type": "integer", "format": "int64", "description": "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 } } }, "ApplyHoldRcRequest": { "type": "object", "properties": { "comments": { "type": "string", "description": "Comment stored with the hold.", "default": "" }, "objectVersion": { "type": "integer", "format": "int64", "description": "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 } } }, "HoldLine": { "type": "object", "description": "Item to put on hold. Supply the identifier that matches the hold level of the endpoint.", "properties": { "lineId": { "type": "integer", "format": "int64", "description": "Revenue contract line ID. Required for line-level holds." }, "rcPobId": { "type": "integer", "format": "int64", "description": "POB ID. Required for POB-level holds." }, "chargeNumber": { "type": "string", "description": "Zuora Billing charge number. Required for charge-level holds." }, "holdComments": { "type": "string", "description": "Comment for this item.", "default": "" } } }, "ApplyHoldItemsRequest": { "type": "object", "required": [ "lines" ], "properties": { "comments": { "type": "string", "description": "Comment stored with the hold.", "default": "" }, "lines": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/HoldLine" }, "description": "Items to put on hold." }, "objectVersion": { "type": "integer", "format": "int64", "description": "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 } } }, "ReleaseHoldRcRequest": { "type": "object", "properties": { "comments": { "type": "string", "description": "Release comment.", "default": "" }, "reason": { "type": "string", "description": "Release reason.", "default": "" }, "objectVersion": { "type": "integer", "format": "int64", "description": "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 } } }, "ReleaseHoldItem": { "type": "object", "description": "Item to release. Supply the identifier that matches the hold level of the endpoint.", "properties": { "lineId": { "type": "integer", "format": "int64", "description": "Revenue contract line ID. Required for line-level releases." }, "rcPobId": { "type": "integer", "format": "int64", "description": "POB ID. Required for POB-level releases." }, "chargeNumber": { "type": "string", "description": "Zuora Billing charge number. Required for charge-level releases." }, "releaseComments": { "type": "string", "description": "Release comment for this item.", "default": "" }, "releaseReason": { "type": "string", "description": "Release reason for this item.", "default": "" } } }, "ReleaseHoldItemsRequest": { "type": "object", "required": [ "items" ], "properties": { "comments": { "type": "string", "description": "Release comment.", "default": "" }, "reason": { "type": "string", "description": "Release reason.", "default": "" }, "items": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/ReleaseHoldItem" }, "description": "Items to release. Note that this field is `items`, while apply-hold uses `lines`." }, "objectVersion": { "type": "integer", "format": "int64", "description": "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 } } }, "DeferReleaseRevenueRcRequest": { "type": "object", "required": [ "comments" ], "properties": { "comments": { "type": "string", "description": "Reason for the action, recorded in the audit history.", "minLength": 1 }, "startDate": { "type": "string", "description": "Start of the date window the action applies to (`yyyy-MM-dd`).", "format": "date" }, "endDate": { "type": "string", "description": "End of the date window the action applies to (`yyyy-MM-dd`).", "format": "date" }, "releaseAmount": { "type": "number", "format": "double", "description": "Amount to release. Used by release actions for a partial release." }, "releasePercentage": { "type": "number", "format": "double", "description": "Percentage to release. Used by release actions for a partial release." }, "contProsType": { "type": "string", "description": "Contingency processing type code configured in your tenant.", "default": "" }, "objectVersion": { "type": "integer", "format": "int64", "description": "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 }, "rcPobIds": { "type": "array", "items": { "type": "integer", "format": "int64" }, "description": "Limit the action to these POBs. Omit to act on the whole contract." } } }, "DeferReleaseRevenuePobRequest": { "type": "object", "required": [ "comments" ], "properties": { "comments": { "type": "string", "description": "Reason for the action, recorded in the audit history.", "minLength": 1 }, "startDate": { "type": "string", "description": "Start of the date window the action applies to (`yyyy-MM-dd`).", "format": "date" }, "endDate": { "type": "string", "description": "End of the date window the action applies to (`yyyy-MM-dd`).", "format": "date" }, "releaseAmount": { "type": "number", "format": "double", "description": "Amount to release. Used by release actions for a partial release." }, "releasePercentage": { "type": "number", "format": "double", "description": "Percentage to release. Used by release actions for a partial release." }, "contProsType": { "type": "string", "description": "Contingency processing type code configured in your tenant.", "default": "" }, "objectVersion": { "type": "integer", "format": "int64", "description": "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 } } }, "DeferReleaseCostRequest": { "type": "object", "required": [ "lineId", "costTypeId", "comments" ], "properties": { "lineId": { "type": "integer", "format": "int64", "description": "Revenue contract line that carries the cost." }, "costTypeId": { "type": "integer", "format": "int64", "description": "Cost type ID configured in your tenant (for example commissions)." }, "comments": { "type": "string", "description": "Reason for the action, recorded in the audit history.", "minLength": 1 }, "releaseAmount": { "type": "number", "format": "double", "description": "Amount of cost to release." }, "releasePercentage": { "type": "number", "format": "double", "description": "Percentage of cost to release." }, "releaseQuantity": { "type": "integer", "format": "int32", "description": "Quantity of cost to release." }, "ruleStartDate": { "type": "string", "description": "Start date of the cost amortization rule (`yyyy-MM-dd`).", "default": "" }, "ruleEndDate": { "type": "string", "description": "End date of the cost amortization rule (`yyyy-MM-dd`).", "default": "" }, "objectVersion": { "type": "integer", "format": "int64", "description": "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 } } }, "AllocateActionRequest": { "type": "object", "required": [ "action" ], "properties": { "action": { "type": "string", "description": "Allocation action. `REALLOCATE` re-runs the allocation of the transaction price across the contract's POBs. `ALLOCATION_ELIGIBLE` marks the contract as eligible for allocation. Values are case-sensitive.", "enum": [ "REALLOCATE", "ALLOCATION_ELIGIBLE" ] }, "objectVersion": { "type": "integer", "format": "int64", "description": "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 } } }, "SwitchAllocationRequest": { "type": "object", "description": "Send `{}` to use the current version.", "properties": { "objectVersion": { "type": "integer", "format": "int64", "description": "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 } } }, "EditLineRequest": { "type": "object", "description": "Only the attributes you send are changed. Omitted attributes keep their value.", "required": [ "comments" ], "properties": { "comments": { "type": "string", "description": "Reason for the edit, recorded in the audit history.", "minLength": 1 }, "objectVersion": { "type": "integer", "format": "int64", "description": "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 }, "atr1": { "type": "string", "description": "Custom text attribute 1." }, "atr2": { "type": "string", "description": "Custom text attribute 2." }, "atr3": { "type": "string", "description": "Custom text attribute 3." }, "atr4": { "type": "string", "description": "Custom text attribute 4." }, "atr5": { "type": "string", "description": "Custom text attribute 5." }, "atr6": { "type": "string", "description": "Custom text attribute 6." }, "atr7": { "type": "string", "description": "Custom text attribute 7." }, "atr8": { "type": "string", "description": "Custom text attribute 8." }, "atr9": { "type": "string", "description": "Custom text attribute 9." }, "atr10": { "type": "string", "description": "Custom text attribute 10." }, "atr11": { "type": "string", "description": "Custom text attribute 11." }, "atr12": { "type": "string", "description": "Custom text attribute 12." }, "atr13": { "type": "string", "description": "Custom text attribute 13." }, "atr14": { "type": "string", "description": "Custom text attribute 14." }, "atr15": { "type": "string", "description": "Custom text attribute 15." }, "atr16": { "type": "string", "description": "Custom text attribute 16." }, "atr17": { "type": "string", "description": "Custom text attribute 17." }, "atr18": { "type": "string", "description": "Custom text attribute 18." }, "atr19": { "type": "string", "description": "Custom text attribute 19." }, "atr20": { "type": "string", "description": "Custom text attribute 20." }, "atr21": { "type": "string", "description": "Custom text attribute 21." }, "atr22": { "type": "string", "description": "Custom text attribute 22." }, "atr23": { "type": "string", "description": "Custom text attribute 23." }, "atr24": { "type": "string", "description": "Custom text attribute 24." }, "atr25": { "type": "string", "description": "Custom text attribute 25." }, "atr26": { "type": "string", "description": "Custom text attribute 26." }, "atr27": { "type": "string", "description": "Custom text attribute 27." }, "atr28": { "type": "string", "description": "Custom text attribute 28." }, "atr29": { "type": "string", "description": "Custom text attribute 29." }, "atr30": { "type": "string", "description": "Custom text attribute 30." }, "atr31": { "type": "string", "description": "Custom text attribute 31." }, "atr32": { "type": "string", "description": "Custom text attribute 32." }, "atr33": { "type": "string", "description": "Custom text attribute 33." }, "atr34": { "type": "string", "description": "Custom text attribute 34." }, "atr35": { "type": "string", "description": "Custom text attribute 35." }, "atr36": { "type": "string", "description": "Custom text attribute 36." }, "atr37": { "type": "string", "description": "Custom text attribute 37." }, "atr38": { "type": "string", "description": "Custom text attribute 38." }, "atr39": { "type": "string", "description": "Custom text attribute 39." }, "atr40": { "type": "string", "description": "Custom text attribute 40." }, "atr41": { "type": "string", "description": "Custom text attribute 41." }, "atr42": { "type": "string", "description": "Custom text attribute 42." }, "atr43": { "type": "string", "description": "Custom text attribute 43." }, "atr44": { "type": "string", "description": "Custom text attribute 44." }, "atr45": { "type": "string", "description": "Custom text attribute 45." }, "atr46": { "type": "string", "description": "Custom text attribute 46." }, "atr47": { "type": "string", "description": "Custom text attribute 47." }, "atr48": { "type": "string", "description": "Custom text attribute 48." }, "atr49": { "type": "string", "description": "Custom text attribute 49." }, "atr50": { "type": "string", "description": "Custom text attribute 50." }, "atr51": { "type": "string", "description": "Custom text attribute 51." }, "atr52": { "type": "string", "description": "Custom text attribute 52." }, "atr53": { "type": "string", "description": "Custom text attribute 53." }, "atr54": { "type": "string", "description": "Custom text attribute 54." }, "atr55": { "type": "string", "description": "Custom text attribute 55." }, "atr56": { "type": "string", "description": "Custom text attribute 56." }, "atr57": { "type": "string", "description": "Custom text attribute 57." }, "atr58": { "type": "string", "description": "Custom text attribute 58." }, "atr59": { "type": "string", "description": "Custom text attribute 59." }, "atr60": { "type": "string", "description": "Custom text attribute 60." }, "num1": { "type": "number", "format": "double", "description": "Custom number attribute 1." }, "num2": { "type": "number", "format": "double", "description": "Custom number attribute 2." }, "num3": { "type": "number", "format": "double", "description": "Custom number attribute 3." }, "num4": { "type": "number", "format": "double", "description": "Custom number attribute 4." }, "num5": { "type": "number", "format": "double", "description": "Custom number attribute 5." }, "num6": { "type": "number", "format": "double", "description": "Custom number attribute 6." }, "num7": { "type": "number", "format": "double", "description": "Custom number attribute 7." }, "num8": { "type": "number", "format": "double", "description": "Custom number attribute 8." }, "num9": { "type": "number", "format": "double", "description": "Custom number attribute 9." }, "num10": { "type": "number", "format": "double", "description": "Custom number attribute 10." }, "num11": { "type": "number", "format": "double", "description": "Custom number attribute 11." }, "num12": { "type": "number", "format": "double", "description": "Custom number attribute 12." }, "num13": { "type": "number", "format": "double", "description": "Custom number attribute 13." }, "num14": { "type": "number", "format": "double", "description": "Custom number attribute 14." }, "num15": { "type": "number", "format": "double", "description": "Custom number attribute 15." }, "date1": { "type": "string", "description": "Custom date attribute 1 (`yyyy-MM-dd`).", "format": "date" }, "date2": { "type": "string", "description": "Custom date attribute 2 (`yyyy-MM-dd`).", "format": "date" }, "date3": { "type": "string", "description": "Custom date attribute 3 (`yyyy-MM-dd`).", "format": "date" }, "date4": { "type": "string", "description": "Custom date attribute 4 (`yyyy-MM-dd`).", "format": "date" }, "date5": { "type": "string", "description": "Custom date attribute 5 (`yyyy-MM-dd`).", "format": "date" } } }, "EditPobItem": { "type": "object", "required": [ "id", "name", "pobTemplateId", "pobVersion", "expiryDate", "leadLineId", "comments" ], "properties": { "id": { "type": "integer", "format": "int64", "description": "POB ID to edit." }, "name": { "type": "string", "description": "POB name." }, "pobTemplateId": { "type": "integer", "format": "int64", "description": "POB template ID that defines the recognition rules." }, "pobVersion": { "type": "integer", "format": "int64", "description": "Version of the POB template." }, "expiryDate": { "type": "string", "description": "POB expiry date (`yyyy-MM-dd`).", "example": "2026-12-31" }, "leadLineId": { "type": "integer", "format": "int64", "description": "Line that acts as the lead line of the POB." }, "comments": { "type": "string", "description": "Reason for the edit. Can be empty but must be present." } } }, "EditPobsRequest": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/EditPobItem" }, "description": "POBs to edit." }, "objectVersion": { "type": "integer", "format": "int32", "description": "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 } } }, "EditPobRequest": { "type": "object", "required": [ "name", "pobTemplateId", "pobVersion", "expiryDate", "leadLineId", "comments" ], "properties": { "name": { "type": "string", "description": "POB name." }, "pobTemplateId": { "type": "integer", "format": "int64", "description": "POB template ID that defines the recognition rules." }, "pobVersion": { "type": "integer", "format": "int64", "description": "Version of the POB template." }, "expiryDate": { "type": "string", "description": "POB expiry date (`yyyy-MM-dd`).", "example": "2026-12-31" }, "leadLineId": { "type": "integer", "format": "int64", "description": "Line that acts as the lead line of the POB." }, "comments": { "type": "string", "description": "Reason for the edit. Can be empty but must be present." }, "objectVersion": { "type": "integer", "format": "int32", "description": "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 } } }, "CopyLineRequest": { "type": "object", "description": "Values you omit are copied from the source line.", "required": [ "objectVersion", "docLineId", "pobName", "pobTemplateId" ], "properties": { "objectVersion": { "type": "integer", "format": "int64", "description": "Current version of the revenue contract. Required for this action.", "example": 5 }, "docLineId": { "type": "string", "description": "Source document line ID to copy." }, "pobName": { "type": "string", "description": "Name of the new manual POB." }, "pobTemplateId": { "type": "integer", "format": "int64", "description": "POB template for the new POB." }, "fvPrice": { "type": "number", "format": "double", "description": "Fair value price of the new line." }, "itemNum": { "type": "string", "description": "Item number." }, "ordQty": { "type": "number", "format": "double", "description": "Ordered quantity." }, "unitListPrc": { "type": "number", "format": "double", "description": "Unit list price." }, "unitSellPrc": { "type": "number", "format": "double", "description": "Unit selling price." }, "extLstPrc": { "type": "number", "format": "double", "description": "Extended list price." }, "extSllPrc": { "type": "number", "format": "double", "description": "Extended selling price." }, "docNum": { "type": "string", "description": "Document number." }, "docLineNum": { "type": "string", "description": "Document line number." }, "docDate": { "type": "string", "description": "Document date (`yyyy-MM-dd`)." }, "comments": { "type": "string", "description": "Comment recorded in the audit history." } } }, "SwitchLeadLineRequest": { "type": "object", "required": [ "lineId", "rcPobId" ], "properties": { "lineId": { "type": "integer", "format": "int64", "description": "Line that becomes the lead line." }, "rcPobId": { "type": "integer", "format": "int64", "description": "POB whose lead line changes." }, "objectVersion": { "type": "integer", "format": "int64", "description": "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 } } }, "MovePobRequest": { "type": "object", "required": [ "rcPobId", "rcDerivedPobId", "action", "comments" ], "properties": { "rcPobId": { "type": "integer", "format": "int64", "description": "POB to move." }, "rcDerivedPobId": { "type": "integer", "format": "int64", "description": "Target derived POB." }, "action": { "type": "string", "description": "Move action. Use `MOVE`.", "example": "MOVE" }, "comments": { "type": "string", "description": "Reason for the move.", "minLength": 1 }, "lineId": { "type": "integer", "format": "int64", "description": "Move only this line of the POB. Omit to move the whole POB." }, "derivedPobVal": { "type": "string", "description": "Derived POB value.", "default": "" }, "objectVersion": { "type": "integer", "format": "int64", "description": "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 } } }, "CreateManualRcPob": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "integer", "format": "int64", "description": "POB ID." }, "retain": { "type": "boolean", "default": false, "description": "`true` keeps the POB in its source contract as well." } } }, "CreateManualRcRequest": { "type": "object", "description": "Provide either `rcIds`, or `rcPobIds` and/or `docLineIds`. When `rcIds` is not empty the contract is built at contract level.", "properties": { "rcIds": { "type": "array", "items": { "type": "integer", "format": "int64" }, "description": "Whole contracts to group into the new contract." }, "rcPobIds": { "type": "array", "items": { "$ref": "#/components/schemas/CreateManualRcPob" }, "description": "POBs to group into the new contract." }, "docLineIds": { "type": "array", "items": { "type": "string" }, "description": "Document lines to group into the new contract." }, "groupingTemplate": { "type": "integer", "format": "int64", "description": "Revenue contract grouping template ID." }, "comments": { "type": "string", "description": "Comment recorded in the audit history.", "default": "" }, "secAtrVal": { "type": "string", "description": "Organization (security attribute value) of the new contract, for multi-organization tenants.", "default": "" } } }, "LinkRcRequest": { "type": "object", "required": [ "targetRcIds" ], "properties": { "targetRcIds": { "type": "array", "minItems": 1, "items": { "type": "integer", "format": "int64" }, "description": "Contracts to merge into the contract in the path." }, "comments": { "type": "string", "description": "Comment recorded in the contract's audit history.", "default": "" }, "objectVersion": { "type": "integer", "format": "int64", "description": "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 } } }, "LinkPobsRequest": { "type": "object", "required": [ "rcPobIds" ], "properties": { "rcPobIds": { "type": "array", "minItems": 1, "items": { "type": "integer", "format": "int64" }, "description": "POBs to link into the contract." }, "comments": { "type": "string", "description": "Comment recorded in the contract's audit history.", "default": "" }, "objectVersion": { "type": "integer", "format": "int64", "description": "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 } } }, "LinkLinesRequest": { "type": "object", "required": [ "docLineIds" ], "properties": { "docLineIds": { "type": "array", "minItems": 1, "items": { "type": "string" }, "description": "Document line IDs to link." }, "leadLineId": { "type": "integer", "format": "int64", "description": "Group the linked lines under this lead line. Takes precedence over `rcPobId`." }, "rcPobId": { "type": "integer", "format": "int64", "description": "Attach the linked lines to this POB. Used only when `leadLineId` is omitted." }, "comments": { "type": "string", "description": "Comment recorded in the contract's audit history.", "default": "" }, "objectVersion": { "type": "integer", "format": "int64", "description": "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 } } }, "LinkChargesRequest": { "type": "object", "required": [ "chargeNumbers" ], "properties": { "chargeNumbers": { "type": "array", "minItems": 1, "items": { "type": "string" }, "description": "Zuora Billing charge numbers to link." }, "comments": { "type": "string", "description": "Comment recorded in the contract's audit history.", "default": "" }, "objectVersion": { "type": "integer", "format": "int64", "description": "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 } } }, "LinkSubscriptionsRequest": { "type": "object", "required": [ "subscriptionIds" ], "properties": { "subscriptionIds": { "type": "array", "minItems": 1, "items": { "type": "string" }, "description": "Subscriptions to link." }, "comments": { "type": "string", "description": "Comment recorded in the contract's audit history.", "default": "" }, "objectVersion": { "type": "integer", "format": "int64", "description": "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 } } }, "DelinkRcRequest": { "type": "object", "properties": { "comments": { "type": "string", "description": "Comment recorded in the contract's audit history.", "default": "" }, "objectVersion": { "type": "integer", "format": "int64", "description": "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 } } }, "DelinkPobsRequest": { "type": "object", "required": [ "rcPobIds" ], "properties": { "rcPobIds": { "type": "array", "minItems": 1, "items": { "type": "integer", "format": "int64" }, "description": "POBs to remove from the contract." }, "comments": { "type": "string", "description": "Comment recorded in the contract's audit history.", "default": "" }, "objectVersion": { "type": "integer", "format": "int64", "description": "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 } } }, "DelinkLinesRequest": { "type": "object", "required": [ "docLineIds" ], "properties": { "docLineIds": { "type": "array", "minItems": 1, "items": { "type": "string" }, "description": "Document line IDs to remove from the contract." }, "comments": { "type": "string", "description": "Comment recorded in the contract's audit history.", "default": "" }, "objectVersion": { "type": "integer", "format": "int64", "description": "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 } } }, "DelinkChargesRequest": { "type": "object", "required": [ "chargeNumbers" ], "properties": { "chargeNumbers": { "type": "array", "minItems": 1, "items": { "type": "string" }, "description": "Zuora Billing charge numbers to remove." }, "comments": { "type": "string", "description": "Comment recorded in the contract's audit history.", "default": "" }, "objectVersion": { "type": "integer", "format": "int64", "description": "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 } } }, "DelinkSubscriptionsRequest": { "type": "object", "required": [ "subscriptionIds" ], "properties": { "subscriptionIds": { "type": "array", "minItems": 1, "items": { "type": "string" }, "description": "Subscriptions to remove." }, "comments": { "type": "string", "description": "Comment recorded in the contract's audit history.", "default": "" }, "objectVersion": { "type": "integer", "format": "int64", "description": "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 } } }, "UndoDelinkRequest": { "type": "object", "required": [ "objectVersion" ], "properties": { "objectVersion": { "type": "integer", "format": "int64", "description": "Current version of the revenue contract. Required.", "example": 5 }, "comments": { "type": "string", "description": "Comment recorded in the audit history." } } }, "ApplyVcRequest": { "type": "object", "required": [ "rcLineId", "vcTypeId", "applyValue", "applyType", "vcRuleType" ], "properties": { "rcLineId": { "type": "integer", "format": "int64", "description": "Revenue contract line to adjust." }, "vcTypeId": { "type": "integer", "format": "int64", "description": "Variable consideration type. List valid values with `GET /revenue-management/contracts/{rcId}/vc-types`." }, "applyValue": { "type": "number", "format": "double", "description": "Amount or percentage to apply, depending on `applyType`." }, "applyType": { "type": "string", "description": "Whether `applyValue` is an amount or a percentage. Case-sensitive. Ignored (treated as `AMOUNT`) when `vcRuleType` is `S`, but still required.", "enum": [ "AMOUNT", "PERCENT" ] }, "vcRuleType": { "type": "string", "description": "Variable consideration rule type: `E` estimate, `A` actuals, `S` set. Case-sensitive.", "enum": [ "E", "A", "S" ] }, "applyOn": { "type": "string", "description": "Line amount or quantity field the variable consideration is based on.", "default": "" }, "comments": { "type": "string", "description": "Comment recorded in the audit history.", "default": "" }, "calcMethod": { "type": "string", "description": "Calculation method, for financing-type variable consideration.", "default": "" }, "intFreq": { "type": "string", "description": "Interest frequency, for financing-type variable consideration.", "default": "" }, "intRate": { "type": "string", "description": "Interest rate, for financing-type variable consideration.", "default": "" }, "startDate": { "type": "string", "description": "Start date (`yyyy-MM-dd`).", "default": "" }, "endDate": { "type": "string", "description": "End date (`yyyy-MM-dd`).", "default": "" }, "dryRun": { "type": "boolean", "default": false, "description": "`true` returns a preview in `previewData` without saving the adjustment." }, "objectVersion": { "type": "integer", "format": "int32", "description": "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 } } }, "ExpireVcRequest": { "type": "object", "required": [ "rcLinePriceAdjustmentId", "amount" ], "properties": { "rcLinePriceAdjustmentId": { "type": "integer", "format": "int64", "description": "Line price adjustment to expire (`rcLineAdjustmentRecords[].id` from apply-vc).", "maximum": 2147483647 }, "amount": { "type": "number", "format": "double", "description": "Amount to expire." }, "objectVersion": { "type": "integer", "format": "int64", "description": "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 } } }, "ImpairmentLine": { "type": "object", "required": [ "id", "comments", "impairmentType" ], "properties": { "id": { "type": "integer", "format": "int64", "description": "Revenue contract line ID." }, "comments": { "type": "string", "description": "Reason for the impairment.", "minLength": 1 }, "impairmentType": { "type": "string", "description": "Impairment type code: `1` contract impairment, `2` new POB ratable, `4` R and R within SSP, `N` none.", "example": "1" } } }, "ApplyImpairmentRequest": { "type": "object", "required": [ "lines" ], "properties": { "lines": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/ImpairmentLine" } }, "objectVersion": { "type": "integer", "format": "int64", "description": "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 } } }, "EditUsageItem": { "type": "object", "description": "Only the fields you send are changed.", "required": [ "id" ], "properties": { "id": { "type": "integer", "format": "int64", "description": "Usage record ID.", "minimum": 1 }, "quantity": { "type": "number", "format": "double", "description": "New usage quantity." }, "usageAmount": { "type": "number", "format": "double", "description": "New usage amount." }, "unitPrice": { "type": "number", "format": "double", "description": "New unit price." }, "atr1": { "type": "string", "description": "Usage attribute 1." }, "atr2": { "type": "string", "description": "Usage attribute 2." }, "atr3": { "type": "string", "description": "Usage attribute 3." }, "atr4": { "type": "string", "description": "Usage attribute 4." }, "atr5": { "type": "string", "description": "Usage attribute 5." } } }, "EditUsageRequest": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/EditUsageItem" } } } }, "CancelUsageRequest": { "type": "object", "required": [ "usageId" ], "properties": { "usageId": { "type": "integer", "format": "int64", "description": "Usage record ID to cancel.", "minimum": 1 } } }, "VoidBillingRequest": { "type": "object", "required": [ "billDocNumber", "reason" ], "properties": { "billDocNumber": { "type": "string", "description": "Billing document (invoice or credit memo) number to void.", "minLength": 1 }, "reason": { "type": "string", "description": "Reason for voiding.", "minLength": 1 }, "comment": { "type": "string", "description": "Additional comment.", "default": "" } } }, "PageMetadata": { "type": "object", "description": "Pagination details for a list response.", "required": [ "number", "size", "totalElements", "totalPages", "first", "last" ], "properties": { "number": { "type": "integer", "format": "int32", "description": "Current page number (1-based)." }, "size": { "type": "integer", "format": "int32", "description": "Page size applied." }, "totalElements": { "type": "integer", "format": "int64", "description": "Total records matching the filters across all pages." }, "totalPages": { "type": "integer", "format": "int32", "description": "Total number of pages. `0` when no record matches." }, "first": { "type": "boolean", "description": "True when this is the first page." }, "last": { "type": "boolean", "description": "True when this is the last page, or past the last page." } } }, "Indicators": { "type": "object", "description": "Status flags of the record. Each key is a flag name in camelCase and each value is a single-character code, usually `Y` or `N`. The set of keys depends on the record type and the Zuora Revenue release.", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 1 }, "example": { "allocationEligible": "Y", "multiCurrency": "N" } }, "RevenueContractHead": { "type": "object", "description": "Header record of a revenue contract (RC). A revenue contract groups the sales order, billing, and contract lines that Zuora Revenue allocates and recognizes together under ASC 606 / IFRS 15. Amounts are returned as decimal strings. Dates without a time are `yyyy-MM-dd`; timestamps are ISO 8601. The record carries additional contract attributes beyond the properties listed here (for example currencies, exchange rates, custom attributes `atr1`-`atr5`, and audit fields); clients must tolerate additional properties.", "required": [ "id", "bookId" ], "properties": { "id": { "type": "integer", "format": "int64", "description": "Revenue contract ID. Use it as `rcId` in other calls." }, "bookId": { "type": "integer", "format": "int64", "description": "Revenue book the contract belongs to." }, "indicators": { "$ref": "#/components/schemas/Indicators" }, "totalCarveAmount": { "type": "string", "nullable": true, "description": "Total allocation (carve-in/carve-out) amount of the contract.", "example": "1000.00" } }, "additionalProperties": true }, "RevenueContractLine": { "type": "object", "description": "A transaction line (sales order, contract, or invoice line) grouped into a revenue contract. Custom attributes are returned in nested objects. Amounts are returned as decimal strings. The record carries additional line attributes beyond the properties listed here (for example prices, quantities, and dates); clients must tolerate additional properties. Calculated and account fields are not returned.", "required": [ "id", "rcId" ], "properties": { "id": { "type": "integer", "format": "int64", "description": "Revenue contract line ID." }, "rcId": { "type": "integer", "format": "int64", "description": "Revenue contract the line belongs to." }, "indicators": { "$ref": "#/components/schemas/Indicators" }, "stringAttributes": { "type": "object", "description": "Custom text attributes `atr1` to `atr60`.", "properties": { "atr1": { "type": "string", "nullable": true }, "atr2": { "type": "string", "nullable": true }, "atr3": { "type": "string", "nullable": true }, "atr4": { "type": "string", "nullable": true }, "atr5": { "type": "string", "nullable": true }, "atr6": { "type": "string", "nullable": true }, "atr7": { "type": "string", "nullable": true }, "atr8": { "type": "string", "nullable": true }, "atr9": { "type": "string", "nullable": true }, "atr10": { "type": "string", "nullable": true }, "atr11": { "type": "string", "nullable": true }, "atr12": { "type": "string", "nullable": true }, "atr13": { "type": "string", "nullable": true }, "atr14": { "type": "string", "nullable": true }, "atr15": { "type": "string", "nullable": true }, "atr16": { "type": "string", "nullable": true }, "atr17": { "type": "string", "nullable": true }, "atr18": { "type": "string", "nullable": true }, "atr19": { "type": "string", "nullable": true }, "atr20": { "type": "string", "nullable": true }, "atr21": { "type": "string", "nullable": true }, "atr22": { "type": "string", "nullable": true }, "atr23": { "type": "string", "nullable": true }, "atr24": { "type": "string", "nullable": true }, "atr25": { "type": "string", "nullable": true }, "atr26": { "type": "string", "nullable": true }, "atr27": { "type": "string", "nullable": true }, "atr28": { "type": "string", "nullable": true }, "atr29": { "type": "string", "nullable": true }, "atr30": { "type": "string", "nullable": true }, "atr31": { "type": "string", "nullable": true }, "atr32": { "type": "string", "nullable": true }, "atr33": { "type": "string", "nullable": true }, "atr34": { "type": "string", "nullable": true }, "atr35": { "type": "string", "nullable": true }, "atr36": { "type": "string", "nullable": true }, "atr37": { "type": "string", "nullable": true }, "atr38": { "type": "string", "nullable": true }, "atr39": { "type": "string", "nullable": true }, "atr40": { "type": "string", "nullable": true }, "atr41": { "type": "string", "nullable": true }, "atr42": { "type": "string", "nullable": true }, "atr43": { "type": "string", "nullable": true }, "atr44": { "type": "string", "nullable": true }, "atr45": { "type": "string", "nullable": true }, "atr46": { "type": "string", "nullable": true }, "atr47": { "type": "string", "nullable": true }, "atr48": { "type": "string", "nullable": true }, "atr49": { "type": "string", "nullable": true }, "atr50": { "type": "string", "nullable": true }, "atr51": { "type": "string", "nullable": true }, "atr52": { "type": "string", "nullable": true }, "atr53": { "type": "string", "nullable": true }, "atr54": { "type": "string", "nullable": true }, "atr55": { "type": "string", "nullable": true }, "atr56": { "type": "string", "nullable": true }, "atr57": { "type": "string", "nullable": true }, "atr58": { "type": "string", "nullable": true }, "atr59": { "type": "string", "nullable": true }, "atr60": { "type": "string", "nullable": true } } }, "numberAttributes": { "type": "object", "description": "Custom number attributes `num1` to `num15`.", "properties": { "num1": { "type": "string", "nullable": true, "description": "Decimal value serialized as a string." }, "num2": { "type": "string", "nullable": true, "description": "Decimal value serialized as a string." }, "num3": { "type": "string", "nullable": true, "description": "Decimal value serialized as a string." }, "num4": { "type": "string", "nullable": true, "description": "Decimal value serialized as a string." }, "num5": { "type": "string", "nullable": true, "description": "Decimal value serialized as a string." }, "num6": { "type": "string", "nullable": true, "description": "Decimal value serialized as a string." }, "num7": { "type": "string", "nullable": true, "description": "Decimal value serialized as a string." }, "num8": { "type": "string", "nullable": true, "description": "Decimal value serialized as a string." }, "num9": { "type": "string", "nullable": true, "description": "Decimal value serialized as a string." }, "num10": { "type": "string", "nullable": true, "description": "Decimal value serialized as a string." }, "num11": { "type": "string", "nullable": true, "description": "Decimal value serialized as a string." }, "num12": { "type": "string", "nullable": true, "description": "Decimal value serialized as a string." }, "num13": { "type": "string", "nullable": true, "description": "Decimal value serialized as a string." }, "num14": { "type": "string", "nullable": true, "description": "Decimal value serialized as a string." }, "num15": { "type": "string", "nullable": true, "description": "Decimal value serialized as a string." } } }, "dateAttributes": { "type": "object", "description": "Custom date attributes `date1` to `date5` (`yyyy-MM-dd`).", "properties": { "date1": { "type": "string", "format": "date", "nullable": true }, "date2": { "type": "string", "format": "date", "nullable": true }, "date3": { "type": "string", "format": "date", "nullable": true }, "date4": { "type": "string", "format": "date", "nullable": true }, "date5": { "type": "string", "format": "date", "nullable": true } } }, "rcLineOtrAttributes": { "type": "object", "description": "Other line attributes.", "additionalProperties": true, "properties": { "rpcNum": { "type": "string", "nullable": true, "description": "Zuora Billing rate plan charge number of the line." } } } }, "additionalProperties": true }, "RevenueHoldFlags": { "type": "object", "description": "Configuration flags of a revenue hold definition.", "properties": { "enabled": { "type": "string", "enum": [ "Y", "N" ], "description": "Whether the hold is active." }, "allowManualRelease": { "type": "string", "enum": [ "Y", "N" ], "description": "Whether users and APIs can release the hold manually." }, "allowManualApply": { "type": "string", "enum": [ "Y", "N" ], "description": "Whether users and APIs can apply the hold manually." }, "holdType": { "type": "string", "enum": [ "Revenue Hold", "Transfer Hold" ], "description": "Hold type. Omitted when not configured." }, "holdLevel": { "type": "string", "enum": [ "RC", "POB", "LINE", "CHARGE" ], "description": "Level the hold applies to. Omitted when not configured." }, "scheduleType": { "type": "string", "enum": [ "Revenue", "Allocation", "Both", "None" ], "description": "Schedules blocked by the hold." } } }, "RevenueHold": { "type": "object", "description": "A revenue hold definition configured in Zuora Revenue setup. Apply and release these holds with the Manual Action APIs by passing `id` as `holdId`.", "properties": { "id": { "type": "integer", "format": "int64", "description": "Hold definition ID (`holdId`)." }, "name": { "type": "string", "description": "Hold name." }, "description": { "type": "string", "nullable": true, "description": "Hold description." }, "startDate": { "type": "string", "nullable": true, "description": "Date the hold definition becomes effective." }, "endDate": { "type": "string", "nullable": true, "description": "Date the hold definition stops being effective." }, "eventId": { "type": "integer", "format": "int64", "nullable": true, "description": "Release event linked to the hold." }, "expiryFieldName": { "type": "string", "nullable": true, "description": "Field used to calculate automatic expiry of the hold." }, "expiryNumberType": { "type": "string", "nullable": true, "description": "Unit of the expiry duration, such as days or months." }, "expiryDuration": { "type": "integer", "format": "int64", "nullable": true, "description": "Number of expiry units after which the hold expires." }, "flags": { "$ref": "#/components/schemas/RevenueHoldFlags" }, "createdPeriodId": { "type": "integer", "format": "int64", "description": "Period in which the hold was created." }, "clientId": { "type": "integer", "format": "int64", "description": "Zuora Revenue client ID." }, "createdBy": { "type": "string", "description": "User who created the hold." }, "createdDate": { "type": "string", "format": "date", "description": "Creation date (`yyyy-MM-dd`)." }, "updatedBy": { "type": "string", "description": "User who last updated the hold." }, "updatedDate": { "type": "string", "format": "date", "description": "Last update date (`yyyy-MM-dd`)." } }, "additionalProperties": true }, "RevenueContractHeadPage": { "type": "object", "required": [ "data", "page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RevenueContractHead" } }, "page": { "$ref": "#/components/schemas/PageMetadata" } } }, "RevenueContractLinePage": { "type": "object", "required": [ "data", "page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RevenueContractLine" } }, "page": { "$ref": "#/components/schemas/PageMetadata" } } }, "RevenueHoldPage": { "type": "object", "required": [ "data", "page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RevenueHold" } }, "page": { "$ref": "#/components/schemas/PageMetadata" } } }, "ContractQueryErrorResponse": { "type": "object", "required": [ "error" ], "description": "Error returned by the Revenue Contract Management APIs.", "properties": { "error": { "type": "string", "description": "Human-readable error message." } } }, "ReportingRiaError": { "type": "object", "description": "Error envelope used by the Revenue Integration Reporting APIs. `Status` is usually `Error`, and `Message` carries the detail.", "properties": { "Status": { "description": "`Error` for most failures. On a few errors (for example a signing-service failure on Get a signed URL) the error text itself is returned here.", "example": "Error" }, "Message": { "description": "Human-readable error detail. A string on most errors; an object such as `{\"Invalid_fields\": [...]}` on field validation errors.", "example": "Invalid date format 2026-09-22 for createddate" }, "Result": { "description": "Additional error detail, or `null`." } } } }, "parameters": { "BookId": { "name": "X-REV-BOOK-ID", "in": "header", "required": false, "description": "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.", "schema": { "type": "integer", "format": "int64", "default": 1 }, "example": 1 }, "RequestId": { "name": "Zuora-Request-Id", "in": "header", "required": false, "description": "Optional correlation ID, echoed in the `traceId` response header.", "schema": { "type": "string", "maxLength": 64 }, "example": "b8f1c2d4-6e1a-4c7b-9d2e-0f3a5b7c9e11" }, "RcId": { "name": "rcId", "in": "path", "required": true, "description": "Revenue contract ID.", "schema": { "type": "integer", "format": "int64" }, "example": 111442 }, "HoldId": { "name": "holdId", "in": "path", "required": true, "description": "Revenue hold definition ID. List holds with `GET /revenue-holds`.", "schema": { "type": "integer", "format": "int64" }, "example": 20 }, "PobId": { "name": "pobId", "in": "path", "required": true, "description": "Performance obligation (POB) ID.", "schema": { "type": "integer", "format": "int64" }, "example": 156912 }, "LineId": { "name": "lineId", "in": "path", "required": true, "description": "Revenue contract line ID.", "schema": { "type": "integer", "format": "int64" }, "example": 85922 }, "Page": { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1. `0` and an omitted value both return the first page.", "schema": { "type": "integer", "format": "int32", "minimum": 0, "default": 1 }, "example": 1 }, "Size": { "name": "size", "in": "query", "required": false, "description": "Records per page. Default 20, maximum 100.", "schema": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 100, "default": 20 }, "example": 20 } }, "headers": { "traceId": { "description": "Identifier of the request. Quote it when you contact Zuora Support.", "schema": { "type": "string" } }, "TraceId": { "description": "Correlation ID of the request. Quote it when you contact Zuora Global Support.", "schema": { "type": "string" } } }, "responses": { "Unauthorized": { "description": "Missing or expired access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MjeGatewayError" }, "examples": { "missingOrExpiredAccessToken": { "$ref": "#/components/examples/MjeUnauthorized" } } } } }, "Forbidden": { "description": "The revenue engine denied the action for the caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientErrorResponse" }, "examples": { "permissionDenied": { "$ref": "#/components/examples/EnginePermissionDenied" } } } } }, "TooManyRequests": { "description": "Too many requests. Wait for the time in the `Retry-After` header, then retry with backoff.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" }, "examples": { "rateLimited": { "$ref": "#/components/examples/RateLimited" } } } } }, "BadRequest": { "description": "**Failure.** The tenant could not be resolved for Zuora Revenue, or the database connection failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpringError" }, "examples": { "tenant": { "$ref": "#/components/examples/Tenant" } } } } }, "ServerError": { "description": "**Failure.** Unexpected server error. Retry later; if it persists, contact Zuora Support with the `Zuora-Track-Id` and the `traceId` response header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceError" }, "examples": { "serverError": { "$ref": "#/components/examples/ServerError" } } } } }, "NotFound": { "description": "The revenue contract, or an object referenced in the request, was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientErrorResponse" }, "examples": { "contractNotFound": { "$ref": "#/components/examples/ContractNotFound" }, "engineNotFound": { "$ref": "#/components/examples/EngineNotFound" } } } } }, "NotFound2": { "description": "**Failure.** No run has this identifier. The response has no body." }, "Unauthorized2": { "description": "The access token is missing, invalid or expired (gateway), or the OAuth client's user is not a Zuora Revenue user.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/GatewayError" }, { "$ref": "#/components/schemas/RiaError" } ] }, "examples": { "unauthorized": { "$ref": "#/components/examples/Unauthorized" }, "noRevenueUser": { "$ref": "#/components/examples/NoRevenueUser" } } } } }, "Forbidden2": { "description": "The request was rejected by the Integration service. Either the tenant is not enabled for this API, or the tenant requires custom request headers that were not sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RiaError" }, "examples": { "restricted": { "$ref": "#/components/examples/Restricted" }, "customHeaders": { "$ref": "#/components/examples/CustomHeaders" } } } } }, "ServerError2": { "description": "Unexpected server or database error. Retry later; if it persists, contact Zuora Support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RiaError" }, "examples": { "dbError": { "$ref": "#/components/examples/DbError" } } } } }, "BadGateway": { "description": "An internal query service did not respond correctly. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RiaError" }, "examples": { "queryService": { "$ref": "#/components/examples/QueryService" } } } } }, "BadRequest2": { "description": "**Failure.** The OAuth client is not linked to a Zuora user. Also returned when the database connection fails (retry with backoff).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportingRiaError" }, "examples": { "noUser": { "$ref": "#/components/examples/NoUser" }, "dbConnect": { "$ref": "#/components/examples/DbConnect" } } } } }, "Response200": { "description": "**Success.** The signed URL.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedUrlResponse" }, "examples": { "url": { "summary": "URL issued", "value": { "success": true, "signed_url": "https://files.zuora.com/rev/1234567/reports/WF_SUMMARY_482391.csv?X-Amz-Expires=1800&X-Amz-Signature=9ac2..." } } } } } }, "BadRequest3": { "description": "**Failure.** The signing service returned an error, or an unexpected error occurred. `Status` holds the error text. Retry once, then contact Zuora Support with the submission ID. Also returned when the database connection fails (retry with backoff).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportingRiaError" }, "examples": { "signing": { "summary": "Signing service error", "value": { "Status": "Object of type Response is not JSON serializable", "Result": {} } }, "dbConnect": { "$ref": "#/components/examples/DbConnect" } } } } }, "Forbidden3": { "description": "**Failure.** HTTP GET is disabled for the tenant (use POST), the tenant is not enabled for this API, or required custom headers are missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportingRiaError" }, "examples": { "getDisabled": { "summary": "GET disabled", "value": { "Status": "Error", "Result": null, "Message": "HTTP GET API is disabled for this tenant" } }, "restricted": { "summary": "API not enabled", "value": { "Message": "You are not authorized to access this endpoint. Please contact Zuora Revenue Support" } } } } } }, "NotFound3": { "description": "**Failure.** The run was not found, is not Available, or its file is not in cloud storage (use Download a report file instead), or URL signing is not configured for the tenant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedUrlError" }, "examples": { "notFound": { "summary": "Run not found or not ready", "value": { "success": false, "error": "Report not found for Submission Id: 482399" } }, "notConfigured": { "summary": "Signing not configured", "value": { "success": false, "error": "Unable to generate URL. Please contact Zuora Revenue Support" } } } } } }, "Response2002": { "description": "One page of rows. The `continuation-token` header identifies the background task; send it on the next page.", "headers": { "continuation-token": { "description": "Task identifier to send when requesting later pages.", "schema": { "type": "string" } } }, "content": { "text/csv": { "schema": { "type": "string" }, "examples": { "csvPage": { "summary": "Page 1 as CSV (outputType=csv)", "value": "\"RC_ID\",\"RC_NUM\",\"LINE_ID\",\"EXT_SLL_PRC\",\"UPDT_DT\"\n\"120045\",\"RC-120045\",\"880113\",\"12000\",\"2026-09-14 10:22:05\"\n" } } }, "application/gzip": { "schema": { "type": "string", "format": "binary" }, "examples": { "gzipPage": { "summary": "Page 1 as gzip (default outputType)", "value": "" } } } } }, "NoContent": { "description": "`pagenum` is 0. No body." }, "BadRequest4": { "description": "A parameter is missing or invalid, a later page was requested without a `continuation-token`, `pageSize` is above the limit, a selected field does not exist, the view name is unknown, or the tenant's query quota is used up. Also returned when the database connection fails (retry with backoff).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RiaError" }, "examples": { "missingParam": { "$ref": "#/components/examples/MissingParam" }, "badDate": { "$ref": "#/components/examples/BadDate" }, "noToken": { "summary": "continuation-token missing for page 2", "value": { "Status": "Error", "Result": "Continuation-Token is Mandatory in request header for Pages greater than 1" } }, "pageSize": { "summary": "pageSize too large", "value": { "Status": "Error", "Message": "pageSize cannot exceed 10000. Provided value was 15000.. Max limit for CSV format is 10000, GZIP format is 20000. Use outputType parameter to specify format. If you want more than 10000 records per page, please provide the outputType='gzip'" } }, "badField": { "summary": "Unknown column in Fields", "value": { "Status": "Error", "Message": "One or more fields from ['RC_ID', 'RC_NUMBER'] does not exist. For list of valid fields use the describe view api /integration/v2/biviews//describe-columns" } }, "badView": { "$ref": "#/components/examples/BadView" }, "notCached": { "summary": "Later page not ready yet", "value": { "Status": "Error", "Result": "Page still not yet cached. Please retry." } }, "quota": { "summary": "Query quota reached", "value": { "Status": "Error", "Message": "Reached allocated limits. Quota: Maximum Queries: 5 and Maximum Number of Queries per object: 2. ." }, "description": "Wait for running tasks to finish (see List BI View tasks) or cancel tasks you no longer need." }, "dbConnect": { "$ref": "#/components/examples/DbConnect" } } } } }, "NotFound4": { "description": "The requested page is beyond the last page. `Result` gives the total pages and rows. Stop paging.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RiaError" }, "examples": { "lastPage": { "summary": "Past the last page", "value": { "Status": "Success", "Result": "This page will not exist. Total Pages available are 3. Number of rows across these pages are 12430" } } } } } }, "ServerError3": { "description": "The background worker was interrupted, or an unexpected error occurred. Retry page 1.", "headers": { "continuation-token": { "description": "Task identifier of the interrupted task.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RiaError" }, "examples": { "worker": { "summary": "Worker lost", "value": { "Status": "Error", "Result": "Unable to process job. Please retry" } } } } } }, "Response2003": { "description": "CSV rows (`text/csv`), or JSON with the row count (`count=true`) or the column list (no dates; the columns are returned in `Status`).", "content": { "text/html": { "schema": { "type": "string" }, "examples": { "rows": { "summary": "CSV rows", "value": "\"120045\",\"RC-120045\",\"USD\",\"2026-09-14 10:22:05\"\n\"120046\",\"RC-120046\",\"EUR\",\"2026-09-15 08:01:44\"\n" } } }, "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BiViewCountV1" }, { "$ref": "#/components/schemas/RiaError" } ] }, "examples": { "count": { "summary": "Row count (count=true)", "value": { "Status": "Success", "Result": { "count": 12430 } } }, "columns": { "summary": "Columns (no dates)", "value": { "Status": [ { "column_name": "RC_ID", "data_type": "NUMBER", "data_length": 22 }, { "column_name": "RC_NUM", "data_type": "VARCHAR2", "data_length": 200 } ], "Result": {} } } } } } }, "NoContent2": { "description": "No rows for the criteria, or past the last page. No body." }, "BadRequest5": { "description": "The view name is unknown, `clientId` is missing or wrong, a date is invalid or out of order, the POST body is not JSON, a selected field does not exist, or the row count failed. Also returned when the database connection fails (retry with backoff).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RiaError" }, "examples": { "badView": { "summary": "Unknown view", "value": { "Status": "Template does not exist", "Result": [ "BI3_ACCT_TYPE", "BI3_APPR_DTL", "BI3_BOOK", "..." ] } }, "badClient": { "summary": "clientId invalid", "value": { "Status": "ClientId is invalid", "Result": {} } }, "dateOrder": { "summary": "toDate before fromDate", "value": { "Status": "ToDate must be greater than FromDate", "Result": {} } }, "dateFormat": { "summary": "Wrong date format", "value": { "Status": "Error in date format expected format is :2016-07-26T00:00:00", "Result": {} } }, "badBody": { "summary": "POST body not JSON", "value": { "Status": "No Json body found for POST", "Result": {} } }, "badField": { "summary": "Unknown column", "value": { "Status": "Invalid Fields", "Message": { "Invalid_fields": [ "RC_NUMBER" ] }, "Result": {} } }, "countFailed": { "summary": "Row count failed", "value": { "Status": "Error", "Message": "Error retrieving BI View Count", "Result": { "count": 0 } } }, "dbConnect": { "$ref": "#/components/examples/DbConnect" } } } } }, "ServerError4": { "description": "Column information for the CSV header could not be read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RiaError" }, "examples": { "meta": { "summary": "Metadata error", "value": { "Status": "Error occurred while fetching column metadata for the given view", "Result": {} } } } } } }, "BadRequest6": { "description": "The database connection failed. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RiaError" }, "examples": { "dbConnect": { "$ref": "#/components/examples/DbConnect" } } } } }, "NoContent3": { "description": "The task is unknown or has expired. No body." }, "ForbiddenRead": { "description": "Manual Journal Entry APIs not enabled; Role lacks Manual Journal access", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformErrorResponse" }, "examples": { "manualJournalEntryApisNotEnabled": { "$ref": "#/components/examples/MjeApisNotEnabled" }, "roleLacksManualJournalAccess": { "$ref": "#/components/examples/RoleLacksReadAccess" } } } } }, "MjeTooManyRequests": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MjeGatewayError" }, "examples": { "tooManyRequests": { "$ref": "#/components/examples/TooManyRequests" } } } } }, "UnexpectedError": { "description": "Unexpected error", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unexpectedError": { "$ref": "#/components/examples/UnexpectedError" } } } } }, "ServiceUnavailable": { "description": "Journal entry service unavailable", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "journalEntryServiceUnavailable": { "$ref": "#/components/examples/ServiceUnavailable" } } } } }, "ForbiddenEdit": { "description": "Manual Journal Entry APIs not enabled; Role lacks Manual Journal access", "headers": { "traceId": { "$ref": "#/components/headers/traceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformErrorResponse" }, "examples": { "manualJournalEntryApisNotEnabled": { "$ref": "#/components/examples/MjeApisNotEnabled" }, "roleLacksManualJournalAccess": { "$ref": "#/components/examples/RoleLacksEditAccess" } } } } }, "ContractNotFound": { "description": "The revenue contract, or an object referenced in the request, was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientErrorResponse" }, "examples": { "contractNotFound": { "$ref": "#/components/examples/ContractNotFound" } } } } }, "EngineNotFound": { "description": "The revenue contract, or an object referenced in the request, was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientErrorResponse" }, "examples": { "engineNotFound": { "$ref": "#/components/examples/EngineNotFound" } } } } }, "Conflict": { "description": "The action conflicts with a concurrent change to the contract. Read the contract again and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientErrorResponse" }, "examples": { "conflict": { "$ref": "#/components/examples/EngineConflict" } } } } }, "RcTooManyRequests": { "description": "The revenue engine is temporarily out of capacity. Retry with exponential backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientErrorResponse" }, "examples": { "resourceExhausted": { "$ref": "#/components/examples/EngineResourceExhausted" } } } } }, "InternalServerError": { "description": "Unexpected failure inside Zuora Revenue. This status is also returned when a path ID is not numeric. Do not retry the same request unchanged; contact Zuora Global Support if it persists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerErrorResponse" }, "examples": { "systemError": { "$ref": "#/components/examples/SystemError" } } } } }, "RcServiceUnavailable": { "description": "The revenue engine is temporarily unavailable. Retry with exponential backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerErrorResponse" }, "examples": { "unavailable": { "$ref": "#/components/examples/EngineUnavailable" } } } } }, "GatewayTimeout": { "description": "The revenue engine did not respond in time. Check the contract before retrying, because the action may have completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerErrorResponse" }, "examples": { "timeout": { "$ref": "#/components/examples/EngineTimeout" } } } } }, "ReportingUnauthorized": { "description": "**Failure.** The access token is missing, invalid or expired. Request a new token and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" }, "examples": { "unauthorized": { "$ref": "#/components/examples/Unauthorized" } } } } }, "ReportingForbidden": { "description": "**Failure.** The OAuth client is authenticated but is not permitted to use Zuora Revenue APIs for this tenant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" }, "examples": { "forbidden": { "$ref": "#/components/examples/Forbidden" } } } } }, "ReportingTooManyRequests": { "description": "**Failure.** Too many requests. Wait for the time in the `Retry-After` header, then retry with backoff.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" }, "examples": { "rateLimited": { "$ref": "#/components/examples/RateLimited" } } } } }, "ReportingNotFound": { "description": "**Failure.** The layout does not exist or does not belong to the report. The response has no body." }, "ReportingUnauthorized2": { "description": "**Failure.** The access token is missing, invalid or expired (gateway), or the OAuth client's user is not a Zuora Revenue user.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/GatewayError" }, { "$ref": "#/components/schemas/ReportingRiaError" } ] }, "examples": { "unauthorized": { "$ref": "#/components/examples/Unauthorized" }, "noRevenueUser": { "$ref": "#/components/examples/NoRevenueUser" } } } } }, "ReportingForbidden2": { "description": "**Failure.** The request was rejected by the Integration service. Either the tenant is not enabled for this API, or the tenant requires custom request headers that were not sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportingRiaError" }, "examples": { "restricted": { "$ref": "#/components/examples/Restricted" }, "customHeaders": { "$ref": "#/components/examples/CustomHeaders" } } } } }, "ReportingServerError2": { "description": "**Failure.** Unexpected server or database error. Retry later; if it persists, contact Zuora Support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportingRiaError" }, "examples": { "dbError": { "$ref": "#/components/examples/DbError" } } } } }, "ReportingBadGateway": { "description": "**Failure.** An internal query service did not respond correctly. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportingRiaError" }, "examples": { "queryService": { "$ref": "#/components/examples/QueryService" } } } } } }, "examples": { "Tenant": { "summary": "Tenant could not be resolved", "value": { "timestamp": "2026-10-09T07:15:02.123+00:00", "status": 400, "error": "Bad Request" }, "description": "Returned before the operation runs when the Zuora tenant of the token is not provisioned for Zuora Revenue, or the Revenue database connection could not be set up. Confirm the tenant has Zuora Revenue enabled; if it has, retry later and contact Zuora Support." }, "Unauthorized": { "summary": "Expired or missing token", "value": { "message": "Authentication error" } }, "Forbidden": { "summary": "Client not entitled", "value": { "message": "Failed to get user info." } }, "RateLimited": { "summary": "Rate limit exceeded", "value": { "message": "Too many requests" } }, "ServerError": { "summary": "Unexpected error", "value": { "message": "An error occurred: Unexpected internal error", "code": "1" } }, "NoUser": { "summary": "OAuth client not linked to a Zuora user", "value": { "Status": "Error", "Result": null, "Message": "Zuora-Global-User-Id header is required for OAuth authentication" }, "description": "The OAuth client must be created by, or mapped to, a Zuora user that has a Zuora Revenue role." }, "DbConnect": { "summary": "Database connection failed", "value": { "Status": "Error", "Result": null, "Message": "Error connecting to database. Please retry after sometime. If this issue persists, please call Zuora Revenue Support" }, "description": "Temporary. Retry with backoff." }, "NoRevenueUser": { "summary": "User of the OAuth client not found in Zuora Revenue", "value": { "Status": "Error", "Result": null, "Message": "Error decoding token" }, "description": "The OAuth client's Zuora user has no matching Zuora Revenue user. Map the user in Zuora Revenue." }, "Restricted": { "summary": "API not enabled for the tenant", "value": { "Message": "You are not authorized to access this endpoint. Please contact Zuora Revenue Support" } }, "CustomHeaders": { "summary": "Required custom headers missing", "value": { "Status": "Error", "Result": null, "Message": "Missing/Invalid request headers" } }, "NotFound": { "summary": "No data", "value": { "Status": "Error", "Message": "No data found matching the criteria" } }, "DbError": { "summary": "Database error", "value": { "Status": "Error", "Result": null, "Message": "Unexpected Error. Please contact Zuora Revenue Support" } }, "QueryService": { "summary": "Query service error", "value": { "Status": "Error", "Result": null, "Message": "Query service error. Please contact Zuora Revenue Support" } }, "MissingParam": { "summary": "fromDate missing", "value": { "Status": "Error", "Message": "Mandatory field fromDate is missing in path" } }, "BadDate": { "summary": "Wrong date format", "value": { "Status": "Error", "Message": "Invalid date format 2026-09-01 for fromDate" } }, "BadView": { "summary": "Unknown BI View name", "value": { "Status": "Error", "Message": "('BI3_RC_LINES', {'BI3_ACCT_TYPE': 'RPRO_BI3_ACCT_TYPE_V', '...': '...'}, None)" }, "description": "The message lists the requested name and the views supported for the tenant. Correct the name using the list in the `tmpl_name` description." }, "MjeUnauthorized": { "summary": "Missing or expired access token", "description": "The `Authorization` header is missing, malformed or the bearer token has expired. The request is rejected by the Zuora API gateway before it reaches the service. Obtain a new token and retry.", "value": { "message": "Authentication error" } }, "MjeApisNotEnabled": { "summary": "Manual Journal Entry APIs not enabled", "description": "Your tenant is not on the New MJE experience, which is a prerequisite for these APIs. Contact Zuora Support to enable it.", "value": { "timestamp": "2026-10-07T10:15:30.123+00:00", "status": 403, "error": "Forbidden", "message": "This version of MJE cannot use APIs. Please contact support to upgrade to New MJE UI.", "path": "/journal-entries" } }, "RoleLacksReadAccess": { "summary": "Role lacks Manual Journal access", "description": "The user behind the token does not have **read** access to the Manual Journal function in Zuora Revenue role setup. GET operations require read access.", "value": { "timestamp": "2026-10-07T10:15:30.123+00:00", "status": 403, "error": "Forbidden", "message": "No message available", "path": "/journal-entries" } }, "TooManyRequests": { "summary": "Too many requests", "description": "You exceeded the API rate limit for your tenant. Wait and retry using the `Retry-After` response header when present.", "value": { "message": "Too many requests" } }, "UnexpectedError": { "summary": "Unexpected error", "description": "An unexpected error occurred, for example a malformed JSON body, a non-numeric path ID, a missing required query parameter, or the requested entry could not be loaded. Check the request; if it is valid, retry with backoff and contact Zuora Support with the response `traceId` header.", "value": { "success": false, "reasons": [ { "code": "SystemError", "message": "internal server error" } ] } }, "ServiceUnavailable": { "summary": "Journal entry service unavailable", "description": "The journal entry processing service could not be reached. Retry with exponential backoff.", "value": { "success": false, "reasons": [ { "code": "UPSTREAM_SERVICE_ERROR", "message": "MJE backend is not reachable: I/O error on POST request" } ] } }, "RoleLacksEditAccess": { "summary": "Role lacks Manual Journal access", "description": "The user behind the token does not have **edit** access to the Manual Journal function in Zuora Revenue role setup. All POST, PATCH and DELETE operations (including POST searches and exports) require edit access.", "value": { "timestamp": "2026-10-07T10:15:30.123+00:00", "status": 403, "error": "Forbidden", "message": "No message available", "path": "/journal-entries" } }, "ContractNotFound": { "summary": "Revenue contract not found", "description": "The contract does not exist in the book, or the caller's organization cannot see it.", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "NotFound", "message": "Revenue contract not found for rcId=999999, bookId=1" } ] } }, "ObjectVersionUnresolved": { "summary": "Object version cannot be resolved", "description": "`objectVersion` was omitted and the contract has no stored version. Send `objectVersion` explicitly.", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "InvalidRequest", "message": "objectVersion was not supplied and could not be resolved from DB for rcId=111442, bookId=1" } ] } }, "MalformedBody": { "summary": "Malformed request body", "description": "The body is missing, is not valid JSON, or a field has the wrong type (for example text in a numeric field).", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "InvalidRequest", "message": "Request body is malformed or contains invalid values" } ] } }, "InvalidBookHeader": { "summary": "Invalid book header", "description": "`X-REV-BOOK-ID` is not numeric.", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "InvalidRequest", "message": "For input string: \"abc\"" } ] } }, "SystemError": { "summary": "Internal server error", "value": { "reasons": [ { "code": "SystemError", "message": "internal server error" } ] } }, "EngineRejected": { "summary": "Rejected by the revenue engine", "description": "The revenue engine rejected the request as invalid for the contract's current state (`INVALID_ARGUMENT`, `FAILED_PRECONDITION`, or `OUT_OF_RANGE`).", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "FAILED_PRECONDITION", "message": "Service call failed. Please try again or contact support." } ] } }, "EngineNotFound": { "summary": "Object not found by the revenue engine", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "NOT_FOUND", "message": "Service call failed. Please try again or contact support." } ] } }, "EngineConflict": { "summary": "Concurrent update", "description": "Another update to the same contract was in progress, or the object already exists (`ABORTED` or `ALREADY_EXISTS`). Read the contract again and retry.", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "ABORTED", "message": "Service call failed. Please try again or contact support." } ] } }, "EnginePermissionDenied": { "summary": "Not permitted", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "PERMISSION_DENIED", "message": "Service call failed. Please try again or contact support." } ] } }, "EngineResourceExhausted": { "summary": "Engine capacity exceeded", "value": { "success": false, "processId": "3f1c2a7e-9b4d-4c1e-8a55-2d6f0e9b1c11", "requestId": "a7d2e5f0-1c3b-4e8a-9f6d-2b4c6e8a0d13", "reasons": [ { "code": "RESOURCE_EXHAUSTED", "message": "Service call failed. Please try again or contact support." } ] } }, "EngineUnavailable": { "summary": "Revenue engine unavailable", "value": { "reasons": [ { "code": "UNAVAILABLE", "message": "Service call failed. Please try again or contact support." } ] } }, "EngineTimeout": { "summary": "Revenue engine timeout", "value": { "reasons": [ { "code": "DEADLINE_EXCEEDED", "message": "Service call failed. Please try again or contact support." } ] } } } } }