Zuora Billing Preview Run API

openapi: 3.2.0
info:
  version: '2023-12-15'
  title: Reference Billing Preview Run API
  description: '# Introduction


    Welcome to the REST API reference for the Zuora Billing, Payments, and Central Platform!'
  contact:
    email: docs@zuora.com
servers:
- url: https://rest.zuora.com/
tags:
- name: Billing Preview Run
  description: 'A billing preview run asynchronously generates a downloadable CSV file containing a preview of future invoice item data and credit memo item data for a batch of customer accounts.


    **Note**: Credit memo item data is only available if you have the Invoice Settlement feature enabled.'
paths:
  /v1/billing-preview-runs:
    post:
      summary: Create a billing preview run
      operationId: POST_BillingPreviewRun
      description: 'Creates a billing preview run for multiple customer accounts.


        The maximum supported preview duration is 20 years, calculated from the current date to the target date.


        You can run up to 20 billing preview runs in batches concurrently. A single batch of customer accounts can only have one billing preview run at a time. So you can have up to 20 batches running at the same time. If you create a billing preview run for all customer batches, you cannot create another billing preview run until this preview run is completed.


        Note that the preview results for each billing preview run will be stored in the system for 180 days; after that they will be purged.'
      parameters:
      - $ref: '#/components/parameters/GLOBAL_HEADER_Idempotency_Key'
      - $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding'
      - $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding'
      - $ref: '#/components/parameters/GLOBAL_HEADER_Authorization_OAuth_optional'
      - $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Track_Id'
      - $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Entity_Ids_Single'
      - $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Org_Ids'
      - name: zuora-version
        in: header
        required: false
        description: "\nThe minor version of the Zuora REST API. See [Minor Version](/api-references/api/overview/#section/API-Versions/Minor-Version) for information about REST API version control. \n\nThis header affects the availability of the following request fields:\n* `batch`\n* `batches`        \n"
        schema:
          type: string
      tags:
      - Billing Preview Run
      responses:
        200:
          headers:
            Content-Encoding:
              description: "This header is returned if you specify the `Accept-Encoding: gzip` request header and the response contains over 1000 bytes of data.\n\nNote that only the following MIME types support gzipped responses:\n  - `application/json`\n  - `application/xml`\n  - `text/html`\n  - `text/csv`\n  - `text/plain`\n"
              schema:
                type: string
            RateLimit-Limit:
              description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://knowledgecenter.zuora.com/BB_Introducing_Z_Business/Policies/Concurrent_Request_Limits#Rate_limits) for more information.

                '
              schema:
                type: string
            RateLimit-Remaining:
              description: 'The number of requests remaining in the time window closest to quota exhaustion. See [rate limits](https://knowledgecenter.zuora.com/BB_Introducing_Z_Business/Policies/Concurrent_Request_Limits#Rate_limits) for more information.

                '
              schema:
                type: number
            RateLimit-Reset:
              description: 'The number of seconds until the quota resets for the time window closest to quota exhaustion. See [rate limits](https://knowledgecenter.zuora.com/BB_Introducing_Z_Business/Policies/Concurrent_Request_Limits#Rate_limits) for more information.

                '
              schema:
                type: number
            Zuora-Request-Id:
              description: 'The Zuora internal identifier of the API call. You cannot control the value of this header.

                '
              schema:
                type: string
                maxLength: 36
                minLength: 36
            Zuora-Track-Id:
              description: 'A custom identifier for tracing the API call. If you specified a tracing identifier in the request headers, Zuora returns the same tracing identifier. Otherwise, Zuora does not set this header.

                '
              schema:
                type: string
                maxLength: 64
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: 'Returns `true` if the request was processed successfully.

                      '
                  billingPreviewRunId:
                    type: string
                    description: 'Id of the billing preview run.

                      '
              example:
                success: true
                billingPreviewRunId: 402890b757d1ec1b0157d5aa3d6802aa
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostBillingPreviewRunParam'
        required: true
  /v1/billing-preview-runs/{billingPreviewRunId}:
    get:
      summary: Retrieve a billing preview run
      operationId: GET_BillingPreviewRun
      description: 'Retrieves a preview of future invoice items for multiple customer accounts through a billing preview run. If you have the Invoice Settlement feature enabled, you can also retrieve a preview of future credit memo items. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information.


        A billing preview run asynchronously generates a downloadable CSV file containing a preview of invoice item data and credit memo item data for a batch of customer accounts. Note that if you set `storageOption` to `Database`, no CSV file is generate; instead, you can have a record in the billing preview result. You can use data source to query Billing Preview Run Result.'
      parameters:
      - $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding'
      - $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding'
      - $ref: '#/components/parameters/GLOBAL_HEADER_Authorization_OAuth_optional'
      - $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Track_Id'
      - $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Entity_Ids_Single'
      - $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Org_Ids'
      - name: zuora-version
        in: header
        required: false
        description: "\nThe minor version of the Zuora REST API. See [Minor Version](/api-references/api/overview/#section/API-Versions/Minor-Version) for information about REST API version control. \n\nThis header affects the availability of the following request fields:\n* `batch`\n* `batches`\n"
        schema:
          type: string
      - name: billingPreviewRunId
        in: path
        description: 'Id of the billing preview run.

          '
        required: true
        schema:
          type: string
      tags:
      - Billing Preview Run
      responses:
        200:
          headers:
            Content-Encoding:
              description: "This header is returned if you specify the `Accept-Encoding: gzip` request header and the response contains over 1000 bytes of data.\n\nNote that only the following MIME types support gzipped responses:\n  - `application/json`\n  - `application/xml`\n  - `text/html`\n  - `text/csv`\n  - `text/plain`\n"
              schema:
                type: string
            RateLimit-Limit:
              description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://knowledgecenter.zuora.com/BB_Introducing_Z_Business/Policies/Concurrent_Request_Limits#Rate_limits) for more information.

                '
              schema:
                type: string
            RateLimit-Remaining:
              description: 'The number of requests remaining in the time window closest to quota exhaustion. See [rate limits](https://knowledgecenter.zuora.com/BB_Introducing_Z_Business/Policies/Concurrent_Request_Limits#Rate_limits) for more information.

                '
              schema:
                type: number
            RateLimit-Reset:
              description: 'The number of seconds until the quota resets for the time window closest to quota exhaustion. See [rate limits](https://knowledgecenter.zuora.com/BB_Introducing_Z_Business/Policies/Concurrent_Request_Limits#Rate_limits) for more information.

                '
              schema:
                type: number
            Zuora-Request-Id:
              description: 'The Zuora internal identifier of the API call. You cannot control the value of this header.

                '
              schema:
                type: string
                maxLength: 36
                minLength: 36
            Zuora-Track-Id:
              description: 'A custom identifier for tracing the API call. If you specified a tracing identifier in the request headers, Zuora returns the same tracing identifier. Otherwise, Zuora does not set this header.

                '
              schema:
                type: string
                maxLength: 64
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetBillingPreviewRunResponse'
              example:
                assumeRenewal: Autorenew
                batches: ''
                chargeTypeToExclude: OneTime
                createdById: 4028906d58240f960158241132be0003
                createdDate: '2016-11-04 16:18:56'
                endDate: '2016-11-04 16:19:00'
                errorMessage: null
                includingEvergreenSubscription: true
                includingDraftItems: false
                resultFileUrl: https://rest.zuora.com/v1/files/4028906d582d21a101582e6b663c0a65
                runNumber: BPR-00000010
                startDate: '2016-11-04 16:19:00'
                status: Completed
                succeededAccounts: 7
                targetDate: '2016-12-01'
                totalAccounts: 7
                updatedById: 4028906d58240f960158241132be0003
                updatedDate: '2016-11-04 16:19:00'
                success: true
components:
  parameters:
    GLOBAL_HEADER_Zuora_Org_Ids:
      name: Zuora-Org-Ids
      in: header
      required: false
      description: "Comma separated IDs. If you have <a href=\"https://knowledgecenter.zuora.com/Zuora_Central_Platform/Multi-Org\" target=\"_blank\">Zuora Multi-Org</a> enabled, \nyou can use this header to specify which orgs to perform the operation in. If you do not have Zuora Multi-Org enabled, you should not set this header.\n\nThe IDs must be a sub-set of the user's accessible orgs. If you specify an org that the user does not have access to, the operation fails.\n\nIf the header is not set, the operation is performed in scope of the user's accessible orgs.\n"
      schema:
        type: string
    GLOBAL_HEADER_Zuora_Entity_Ids_Single:
      name: Zuora-Entity-Ids
      in: header
      required: false
      description: 'An entity ID. If you have [Zuora Multi-entity](https://knowledgecenter.zuora.com/BB_Introducing_Z_Business/Multi-entity) enabled and the OAuth token is valid for more than one entity, you must use this header to specify which entity to perform the operation in. If the OAuth token is only valid for a single entity, or you do not have Zuora Multi-entity enabled, you do not need to set this header.

        '
      schema:
        type: string
    GLOBAL_HEADER_Authorization_OAuth_optional:
      name: Authorization
      in: header
      required: false
      description: 'The value is in the `Bearer {token}` format where {token} is a valid OAuth token generated by calling [Create an OAuth token](/api-references/api/operation/createToken).

        '
      schema:
        type: string
    GLOBAL_HEADER_Content_Encoding:
      name: Content-Encoding
      in: header
      required: false
      description: 'Include the `Content-Encoding: gzip` header to compress a request. With this header specified, you should upload a gzipped file for the request payload instead of sending the JSON payload.

        '
      schema:
        type: string
    GLOBAL_HEADER_Accept_Encoding:
      name: Accept-Encoding
      in: header
      required: false
      description: "Include the `Accept-Encoding: gzip` header to compress responses as a gzipped file. It can significantly reduce the bandwidth required for a response. \n\nIf specified, Zuora automatically compresses responses that contain over 1000 bytes of data, and the response contains a `Content-Encoding` header with the compression algorithm so that your client can decompress it.\n"
      schema:
        type: string
    GLOBAL_HEADER_Zuora_Track_Id:
      name: Zuora-Track-Id
      in: header
      required: false
      description: 'A custom identifier for tracing the API call. If you set a value for this header, Zuora returns the same value in the response headers. This header enables you to associate your system process identifiers with Zuora API calls, to assist with troubleshooting in the event of an issue.


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

        '
      schema:
        type: string
        maxLength: 64
    GLOBAL_HEADER_Idempotency_Key:
      name: Idempotency-Key
      in: header
      required: false
      description: "Specify a unique idempotency key if you want to perform an idempotent POST or PATCH request. Do not use this header in other request types. \n\nWith this header specified, the Zuora server can identify subsequent retries of the same request using this value, which prevents the same operation from being performed multiple times by accident. \n"
      schema:
        type: string
        maxLength: 255
  schemas:
    PostBillingPreviewRunParam:
      example:
        assumeRenewal: None
        batches: Batch1, Batch2
        chargeTypeToExclude: ''
        includingDraftItems: 'false'
        includingEvergreenSubscription: 'true'
        targetDate: '2017-01-10'
      properties:
        assumeRenewal:
          description: "Indicates whether to generate a preview of future invoice items and credit memo items with the assumption that the subscriptions are renewed.\n\nSet one of the following values in this field to decide how the assumption is applied in the billing preview.\n\n  * **All:** The assumption is applied to all the subscriptions. Zuora generates preview invoice item data and credit memo item data from the first day of the customer's next billing period to the target date.\n  \n  * **None:** (Default) The assumption is not applied to the subscriptions. Zuora generates preview invoice item data and credit memo item data based on the current term end date and the target date.\n  \n    * If the target date is later than the current term end date, Zuora generates preview invoice item data and credit memo item data from the first day of the customer's next billing period to the current term end date.\n\n    * If the target date is earlier than the current term end date, Zuora generates preview invoice item data and credit memeo item data from the first day of the customer's next billing period to the target date.\n\n  * **Autorenew:** The assumption is applied to the subscriptions that have auto-renew enabled. Zuora generates preview invoice item data and credit memo item data from the first day of the customer's next billing period to the target date.\n  \n**Note:** \n  - This field can only be used if the subscription renewal term is not set to 0.  \n  \n  \n  - The credit memo item data is only available if you have Invoice Settlement feature enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see [Invoice Settlement Enablement and Checklist Guide](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement/Invoice_Settlement_Migration_Checklist_and_Guide) for more information. \n"
          type: string
        batch:
          description: "The customer batch to include in the billing preview run. If not specified, all customer batches are included. \n\n**Note**: \n  - **Note**: By default, you have 50 configurable account batches. To increase the limit to 200 batches, you must have the <a href=\"https://knowledgecenter.zuora.com/Zuora_Central_Platform/Performance_Booster_Elite\" target=\"_blank\">Performance Booster Elite</a> package.\n  - This field is not available if you set the `zuora-version` request header to `314.0` or later [available versions](/api-references/api/overview/#section/API-Versions/Minor-Version).\n"
          maxLength: 255
          type: string
        batches:
          description: "The customer batches to include in the billing preview run. You can specify multiple batches separated by comma. If not specified, all customer batches are included.\n\n**Note**: \n  - By default, you have 50 configurable account batches. To increase the limit to 200 batches, you must have the <a href=\"https://knowledgecenter.zuora.com/Zuora_Central_Platform/Performance_Booster_Elite\" target=\"_blank\">Performance Booster Elite</a> package.\n  - This field is only available if you set the `zuora-version` request header to `314.0` or later [available versions](/api-references/api/overview/#section/API-Versions/Minor-Version).\n"
          maxLength: 1000
          type: string
        chargeTypeToExclude:
          description: 'The charge types to exclude from the forecast run.


            **Possible values:** OneTime, Recurring, Usage, and any comma-separated combination of these values.

            '
          type: string
        includingDraftItems:
          description: 'Whether draft document items are included in the billing preview run. By default, draft document items are not included.


            This field loads draft invoice items and credit memo items. The `chargeTypeToExclude`, `targetDate`, `includingEvergreenSubscription`, and `assumeRenewal` fields do not affect the behavior of the `includingDraftItems` field.

            '
          type: boolean
        includingEvergreenSubscription:
          description: 'Whether evergreen subscriptions are included in the billing preview run. By default, evergreen subscriptions are not included.

            '
          type: boolean
        organizationLabels:
          description: "The organization(s) that this billing preview run is created for. \n\nFor each item in the array, either the `organizationId` or the `organizationName` field is required.\n\nThis field is only required when you have already turned on Multi-Org feature.\n"
          items:
            properties:
              organizationId:
                description: 'The organization ID.

                  '
                type: string
              organizationName:
                description: 'The organization name.

                  '
                type: string
            type: object
          type: array
        storageOption:
          description: 'The saving options. The default value is `Csv`.

            '
          enum:
          - Csv
          - Database
          type: string
        targetDate:
          description: "The target date for the billing preview run. The billing preview run generates preview invoice item data and credit memo item data from the first day of the customer's next billing period to the target date. \n\nThe value for the `targetDate` field must be in _`YYYY-MM-DD`_ format.\n\nIf the target date is later than the subscription current term end date, the preview invoice item data and credit memo item data is generated from the first day of the customer's next billing period to the current term end date. If you want to generate preview invoice item data and credit memo item data past the end of the subscription current term, specify the AssumeRenewal field in the request.\n\n**Note:** The credit memo item data is only available if you have Invoice Settlement feature enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see [Invoice Settlement Enablement and Checklist Guide](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement/Invoice_Settlement_Migration_Checklist_and_Guide) for more information.\n"
          format: date
          type: string
      required:
      - targetDate
      type: object
    GetBillingPreviewRunResponse:
      description: get billingPreviewRun response
      properties:
        assumeRenewal:
          description: ''
          type: string
        batch:
          description: "The customer batch included in the billing preview run.       \n\n**Note**: This field is not available if you set the `zuora-version` request header to `314.0` or later [available versions](/api-references/api/overview/#section/API-Versions/Minor-Version).\n"
          type: string
        batches:
          description: "The customer batches included in the billing preview run. \n\n**Note**: This field is only available if you set the `zuora-version` request header to `314.0` or later [available versions](/api-references/api/overview/#section/API-Versions/Minor-Version).\n"
          type: string
        chargeTypeToExclude:
          description: 'The charge types excluded from the forecast run.

            '
          type: string
        createdById:
          description: 'The ID of the user who created the billing preview run.

            '
          type: string
        createdDate:
          description: 'The date and time when the billing preview run was created.

            '
          format: datetime
          type: string
        endDate:
          description: 'The date and time when the billing preview run completes.

            '
          format: datetime
          type: string
        errorMessage:
          description: 'The error message generated by a failed billing preview run.

            '
          type: string
        includingDraftItems:
          description: 'Whether draft document items are included in the billing preview run. By default, draft document items are not included.

            '
          type: boolean
        includingEvergreenSubscription:
          description: 'Indicates if evergreen subscriptions are included in the billing preview run.

            '
          type: boolean
        organizationLabels:
          description: "The organization(s) that the object belongs to. \n\nNote: This field is available only when the Multi-Org feature is enabled.            \n"
          items:
            properties:
              organizationId:
                description: 'The organization ID.

                  '
                type: string
              organizationName:
                description: 'The organization name.

                  '
                type: string
            type: object
          type: array
        resultFileUrl:
          description: 'The URL of the zipped CSV result file generated by the billing preview run. This file contains the preview invoice item data and credit memo item data for the specified customers.


            If the value of `storageOption` field is `Database`, the returned `resultFileUrl` field is null.


            **Note:** The credit memo item data is only available if you have Invoice Settlement feature enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see [Invoice Settlement Enablement and Checklist Guide](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement/Invoice_Settlement_Migration_Checklist_and_Guide) for more information.

            '
          type: string
        runNumber:
          description: 'The run number of the billing preview run.

            '
          type: string
        startDate:
          description: 'The date and time when the billing preview run starts.

            '
          format: datetime
          type: string
        status:
          description: "The status of the >billing preview run.\n\n**Possible values:** \n\n* 0: Pending\n* 1: Processing\n* 2: Completed\n* 3: Error\n* 4: Canceled\n"
          type: string
        storageOption:
          description: "The saving options. The default value is `Csv`.    \n"
          enum:
          - Csv
          - Database
          type: string
        succeededAccounts:
          description: 'The number of accounts for which preview invoice item data and credit memo item data was successfully generated during the billing preview run.


            **Note:** The credit memo item data is only available if you have Invoice Settlement feature enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see [Invoice Settlement Enablement and Checklist Guide](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement/Invoice_Settlement_Migration_Checklist_and_Guide) for more information.

            '
          type: integer
        success:
          description: Returns `true` if the request was processed successfully.
          type: boolean
        targetDate:
          description: "The target date for the billing preview run.          \n"
          format: date
          type: string
        totalAccounts:
          description: 'The total number of accounts in the billing preview run.

            '
          format: int32
          type: integer
        updatedById:
          description: 'The ID of the user who last updated the billing preview run.

            '
          type: string
        updatedDate:
          description: 'The date and time when the billing preview run was last updated.

            '
          format: date-time
          type: string
      type: object
x-tagGroups:
- name: Authentication
  tags:
  - OAuth
- name: Products
  tags:
  - Products
  - Catalog
  - Catalog Groups
  - Offers
  - Price Book Items
  - Product Rate Plans
  - Product Rate Plan Definitions
  - Product Rate Plan Charges
  - Product Charge Definitions
  - Product Rate Plan Charge Tiers
  - Zuora Revenue Integration
- name: Customer Accounts
  tags:
  - Accounts
  - Contacts
  - Contact Snapshots
- name: Orders and Subscriptions
  tags:
  - Sign Up
  - Orders
  - Order Actions
  - Order Line Items
  - Fulfillments
  - Ramps
  - Subscriptions
  - Rate Plans
- name: Advanced Consumption Billing
  tags:
  - Prepaid with Drawdown
- name: Usage
  tags:
  - Usage
- name: Billing Documents
  tags:
  - Delivery Adjustments
  - Billing Documents
  - Invoices
  - Credit Memos
  - Debit Memos
  - E-Invoicing
  - Invoice Schedules
  - Taxation Items
  - Sequence Sets
  - Operations
- name: Bill Runs
  tags:
  - Bill Run
  - Billing Preview Run
- name: Payment Methods
  tags:
  - Payment Methods
  - Custom Payment Method Types
  - Payment Method Updater
  - Payment Method Snapshots
  - Payment Method Transaction Logs
  - Hosted Pages
  - RSA Signatures
- name: Payments
  tags:
  - Payment Authorization
  - Payment Gateways
  - Payment Gateway Reconciliation
  - Payments
  - Payment Transaction Logs
  - Payment Runs
  - Payment Schedules
  - Refunds
- name: Finance
  tags:
  - Accounting Codes
  - Accounting Periods
  - Summary Journal Entries
  - Journal Runs
  - Mass Updater
- name: Events and Notifications
  tags:
  - Notifications
  - Custom Event Triggers
  - Custom Scheduled Events
- name: Custom Objects
  tags:
  - Custom Object Definitions
  - Custom Object Records
  - Custom Object Jobs
- name: System Health
  tags:
  - API Health
  - Bill Run Health
  - Electronic Payments Health
- name: Workflow
  tags:
  - Workflows
- name: Data Query
  tags:
  - Data Queries
- name: AQuA
  tags:
  - Aggregate Queries
- name: Deployment Manager
  tags:
  - Configuration Templates
- name: Multiple Organizations
  tags:
  - Data Labeling
- name: Order to Revenue
  tags:
  - Regenerate
- name: General-Purpose Operations
  tags:
  - Actions
  - Settings
  - Files
  - Imports
  - Custom Exchange Rates
  - Attachments
  - Describe