Zuora Settings API

openapi: 3.2.0
info:
  version: '2023-12-15'
  title: Reference Settings 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: Settings
  description: The Setting API provides a central API for managing settings in your Zuora tenant.
paths:
  /settings/listing:
    get:
      tags:
      - Settings
      summary: List all settings
      description: 'Get a list of all available settings in your tenant.


        The response message is by default in JSON format. If you want to receive all the available settings in csv format, include `Accept` in the header parameters and set it to `application/csv`.


        See a 200 response sample in JSON format that lists all available settings.


        See a 200 response sample in CSV format that lists all available settings.


        You can find a specific operation of an available setting item in your tenant from the 200 response body of this call. See the following common use cases of Settings API for how to operate on a specifc setting item.


        * Billing Rules:

        * Get a specific setting - Billing Rules

        * Update a specific setting - Billing Rules

        * Age Buckets:

        * Get Age Buckets

        * Update Age Buckets

        * Invoice Templates:

        * Get a specific Invoice Template

        * Get all Invoice Templates

        * Create a new Invoice Template

        * Update a specific Invoice Template

        * Delete a specific Invoice Template

        * Communications Profiles:

        * Create a new Communication Profile

        * Get a Communication Profile

        * Get all Communication Profiles

        * Modify a Communication Profile

        * Notification Definitions:

        * Get all notification definitions under a particular Communication Profile

        * Get a notification definition

        * Update a notification definition

        * Delete a notification definition

        * Chart of Accounts:

        * Get Chart of Accounts

        * Add a new Chart of Account

        * Quote Templates:

        * Get all Quote Templates

        * Get a specific Quote Template

        * Create a new Quote Template

        * Connect Tax Engines:

        * Create a Connect Tax Engine

        * Get a Connect Tax Engine

        * Update a Connect Tax Engine

        * Delete a Connect Tax Engine

        * Custom Fields:

        * View all custom fields

        * View custom fields of a specific object

        * Update custom fields of a specific object

        * Units of Measure:

        * Create a Unit of Measure

        * Get a Unit of Measure

        * Get all Units of Measure

        * Update a Unit of Measure

        * Delete a Unit of Measure'
      operationId: GET_ListAllSettings
      parameters:
      - $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding'
      - $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding'
      - $ref: '#/components/parameters/GLOBAL_HEADER_Authorization_OAuth'
      - $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Entity_Ids_Single'
      - $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Org_Ids'
      - $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Track_Id'
      - name: Accept
        in: header
        required: false
        description: 'Specifies response media type. If you omit the `Accept` header parameter, the response body is by default in JSON format. If you include `Accept` header parameter and set it to `application/csv`, the response body is in csv format.

          '
        schema:
          type: string
          maxLength: 64
      responses:
        200:
          description: OK
          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
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListAllSettingsResponse'
              example:
                settings:
                - key: AccountingRules
                  description: Accounting Rules settings
                  context: Entity
                  pathPattern: /accounting-rules
                  httpOperations:
                  - method: GET
                    url: /settings/accounting-rules
                    parameters: []
                    responseType: {}
                  - method: PUT
                    url: /settings/accounting-rules
                    parameters: []
                    requestType: {}
                    responseType: {}
            application/csv:
              schema:
                $ref: '#/components/schemas/ListAllSettingsResponse'
  /settings/batch-requests:
    post:
      tags:
      - Settings
      summary: Submit settings requests
      description: 'Submit a batch of settings requests by this single API operation.


        By default, one batch settings request can contain a maximum of 100 single operation requests, including:

        * All the single requests in the process batch settings request.

        * All the children requests of the single requests.


        This maximum value is configurable.'
      operationId: POST_ProcessSettingsBatchRequest
      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'
      - $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Entity_Ids_Single'
      - $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Org_Ids'
      - $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Track_Id'
      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: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettingsBatchResponse'
              example:
                responses:
                - id: '1'
                  method: GET
                  url: /billing-rules
                  children: []
                  response:
                    status: 200 OK
                    body:
                      oneTimeCreditBack: false
                      proratePeriodOfRecurringCharge: true
                      prorateRecurringWeeklyCharges: true
                      prorateRecurringMonthlyCharges: true
                      prorateUsageMonthlyCharges: true
                      prorateUsageWeeklyCharges: true
                      daysInMonth: UseActualDays
                      prorationUnit: ProrateByDay
                      allowAutoPostBillRun: true
                      autoPostBillRunDefaultValue: true
                      includeNegativeInvoice: true
                      includeChildUsage: true
                      rateUsageIndividually: true
                      transactionOnSubscription: true
                      taxAddressOwner: SubscriptionOwner
                      takeContactSnapshot: true
                      taxInclusiveRoundingRule: RoundingNetAmount
                      legalDocumentGeneratingRule: GroupByOriginalSRPC
                      recurringChargeStyle: Advanced
                      preGenerateInvoicePdf: false
                      timeOfDailyInvoice: 0
                      notSendZeroItemsForTax: false
                      taxRateChangeOption: OneTaxItem
                      availableToCreditValidationLevel: HeaderLevel
                      invoicePastEndOfTerm: false
                      billToTermEndWhenAutoRenew: true
                      zuoraTaxRoundingDiffDispersion: false
                - id: '2'
                  method: GET
                  url: /accounting-rules
                  children: []
                  response:
                    status: 200 OK
                    body:
                      allowBlankAccountingCodes: true
                      allowCreationInClosedPeriod: true
                      allowUsageInClosedPeriod: true
                      allowRevenueScheduleNegativeAmounts: true
                      differentCurrencies: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SettingsBatchRequest'
        required: true
components:
  parameters:
    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
    GLOBAL_HEADER_Authorization_OAuth:
      name: Authorization
      in: header
      required: true
      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_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_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_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_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_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
  schemas:
    ChildrenSettingValueRequest:
      properties:
        body:
          $ref: '#/components/schemas/BodyInSettingValueRequest'
        id:
          description: 'The id of the request. You can set it to any string. It must be unique within the whole batch.

            '
          type: string
        method:
          description: 'One of the HTTP methods supported by the setting endpoint, for example, GET,PUT,POST or DELETE.

            '
          enum:
          - GET
          - HEAD
          - POST
          - PUT
          - PATCH
          - DELETE
          - OPTIONS
          - TRACE
          type: string
        url:
          description: 'The relative URL of the setting. It is the same as in the `pathPattern` field in the response body of [Listing all settings](/api-references/api/operation/GET_ListAllSettings). For example, `/billing-rules`.

            '
          type: string
      title: childSettingsRequest
      type: object
    SettingValueRequest:
      properties:
        body:
          $ref: '#/components/schemas/BodyInSettingValueRequest'
        children:
          description: 'An array of requests that can only be executed after its parent request has been executed successfully.

            '
          items:
            $ref: '#/components/schemas/ChildrenSettingValueRequest'
          type: array
        id:
          description: 'The id of the request. You can set it to any string. It must be unique within the whole batch.

            '
          type: string
        method:
          description: 'One of the HTTP methods supported by the setting endpoint, for example, GET,PUT,POST or DELETE.

            '
          enum:
          - GET
          - HEAD
          - POST
          - PUT
          - PATCH
          - DELETE
          - OPTIONS
          - TRACE
          type: string
        url:
          description: 'The relative URL of the setting. It is the same as in the `pathPattern` field in the response body of [Listing all Settings](/api-references/api/operation/GET_ListAllSettings). For example, `/billing-rules`.

            '
          type: string
      title: settingsRequest
      type: object
    SettingItemHttpRequestParameter:
      properties:
        description:
          description: The description of the paramter.
          type: string
        name:
          description: The name of the parameter.
          type: string
      title: httpRequestParameter
      type: object
    ListAllSettingsResponse:
      properties:
        settings:
          items:
            $ref: '#/components/schemas/SettingItemWithOperationsInformation'
          type: array
      title: allSettings
      type: object
    SettingItemHttpOperation:
      properties:
        method:
          description: One of the HTTP methods supported by the setting endpoint, for example, GET,PUT,POST or DELETE.
          enum:
          - GET
          - HEAD
          - POST
          - PUT
          - PATCH
          - DELETE
          - OPTIONS
          - TRACE
          type: string
        parameters:
          description: An array of paramters required by this operation.
          items:
            $ref: '#/components/schemas/SettingItemHttpRequestParameter'
          type: array
        requestType:
          description: JSON Schema for the request body of this operation.
          type: object
        responseType:
          description: JSON Schema for the response body of this operation.
          type: object
        url:
          description: The endpoint url of the operation method. For example, `/settings/billing-rules`.
          type: string
      title: httpOperation
      type: object
    SettingValueResponse:
      properties:
        body:
          $ref: '#/components/schemas/BodyInSettingValueReponse'
        errorMessages:
          description: 'An array of error messages if errors occur when executing the request.

            '
          items:
            type: string
          type: array
        status:
          description: 'User readable response status, for example, 502 BAD_GATEWAY.

            '
          type: string
      title: settingsValueResponse
      type: object
    BodyInSettingValueRequest:
      additionalProperties: true
      description: Request payload if any
      title: settingsRequestBody
      type: object
    SettingItemWithOperationsInformation:
      properties:
        context:
          description: The context where this setting item is effective.
          enum:
          - Tenant
          - Entity
          - User
          - None
          type: string
        description:
          description: The description of the setting item as you see from Zuora UI.
          type: string
        httpOperations:
          description: An array of HTTP operation methods that are supported on this setting endpoint.
          items:
            $ref: '#/components/schemas/SettingItemHttpOperation'
          type: array
        key:
          description: The unique key to distinguish the setting item.
          type: string
        pathPattern:
          description: The path pattern of the setting endpoint, relative to `/settings`. For example, `/billing-rules`.
          type: string
      title: settingItem
      type: object
    SettingsBatchResponse:
      properties:
        responses:
          items:
            $ref: '#/components/schemas/SettingValueResponseWrapper'
          type: array
      title: batchResponse
      type: object
    SettingsBatchRequest:
      example:
        requests:
        - id: '1'
          method: GET
          url: /billing-rules
        - id: '2'
          method: GET
          url: /accounting-rules
      properties:
        requests:
          items:
            $ref: '#/components/schemas/SettingValueRequest'
          type: array
      type: object
    SettingValueResponseWrapper:
      properties:
        id:
          description: 'The Id of the corresponding request.

            '
          type: string
        method:
          description: 'The HTTP method. It is the same as that of the corresponding request.

            '
          enum:
          - GET
          - HEAD
          - POST
          - PUT
          - PATCH
          - DELETE
          - OPTIONS
          - TRACE
          type: string
        response:
          $ref: '#/components/schemas/SettingValueResponse'
        url:
          description: 'The url as specified in the corresponding request.

            '
          type: string
      title: settingsValueResponseWrapper
      type: object
    BodyInSettingValueReponse:
      additionalProperties: true
      description: Response body if the request is executed successfully.
      title: settingsResponseBody
      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