Some of our older APIs are no longer recommended but still available, not
affecting any existing integration. To find related API documentation, see
[Older API
Reference](https://developer.zuora.com/v1-api-reference/older-api/overview/).
### More OpenAPI specification options
To support your integration with our OpenAPI specifications, whether using in-house solutions or third-party tools, we provide the following resources:
- **Order-to-Cash operations (detailed)**: Download Order-to-Cash OpenAPI spec, which includes full descriptions and examples
- **Order-to-Cash operations (compact)**: Download Order-to-Cash Compact OpenAPI spec, which excludes descriptions and code examples.
- **Full OpenAPI spec (compact)**: Download Compact OpenAPI Spec, which covers the entire API set without descriptions or samples.
If you need a different API specification beyond the options above, contact Zuora Global Support, and we will provide a custom spec tailored to your needs.
servers:
- url: https://rest.test.zuora.com
description: US Developer & Central Sandbox (incl. Test Drive)
- url: https://rest.sandbox.na.zuora.com
description: US API Sandbox Cloud 1
- url: https://rest.apisandbox.zuora.com
description: US API Sandbox Cloud 2
- url: https://rest.na.zuora.com
description: US Production Cloud 1
- url: https://rest.zuora.com
description: US Production Cloud 2
- url: https://rest.test.eu.zuora.com
description: EU Developer & Central Sandbox
- url: https://rest.sandbox.eu.zuora.com
description: EU API Sandbox
- url: https://rest.eu.zuora.com
description: EU Production
- url: https://rest.test.ap.zuora.com
description: APAC Developer & Central Sandbox
- url: https://rest.ap.zuora.com
description: APAC Production
security:
- bearerAuth: []
tags:
- description: |
Accounting Codes are commonly referred to as General Ledger Accounts or General Ledger Account Codes. In Zuora, the use of accounting codes are optional but recommended.
This section contains the operations that allow you to create, update, get, delete, activate, or deactivate accounting codes in Zuora.
name: Accounting Codes
- description: |
A key step in configuring Finance is to create accounting periods in Zuora to match your company's financial calendar.
This allows Zuora to produce reports and data exports organized by accounting periods, and to perform the work of closing the accounting periods for the revenue sub-ledger.
name: Accounting Periods
- description: |
Some operations in this section are similar to each other, but are
provided for different use scenarios. You should choose the one that best suits
your needs.
For example, the [Retrieve an account](https://developer.zuora.com/v1-api-reference/api/operation/GET_Account/) operation retrieves the basic information of an account, such as bill-to and sold-to contacts, billing and payments setup information, and metrics data for the account.
The [Retrieve an account summary](https://developer.zuora.com/v1-api-reference/api/operation/GET_AccountSummary/) operation returns the more detailed information of an account, such as bill-to and sold-to contacts, subscriptions, invoices, payments, and usages associated with this account.
name: Accounts
- description: |
Delivery Adjustments are used to handle end customer delivery complaints for the Delivery Pricing charge model. For more information, see Delivery Adjustments.
name: Delivery Adjustments
- description: |
Use the Bill Run call to create ad hoc bill runs and Post, Cancel, Query, and Delete bill runs.
For more information about bill runs, see Bill runs.
name: Bill Run
- description: |
Billing documents include invoices, credit memos, and debit memos.
**Note**: Credit memos and debit memos are only available if you have the Invoice Settlement feature enabled.
name: Billing Documents
- 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.
name: Billing Preview Run
- description: |
**Note** - The APIs in this section are legacy APIs. Zuora recommends using the newer, faster APIs for managing products and catalogs more efficiently instead.
For more information, see our latest Commerce API.
The Zuora Billing product catalog is where you define your products
and pricing. The product catalog's ability to handle sophisticated pricing models
gives you the power to easily adapt your pricing to customer and market needs,
to grow your business and drive more revenue.
name: Catalog
- description: |
**Note** - The APIs in this section are legacy APIs. Zuora recommends using the newer, faster APIs for managing products and catalogs more efficiently instead.
For more information, see our latest Commerce API.
A catalog group is used to group a list of product rate plans with
a specific grade.
name: Catalog Groups
- description: |
The Commerce APIs provide access to product catalog, plans, charges, and order
management functionality in Zuora. These endpoints are used to create, update,
and query product rate plans, charges, and dynamic pricing details that drive
subscription and billing behavior.
In a typical use case, the Commerce APIs are called to provision new products
or plans in the catalog, configure dimensional pricing, or submit orders that
create and modify subscriptions.
Changes made with these APIs affect the product catalog and active subscriptions,
depending on the endpoint. Catalog changes update future subscription behavior,
while order operations directly impact customer subscriptions in real time.'
name: Commerce
- description: |
A commitment represents a minimum or maximum spend amount a customer is obligated to pay within a spend period, compared with customer's actual fees incurred in connection with customer's accounts and their use of applicable products.
The Commitments API allows you to retrieve details of the commitments a customer has.
name: Commitments
- description: |
Every time a contact is updated a snapshot is taken.
name: Contact Snapshots
- description: |
Configurable Payment Retry APIs use basic authentication. 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.
Click the drop-down arrow at the end of an endpoint to display the full endpoint. To learn more about the configuration and usage of Configurable Payment Retry, see [Configurable Payment Retry](https://knowledgecenter.zuora.com/Zuora_Payments/Configure_payment_orchestration/Payment_Retry/Configurable_Payment_Retry).
name: Configurable Payment Retry
- description: |
A contact defines the customer who holds an account or who is otherwise a person to contact about an account. An account requires a contact for the `BillToId` and `SoldToId` fields before the account can be active.
name: Contacts
- description: |
Credit memos reduce invoice and account balances. By applying one or more credit memos to invoices with positive balances, you can reduce the invoice balances in the same way that applying a payment to an invoice.
For more information about credit memos, see Credit and debit memos.
name: Credit Memos
- description: |
Open Payment Method (OPM) service is a framework developed by Zuora, which allows you to integrate your custom payment method to Zuora subscription, billing, and revenue management in a dynamic and flexible manner. With the support of the OPM service, you are able to define your custom payment method types and create custom payment methods of the defined types. The custom payment method of the defined type can only be used with the custom payment gateway that you set up through the Universal Payment Connector (UPC) service. It cannot be used with the Zuora out-of-box gateway integrations such as GoCardless, Stripe, etc.
You can define up to 20 custom payment method types for one tenant. Do not define your fields with the [Zuora-reserved fields](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/MB_Set_up_custom_payment_gateways_and_payment_methods/C_Configure_and_manage_your_custom_payment_method_types_through_Zuora_REST_APIs#Zuora-reserved_fields).
See [Set up custom payment gateways and payment methods](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/MB_Set_up_custom_payment_gateways_and_payment_methods) for more information about the OPM and UPC services.
Note: You can only use the bearer token to access the "Custom Payment Method Types" API operations. Access with `apiAccessKeyId` and `apiSecretAccessKey` is not supported.
name: Custom Payment Method Types
- description: |
Debit memos increase the amount a customer owes. It is a separate document from the invoice. Debit memos can be used to correct undercharging on an invoice or to levy ad hoc charges outside the context of a subscription. Just like an invoice, debit memo balances can be settled by applying either a payment or a credit memo.
For more information about debit memos, see Credit and debit memos.
name: Debit Memos
- description: |
With the E-Invoicing feature, Zuora supports electronic invoices through an integration with partners that have a local presence, where required, which guarantees compliance with local invoice regulations.
All the operations in this section are available only if you have the E-Invoicing feature enabled.
name: E-Invoicing
- description: |
Fulfillments are subordinate objects attached to their related order line item. Fulfillment items are subordinate objects attached to their related fulfillment.
For more information, see Overview of Order Line Items.
name: Fulfillments
- description: |
Hosted payment pages allow your customers to set up a payment method, such as providing a credit card. Since it only handles the payment method, it is suitable for a simple workflow or a complex multi-page, multi-product workflow.
For more information, see Hosted Payment Pages.
name: Hosted Pages
- description: |
Use invoice schedules to trigger invoice generation processes.
For more information about invoice schedules, see Billing Schedule overview.
name: Invoice Schedules
- description: |
Invoices provides information about customers' accounts for invoices, for examples, dates, status, and amounts.
For more information about invoices, see Invoice.
name: Invoices
- description: |
Use journal runs to automatically create summary journal entities that are suitable for importing into your general ledger system.
For more information about journal runs, see Journal Runs.
name: Journal Runs
- description: |
Use mass updater to perform mass actions more easily.
For more information about mass updater, see Mass Updater.
name: Mass Updater
- description: The Zuora Mediation APIs provide a comprehensive set of endpoints to manage, test, run, and monitor usage meters. These APIs support actions such as running or testing specific meter versions, importing and exporting meter configurations, managing input files, performing event store operations, and ingesting usage data in real time via streaming. All APIs follow a consistent response structure to simplify integration and error handling. Use these APIs to automate and streamline your usage processing pipeline—from data ingestion to transformation and billing.
name: Meters
- description: |
Zuora recommends that you use OAuth v2.0 to authenticate to the Zuora REST API.
You must first create an OAuth client in the Zuora UI before using the [Create an OAuth token](https://developer.zuora.com/api-references/api/operation/createToken) operation to create an OAuth token. See [Authentication](https://developer.zuora.com/rest-api/general-concepts/authentication/) for more information.
name: OAuth
- description: |
The Object Query API contains GET operations that allow you to query objects in your Zuora tenant in an efficient, consistent, and flexible manner.
With the `expand[]` and `filter[]` query parameters, you have the flexibility to retrieve related object information in a single call and define the returned response that best suits your needs.
You can also use the `fields[]` query parameter to define which fields are returned in the response for a given object.
The `sort[]` query parameter allows you to sort the results in ascending or descending order based on the specified field.
These parameters are case-insensitive matching.
For general Object Queries limitations and comprehensive introduction to these query parameters, see [Expand, filter, fields, and sort](https://developer.zuora.com/docs/guides/expand-filter-fields-sort/).
For filterable, expandable, and sortable fields on each object, refer to the Query Parameters section for each API operation.
name: Object Queries
- description: |
Use operations to generate invoices and credit memos, collect payments for posted invoices, and generate previews of future invoice items for customer accounts.
name: Operations
- description: |
Orders are contractual agreements between merchants and customers.
You can create multiple subscriptions and subscription amendments at once in a single order. All the operations on subscriptions in orders are done by order actions.
You can also create order line items to support your non-subscription based business models.
Zuora calculates order delta metrics when orders take place. You can retrieve order delta metrics and measure billed and unbilled amounts by order.
For more information about Orders, see Overview Of Orders.
To learn how orders interacts with billing accounts, subscriptions, and product catalog, see [Zuora object model](https://developer.zuora.com/v1-api-reference/object-model/).
name: Orders
- description: |
You need to have the [Orders](https://knowledgecenter.zuora.com/Zuora_Billing/Subscriptions/Orders) or [Orders Harmonization](https://knowledgecenter.zuora.com/Zuora_Billing/Subscriptions/Orders/Orders_Harmonization) feature enabled to use this API.
name: Order Actions
- description: |
Use order line item to launch non-subscription and unified monetization business models in Zuora, in addition to subscription business models.
For more information about order line items, see Order Line Items.
name: Order Line Items
- description: |
Use payment gateways to pass authorization, payments, and settlement data securely to and from the merchant's website to the merchant's processor.
For more information about payment gateways, see Payment Gateways.
name: Payment Gateways
- description: |
Gateway reconciliation is the process of verifying that the electronic payment and refund transactions processed in Zuora match the transactions reported by the gateway.
For example, if Zuora processed 200 transactions through a gateway, you should see the same number of transactions on the gateway's reconciliation report, sometimes also called the settlement report.
You can complete the following Gateway Reconciliation tasks through API:
- [Settle a payment](https://developer.zuora.com/api-references/api/operation/POST_SettlePayment/)
- [Reject a payment](https://developer.zuora.com/api-references/api/operation/POST_RejectPayment/)
- [Reverse a payment](https://developer.zuora.com/api-references/api/operation/POST_ReversePayment/)
- [Reconcile a refund](https://developer.zuora.com/api-references/api/operation/POST_ReconcileRefund/)
name: Payment Gateway Reconciliation
- description: |
A Payment Method Snapshot is a copy of the particular Payment Method used in a transaction. If the Payment Method is deleted, the Snapshot continues to retain the data used in each of the past transactions.
As such, the Snapshot helps with display of historical transactions, integrations to external systems, and reporting.
name: Payment Method Snapshots
- description: |
The PaymentMethodTransactionLog object contains payment method transaction log data.
You can use the [CRUD: Retrieve a payment method transaction log](https://developer.zuora.com/v1-api-reference/api/operation/Object_GETPaymentMethodTransactionLog/) operation to export such data.
name: Payment Method Transaction Logs
- description: |
Payment methods represents payment method details associated with a customer account.
name: Payment Methods
- description: |
Zuora Payment Method Updater (PMU) enables merchants to automatically incorporate changes made to a customer's credit cards. For more information about Zuora PMU, see Payment Method Updater.
name: Payment Method Updater
- description: |
Use payment runs to collect payments using electronic payment methods, for example, credit cards and ACH.
For more information about payment runs, see Payment Runs.
name: Payment Runs
- description: |
Payment profiles enable payment flexibility for subscribers by allowing payment methods to be associated with specific subscriptions.
To learn more about the configuration and usage of Payment Profiles, see Payment Profiles.
name: Payment Profiles
- description: |
Use payment schedules to split invoice or account balances into several installments and automatically process payments for the installments.
For more information about payment schedules, see Payment Schedules.
name: Payment Schedules
- description: |
Use payment transaction logs to export logs of all transactions from Zuora to the Gateway for Payments.
name: Payment Transaction Logs
- description: |
The Delayed Capture feature allows you to authorize the availability of funds for a transaction but delay the capture of funds until a later time.
You can use the [Create authorization](https://developer.zuora.com/api-references/api/operation/POST_CreateAuthorization/) operation to authorize a payment amount before capturing the payment.
Subsequently, you can use [Create a payment](https://developer.zuora.com/api-references/api/operation/POST_CreatePayment) or [Create an order](https://developer.zuora.com/api-references/api/operation/POST_Order/) to capture the authorized funds, or use [Cancel authorization](https://developer.zuora.com/api-references/api/operation/POST_CancelAuthorization) to cancel the authorization.
name: Payment Authorization
- description: |
Use payments to process payments, for example, automate recurring payments, manage overpayments, and create refunds.
For more information about payments, see Payments.
name: Payments
- description: |
The Prepaid with Drawdown feature is a pricing model for consumption-based services, such as data storage. Under this model, customers pay upfront to receive a number of units, usually for a period of time like a month or a year. Then they consume against that prepayment balance in a use-it-or-lose-it fashion, with a possibility of topping up more units or being charged for any overage. This model strikes a balance between upfront commitment and the pure pay-as-you-go pricing models. For more information, see Prepaid with Drawdown.
name: Prepaid with Drawdown
- description: |
**Note** - The APIs in this section are legacy APIs. Zuora recommends using the newer, faster APIs for managing products and catalogs more efficiently instead.
For more information, see our latest Commerce API.
Use product charge definitions to define the attributes that can determine
the charge behavior, such as billing attributes, pricing attributes, taxation
attributes, or accounting attributes.\n\nThe Product Charge Definition object
is in the **Early Adopter** phase. We are actively soliciting feedback from
a small set of early adopters before releasing it as generally available. If
you are interested, please reach out to your CSM.
name: Product Charge Definitions
- description: |
**Note** - The APIs in this section are legacy APIs. Zuora recommends using the newer, faster APIs for managing products and catalogs more efficiently instead.
For more information, see our latest Commerce API.
Use product rate plan definitions to reuse charges in different product
rate plans. The Product Rate Plan Definition object is in the **Early Adopter**
phase. We are actively soliciting feedback from a small set of early adopters
before releasing it as generally available. If you are interested, please reach
out to your CSM.
name: Product Rate Plan Definitions
- description: |
**Note** - The APIs in this section are legacy APIs. Zuora recommends using the newer, faster APIs for managing products and catalogs more efficiently instead.
For more information, see our latest Commerce API.
To manage product rate plan charge tiers, use the [Product Rate Plan
Charges](https://developer.zuora.com/api-references/api/tag/Product-Rate-Plan-Charges)
operations instead to update the corresponding product rate plan charge with all
the tiers.
name: Product Rate Plan Charge Tiers
- description: |
**Note** - The APIs in this section are legacy APIs. Zuora recommends using the newer, faster APIs for managing products and catalogs more efficiently instead.
For more information, see our latest Commerce API.
A product rate plan charge represents a charge model or a set of fees
associated with a product rate plan, which is the part of a product that your
customers subscribe to. Each product rate plan can have multiple product rate
plan charges.
Product rate plan charges can be of three types: one-time fees, recurring fees,
and usage fees. For example, the $50 activation fee for the Topaz product rate
plan is a one-time product rate plan charge.
name: Product Rate Plan Charges
- description: |
**Note** - The APIs in this section are legacy APIs. Zuora recommends using the newer, faster APIs for managing products and catalogs more efficiently instead.
For more information, see our latest Commerce API.
A product rate plan is the part of a product that your customers subscribe
to. Each product can have multiple product rate plans, and each product rate plan
can have multiple product rate plan charges, which are fees for products and their
product rate plans.
name: Product Rate Plans
- description: |
**Note** - The APIs in this section are legacy APIs. Zuora recommends using the newer, faster APIs for managing products and catalogs more efficiently instead.
For more information, see our latest Commerce API.
A product is an item or service that your company sells. In the subscription
economy, a product is generally a service that your customers subscribe to rather
than a physical item that they purchase one time. For example, customers subscribe
to a service that provides them a car when and where they need a car rather than
buying a car outright.
A Product object contains all of the items in a specific product, especially product
rate plans and product rate plan charges. Each Product object can have multiple
rate plans, which in turn can each have multiple rate plan charges. Each rate
plan charge can have multiple tiers. Taken together, all of these items create
a single product.
Customers subscribe to products that are in your product catalog. Product objects
collectively compose your product catalog. You create your product catalog by
creating products. As soon as you create your first product, you create your product
catalog.
name: Products
- description: |
A Ramp is a time container to associate with rate plan charges in your subscription. Inside the Ramp, you can further define a set of Ramp Intervals (time-based periods) where products or pricing can change. These periods are sub time containers to enable you to report out-of-the-box metrics based on Ramp Intervals.
**Notes**: You must have both the Ramps feature and Orders feature enabled for your tenant to use the Ramps operations.
For more information, see Ramps and Ramp Metrics.
name: Ramps
- description: |
A rate plan is part of a subscription or an amendment to a subscription, and it comes from a product rate plan. Like a product and its product rate plans, a subscription can have one or more rate plans.
Rate plans are sometimes called subscription rate plans. Rate plans that are part of an amendment are sometimes called amendment rate plans.
Rate plans represent a price or a collection of prices for a service you sell. An individual rate plan contains all charges specific to a particular subscription.
name: Rate Plans
- description: |
Zuora allows you to issue and track refunds on payments. Similar to external payments, users can enter external refunds to track refunds that have been performed outside of Zuora Payments (for example, by issuing a check).
In addition, you can make electronic refunds using our supported payment gateways, which will automatically refund money to the customer.
name: Refunds
- description: |
The REST API used in Payment Pages 2.0 are CORS (Cross-Origin Resource Sharing) enabled and therefore requires a digital signature.
You can use the [Generate an RSA signature](https://developer.zuora.com/v1-api-reference/api/operation/POST_RSASignatures/) operation to generate the required digital signature and token for a Payment Pages 2.0 form, then use the [Decrypt an RSA signature](https://developer.zuora.com/v1-api-reference/api/operation/POST_DecryptRSASignatures/) operation to decrypt the signature to validate the signature and key."
name: RSA Signatures
- description: |
You can create billing document sequence sets through the REST API or the Zuora UI, allowing distinct numbering sequences for billing documents, payments, and refunds.
To create a billing document sequence set through the Zuora UI, see Create Billing Document Sequence Sets for more information.
name: Sequence Sets
- description: |
A light-weight API to sign up customers and subscribe.
You need to have the [Orders](https://knowledgecenter.zuora.com/Zuora_Billing/Subscriptions/Orders) or [Orders Harmonization](https://knowledgecenter.zuora.com/Zuora_Billing/Subscriptions/Orders/Orders_Harmonization) feature enabled to use this API.
name: Sign Up
- description: |
A subscription is a product or service that has recurring charges,
such as a monthly flat fee or charges based on usage. Subscriptions can also include
one-time charges, such as activation fees. Every subscription must be associated
with an account. At least one active account must exist before any subscriptions
can be created.
For more information, see Subscriptions.
name: Subscriptions
- description: |
An omnichannel subscription is a subscription originating from external and source systems, such as the Apple App Store, Google Play Store, and Roku Store.
To create, update, delete, or retrieve an omnichannel subscription, you must turn on the Omni-Channel Subscription feature. For more information, see Omni-Channel Subscription.
name: Omnichannel Subscriptions
- description: |
The change histories of single version subscriptions.
**Note**: To access the change histories, you must turn on the following features:
- Orders
- Single Version Subscription
name: Subscription Change History
- description: |
A summary journal entry is a summary of Zuora transaction amounts organized by accounting code and general ledger segments. A segment adds more reporting granularity through business dimensions, such as country or product.
For more information, see Summary Journal Entries Introduction
name: Summary Journal Entries
- description: |
The Summary Statement feature provides a comprehensive overview of billing activities for each account using HTML templates that compile data like invoices, credit memos, payments, and more. The associated APIs help automate the creation and management of these statements. See Account Summary Statements for more information.
name: Summary Statements
- description: |
The TaxationItem object is used to add a tax amount to an invoice item. In the typical use case, the tax amount that you specify in the object is calculated by Z-Tax or a third-party tax engine such as Avalara or Connect tax engine.
Changes that you make with this object affect the product charges in your product catalog, but not the charges in existing subscriptions.
name: Taxation Items
- description: |
Consumption of a billable service or resource (such as database storage space or bundles of emails sent) provides the basis for some charge models - simple usage, tiered pricing, or volume pricing.
To make this work, usage must be tracked in the system and usage charges must be calculated and invoiced.
Usage is always billed in arrears - for example, you might bill customers in February for their January usage. Usage can be billed on a recurring monthly, quarterly, semi-annual, or annual basis.
### Limitations for dynamic pricing usage charges
Legacy Billing Usage APIs (for example, "Upload a usage file" and the "CRUD: Create/Update/Delete a usage record" operations) do not support usage records that are associated with a dynamic pricing usage charge. When a usage record is associated with a product rate plan charge that is configured for dynamic pricing, these endpoints reject the request and do not create, update, or delete the record. For dynamic pricing usage charges, usage events must be ingested through Mediation (for example, via Meters and the Rating processor) rather than through the legacy Billing usage upload APIs.
For more information about working with usage data, see Usage.
name: Usage
- description: |
**Note:** You can only use the operations in this section if you have the Billing - Revenue Integration feature enabled. See Billing - Revenue Integration for more information.
The APIs in this section are legacy APIs. Zuora recommends using the newer, faster APIs for managing products and catalogs more efficiently instead. For more information, see our latest Commerce API.
name: Zuora Revenue Integration
paths:
/oauth/token:
post:
security: []
description: |
Creates a bearer token that enables an OAuth client to authenticate with the Zuora REST API. The OAuth client must have been created using the Zuora UI. See [Authentication](https://developer.zuora.com/rest-api/general-concepts/authentication/) for more information.
**Note:** When using this operation, do not set any authentication headers such as `Authorization`, `apiAccessKeyId`, or `apiSecretAccessKey`.
You should not use this operation to generate a large number of bearer tokens in a short period of time; each token should be used until it expires. If you receive a 429 Too Many Requests response when using this operation, reduce the frequency of requests. This endpoint is rate limited by IP address.
For the rate limit information of authentication, see [Rate and concurrent request limits](https://developer.zuora.com/rest-api/general-concepts/rate-concurrency-limits/).
operationId: createToken
parameters:
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Track_Id'
- name: Zuora-Entity-Ids
in: header
required: false
description: |
An entity ID if you have Multi-entity enabled.
The value must be a 36-character UUID that contains hyphens(`-`).
If your entity ID is not a valid UUID, convert it to a valid UUID before specifying this parameter.
schema:
type: string
format: uuid
example: 11e643f4-a3ee-8bad-b061-0025904c756d
requestBody:
content:
application/x-www-form-urlencoded:
schema:
properties:
client_id:
description: |
The Client ID of the OAuth client.
maxLength: 36
minLength: 36
type: string
client_secret:
description: |
The Client Secret that was displayed when the OAuth client was created.
maxLength: 42
type: string
grant_type:
description: |
The OAuth grant type that will be used to generate the token. The value of this parameter must be `client_credentials`.
enum:
- client_credentials
type: string
required:
- client_id
- client_secret
- grant_type
type: object
required: true
responses:
'200':
content:
application/json:
examples:
response:
value:
access_token: c652cbc0ea384b9f81856a93a2a74538
expires_in: 3599
jti: c652cbc0ea384b9f81856a93a2a74539
scope: user.7c4d5433dc234c369a01b9719ecd059f entity.1a2b7a37-3e7d-4cb3-b0e2-883de9e766cc entity.c92ed977-510c-4c48-9b51-8d5e848671e9 service.echo.read tenant.19
token_type: bearer
schema:
$ref: '#/components/schemas/tokenResponse'
description: OK
headers:
X-RateLimit-Limit-minute:
description: |
The rate limit of this operation, in requests per minute. See [rate limits](https://developer.zuora.com/docs/guides/rate-limits/) for more information.
schema:
type: integer
X-RateLimit-Remaining-minute:
description: |
The number of requests that you may make in the next minute. See [rate limits](https://developer.zuora.com/docs/guides/rate-limits/) for more information.
schema:
type: integer
Zuora-Request-Id:
description: |
The Zuora internal identifier of the API call. You cannot control the value of this header.
schema:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
'429':
description: Too Many Requests
headers:
X-RateLimit-Limit-minute:
description: |
The rate limit of this operation, in requests per minute. See [rate limits](https://developer.zuora.com/docs/guides/rate-limits/) for more information.
schema:
type: integer
X-RateLimit-Remaining-minute:
description: |
The number of requests that you may make in the next minute. See [rate limits](https://developer.zuora.com/docs/guides/rate-limits/) for more information.
schema:
type: integer
Zuora-Request-Id:
description: |
The Zuora internal identifier of the API call. You cannot control the value of this header.
schema:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
summary: Create an OAuth token
tags:
- OAuth
x-code-samples:
- label: Curl
lang: curl
source: |
curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d "client_id=b64e42ba-7e1a-4bc6-9146-5e1b420306b5" --data-urlencode "client_secret=dOFENLWU193EEoEsWjPZrcjLKVr5OrN1HC9Kqg" -d "grant_type=client_credentials" "https://rest.zuora.com/oauth/token"
/v1/object/product:
post:
description: ''
operationId: Object_POSTProduct
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_REQUEST_rejectUnknownFields'
- $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'
- $ref: '#/components/parameters/GLOBAL_HEADER_X_Zuora_WSDL_Version'
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Version'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ProxyCreateProduct'
required: true
responses:
'200':
content:
application/json:
examples:
response:
value:
Id: 2c93808457d787030157e03246ae5129
Success: true
schema:
$ref: '#/components/schemas/ProxyCreateOrModifyResponse'
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'400':
content:
application/json:
examples:
response:
value:
Errors:
- Code: INVALID_VALUE
Message: The account number 123xProxy is invalid.
Success: false
schema:
$ref: '#/components/schemas/ProxyBadRequestResponse'
description: ''
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'401':
content:
application/json:
examples:
response:
value:
message: Authentication error
schema:
$ref: '#/components/schemas/ProxyUnauthorizedResponse'
description: Unauthorized
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information.
schema:
type: number
WWW-Authenticate:
description: |
The value of this header is:
```
Basic realm=Zuora API, ZSession realm=Zuora API, Bearer realm=Zuora API
```
schema:
enum:
- Basic realm=Zuora API, ZSession realm=Zuora API, Bearer realm=Zuora API
type: string
Zuora-Request-Id:
description: |
The Zuora internal identifier of the API call. You cannot control the value of this header.
schema:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
summary: 'CRUD: Create a product'
tags:
- Products
/v1/object/product/{id}:
get:
description: Retrieve a specific product.
operationId: Object_GETProduct
parameters:
- $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding'
- $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding'
- $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'
- $ref: '#/components/parameters/GLOBAL_HEADER_X_Zuora_WSDL_Version'
- description: Object fields to return
in: query
name: fields
required: false
schema:
type: string
- description: Object id
in: path
name: id
required: true
schema:
type: string
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Version'
responses:
'200':
content:
application/json:
examples:
response:
value:
CreatedById: 2c93808457d787030157e02e62af2097
CreatedDate: '2016-10-20T05:42:05.000+02:00'
Description: Create product via API_new
EffectiveEndDate: '2066-10-20'
EffectiveStartDate: '1966-10-20'
Id: 2c93808457d787030157e02e7be22210
Name: P_1476934925293_new
SKU: API-SKU1476934925293
UpdatedById: 2c93808457d787030157e02e62af2097
UpdatedDate: '2016-10-20T05:42:05.000+02:00'
schema:
$ref: '#/components/schemas/ProxyGetProduct'
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'401':
content:
application/json:
examples:
response:
value:
message: Authentication error
schema:
$ref: '#/components/schemas/ProxyUnauthorizedResponse'
description: Unauthorized
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information.
schema:
type: number
WWW-Authenticate:
description: |
The value of this header is:
```
Basic realm=Zuora API, ZSession realm=Zuora API, Bearer realm=Zuora API
```
schema:
enum:
- Basic realm=Zuora API, ZSession realm=Zuora API, Bearer realm=Zuora API
type: string
Zuora-Request-Id:
description: |
The Zuora internal identifier of the API call. You cannot control the value of this header.
schema:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'404':
content:
application/json:
examples:
response:
value:
done: true
records: {}
size: 0
schema:
$ref: '#/components/schemas/ProxyNoDataResponse'
description: ''
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
summary: 'CRUD: Retrieve a product'
tags:
- Products
put:
description: Updates a Product object.
operationId: Object_PUTProduct
parameters:
- $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding'
- $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding'
- $ref: '#/components/parameters/GLOBAL_REQUEST_rejectUnknownFields'
- $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'
- $ref: '#/components/parameters/GLOBAL_HEADER_X_Zuora_WSDL_Version'
- description: Object id
in: path
name: id
required: true
schema:
type: string
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Version'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ProxyModifyProduct'
required: true
responses:
'200':
content:
application/json:
examples:
response:
value:
Id: 2c93808457d787030157e02e7be22210
Success: true
schema:
$ref: '#/components/schemas/ProxyCreateOrModifyResponse'
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'401':
content:
application/json:
examples:
response:
value:
message: Authentication error
schema:
$ref: '#/components/schemas/ProxyUnauthorizedResponse'
description: Unauthorized
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information.
schema:
type: number
WWW-Authenticate:
description: |
The value of this header is:
```
Basic realm=Zuora API, ZSession realm=Zuora API, Bearer realm=Zuora API
```
schema:
enum:
- Basic realm=Zuora API, ZSession realm=Zuora API, Bearer realm=Zuora API
type: string
Zuora-Request-Id:
description: |
The Zuora internal identifier of the API call. You cannot control the value of this header.
schema:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
summary: 'CRUD: Update a product'
tags:
- Products
delete:
description: Deletes a specific product.
operationId: Object_DELETEProduct
parameters:
- $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding'
- $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding'
- $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'
- description: Object id
in: path
name: id
required: true
schema:
type: string
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Version'
responses:
'200':
content:
application/json:
examples:
response:
value:
id: 2c93808457d787030157e02e7a22220e
success: true
schema:
$ref: '#/components/schemas/ProxyDeleteResponse'
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'401':
content:
application/json:
examples:
response:
value:
message: Authentication error
schema:
$ref: '#/components/schemas/ProxyUnauthorizedResponse'
description: Unauthorized
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information.
schema:
type: number
WWW-Authenticate:
description: |
The value of this header is:
```
Basic realm=Zuora API, ZSession realm=Zuora API, Bearer realm=Zuora API
```
schema:
enum:
- Basic realm=Zuora API, ZSession realm=Zuora API, Bearer realm=Zuora API
type: string
Zuora-Request-Id:
description: |
The Zuora internal identifier of the API call. You cannot control the value of this header.
schema:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
summary: 'CRUD: Delete a product'
tags:
- Products
/v1/catalog/products:
get:
description: |
Retrieves the entire product catalog, including all products, features, and their corresponding product rate plans, charges. Products are returned in reverse chronological order on the `UpdatedDate` field.
For each product, this operation returns a maximum of 300 product rate plans in the response. Across the returned product rate plans, up to 300 product rate plan charges can be returned for each product.
operationId: GET_Catalog
parameters:
- $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding'
- $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding'
- $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'
- $ref: '#/components/parameters/GLOBAL_REQUEST_page'
- $ref: '#/components/parameters/GLOBAL_REQUEST_pageSize_catalog'
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Version'
responses:
'200':
content:
application/json:
examples:
response:
value:
products:
- category: Base Products
description: ''
effectiveEndDate: '2020-01-01'
effectiveStartDate: '2017-01-01'
id: 8a8082c45aa81b51015ad5a2d07d0e89
name: ABC
productNumber: PC-00000011
productRatePlans: https://rest.zuora.com/v1/rateplan/40289f466463d683016463ef8b7301a0/productRatePlan
sku: SKU-00000987
success: true
schema:
$ref: '#/components/schemas/GETCatalogType'
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'500':
content:
application/json:
examples:
response:
value:
reasons:
- code: SystemError
message: internal server error
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal Server Error
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
4XX:
content:
application/json:
examples:
response:
value:
processId: 738CBB9234B47A47
reasons:
- code: '58730222'
message: orderDate may not be null
requestId: d7479cf6-b410-4630-b841-268ccd48f0d2
success: false
schema:
$ref: '#/components/schemas/CommonResponse'
description: Request Errors
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
summary: List all products
tags:
- Catalog
/v1/catalog/products/{product-key}:
get:
description: |
Retrieves detailed information about a specific product, including information about its product rate plans and charges.
This operation returns a maximum of 300 product rate plans and 300 product rate plan charges across all product rate plans in the response.
operationId: GET_Product
parameters:
- $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding'
- $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding'
- $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'
- description: |
The unique ID, SKU, or product number of the product that you want to retrieve. For example, 8a808255575bdae4015774e9602e16fe, SKU-00000987, or PC-00000006.
in: path
name: product-key
required: true
schema:
type: string
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Version'
responses:
'200':
content:
application/json:
examples:
response:
value:
category: Base Products
description: ''
effectiveEndDate: '2020-01-01'
effectiveStartDate: '2017-01-01'
id: 8a8082c45aa81b51015ad5a2d07d0e89
name: ABC
productNumber: PC-00000006
productRatePlans: https://rest.zuora.com/v1/rateplan/40289f466463d683016463ef8b7301a0/productRatePlan
sku: SKU-00000987
success: true
schema:
$ref: '#/components/schemas/GETProductType'
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'500':
content:
application/json:
examples:
response:
value:
reasons:
- code: SystemError
message: internal server error
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal Server Error
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
4XX:
content:
application/json:
examples:
response:
value:
processId: 738CBB9234B47A47
reasons:
- code: '58730222'
message: orderDate may not be null
requestId: d7479cf6-b410-4630-b841-268ccd48f0d2
success: false
schema:
$ref: '#/components/schemas/CommonResponse'
description: Request Errors
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
summary: Retrieve a product
tags:
- Catalog
/v1/catalog-groups:
post:
description: |
**Note**: This operation is in the Early Adopter phase. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available. If you want to join this early adopter program, submit a request at [Zuora Global Support](http://support.zuora.com/).
Creates a catalog group which groups a list of product rate plans.
operationId: POST_CreateCatalogGroup
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_Zuora_Track_Id'
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Entity_Ids_Single'
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Org_Ids'
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Version'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/POSTCatalogGroupRequest'
required: true
responses:
'200':
content:
application/json:
examples:
response:
value:
catalogGroupNumber: CG-00000001
description: some description
id: 4028e5ab7f1b600c017f1b7a5e8901d2
name: test
productRatePlans:
- description: null
effectiveEndDate: '2023-02-21'
effectiveStartDate: '2022-02-21'
grade: 1
id: 4028e5ab7f1b600c017f1b787d5d01cf
name: '222'
status: Active
type: Grading
schema:
$ref: '#/components/schemas/CatalogGroupResponse'
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'500':
content:
application/json:
examples:
response:
value:
reasons:
- code: SystemError
message: internal server error
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal Server Error
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
4XX:
content:
application/json:
examples:
response:
value:
processId: 738CBB9234B47A47
reasons:
- code: '58730222'
message: orderDate may not be null
requestId: d7479cf6-b410-4630-b841-268ccd48f0d2
success: false
schema:
$ref: '#/components/schemas/CommonResponse'
description: Request Errors
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
summary: Create a catalog group
tags:
- Catalog Groups
get:
description: |
**Note**: This operation is in the Early Adopter phase. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available. If you want to join this early adopter program, submit a request at [Zuora Global Support](http://support.zuora.com/).
Retrieves basic information about all catalog groups.
operationId: GET_ListAllCatalogGroups
parameters:
- $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding'
- $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding'
- $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'
- $ref: '#/components/parameters/GLOBAL_REQUEST_pageSize'
- $ref: '#/components/parameters/GLOBAL_REQUEST_page'
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Version'
responses:
'200':
content:
application/json:
examples:
response:
value:
catalogGroups:
- catalogGroupNumber: CG-00000001
description: some description
id: 4028e5ab7f1b600c017f1b7a5e8901d2
name: test
productRatePlans:
- description: null
effectiveEndDate: '2023-02-21'
effectiveStartDate: '2022-02-21'
grade: 1
id: 4028e5ab7f1b600c017f1b787d5d01cf
name: '222'
status: Active
type: Grading
nextPage: false
schema:
$ref: '#/components/schemas/ListAllCatalogGroupsResponse'
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'500':
content:
application/json:
examples:
response:
value:
reasons:
- code: SystemError
message: internal server error
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal Server Error
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
4XX:
content:
application/json:
examples:
response:
value:
processId: 738CBB9234B47A47
reasons:
- code: '58730222'
message: orderDate may not be null
requestId: d7479cf6-b410-4630-b841-268ccd48f0d2
success: false
schema:
$ref: '#/components/schemas/CommonResponse'
description: Request Errors
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
summary: List all catalog groups
tags:
- Catalog Groups
/v1/catalog-groups/{catalog-group-key}:
get:
description: |
**Note**: This operation is in the Early Adopter phase. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available. If you want to join this early adopter program, submit a request at [Zuora Global Support](http://support.zuora.com/).
Retrieves basic information about a catalog group.
operationId: GET_RetrieveCatalogGroup
parameters:
- $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding'
- $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding'
- $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'
- description: |
The unique number or ID of the catalog group to be retrieved.
in: path
name: catalog-group-key
required: true
schema:
type: string
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Version'
responses:
'200':
content:
application/json:
examples:
response:
value:
catalogGroupNumber: CG-00000001
description: some description
id: 4028e5ab7f1b600c017f1b7a5e8901d2
name: test
productRatePlans:
- description: null
effectiveEndDate: '2023-02-21'
effectiveStartDate: '2022-02-21'
grade: 1
id: 4028e5ab7f1b600c017f1b787d5d01cf
name: '222'
status: Active
type: Grading
schema:
$ref: '#/components/schemas/CatalogGroupResponse'
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'500':
content:
application/json:
examples:
response:
value:
reasons:
- code: SystemError
message: internal server error
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal Server Error
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
4XX:
content:
application/json:
examples:
response:
value:
processId: 738CBB9234B47A47
reasons:
- code: '58730222'
message: orderDate may not be null
requestId: d7479cf6-b410-4630-b841-268ccd48f0d2
success: false
schema:
$ref: '#/components/schemas/CommonResponse'
description: Request Errors
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
summary: Retrieve a catalog group
tags:
- Catalog Groups
put:
description: |
**Note**: This operation is in the Early Adopter phase. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available. If you want to join this early adopter program, submit a request at [Zuora Global Support](http://support.zuora.com/).
Updates a catalog group by its unique number or ID.
### Notes
- It is best practice to only specify the fields that you want to change in the request body.
- If you specify an empty value for a field in the request body, the corresponding field in the catalog group is emptied.
- The catalog group type cannot be changed.
operationId: PUT_UpdateCatalogGroup
parameters:
- $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding'
- $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding'
- $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'
- description: |
The unique number or ID of the catalog group to be updated.
in: path
name: catalog-group-key
required: true
schema:
type: string
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Version'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PUTCatalogGroup'
required: true
responses:
'200':
content:
application/json:
examples:
response:
value:
catalogGroupNumber: CG-00000001
description: some description
id: 4028e5ab7f1b600c017f1b7a5e8901d2
name: test
productRatePlans:
- description: null
effectiveEndDate: '2023-02-21'
effectiveStartDate: '2022-02-21'
grade: 1
id: 4028e5ab7f1b600c017f1b787d5d01cf
name: '222'
status: Active
type: Grading
schema:
$ref: '#/components/schemas/CatalogGroupResponse'
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'500':
content:
application/json:
examples:
response:
value:
reasons:
- code: SystemError
message: internal server error
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal Server Error
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
4XX:
content:
application/json:
examples:
response:
value:
processId: 738CBB9234B47A47
reasons:
- code: '58730222'
message: orderDate may not be null
requestId: d7479cf6-b410-4630-b841-268ccd48f0d2
success: false
schema:
$ref: '#/components/schemas/CommonResponse'
description: Request Errors
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
summary: Update a catalog group
tags:
- Catalog Groups
delete:
description: |
**Note**: This operation is in the Early Adopter phase. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available. If you want to join this early adopter program, submit a request at [Zuora Global Support](http://support.zuora.com/).
Deletes a catalog group.
operationId: DELETE_CatalogGroup
parameters:
- $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding'
- $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding'
- $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'
- description: |
The unique number or ID of the catalog group to be deleted.
in: path
name: catalog-group-key
required: true
schema:
type: string
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Version'
responses:
'200':
content:
application/json:
examples:
response:
value:
success: 'true'
schema:
$ref: '#/components/schemas/CommonResponse'
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'500':
content:
application/json:
examples:
response:
value:
reasons:
- code: SystemError
message: internal server error
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal Server Error
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
4XX:
content:
application/json:
examples:
response:
value:
processId: 738CBB9234B47A47
reasons:
- code: '58730222'
message: orderDate may not be null
requestId: d7479cf6-b410-4630-b841-268ccd48f0d2
success: false
schema:
$ref: '#/components/schemas/CommonResponse'
description: Request Errors
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
summary: Delete a catalog group
tags:
- Catalog Groups
/v1/products/{product-key}/product-rate-plans:
get:
description: |
Retrieves information about all product rate plans of a specific product.
operationId: GET_ProductRatePlans
parameters:
- $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding'
- $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding'
- $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'
- $ref: '#/components/parameters/GLOBAL_REQUEST_page'
- $ref: '#/components/parameters/GLOBAL_REQUEST_pageSize'
- description: |
The unique ID or SKU of a product. For example, 2c92c0f96487e16a016487f663c71a61 or SKU-00000987.
in: path
name: product-key
required: true
schema:
type: string
- description: |
Specifies whether to include the product charge definitions of this rate plan in the response.
**Note**: This parameter is applicable only if the Attribute Based Pricing feature is enabled. To access this feature, submit a request at Zuora Global Support.
in: query
name: show-charge-definitions
required: false
schema:
type: boolean
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Version'
responses:
'200':
content:
application/json:
examples:
response:
value:
productRatePlans:
- description: ''
effectiveEndDate: '2020-07-31'
effectiveStartDate: '2016-07-01'
grade: 3
id: 40289f466464127601646473d6f7000f
name: New Rate Plan
productRatePlanCharges:
- applyDiscountTo: null
billingDay: DefaultFromCustomer
billingPeriod: Month
billingPeriodAlignment: AlignToCharge
billingTiming: IN_ADVANCE
defaultQuantity: null
description: ''
discountClass: null
discountLevel: null
endDateCondition: Subscription_End
financeInformation:
deferredRevenueAccountingCode: ''
deferredRevenueAccountingCodeType: null
recognizedRevenueAccountingCode: ''
recognizedRevenueAccountingCodeType: null
id: 40289f4664641276016464740dd0001c
listPriceBase: Per_Billing_Period
model: FlatFee
name: New Component
numberOfPeriods: null
overageCalculationOption: null
overageUnusedUnitsCreditOption: null
priceChangeOption: null
priceIncreasePercentage: null
pricing:
- currency: USD
discountAmount: null
discountPercentage: null
includedUnits: null
overagePrice: null
price: 100
tiers: null
pricingSummary:
- USD100
productChargeDefinitions: https://rest.zuora.com/v1/product-charge-definitions?charge=8a80808e8aaf3b0a018aaf3f2beb022b&rateplan=8a80808e8aaf3b0a018aaf3ed4cf021e
productDiscountApplyDetails: []
productRatePlanChargeNumber: PRPC-00000001
revRecCode: ''
revRecTriggerCondition: ContractEffectiveDate
revenueRecognitionRuleName: Recognize upon invoicing
smoothingModel: null
specificBillingPeriod: null
specificListPriceBase: null
taxCode: ''
taxMode: null
taxable: false
triggerEvent: ContractEffective
type: Recurring
unusedIncludedUnitPrice: null
uom: null
upToPeriods: null
upToPeriodsType: null
usageRecordRatingOption: null
useDiscountSpecificAccountingCode: null
useTenantDefaultForPriceChange: null
productRatePlanNumber: PRP-00000001
status: Active
success: true
schema:
$ref: '#/components/schemas/GETProductRatePlansResponse'
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'500':
content:
application/json:
examples:
response:
value:
reasons:
- code: SystemError
message: internal server error
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal Server Error
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
4XX:
content:
application/json:
examples:
response:
value:
processId: 738CBB9234B47A47
reasons:
- code: '58730222'
message: orderDate may not be null
requestId: d7479cf6-b410-4630-b841-268ccd48f0d2
success: false
schema:
$ref: '#/components/schemas/CommonResponse'
description: Request Errors
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
summary: List all product rate plans of a product
tags:
- Product Rate Plans
/v1/product-rate-plans/{id}:
get:
description: |
Retrieves a product rate plan by its ID.
operationId: GET_ProductRatePlan
parameters:
- $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding'
- $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding'
- $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'
- description: |
The ID, external ID, or the natural key of the product rate plan to be retrieved. For example, `402888e67f8b3a68017f8bbb2a06062d`, `Apple0001`, or `PRP-00000008`.
in: path
name: id
required: true
schema:
type: string
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Version'
responses:
'200':
content:
application/json:
examples:
response:
value:
description: ''
effectiveEndDate: '2032-02-01'
effectiveStartDate: '2012-02-01'
externalIdSourceSystem: apple
externallyManagedPlanIds:
- Apple0001
- Apple0002
- Google0003
grade: 3
id: 402888e67f8b3a68017f8bbb2a06062d
name: New Rate Plan Change
productRatePlanNumber: PRP-00000008
status: Active
success: true
schema:
$ref: '#/components/schemas/GETProductRatePlanWithExternalIdResponse'
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'500':
content:
application/json:
examples:
response:
value:
reasons:
- code: SystemError
message: internal server error
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal Server Error
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
4XX:
content:
application/json:
examples:
response:
value:
processId: 738CBB9234B47A47
reasons:
- code: '58730222'
message: orderDate may not be null
requestId: d7479cf6-b410-4630-b841-268ccd48f0d2
success: false
schema:
$ref: '#/components/schemas/CommonResponse'
description: Request Errors
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
summary: Retrieve a product rate plan by ID
tags:
- Product Rate Plans
/v1/product-rate-plans/external-id/{id}:
get:
description: |
Retrieves information about one or multiple product rate plans by external ID.
operationId: GET_ProductRatePlansByExternalID
parameters:
- $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding'
- $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding'
- $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'
- description: |
The external ID of the product rate plan to be retrieved. For example, `Apple0001`.
in: path
name: id
required: true
schema:
type: string
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Version'
responses:
'200':
content:
application/json:
examples:
response:
value:
success: true
productRatePlans:
- id: 2c989020823f450c01823fef40421eb6
status: Active
name: My rate plan - Monthly Basic
description: ''
effectiveStartDate: '2024-01-01'
effectiveEndDate: '2026-01-01'
externalIdSourceSystem: apple
externallyManagedPlanIds:
- zuora-us-monthly-basic
productRatePlanNumber: 1001
schema:
$ref: '#/components/schemas/GETProductRatePlanWithExternalIdMultiResponse'
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'500':
content:
application/json:
examples:
response:
value:
reasons:
- code: SystemError
message: internal server error
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal Server Error
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
4XX:
content:
application/json:
examples:
response:
value:
processId: 738CBB9234B47A47
reasons:
- code: '58730222'
message: orderDate may not be null
requestId: d7479cf6-b410-4630-b841-268ccd48f0d2
success: false
schema:
$ref: '#/components/schemas/CommonResponse'
description: Request Errors
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
summary: List product rate plans by external ID
tags:
- Product Rate Plans
/v1/object/product-rate-plan:
post:
description: |
Retrieves a product rate plan.
operationId: Object_POSTProductRatePlan
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_REQUEST_rejectUnknownFields'
- $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'
- $ref: '#/components/parameters/GLOBAL_HEADER_X_Zuora_WSDL_Version'
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Version'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ProxyCreateProductRatePlan'
required: true
responses:
'200':
content:
application/json:
examples:
response:
value:
Id: 2c93808457d787030157e0324735512b
Success: true
schema:
$ref: '#/components/schemas/ProxyCreateOrModifyResponse'
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'400':
content:
application/json:
examples:
response:
value:
Errors:
- Code: INVALID_VALUE
Message: The account number 123xProxy is invalid.
Success: false
schema:
$ref: '#/components/schemas/ProxyBadRequestResponse'
description: ''
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'401':
content:
application/json:
examples:
response:
value:
message: Authentication error
schema:
$ref: '#/components/schemas/ProxyUnauthorizedResponse'
description: Unauthorized
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information.
schema:
type: number
WWW-Authenticate:
description: |
The value of this header is:
```
Basic realm=Zuora API, ZSession realm=Zuora API, Bearer realm=Zuora API
```
schema:
enum:
- Basic realm=Zuora API, ZSession realm=Zuora API, Bearer realm=Zuora API
type: string
Zuora-Request-Id:
description: |
The Zuora internal identifier of the API call. You cannot control the value of this header.
schema:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
summary: 'CRUD: Create a product rate plan'
tags:
- Product Rate Plans
/v1/object/product-rate-plan/{id}:
get:
description: |
Retrieves a product rate plan.
operationId: Object_GETProductRatePlan
parameters:
- $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding'
- $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding'
- $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'
- $ref: '#/components/parameters/GLOBAL_HEADER_X_Zuora_WSDL_Version'
- description: Object fields to return
in: query
name: fields
required: false
schema:
type: string
- description: Object id
in: path
name: id
required: true
schema:
type: string
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Version'
responses:
'200':
content:
application/json:
examples:
response:
value:
CreatedById: 2c93808457d787030157e02d84c116d5
CreatedDate: '2016-10-20T05:41:09.000+02:00'
Description: Test create product rateplan via API
EffectiveEndDate: '2066-10-20'
EffectiveStartDate: '1966-10-20'
Grade: 3
Id: 2c93808457d787030157e02da0d91852
Name: ProductRatePlan1476934869186_new
ProductId: 2c93808457d787030157e02da0231850
UpdatedById: 2c93808457d787030157e02d84c116d5
UpdatedDate: '2016-10-20T05:41:09.000+02:00'
schema:
$ref: '#/components/schemas/ProxyGetProductRatePlan'
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'401':
content:
application/json:
examples:
response:
value:
message: Authentication error
schema:
$ref: '#/components/schemas/ProxyUnauthorizedResponse'
description: Unauthorized
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information.
schema:
type: number
WWW-Authenticate:
description: |
The value of this header is:
```
Basic realm=Zuora API, ZSession realm=Zuora API, Bearer realm=Zuora API
```
schema:
enum:
- Basic realm=Zuora API, ZSession realm=Zuora API, Bearer realm=Zuora API
type: string
Zuora-Request-Id:
description: |
The Zuora internal identifier of the API call. You cannot control the value of this header.
schema:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'404':
content:
application/json:
examples:
response:
value:
done: true
records: {}
size: 0
schema:
$ref: '#/components/schemas/ProxyNoDataResponse'
description: ''
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
summary: 'CRUD: Retrieve a product rate plan'
tags:
- Product Rate Plans
put:
description: |
Updates a product rate plan.
operationId: Object_PUTProductRatePlan
parameters:
- $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding'
- $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding'
- $ref: '#/components/parameters/GLOBAL_REQUEST_rejectUnknownFields'
- $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'
- $ref: '#/components/parameters/GLOBAL_HEADER_X_Zuora_WSDL_Version'
- description: Object id
in: path
name: id
required: true
schema:
type: string
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Version'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ProxyModifyProductRatePlan'
required: true
responses:
'200':
content:
application/json:
examples:
response:
value:
Id: 2c93808457d787030157e02da0d91852
Success: true
schema:
$ref: '#/components/schemas/ProxyCreateOrModifyResponse'
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'401':
content:
application/json:
examples:
response:
value:
message: Authentication error
schema:
$ref: '#/components/schemas/ProxyUnauthorizedResponse'
description: Unauthorized
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information.
schema:
type: number
WWW-Authenticate:
description: |
The value of this header is:
```
Basic realm=Zuora API, ZSession realm=Zuora API, Bearer realm=Zuora API
```
schema:
enum:
- Basic realm=Zuora API, ZSession realm=Zuora API, Bearer realm=Zuora API
type: string
Zuora-Request-Id:
description: |
The Zuora internal identifier of the API call. You cannot control the value of this header.
schema:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
summary: 'CRUD: Update a product rate plan'
tags:
- Product Rate Plans
delete:
description: |
Deletes a product rate plan.
operationId: Object_DELETEProductRatePlan
parameters:
- $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding'
- $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding'
- $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'
- description: Object id
in: path
name: id
required: true
schema:
type: string
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Version'
responses:
'200':
content:
application/json:
examples:
response:
value:
id: 2c93808457d787030157e02d9dde184f
success: true
schema:
$ref: '#/components/schemas/ProxyDeleteResponse'
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'401':
content:
application/json:
examples:
response:
value:
message: Authentication error
schema:
$ref: '#/components/schemas/ProxyUnauthorizedResponse'
description: Unauthorized
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information.
schema:
type: number
WWW-Authenticate:
description: |
The value of this header is:
```
Basic realm=Zuora API, ZSession realm=Zuora API, Bearer realm=Zuora API
```
schema:
enum:
- Basic realm=Zuora API, ZSession realm=Zuora API, Bearer realm=Zuora API
type: string
Zuora-Request-Id:
description: |
The Zuora internal identifier of the API call. You cannot control the value of this header.
schema:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
summary: 'CRUD: Delete a product rate plan'
tags:
- Product Rate Plans
/v1/product-rateplan-definitions:
post:
description: |
Creates a product rate plan definition to use a charge in a product rate plan.
In the request, you must specify either the unique ID or number of both the charge and the product rate plan to add the specified charge to a specific rate plan.
**Note**: This operation requires the [Attribute-based Pricing](https://knowledgecenter.zuora.com/Zuora_Billing/Build_products_and_prices/Attribute_based_pricing/AA_Overview_of_Attribute-based_Pricing) feature to be enabled, which is in the **Early Adopter** phase.
operationId: POST_CreateProductRatePlanDefinition
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_Zuora_Track_Id'
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Entity_Ids_Single'
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Version'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/POSTRatePlanDefinitionRequest'
required: true
responses:
'200':
content:
application/json:
examples:
response:
value:
id: 2c9890f78aba5c16018ababa00120019
success: true
schema:
$ref: '#/components/schemas/POSTRatePlanDefinitionResponse'
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'500':
content:
application/json:
examples:
response:
value:
reasons:
- code: SystemError
message: internal server error
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal Server Error
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
4XX:
content:
application/json:
examples:
response:
value:
processId: 738CBB9234B47A47
reasons:
- code: '58730222'
message: orderDate may not be null
requestId: d7479cf6-b410-4630-b841-268ccd48f0d2
success: false
schema:
$ref: '#/components/schemas/CommonResponse'
description: Request Errors
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
summary: Create a product rate plan definition
tags:
- Product Rate Plan Definitions
get:
description: |
Retrieves basic information about the product rate plan definitions for a product rate plan.
**Note**: This operation requires the [Attribute-based Pricing](https://knowledgecenter.zuora.com/Zuora_Billing/Build_products_and_prices/Attribute_based_pricing/AA_Overview_of_Attribute-based_Pricing) feature to be enabled, which is in the **Early Adopter** phase.
operationId: GET_RetrieveProductRatePlanDefinitions
parameters:
- $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding'
- $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding'
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Track_Id'
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Entity_Ids_Single'
- description: |
The unique number or ID of the charge for which the product rate plan definitions are to be retrieved.
in: query
name: charge
required: false
schema:
type: string
- description: |
The unique number or ID of the product rate plan for which the product rate plan definitions are to be retrieved.
in: query
name: rateplan
required: false
schema:
type: string
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Version'
responses:
'200':
content:
application/json:
examples:
response:
value:
productRatePlanDefinitions:
- id: 2c9890f78b212d76018b218993c9005c
productRatePlanChargeId: 2c9890f78aba5c16018ababa00120019
productRatePlanChargeName: New Component
productRatePlanChargeNumber: PRPC-NEW-00000175
productRatePlanId: 2c9890678b1ca909018b1caea5c30000
productRatePlanName: New Rate Plan2
productRatePlanNumber: PRP-NEW-00000353
- id: 2c9890f78b212d76018b21742683005a
productRatePlanChargeId: 2c9890f78b212d76018b2174263c004a
productRatePlanChargeName: API_Usage_Tiered-multi
productRatePlanChargeNumber: PRPC-NEW-00000246
productRatePlanId: 2c9890678b1ca909018b1caea5c30000
productRatePlanName: New Rate Plan2
productRatePlanNumber: PRP-NEW-00000353
success: true
schema:
$ref: '#/components/schemas/GETProductRatePlanDefinitionsResponse'
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'500':
content:
application/json:
examples:
response:
value:
reasons:
- code: SystemError
message: internal server error
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal Server Error
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
4XX:
content:
application/json:
examples:
response:
value:
processId: 738CBB9234B47A47
reasons:
- code: '58730222'
message: orderDate may not be null
requestId: d7479cf6-b410-4630-b841-268ccd48f0d2
success: false
schema:
$ref: '#/components/schemas/CommonResponse'
description: Request Errors
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
summary: List product rate plan definitions
tags:
- Product Rate Plan Definitions
/v1/product-rateplan-definitions/{product-rateplan-definition-key}:
get:
description: |
Retrieves basic information about a product rate plan definition.
**Note**: This operation requires the [Attribute-based Pricing](https://knowledgecenter.zuora.com/Zuora_Billing/Build_products_and_prices/Attribute_based_pricing/AA_Overview_of_Attribute-based_Pricing) feature to be enabled, which is in the **Early Adopter** phase.
operationId: GET_RetrieveProductRatePlanDefinition
parameters:
- $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding'
- $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding'
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Track_Id'
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Entity_Ids_Single'
- description: |
The unique ID of the product rate plan definition to be retrieved.
in: path
name: product-rateplan-definition-key
required: true
schema:
type: string
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Version'
responses:
'200':
content:
application/json:
examples:
response:
value:
id: 2c9890f78b212d76018b21937228005d
productRatePlanChargeId: 2c9890e489f227bd0189f22f3482001f
productRatePlanChargeName: Per Unit
productRatePlanChargeNumber: null
productRatePlanId: 2c9890678b1ca909018b1caea5c30000
productRatePlanName: New Rate Plan2
productRatePlanNumber: PRP-NEW-00000353
success: true
schema:
$ref: '#/components/schemas/GETProductRatePlanDefinitionResponse'
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'500':
content:
application/json:
examples:
response:
value:
reasons:
- code: SystemError
message: internal server error
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal Server Error
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
4XX:
content:
application/json:
examples:
response:
value:
processId: 738CBB9234B47A47
reasons:
- code: '58730222'
message: orderDate may not be null
requestId: d7479cf6-b410-4630-b841-268ccd48f0d2
success: false
schema:
$ref: '#/components/schemas/CommonResponse'
description: Request Errors
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
summary: Retrieve a product rate plan definition
tags:
- Product Rate Plan Definitions
delete:
description: |
Deletes a product rate plan definition.
**Note**: This operation requires the [Attribute-based Pricing](https://knowledgecenter.zuora.com/Zuora_Billing/Build_products_and_prices/Attribute_based_pricing/AA_Overview_of_Attribute-based_Pricing) feature to be enabled, which is in the **Early Adopter** phase.
operationId: DELETE_ProductRatePlanDefnition
parameters:
- $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding'
- $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding'
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Track_Id'
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Entity_Ids_Single'
- description: |
The unique ID of the product rate plan definition to be deleted.
in: path
name: product-rateplan-definition-key
required: true
schema:
type: string
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Version'
responses:
'200':
content:
application/json:
examples:
response:
value:
success: true
schema:
$ref: '#/components/schemas/CommonResponse'
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'500':
content:
application/json:
examples:
response:
value:
reasons:
- code: SystemError
message: internal server error
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal Server Error
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
4XX:
content:
application/json:
examples:
response:
value:
processId: 738CBB9234B47A47
reasons:
- code: '58730222'
message: orderDate may not be null
requestId: d7479cf6-b410-4630-b841-268ccd48f0d2
success: false
schema:
$ref: '#/components/schemas/CommonResponse'
description: Request Errors
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
summary: Delete a product rate plan definition
tags:
- Product Rate Plan Definitions
/v1/product-rate-plan-charges/{product-rate-plan-charge-key}:
get:
description: |
Retrieves basic information about a product rate plan charge.
operationId: GET_RetrieveProductRatePlanCharge
parameters:
- $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding'
- $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding'
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Track_Id'
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Entity_Ids_Single'
- description: |
The unique number or ID of the product rate plan charge to be retrieved.
in: path
name: product-rate-plan-charge-key
required: true
schema:
type: string
- description: |
Specifies whether to include the product charge definitions of this charge in the response.
**Note**: This parameter is applicable only if the Attribute-based Pricing feature is enabled. The Attribute-based Pricing feature in the **Early Adopter** phase.
We are actively soliciting feedback from a small set of early adopters. If you are interested, please reach out to your CSM.
in: query
name: show-charge-definitions
required: false
schema:
type: boolean
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Version'
responses:
'200':
content:
application/json:
examples:
response:
value:
id: edca018c566983fa11f6d38381b10000
name: Attribute based pricing charge with formula
type: Recurring
model: FlatFee
uom: null
pricingSummary:
- USD60
pricing:
- currency: USD
price: 60
tiers: null
includedUnits: null
overagePrice: null
discountPercentage: null
discountAmount: null
defaultQuantity: null
applyDiscountTo: null
discountLevel: null
discountClass: null
applyToBillingPeriodPartially: false
productDiscountApplyDetails: []
endDateCondition: Subscription_End
upToPeriods: null
upToPeriodsType: null
billingDay: DefaultFromCustomer
listPriceBase: Per_Billing_Period
specificListPriceBase: null
billingTiming: IN_ADVANCE
ratingGroup: null
billingPeriod: Month
billingPeriodAlignment: AlignToCharge
specificBillingPeriod: null
smoothingModel: null
numberOfPeriods: null
overageCalculationOption: null
overageUnusedUnitsCreditOption: null
unusedIncludedUnitPrice: null
usageRecordRatingOption: null
priceChangeOption: null
priceIncreasePercentage: null
useTenantDefaultForPriceChange: true
taxable: false
taxCode: ''
taxMode: null
isPrepaid: false
prepaidOperationType: null
prepaidUom: null
prepaidQuantity: null
prepaidTotalQuantity: null
validityPeriodType: SUBSCRIPTION_TERM
drawdownRate: null
drawdownUom: null
creditOption: TimeBased
isRollover: false
rolloverPeriods: 0
rolloverPeriodLength: 0
rolloverApply: ApplyLast
triggerEvent: ContractEffective
description: ''
revRecCode: null
revRecTriggerCondition: null
revenueRecognitionRuleName: Recognize upon invoicing
useDiscountSpecificAccountingCode: null
excludeItemBookingFromRevenueAccounting: false
excludeItemBillingFromRevenueAccounting: false
financeInformation:
deferredRevenueAccountingCode: ''
deferredRevenueAccountingCodeType: null
recognizedRevenueAccountingCode: ''
recognizedRevenueAccountingCodeType: null
accountsReceivableAccountingCode: Accounts Receivable
accountsReceivableAccountingCodeType: AccountsReceivable
contractAssetAccountingCode: null
contractAssetAccountingCodeType: null
contractLiabilityAccountingCode: null
contractLiabilityAccountingCodeType: null
adjustmentLiabilityAccountingCode: null
adjustmentLiabilityAccountingCodeType: null
unbilledReceivablesAccountingCode: null
unbilledReceivablesAccountingCodeType: null
adjustmentRevenueAccountingCode: null
adjustmentRevenueAccountingCodeType: null
contractRecognizedRevenueAccountingCode: null
contractRecognizedRevenueAccountingCodeType: null
deliverySchedule: null
isStackedDiscount: false
productRatePlanChargeNumber: null
formula: lookup("soldToRegion__c" = fieldLookup("subscription", "soldToRegion__c"))
productChargeDefinitions: https://rest-staging2.zuora.com/apps/v1/product-charge-definitions?charge=edca018c566983fa11f6d38381b10000
success: true
schema:
$ref: '#/components/schemas/GETProductRatePlanChargeResponse'
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
summary: Retrieve a product rate plan charge
tags:
- Product Rate Plan Charges
/v1/object/product-rate-plan-charge:
post:
description: |
Creates a product rate plan charge for a specified rate plan charge.
Product rate plan charges can be of three types, one-time fees, recurring fees, and usage fees.
operationId: Object_POSTProductRatePlanCharge
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_REQUEST_rejectUnknownFields'
- $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'
- $ref: '#/components/parameters/GLOBAL_HEADER_X_Zuora_WSDL_Version'
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Version'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ProxyCreateProductRatePlanCharge'
examples:
valid_per_specific_months:
summary: SpecificListPriceBase at upper bound example
value:
Name: Maximum Specific List Price Base Charge
Description: Charge with maximum specific list price base
ChargeModel: Flat Fee Pricing
ChargeType: Recurring
ProductRatePlanId: '{YourProductRatePlanId}'
BillCycleType: DefaultFromCustomer
BillingPeriod: Month
TriggerEvent: ContractEffective
ListPriceBase: Per Specific Months
SpecificListPriceBase: 120
ProductRatePlanChargeTierData:
ProductRatePlanChargeTier:
- Price: 99.99
UseDiscountSpecificAccountingCode: false
required: true
responses:
'200':
content:
application/json:
examples:
response:
value:
Id: 2c93808457d787030157e03197714910
Success: true
schema:
$ref: '#/components/schemas/ProxyCreateOrModifyResponse'
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'401':
content:
application/json:
examples:
response:
value:
message: Authentication error
schema:
$ref: '#/components/schemas/ProxyUnauthorizedResponse'
description: Unauthorized
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information.
schema:
type: number
WWW-Authenticate:
description: |
The value of this header is:
```
Basic realm=Zuora API, ZSession realm=Zuora API, Bearer realm=Zuora API
```
schema:
enum:
- Basic realm=Zuora API, ZSession realm=Zuora API, Bearer realm=Zuora API
type: string
Zuora-Request-Id:
description: |
The Zuora internal identifier of the API call. You cannot control the value of this header.
schema:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
summary: 'CRUD: Create a product rate plan charge'
tags:
- Product Rate Plan Charges
/v1/object/product-rate-plan-charge/{id}:
get:
description: Retrieves a specific product rate plan charge.
operationId: Object_GETProductRatePlanCharge
parameters:
- $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding'
- $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding'
- $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'
- $ref: '#/components/parameters/GLOBAL_HEADER_X_Zuora_WSDL_Version'
- description: Object fields to return
in: query
name: fields
required: false
schema:
type: string
- description: |
The unique ID of a product rate plan charge to be retrieved. For example, 2c93808457d787030157e031fcd34e19.
in: path
name: id
required: true
schema:
type: string
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Version'
responses:
'200':
content:
application/json:
examples:
response:
value:
AccountingCode: name_1476935155610
BillCycleDay: 1
BillCycleType: DefaultFromCustomer
BillingPeriod: Month
BillingPeriodAlignment: AlignToCharge
BillingTiming: In Advance
ChargeModel: Flat Fee Pricing
ChargeType: Recurring
CreatedById: 2c93808457d787030157e031dd264c85
CreatedDate: '2016-10-20T05:45:55.000+02:00'
DefaultQuantity: 1
DeferredRevenueAccount: name_1476935155610
Description: Recurring Flat Fee Pricing
EndDateCondition: SubscriptionEnd
Id: 2c93808457d787030157e032002b4e21
IncludedUnits: 0
LegacyRevenueReporting: false
ListPriceBase: Per Billing Period
Name: Recurring_Flat Fee Pricing1476935155610
NumberOfPeriod: 1
OverageCalculationOption: EndOfSmoothingPeriod
OverageUnusedUnitsCreditOption: NoCredit
PriceChangeOption: NoChange
PriceIncreasePercentage: 0
ProductRatePlanId: 2c93808457d787030157e031ff054e1e
RecognizedRevenueAccount: name_1476935155610
RevenueRecognitionRuleName: Recognize upon invoicing
Taxable: false
TriggerEvent: ContractEffective
UpToPeriodsType: Billing Periods
UpdatedById: 2c93808457d787030157e031dd264c85
UpdatedDate: '2016-10-20T05:45:55.000+02:00'
UseTenantDefaultForPriceChange: true
Formula: ''
schema:
$ref: '#/components/schemas/ProxyGetProductRatePlanCharge'
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'401':
content:
application/json:
examples:
response:
value:
message: Authentication error
schema:
$ref: '#/components/schemas/ProxyUnauthorizedResponse'
description: Unauthorized
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information.
schema:
type: number
WWW-Authenticate:
description: |
The value of this header is:
```
Basic realm=Zuora API, ZSession realm=Zuora API, Bearer realm=Zuora API
```
schema:
enum:
- Basic realm=Zuora API, ZSession realm=Zuora API, Bearer realm=Zuora API
type: string
Zuora-Request-Id:
description: |
The Zuora internal identifier of the API call. You cannot control the value of this header.
schema:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'404':
content:
application/json:
examples:
response:
value:
done: true
records: {}
size: 0
schema:
$ref: '#/components/schemas/ProxyNoDataResponse'
description: ''
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
summary: 'CRUD: Retrieve a product rate plan charge'
tags:
- Product Rate Plan Charges
put:
description: |
Updates the information about a product rate plan charge.
operationId: Object_PUTProductRatePlanCharge
parameters:
- $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding'
- $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding'
- $ref: '#/components/parameters/GLOBAL_REQUEST_rejectUnknownFields'
- $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'
- $ref: '#/components/parameters/GLOBAL_HEADER_X_Zuora_WSDL_Version'
- description: |
The unique ID of the product rate plan charge to be updated. For example, 2c93808457d787030157e031fcd34e19.
in: path
name: id
required: true
schema:
type: string
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Version'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ProxyModifyProductRatePlanCharge'
required: true
responses:
'200':
content:
application/json:
examples:
response:
value:
Id: 2c93808457d787030157e03197714910
Success: true
schema:
$ref: '#/components/schemas/ProxyCreateOrModifyResponse'
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'401':
content:
application/json:
examples:
response:
value:
message: Authentication error
schema:
$ref: '#/components/schemas/ProxyUnauthorizedResponse'
description: Unauthorized
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information.
schema:
type: number
WWW-Authenticate:
description: |
The value of this header is:
```
Basic realm=Zuora API, ZSession realm=Zuora API, Bearer realm=Zuora API
```
schema:
enum:
- Basic realm=Zuora API, ZSession realm=Zuora API, Bearer realm=Zuora API
type: string
Zuora-Request-Id:
description: |
The Zuora internal identifier of the API call. You cannot control the value of this header.
schema:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'404':
content:
application/json:
examples:
response:
value:
done: true
records: {}
size: 0
schema:
$ref: '#/components/schemas/ProxyNoDataResponse'
description: ''
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
summary: 'CRUD: Update a product rate plan charge'
tags:
- Product Rate Plan Charges
delete:
description: |
Deletes a product rate plan charge.
operationId: Object_DELETEProductRatePlanCharge
parameters:
- $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding'
- $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding'
- $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'
- description: |
The unique ID of the product rate plan charge to be deleted. For example, 2c93808457d787030157e031fcd34e19.
in: path
name: id
required: true
schema:
type: string
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Version'
responses:
'200':
content:
application/json:
examples:
response:
value:
id: 2c93808457d787030157e031fcd34e19
success: true
schema:
$ref: '#/components/schemas/ProxyDeleteResponse'
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'401':
content:
application/json:
examples:
response:
value:
message: Authentication error
schema:
$ref: '#/components/schemas/ProxyUnauthorizedResponse'
description: Unauthorized
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information.
schema:
type: number
WWW-Authenticate:
description: |
The value of this header is:
```
Basic realm=Zuora API, ZSession realm=Zuora API, Bearer realm=Zuora API
```
schema:
enum:
- Basic realm=Zuora API, ZSession realm=Zuora API, Bearer realm=Zuora API
type: string
Zuora-Request-Id:
description: |
The Zuora internal identifier of the API call. You cannot control the value of this header.
schema:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
summary: 'CRUD: Delete a product rate plan charge'
tags:
- Product Rate Plan Charges
/v1/product-charge-definitions:
post:
description: |
Creates a product charge definition for a charge. You can create as many product charge definitions as needed for one charge.
In the request, you must specify the unique ID or number of the charge for which this charge definition is to be created.
The ID or number of a product rate plan is optional.
**Note**: This operation requires the [Attribute-based Pricing](https://knowledgecenter.zuora.com/Zuora_Billing/Build_products_and_prices/Attribute_based_pricing/AA_Overview_of_Attribute-based_Pricing) feature to be enabled, which is in the **Early Adopter** phase.
operationId: POST_CreateProductChargeDefinition
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_Zuora_Track_Id'
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Entity_Ids_Single'
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Version'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/POSTChargeDefinitionRequest'
required: true
responses:
'200':
content:
application/json:
examples:
response:
value:
chargeDefinitionId: 8a90988c8b177a24018b17857411002a
chargeDefinitionNumber: CD-00002089
success: true
schema:
$ref: '#/components/schemas/POSTChargeDefinitionResponse'
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'500':
content:
application/json:
examples:
response:
value:
reasons:
- code: SystemError
message: internal server error
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal Server Error
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
4XX:
content:
application/json:
examples:
response:
value:
processId: 738CBB9234B47A47
reasons:
- code: '58730222'
message: orderDate may not be null
requestId: d7479cf6-b410-4630-b841-268ccd48f0d2
success: false
schema:
$ref: '#/components/schemas/CommonResponse'
description: Request Errors
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
summary: Create a product charge definition
tags:
- Product Charge Definitions
get:
description: |
Retrieves basic information about the product charge definitions.
**Note**: This operation requires the [Attribute-based Pricing](https://knowledgecenter.zuora.com/Zuora_Billing/Build_products_and_prices/Attribute_based_pricing/AA_Overview_of_Attribute-based_Pricing) feature to be enabled, which is in the **Early Adopter** phase.
operationId: GET_RetrieveProductChargeDefinitions
parameters:
- $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding'
- $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding'
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Track_Id'
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Entity_Ids_Single'
- description: |
The unique number or ID of the charge for which the product charge definitions are to be retrieved.
in: query
name: charge
required: false
schema:
type: string
- description: |
The unique number or ID of the product rate plan for which the product charge definitions are to be retrieved.
in: query
name: rateplan
required: false
schema:
type: string
- description: |
The flag that controls whether the response will merge the default charge definition fields for those fields that are not overridden.
in: query
name: hide-inherited-values
required: false
schema:
type: boolean
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Version'
responses:
'200':
content:
application/json:
examples:
response:
value:
chargeDefinitions:
- applyDiscountTo: null
billingDay: DefaultFromCustomer
billingPeriod: Month
billingPeriodAlignment: AlignToCharge
billingTiming: IN_ADVANCE
chargeModel: FlatFee
defaultQuantity: 1
deliverySchedule: null
description: ''
discountClass: null
discountLevel: null
effectiveEndDate: '2023-10-13 09:00:00'
effectiveStartDate: '2022-10-07 09:00:00'
endDateCondition: Subscription_End
financeInformation:
accountsReceivableAccountingCode: null
accountsReceivableAccountingCodeType: null
deferredRevenueAccountingCode: ''
deferredRevenueAccountingCodeType: null
recognizedRevenueAccountingCode: ''
recognizedRevenueAccountingCodeType: null
isDefault: true
isStackedDiscount: false
listPriceBase: Per_Billing_Period
numberOfPeriods: null
overageCalculationOption: null
overageUnusedUnitsCreditOption: null
priceChangeOption: null
priceIncreasePercentage: null
prices:
- currency: EUR
price: 10
- currency: JPY
price: 20
- currency: USD
price: 25
productChargeDefinitionId: 2c9890f78b0d09d2018b0d13c7fd0004
productChargeDefinitionNumber: CD-00000201
productDiscountApplyDetails: []
productRatePlanChargeId: 2c9890f78b0d09d2018b0d13c7fd0004
productRatePlanChargeNumber: null
productRatePlanId: null
productRatePlanName: null
productRatePlanNumber: null
ratingGroup: null
revRecCode: null
revRecTriggerCondition: null
revenueRecognitionRuleName: Recognize upon invoicing
smoothingModel: null
specificBillingPeriod: null
specificListPriceBase: null
taxCode: ''
taxMode: null
taxable: false
term: null
termPeriodType: null
termType: null
triggerEvent: ContractEffective
uom: null
upToPeriods: null
upToPeriodsType: null
usageRecordRatingOption: null
useDiscountSpecificAccountingCode: null
useTenantDefaultForPriceChange: true
success: true
schema:
$ref: '#/components/schemas/GETProductChargeDefinitionsResponse'
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'500':
content:
application/json:
examples:
response:
value:
reasons:
- code: SystemError
message: internal server error
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal Server Error
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
4XX:
content:
application/json:
examples:
response:
value:
processId: 738CBB9234B47A47
reasons:
- code: '58730222'
message: orderDate may not be null
requestId: d7479cf6-b410-4630-b841-268ccd48f0d2
success: false
schema:
$ref: '#/components/schemas/CommonResponse'
description: Request Errors
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
summary: List product charge definitions
tags:
- Product Charge Definitions
/v1/product-charge-definitions/bulk:
post:
description: |
Bulk creates product charge definitions for a charge. You can create up to 1000 product charge definitions at a given time for a specific charge.
In the request, you must specify the unique ID or number of the charge for which this charge definition is to be created.
The ID or number of a product rate plan is optional.
**Note**: This operation requires the [Attribute-based Pricing](https://knowledgecenter.zuora.com/Zuora_Billing/Build_products_and_prices/Attribute_based_pricing/AA_Overview_of_Attribute-based_Pricing) feature to be enabled, which is in the **Early Adopter** phase.
operationId: POST_CreateProductChargeDefinitionBulk
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_Zuora_Track_Id'
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Entity_Ids_Single'
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Version'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/POSTChargeDefinitionRequestBulk'
required: true
responses:
'200':
content:
application/json:
examples:
response:
value:
summary:
successCount: 1
failureCount: 0
failures: []
results:
- chargeDefinitionId: 8a9084f99325571d01932a15d64a3a1b
chargeDefinitionNumber: CD-00052014
success: true
success: true
schema:
$ref: '#/components/schemas/POSTChargeDefinitionBulkResponse'
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'500':
content:
application/json:
examples:
response:
value:
reasons:
- code: SystemError
message: internal server error
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal Server Error
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
4XX:
content:
application/json:
examples:
response:
value:
processId: 738CBB9234B47A47
reasons:
- code: '58730222'
message: orderDate may not be null
requestId: d7479cf6-b410-4630-b841-268ccd48f0d2
success: false
schema:
$ref: '#/components/schemas/CommonResponse'
description: Request Errors
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
summary: Create product charge definitions
tags:
- Product Charge Definitions
put:
description: |
Bulk updates multiple product charge definitions.
**Note**: This operation requires the [Attribute-based Pricing](https://knowledgecenter.zuora.com/Zuora_Billing/Build_products_and_prices/Attribute_based_pricing/AA_Overview_of_Attribute-based_Pricing) feature to be enabled, which is in the **Early Adopter** phase.
operationId: PUT_UpdateProductChargeDefinitionBulk
parameters:
- $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding'
- $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding'
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Track_Id'
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Entity_Ids_Single'
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Version'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PUTProductChargeDefinitionBulkRequest'
required: true
responses:
'200':
content:
application/json:
examples:
response:
value:
chargeDefinitions:
- applyDiscountTo: null
billingDay: DefaultFromCustomer
billingPeriod: Month
billingPeriodAlignment: AlignToCharge
billingTiming: IN_ADVANCE
chargeModel: FlatFee
defaultQuantity: 1
deliverySchedule: null
description: ''
discountClass: null
discountLevel: null
endDateCondition: Subscription_End
financeInformation:
accountsReceivableAccountingCode: null
accountsReceivableAccountingCodeType: null
deferredRevenueAccountingCode: ''
deferredRevenueAccountingCodeType: null
recognizedRevenueAccountingCode: ''
recognizedRevenueAccountingCodeType: null
isDefault: true
isStackedDiscount: false
listPriceBase: Per_Billing_Period
numberOfPeriods: null
overageCalculationOption: null
overageUnusedUnitsCreditOption: null
priceChangeOption: null
priceIncreasePercentage: null
prices:
- currency: EUR
price: 10
- currency: JPY
price: 20
- currency: USD
price: 25
productChargeDefinitionId: 2c9890f78b0d09d2018b0d13c7fd0004
productChargeDefinitionNumber: CD-00000201
productDiscountApplyDetails: []
productRatePlanChargeId: 2c9890f78b0d09d2018b0d13c7fd0004
productRatePlanChargeNumber: null
productRatePlanId: null
productRatePlanName: null
productRatePlanNumber: null
ratingGroup: null
revRecCode: null
revRecTriggerCondition: null
revenueRecognitionRuleName: Recognize upon invoicing
smoothingModel: null
specificBillingPeriod: null
specificListPriceBase: null
taxCode: ''
taxMode: null
taxable: false
term: null
termPeriodType: null
termType: null
triggerEvent: ContractEffective
uom: null
upToPeriods: null
upToPeriodsType: null
usageRecordRatingOption: null
useDiscountSpecificAccountingCode: null
useTenantDefaultForPriceChange: true
success: true
schema:
$ref: '#/components/schemas/GETProductChargeDefinitionsResponse'
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'500':
content:
application/json:
examples:
response:
value:
reasons:
- code: SystemError
message: internal server error
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal Server Error
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
4XX:
content:
application/json:
examples:
response:
value:
processId: 738CBB9234B47A47
reasons:
- code: '58730222'
message: orderDate may not be null
requestId: d7479cf6-b410-4630-b841-268ccd48f0d2
success: false
schema:
$ref: '#/components/schemas/CommonResponse'
description: Request Errors
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
summary: Update product charge definitions
tags:
- Product Charge Definitions
/v1/product-charge-definitions/{product-charge-definition-key}:
get:
description: |
Retrieves basic information about a product charge definition.
**Note**: This operation requires the [Attribute-based Pricing](https://knowledgecenter.zuora.com/Zuora_Billing/Build_products_and_prices/Attribute_based_pricing/AA_Overview_of_Attribute-based_Pricing) feature to be enabled, which is in the **Early Adopter** phase.
operationId: GET_RetrieveProductChargeDefinition
parameters:
- $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding'
- $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding'
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Track_Id'
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Entity_Ids_Single'
- description: |
The unique number or ID of the product charge definition to be retrieved.
in: path
name: product-charge-definition-key
required: true
schema:
type: string
- description: |
The flag that controls whether the response will merge the default charge definition fields for those fields that are not overridden.
in: query
name: hide-inherited-values
required: false
schema:
type: boolean
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Version'
responses:
'200':
content:
application/json:
examples:
response:
value:
applyDiscountTo: null
billingDay: DefaultFromCustomer
billingPeriod: Month
billingPeriodAlignment: AlignToCharge
billingTiming: IN_ADVANCE
chargeModel: FlatFee
defaultQuantity: 1
deliverySchedule: null
description: ''
discountClass: null
discountLevel: null
effectiveEndDate: '2023-10-13 09:00:00'
effectiveStartDate: '2022-10-07 09:00:00'
endDateCondition: Subscription_End
financeInformation:
accountsReceivableAccountingCode: null
accountsReceivableAccountingCodeType: null
deferredRevenueAccountingCode: ''
deferredRevenueAccountingCodeType: null
recognizedRevenueAccountingCode: ''
recognizedRevenueAccountingCodeType: null
isDefault: true
isStackedDiscount: false
listPriceBase: Per_Billing_Period
numberOfPeriods: null
overageCalculationOption: null
overageUnusedUnitsCreditOption: null
priceChangeOption: null
priceIncreasePercentage: null
prices:
- currency: EUR
price: 10
- currency: JPY
price: 20
- currency: USD
price: 25
productChargeDefinitionId: 2c9890f78b0d09d2018b0d13c7fd0004
productChargeDefinitionNumber: CD-00000201
productDiscountApplyDetails: []
productRatePlanChargeId: 2c9890f78b0d09d2018b0d13c7fd0004
productRatePlanChargeNumber: null
productRatePlanId: null
productRatePlanName: null
productRatePlanNumber: null
ratingGroup: null
revRecCode: null
revRecTriggerCondition: null
revenueRecognitionRuleName: Recognize upon invoicing
smoothingModel: null
specificBillingPeriod: null
specificListPriceBase: null
success: true
taxCode: ''
taxMode: null
taxable: false
term: null
termPeriodType: null
termType: null
triggerEvent: ContractEffective
uom: null
upToPeriods: null
upToPeriodsType: null
usageRecordRatingOption: null
useDiscountSpecificAccountingCode: null
useTenantDefaultForPriceChange: true
schema:
$ref: '#/components/schemas/GETProductChargeDefinitionResponse'
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'500':
content:
application/json:
examples:
response:
value:
reasons:
- code: SystemError
message: internal server error
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal Server Error
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
4XX:
content:
application/json:
examples:
response:
value:
processId: 738CBB9234B47A47
reasons:
- code: '58730222'
message: orderDate may not be null
requestId: d7479cf6-b410-4630-b841-268ccd48f0d2
success: false
schema:
$ref: '#/components/schemas/CommonResponse'
description: Request Errors
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
summary: Retrieve a product charge definition
tags:
- Product Charge Definitions
put:
description: |
Update a product charge definition.
**Note**: This operation requires the [Attribute-based Pricing](https://knowledgecenter.zuora.com/Zuora_Billing/Build_products_and_prices/Attribute_based_pricing/AA_Overview_of_Attribute-based_Pricing) feature to be enabled, which is in the **Early Adopter** phase.
operationId: PUT_UpdateProductChargeDefinition
parameters:
- $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding'
- $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding'
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Track_Id'
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Entity_Ids_Single'
- description: |
The unique number or ID of the product charge definition to be updated.
in: path
name: product-charge-definition-key
required: true
schema:
type: string
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Version'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PUTProductChargeDefinitionRequest'
required: true
responses:
'200':
content:
application/json:
examples:
response:
value:
applyDiscountTo: null
billingPeriod: Month
billingPeriodAlignment: AlignToCharge
billingTiming: IN_ADVANCE
chargeModel: FlatFee
defaultQuantity: 1
discountClass: null
discountLevel: null
effectiveEndDate: '2023-10-13 09:00:00'
effectiveStartDate: '2022-10-07 09:00:00'
isDefault: true
listPriceBase: Per_Billing_Period
numberOfPeriods: null
prices:
- currency: USD
price: 20
productChargeDefinitionId: 2c9890f78b0d09d2018b0d13c7fd0004
productChargeDefinitionNumber: CD-00000201
productRatePlanChargeId: 2c9890f78b0d09d2018b0d13c7fd0004
productRatePlanChargeNumber: null
productRatePlanId: null
productRatePlanName: null
productRatePlanNumber: null
ratingGroup: null
smoothingModel: null
specificBillingPeriod: null
specificListPriceBase: null
success: true
taxCode: ''
taxMode: null
taxable: false
term: null
termPeriodType: null
termType: null
uom: null
schema:
$ref: '#/components/schemas/GETProductChargeDefinitionResponse'
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'500':
content:
application/json:
examples:
response:
value:
reasons:
- code: SystemError
message: internal server error
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal Server Error
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
4XX:
content:
application/json:
examples:
response:
value:
processId: 738CBB9234B47A47
reasons:
- code: '58730222'
message: orderDate may not be null
requestId: d7479cf6-b410-4630-b841-268ccd48f0d2
success: false
schema:
$ref: '#/components/schemas/CommonResponse'
description: Request Errors
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
summary: Update a product charge definition
tags:
- Product Charge Definitions
delete:
description: |
Deletes a product charge definition.
**Note**: This operation requires the [Attribute-based Pricing](https://knowledgecenter.zuora.com/Zuora_Billing/Build_products_and_prices/Attribute_based_pricing/AA_Overview_of_Attribute-based_Pricing) feature to be enabled, which is in the **Early Adopter** phase.
operationId: DELETE_ProductChargeDefnition
parameters:
- $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding'
- $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding'
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Track_Id'
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Entity_Ids_Single'
- description: |
The unique number or ID of the product charge definition to be deleted.
in: path
name: product-charge-definition-key
required: true
schema:
type: string
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Version'
responses:
'200':
content:
application/json:
examples:
response:
value:
success: true
schema:
$ref: '#/components/schemas/CommonResponse'
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'500':
content:
application/json:
examples:
response:
value:
reasons:
- code: SystemError
message: internal server error
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal Server Error
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
4XX:
content:
application/json:
examples:
response:
value:
processId: 738CBB9234B47A47
reasons:
- code: '58730222'
message: orderDate may not be null
requestId: d7479cf6-b410-4630-b841-268ccd48f0d2
success: false
schema:
$ref: '#/components/schemas/CommonResponse'
description: Request Errors
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
summary: Delete a product charge definition
tags:
- Product Charge Definitions
/v1/object/product-rate-plan-charge-tier/{id}:
get:
description: Retrieves a specific product rate plan charge tier.
operationId: Object_GETProductRatePlanChargeTier
parameters:
- $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding'
- $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding'
- $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'
- description: Object fields to return
in: query
name: fields
required: false
schema:
type: string
- description: Object id
in: path
name: id
required: true
schema:
type: string
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Version'
responses:
'200':
content:
application/json:
examples:
response:
value:
CreatedById: 2c93808457d787030157e02fd0f132a4
CreatedDate: '2016-10-20T05:43:38.000+02:00'
Currency: USD
EndingUnit: 0
Id: 2c93808457d787030157e02fe725341f
Price: 30
PriceFormat: Flat Fee
StartingUnit: 0
Tier: 1
UpdatedById: 2c93808457d787030157e02fd0f132a4
UpdatedDate: '2016-10-20T05:43:38.000+02:00'
schema:
$ref: '#/components/schemas/ProxyGetProductRatePlanChargeTier'
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'401':
content:
application/json:
examples:
response:
value:
message: Authentication error
schema:
$ref: '#/components/schemas/ProxyUnauthorizedResponse'
description: Unauthorized
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information.
schema:
type: number
WWW-Authenticate:
description: |
The value of this header is:
```
Basic realm=Zuora API, ZSession realm=Zuora API, Bearer realm=Zuora API
```
schema:
enum:
- Basic realm=Zuora API, ZSession realm=Zuora API, Bearer realm=Zuora API
type: string
Zuora-Request-Id:
description: |
The Zuora internal identifier of the API call. You cannot control the value of this header.
schema:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'404':
content:
application/json:
examples:
response:
value:
done: true
records: {}
size: 0
schema:
$ref: '#/components/schemas/ProxyNoDataResponse'
description: ''
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
summary: 'CRUD: Retrieve a product rate plan charge tier'
tags:
- Product Rate Plan Charge Tiers
put:
description: |
Updates the price of a product rate plan charge tier.
To make other updates to product rate plan charge tiers, use [CRUD: Update a product rate plan charge](https://developer.zuora.com/api-references/api/operation/Object_PUTProductRatePlanCharge) and specify `ProductRatePlanChargeTierData` in the request body.
operationId: Object_PUTProductRatePlanChargeTier
parameters:
- $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding'
- $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding'
- $ref: '#/components/parameters/GLOBAL_REQUEST_rejectUnknownFields'
- $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'
- description: |
The unique ID of the product rate plan charge tier to be updated. For example, 2c92c0f86c85891e016c88d55a6e543b.
in: path
name: id
required: true
schema:
type: string
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Version'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ProxyModifyProductRatePlanChargeTier'
required: true
responses:
'200':
content:
application/json:
examples:
response:
value:
Id: 2c92c0f86c85891e016c88d55a6e543b
Success: true
schema:
$ref: '#/components/schemas/ProxyCreateOrModifyResponse'
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'401':
content:
application/json:
examples:
response:
value:
message: Authentication error
schema:
$ref: '#/components/schemas/ProxyUnauthorizedResponse'
description: Unauthorized
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information.
schema:
type: number
WWW-Authenticate:
description: |
The value of this header is:
```
Basic realm=Zuora API, ZSession realm=Zuora API, Bearer realm=Zuora API
```
schema:
enum:
- Basic realm=Zuora API, ZSession realm=Zuora API, Bearer realm=Zuora API
type: string
Zuora-Request-Id:
description: |
The Zuora internal identifier of the API call. You cannot control the value of this header.
schema:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
summary: 'CRUD: Update a product rate plan charge tier'
tags:
- Product Rate Plan Charge Tiers
/v1/revpro-accounting-codes:
put:
description: Update the Zuora Revenue accounting code that corresponds to a specific Product Rate Plan Charge Id in Zuora Billing.
operationId: PUT_RevProAccountingCodes
parameters:
- $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding'
- $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding'
- $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'
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Version'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RevproAccountingCodes'
required: true
responses:
'200':
content:
application/json:
examples:
response:
value:
success: true
schema:
$ref: '#/components/schemas/PUTRevproAccCodeResponse'
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'500':
content:
application/json:
examples:
response:
value:
reasons:
- code: SystemError
message: internal server error
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal Server Error
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
4XX:
content:
application/json:
examples:
response:
value:
processId: 738CBB9234B47A47
reasons:
- code: '58730222'
message: orderDate may not be null
requestId: d7479cf6-b410-4630-b841-268ccd48f0d2
success: false
schema:
$ref: '#/components/schemas/CommonResponse'
description: Request Errors
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
summary: Update a Zuora Revenue accounting code
tags:
- Zuora Revenue Integration
/commerce/charges:
post:
summary: Create a product rate plan charge with Dynamic Pricing
description: |
Create a product rate plan charge (PRPC) in the Product Catalog.
Use this endpoint to configure Dynamic Pricing, including default pricing at the charge level
and conditional rate cards evaluated by attribute values.
operationId: createProductRatePlanChargeWithDynamicPricing
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_Zuora_Entity_Ids_Single'
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Org_Ids'
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Track_Id'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateChargeRequest'
examples:
perUnitExample:
summary: Per-unit charge example
value:
charge:
charge_model: per_unit
charge_type: recurring
description: description
name: charge with dimensional price 1
unit_of_measure: Each
default_quantity: 10
bill_cycle:
period: bill_cycle_period_month
period_alignment: align_to_charge
timing: in_advance
type: default_from_customer
trigger_event: contract_effective
product_rate_plan_id: f5cf096c5ca94443f76446a981e50000
end_date_condition: subscription_end
up_to_periods_type: billing_periods
up_to_periods: 0
list_price_base: Per_Billing_Period
specific_list_price_base: 0
formula: price + 1
tax_mode: non_taxable
tax_code: TAX_EXEMPT
accounting:
accounting_code: PRPC-REV-001
accounts_receivable_account: Accounts Receivable
deferred_revenue_account: Deferred Revenue
recognized_revenue_account: Recognized Revenue
contract_asset_account: Contract Asset
contract_liability_account: Contract Liability
contract_recognized_revenue_account: Contract Recognized Revenue
unbilled_receivables_account: Unbilled Receivables
adjustment_liability_account: Adjustment Liability
adjustment_revenue_account: Adjustment Revenue
revenue:
revenue_recognition_rule_name: Recognize upon invoicing
exclude_item_billing_from_revenue_accounting: false
exclude_item_booking_from_revenue_accounting: false
custom_fields:
region__c: US
channel__c: Online
netsuite:
SubsidiaryNS: US
RecognizedRevAccountNS: 4000
DeferredRevAccountNS: 2500
attributes:
- name: Age
type: Integer
mapping:
object: account
field: age__c
rate_cards:
- attributes:
- name: Age
operator: <=
value: 12
pricing:
unit_amounts:
USD: 90
- attributes:
- name: Age
operator: between
value:
- 12
- 60
pricing:
unit_amounts:
USD: 100
- attributes:
- name: Age
operator: '>='
value: 60
pricing:
unit_amounts:
USD: 80
tieredExample:
summary: Tiered charge example
value:
charge:
charge_model: tiered
charge_type: usage
name: tiered charge
unit_of_measure: Each
bill_cycle:
period: bill_cycle_period_month
period_alignment: align_to_charge
timing: in_arrears
type: default_from_customer
trigger_event: contract_effective
product_rate_plan_id: f5cf096c5ca94443f76446a981e50000
attributes:
- name: Region
type: String
rate_cards:
- attributes:
- name: Region
operator: '=='
value: US
pricing:
tiers:
- tier: '1'
from: 0
up_to: 10
price_format: price_format_per_unit
unit_amounts:
USD: 2.5
min_amounts:
USD: 6.25
max_amounts:
USD: 25
- tier: '2'
from: 11
price_format: price_format_per_unit
unit_amounts:
USD: 1.5
min_amounts:
USD: 15
max_amounts:
USD: 150
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CreateChargeResponse'
examples:
response:
value:
accounting:
accountingCode: PRPC-REV-001
accountsReceivableAccount: Accounts Receivable
accountsReceivableAccountType: AccountsReceivable
deferredRevenueAccount: Deferred Revenue
deferredRevenueAccountType: DeferredRevenue
recognizedRevenueAccount: Recognized Revenue
recognizedRevenueAccountType: Recognized Revenue
adjustmentLiabilityAccount: adjustL-1
adjustmentLiabilityAccountType: AdjustmentLiability
adjustmentRevenueAccount: adjustRev-1
adjustmentRevenueAccountType: AdjustmentRevenue
contractAssetAccount: CA-2
contractAssetAccountType: ContractAsset
contractLiabilityAccount: CL-2
contractLiabilityAccountType: ContractLiability
contractRecognizedRevenueAccount: Contract Recognized Revenue
contractRecognizedRevenueAccountType: RecognizedRevenue
unbilledReceivablesAccount: unbilledR-1
unbilledReceivablesAccountType: UnbilledReceivables
productRatePlanChargeId: ad95b694d2b8442b84dc8ad26561c7d7
attributes: []
billCycle:
dayOfMonth: 5
period: bill_cycle_period_month
periodAlignment: align_to_charge
timing: in_advance
type: specific_day_of_month
chargeFunction: charge_function_standard
chargeModel: flat_fee
chargeType: recurring
createdById: 53c162482f054f3ca08e1ec82dccfec9
createdTime: '2025-10-13T07:46:02.000+00:00'
customFields: {}
discountOptions:
applyDetails: []
applyTo: []
applyToBillingPeriodPartially: false
reflectDiscountInNetAmount: false
rollover: false
stackedDiscount: false
drawdown: {}
endDateCondition: subscription_end
upToPeriodsType: billing_periods
upToPeriods: 0
extendedPrice: {}
id: ad95b694d2b8442b84dc8ad26561c7d7
isChargeLevelMinCommit: false
isCommitted: false
labels: {}
listPriceBase: Per_Billing_Period
specificListPriceBase: 0
mergedRateCards: []
name: Flat PRPC 1
negotiatedRateCards: []
ocmJsonByCurrency: {}
organizationLabels: []
overageOptions:
includedUnits: 0
unusedUnitsCreditRates: {}
prepaid: false
prepayment:
rollover: false
rolloverApply: apply_last
rolloverPeriodLength: 0
rolloverPeriods: 0
priceChangeOption: no_change
pricing:
adjustments: {}
discountAmounts: {}
discountPercentages: {}
flatAmounts:
USD: 100
maxAmounts: {}
minAmounts: {}
percentages: {}
tiers: []
unitAmounts: {}
pricingSummary:
- USD100
pricingWaterfalls: {}
productChargeDefinitions: []
productRatePlanChargeNumber: PRPC-00000279
productRatePlanId: ee2d1ce1036c4dd6ae9d6945565ff7a0
prorationOption: default_from_tenant_setting
rateCards: []
revenue:
excludeItemBillingFromRevenueAccounting: false
excludeItemBookingFromRevenueAccounting: false
legacyReporting: false
revenueRecognitionRuleName: Recognize upon invoicing
taxMode: non_taxable
taxCode: TAX_EXEMPT
taxable: false
triggerEvent: contract_effective
updatedById: 53c162482f054f3ca08e1ec82dccfec9
updatedTime: '2025-10-13T07:46:02.000+00:00'
useTenantDefaultForPriceChange: true
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ProxyBadRequestResponse'
examples:
response:
value:
Errors:
- Code: INVALID_VALUE
Message: The account number 123xProxy is invalid.
Success: false
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ProxyUnauthorizedResponse'
examples:
response:
value:
message: Authentication error
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information.
schema:
type: number
WWW-Authenticate:
description: The value of this header is:\n\n```\n\nBasic realm=Zuora API, ZSession realm=Zuora API, Bearer realm=Zuora API\n\n```\n
schema:
type: string
enum:
- Basic realm=Zuora API, ZSession realm=Zuora API, Bearer realm=Zuora API
Zuora-Request-Id:
description: The Zuora internal identifier of the API call. You cannot control the value of this header.
schema:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
tags:
- Commerce
put:
description: |
Update an existing product rate plan charge (PRPC). Use this API to update default pricing and/or conditional rate cards.
operationId: updateProductRatePlanChargeWithDynamicPricing
parameters:
- $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding'
- $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding'
- $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'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateChargeRequest'
example:
charge:
id: 9c4867ed55db43a89731605d5654d4ed
pricing:
unit_amounts:
USD: 175
rate_cards:
- attributes:
- name: Age
operator: <=
value: 12
- name: EffectiveDate
operator: '>='
value: '2025-02-01T00:00:00+00:00'
pricing:
unit_amounts:
USD: 180
- attributes:
- name: Age
operator: between
value:
- 12
- 60
- name: EffectiveDate
operator: '>='
value: '2025-02-01T00:00:00+00:00'
pricing:
unit_amounts:
USD: 200
- attributes:
- name: Age
operator: '>='
value: 60
- name: EffectiveDate
operator: '>='
value: '2025-02-01T00:00:00+00:00'
pricing:
unit_amounts:
USD: 160
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CreateChargeResponse'
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
'400':
description: Request Errors or Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/CommonResponse'
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ProxyUnauthorizedResponse'
examples:
response:
value:
message: Authentication error
headers:
Content-Encoding:
schema:
type: string
WWW-Authenticate:
schema:
type: string
description: |
The value of this header is:
```
Basic realm=Zuora API, ZSession realm=Zuora API, Bearer realm=Zuora API
```
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
response:
value:
reasons:
- code: SystemError
message: internal server error
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
summary: Update a product rate plan charge with Dynamic Pricing
tags:
- Commerce
/commerce/charges/query:
post:
description: |
Returns a product rate plan charge (PRPC) by evaluating Dynamic Pricing against the provided attribute values.
If a matching rate-card row is found, its pricing is returned; otherwise, the default charge-level pricing is used (if defined).
This operation can be used to simulate pricing resolution without creating or updating the charge.
operationId: queryProductRatePlanChargeWithDynamicPricing
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_Zuora_Entity_Ids_Single'
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Org_Ids'
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Track_Id'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/QueryChargeRequest'
examples:
minimal:
summary: Query with only the PRPC key (no attributes)
value:
product_rate_plan_charge_key: ad95b694d2b8442b84dc8ad26561c7d7
withAttributes:
summary: Query with optional attribute values
value:
product_rate_plan_charge_key: ad95b694d2b8442b84dc8ad26561c7d7
evaluation_level: LIST_PRICE
attributes:
- name: Age
number_value: 11
- name: EffectiveDate
datetime_value: '2025-02-01T00:00:00Z'
- name: AccountContext
value: Liquidity Provider
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CreateChargeResponse'
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'400':
content:
application/json:
examples:
response:
value:
Errors:
- Code: INVALID_VALUE
Message: The account number 123xProxy is invalid.
Success: false
schema:
$ref: '#/components/schemas/ProxyBadRequestResponse'
description: Bad Request
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'401':
content:
application/json:
examples:
response:
value:
message: Authentication error
schema:
$ref: '#/components/schemas/ProxyUnauthorizedResponse'
description: Unauthorized
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information.
schema:
type: number
WWW-Authenticate:
description: |
The value of this header is:
```
Basic realm=Zuora API, ZSession realm=Zuora API, Bearer realm=Zuora API
```
schema:
enum:
- Basic realm=Zuora API, ZSession realm=Zuora API, Bearer realm=Zuora API
type: string
Zuora-Request-Id:
description: |
The Zuora internal identifier of the API call. You cannot control the value of this header.
schema:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
summary: Query a product rate plan charge with Dynamic Pricing
tags:
- Commerce
/commerce/products:
post:
summary: Create a product with plans and charges
description: |
Create a product in the Product Catalog with one or more plans and charges.
Charges can be usage (per-unit), recurring (flat fee), or other supported models.
operationId: createProduct
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_Zuora_Entity_Ids_Single'
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Org_Ids'
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Track_Id'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateProductRequest'
examples:
createProductExample:
summary: Product with one plan and one recurring flat-fee charge
value:
name: New prod
start_date: '2024-01-01'
end_date: '2050-12-31'
category: base
plans:
- name: Consumer Bronze Monthly
start_date: '2024-01-01'
end_date: '2050-12-31'
active_currencies:
- USD
charges:
- name: Flat PRPC
charge_type: recurring
charge_model: flat_fee
default_quantity: 10
min_quantity: 1
max_quantity: 999999
price_increase_percentage: 0
price_change_option: no_change
use_tenant_default_for_price_change: true
discount_options:
discount_class: ''
discount_level: rate_plan
stacked_discount: false
apply_to:
- one_time
- recurring
- usage
apply_to_billing_period_partially: false
reflect_discount_in_net_amount: false
rollover: false
specific_accounting_codes: false
apply_details: []
pricing:
flat_amounts:
USD: 100
bill_cycle:
type: specific_day_of_month
day_of_month: 5
period_alignment: align_to_charge
period: bill_cycle_period_month
timing: in_advance
trigger_event: contract_effective
end_date_condition: subscription_end
up_to_periods_type: billing_periods
up_to_periods: 0
list_price_base: Per_Billing_Period
specific_list_price_base: 0
accounting:
accounting_code: PRPC-REV-002
accounts_receivable_account: Accounts Receivable
deferred_revenue_account: Deferred Revenue
recognized_revenue_account: Recognized Revenue
adjustment_liability_account: adjustL-2
adjustment_revenue_account: adjustRev-2
contract_asset_account: CA-3
contract_liability_account: CL-3
contract_recognized_revenue_account: Contract Recognized Revenue
unbilled_receivables_account: unbilledR-2
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CreateProductResponse'
examples:
response:
value:
allowFeatureChanges: false
category: base
contextFilters: []
createdBy: 53c162482f054f3ca08e1ec82dccfec9
createdTime: '2025-10-17T04:02:54.621-07:00'
customFields: {}
customObjects: null
description: ''
endDate: '2050-12-31'
features: []
id: 7ec58fadb6f84bc18e59c7529058d941
legacyFeatures: []
name: New prod
netsuite: null
organizationLabels: []
plans:
- activeCurrencies:
- USD
attributes: []
contextFilters: []
createTime: '2025-10-17T04:02:54.655-07:00'
createdBy: 53c162482f054f3ca08e1ec82dccfec9
customFields: {}
description: ''
displayName: ''
endDate: '2050-12-31'
entitlements: []
externalIdSourceSystem: ''
externalRateplanId: []
id: 572a2efe711b449e80cbef94419bc050
name: Consumer Bronze Monthly
netsuite: null
organizationLabels: []
productId: 7ec58fadb6f84bc18e59c7529058d941
productRatePlanCharges:
- accounting:
accountingCode: Accounts Receivable
accountsReceivableAccount: Accounts Receivable
deferredRevenueAccount: Accounts Receivable
recognizedRevenueAccount: Recognized Revenue
attributes: []
billCycle:
dayOfMonth: 5
period: bill_cycle_period_month
periodAlignment: align_to_charge
timing: in_advance
type: specific_day_of_month
chargeFunction: charge_function_standard
chargeModel: flat_fee
chargeType: recurring
createdById: 53c162482f054f3ca08e1ec82dccfec9
createdTime: '2025-10-17T04:02:54.719-07:00'
customFields: {}
discountOptions:
applyDetails: []
applyTo: []
applyToBillingPeriodPartially: false
reflectDiscountInNetAmount: false
rollover: false
stackedDiscount: false
drawdown: {}
endDateCondition: subscription_end
upToPeriodsType: billing_periods
upToPeriods: 0
extendedPrice: {}
id: 42db6ead399a4521bae91b3af469c074
isChargeLevelMinCommit: false
isCommitted: false
labels: {}
listPriceBase: Per_Billing_Period
specificListPriceBase: 0
mergedRateCards: []
name: Flat PRPC
negotiatedRateCards: []
ocmJsonByCurrency: {}
organizationLabels: []
overageOptions:
includedUnits: 0
unusedUnitsCreditRates: {}
prepaid: false
prepayment:
rollover: false
rolloverApply: apply_last
rolloverPeriodLength: 0
rolloverPeriods: 0
priceChangeOption: no_change
pricing:
adjustments: {}
discountAmounts: {}
discountPercentages: {}
flatAmounts:
USD: 100
maxAmounts: {}
minAmounts: {}
percentages: {}
tiers: []
unitAmounts: {}
pricingSummary: []
pricingWaterfalls: {}
productChargeDefinitions: []
productRatePlanChargeNumber: PRPC-00000283
productRatePlanId: 572a2efe711b449e80cbef94419bc050
prorationOption: default_from_tenant_setting
rateCards: []
revenue:
excludeItemBillingFromRevenueAccounting: false
excludeItemBookingFromRevenueAccounting: false
legacyReporting: false
revenueRecognitionRuleName: Recognize upon invoicing
taxable: false
triggerEvent: contract_effective
updatedById: 53c162482f054f3ca08e1ec82dccfec9
updatedTime: '2025-10-17T04:02:54.719-07:00'
useTenantDefaultForPriceChange: true
productRatePlanNumber: PRP-00000198
startDate: '2024-01-01'
state: active
updateTime: '2025-10-17T04:02:54.655-07:00'
updatedBy: 53c162482f054f3ca08e1ec82dccfec9
productNumber: PC-00000105
sku: SKU-00000135
startDate: '2024-01-01'
state: product_active
updatedBy: 53c162482f054f3ca08e1ec82dccfec9
updatedTime: '2025-10-17T04:02:54.621-07:00'
headers:
Content-Encoding:
description: |
Returned if `Accept-Encoding: gzip` is specified and the response exceeds 1000 bytes. Supported MIME types: application/json, application/xml, text/html, text/csv, text/plain.
schema:
type: string
RateLimit-Limit:
schema:
type: string
RateLimit-Remaining:
schema:
type: number
RateLimit-Reset:
schema:
type: number
Zuora-Request-Id:
schema:
type: string
minLength: 36
maxLength: 36
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ProxyBadRequestResponse'
examples:
response:
value:
Errors:
- Code: INVALID_VALUE
Message: The account number 123xProxy is invalid.
Success: false
tags:
- Commerce
put:
summary: Update a product
description: |
Updates an existing product in the Product Catalog. Use this API to update core product fields
such as name, description, category, effective dates, and custom fields.
operationId: updateProduct
tags:
- Commerce
parameters:
- $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding'
- $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding'
- $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'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateProductRequest'
example:
id: 8ad088009840d1c2019855e15c993f2f
name: Software Service
description: Software service - basic edition
category: base
custom_fields:
HelloBay__c: Updated value
Tags__c:
- AI Powered
- Internet Required
startDate: '2025-05-11'
endDate: '2050-12-10'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateProductResponse'
examples:
response:
value:
allowFeatureChanges: false
category: base
contextFilters: []
createdBy: 8a90a2fd8030ea2e018032b11d3a3f06
createdTime: '2025-08-06T18:11:35.000-07:00'
customFields: {}
customObjects: null
description: Software service - basic edition
endDate: '2050-12-31'
features: []
id: 00c86e3a0595442c88ed9ef8474b10a7
legacyFeatures: []
name: Amadeus
netsuite: null
organizationLabels: []
productNumber: PC-00000095
productRatePlans: []
sku: SKU-00000122
startDate: '2024-01-08'
state: product_active
updatedBy: 53c162482f054f3ca08e1ec82dccfec9
updatedTime: '2025-10-23T04:55:54.000-07:00'
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information.
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
'400':
description: Request Errors or Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/CommonResponse'
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information.
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ProxyUnauthorizedResponse'
examples:
response:
value:
message: Authentication error
headers:
Content-Encoding:
schema:
type: string
WWW-Authenticate:
schema:
type: string
description: |
The value of this header is:
```
Basic realm=Zuora API, ZSession realm=Zuora API, Bearer realm=Zuora API
```
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
response:
value:
reasons:
- code: SystemError
message: internal server error
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information.
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
/commerce/plans:
post:
summary: Create a product rate plan
description: |
Create a product rate plan (Plan) under an existing product.
A plan includes one or more **charges**. Each charge **must** include:
- `name`
- `charge_model`
- `charge_type`
- `bill_cycle`
- `trigger_event`
- `end_date_condition`
- `pricing`
Optional charge fields include: `unit_of_measure`, `list_price_base`, and `accounting` (with `accounting_code`, `deferred_revenue_account`, `recognized_revenue_account`).
operationId: createPlan
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_Zuora_Entity_Ids_Single'
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Org_Ids'
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Track_Id'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePlanRequest'
examples:
createPlanExample:
summary: Create a plan with two recurring flat-fee charges
value:
product_key: 6b14067136304e64b090daccae6680cb
name: New plan
start_date: '2024-01-01'
end_date: '2049-12-31'
active_currencies:
- USD
charges:
- name: Flat PRPC 1
charge_model: flat_fee
charge_type: recurring
pricing:
flat_amounts:
USD: 100
bill_cycle:
type: specific_day_of_month
day_of_month: 5
period_alignment: align_to_charge
period: bill_cycle_period_month
end_date_condition: subscription_end
up_to_periods_type: billing_periods
up_to_periods: 0
list_price_base: Per_Billing_Period
specific_list_price_base: 0
trigger_event: contract_effective
accounting:
accounting_code: PRPC-REV-001
accounts_receivable_account: Accounts Receivable
deferred_revenue_account: Deferred Revenue
recognized_revenue_account: Recognized Revenue
adjustment_liability_account: adjustL-1
adjustment_revenue_account: adjustRev-1
contract_asset_account: CA-2
contract_liability_account: CL-2
contract_recognized_revenue_account: Contract Recognized Revenue
unbilled_receivables_account: unbilledR-1
- name: Flat PRPC 2
charge_model: flat_fee
charge_type: recurring
pricing:
flat_amounts:
USD: 100
bill_cycle:
type: specific_day_of_month
day_of_month: 5
period_alignment: align_to_charge
period: bill_cycle_period_month
end_date_condition: subscription_end
trigger_event: contract_effective
accounting:
accounting_code: PRPC-REV-002
accounts_receivable_account: Accounts Receivable
deferred_revenue_account: Deferred Revenue
recognized_revenue_account: Recognized Revenue
adjustment_liability_account: adjustL-2
adjustment_revenue_account: adjustRev-2
contract_asset_account: CA-3
contract_liability_account: CL-3
contract_recognized_revenue_account: Contract Recognized Revenue
unbilled_receivables_account: unbilledR-2
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePlanResponse'
examples:
response:
value:
activeCurrencies:
- USD
attributes: []
contextFilters: []
createTime: '2025-10-13T07:46:02.314-07:00'
createdBy: 53c162482f054f3ca08e1ec82dccfec9
customFields: {}
description: ''
displayName: ''
endDate: '2049-12-31'
entitlements: []
externalIdSourceSystem: ''
externalRateplanId: []
id: ee2d1ce1036c4dd6ae9d6945565ff7a0
name: New plan
netsuite: null
organizationLabels: []
productId: 7228c9e6fd814e3a9e59bcdf0117e34f
productRatePlanCharges:
- accounting:
accountingCode: PRPC-REV-001
accountsReceivableAccount: Accounts Receivable
accountsReceivableAccountType: AccountsReceivable
deferredRevenueAccount: Deferred Revenue
deferredRevenueAccountType: DeferredRevenue
recognizedRevenueAccount: Recognized Revenue
recognizedRevenueAccountType: RecognizedRevenue
adjustmentLiabilityAccount: adjustL-1
adjustmentLiabilityAccountType: AdjustmentLiability
adjustmentRevenueAccount: adjustRev-1
adjustmentRevenueAccountType: AdjustmentRevenue
contractAssetAccount: CA-2
contractAssetAccountType: ContractAsset
contractLiabilityAccount: CL-2
contractLiabilityAccountType: ContractLiability
contractRecognizedRevenueAccount: Contract Recognized Revenue
contractRecognizedRevenueAccountType: RecognizedRevenue
unbilledReceivablesAccount: unbilledR-1
unbilledReceivablesAccountType: UnbilledReceivables
productRatePlanChargeId: ad95b694d2b8442b84dc8ad26561c7d7
attributes: []
billCycle:
dayOfMonth: 5
period: bill_cycle_period_month
periodAlignment: align_to_charge
timing: in_advance
type: specific_day_of_month
chargeFunction: charge_function_standard
chargeModel: flat_fee
chargeType: recurring
createdById: 53c162482f054f3ca08e1ec82dccfec9
createdTime: '2025-10-13T07:46:02.375-07:00'
customFields: {}
discountOptions:
applyToBillingPeriodPartially: false
reflectDiscountInNetAmount: false
rollover: false
stackedDiscount: false
drawdown: {}
endDateCondition: subscription_end
upToPeriodsType: billing_periods
upToPeriods: 0
listPriceBase: Per_Billing_Period
specificListPriceBase: 0
extendedPrice: {}
id: ad95b694d2b8442b84dc8ad26561c7d7
isChargeLevelMinCommit: false
isCommitted: false
labels: {}
mergedRateCards: []
name: Flat PRPC 1
negotiatedRateCards: []
ocmJsonByCurrency: {}
organizationLabels: []
overageOptions:
includedUnits: 0
unusedUnitsCreditRates: {}
prepaid: false
prepayment:
rollover: false
rolloverApply: apply_last
rolloverPeriodLength: 0
rolloverPeriods: 0
priceChangeOption: no_change
pricing:
discountAmounts: {}
discountPercentages: {}
flatAmounts:
USD: 100
maxAmounts: {}
minAmounts: {}
percentages: {}
tiers: []
unitAmounts: {}
pricingSummary: []
pricingWaterfalls: {}
productChargeDefinitions: []
productRatePlanChargeNumber: PRPC-00000279
productRatePlanId: ee2d1ce1036c4dd6ae9d6945565ff7a0
prorationOption: default_from_tenant_setting
rateCards: []
revenue:
excludeItemBillingFromRevenueAccounting: false
excludeItemBookingFromRevenueAccounting: false
legacyReporting: false
revenueRecognitionRuleName: Recognize upon invoicing
taxable: false
triggerEvent: contract_effective
updatedById: 53c162482f054f3ca08e1ec82dccfec9
updatedTime: '2025-10-13T07:46:02.375-07:00'
useTenantDefaultForPriceChange: true
productRatePlanNumber: PRP-00000195
startDate: '2024-01-01'
state: active
updateTime: '2025-10-13T07:46:02.314-07:00'
updatedBy: 53c162482f054f3ca08e1ec82dccfec9
headers:
Content-Encoding:
description: |
Returned if `Accept-Encoding: gzip` is specified and the response exceeds 1000 bytes. Supported MIME types: application/json, application/xml, text/html, text/csv, text/plain.
schema:
type: string
RateLimit-Limit:
description: The request limit quota for the time window closest to exhaustion. See rate limits docs.
schema:
type: string
RateLimit-Remaining:
description: The number of requests remaining in the time window closest to quota exhaustion. See rate limits docs.
schema:
type: number
RateLimit-Reset:
description: The number of seconds until the quota resets for the time window closest to exhaustion. See rate limits docs.
schema:
type: number
Zuora-Request-Id:
description: The Zuora internal identifier of the API call.
schema:
type: string
minLength: 36
maxLength: 36
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ProxyBadRequestResponse'
examples:
response:
value:
Errors:
- Code: INVALID_VALUE
Message: The account number 123xProxy is invalid.
headers:
Content-Encoding:
description: |
Returned if `Accept-Encoding: gzip` is specified and the response exceeds 1000 bytes. Supported MIME types: application/json, application/xml, text/html, text/csv, text/plain.
schema:
type: string
RateLimit-Limit:
description: The request limit quota for the time window closest to exhaustion. See rate limits docs.
schema:
type: string
RateLimit-Remaining:
description: The number of requests remaining in the time window closest to quota exhaustion. See rate limits docs.
schema:
type: number
RateLimit-Reset:
description: The number of seconds until the quota resets for the time window closest to exhaustion. See rate limits docs.
schema:
type: number
WWW-Authenticate:
description: |
The value of this header is:
```
Basic realm=Zuora API, ZSession realm=Zuora API, Bearer realm=Zuora API
```
schema:
type: string
enum:
- Basic realm=Zuora API, ZSession realm=Zuora API, Bearer realm=Zuora API
Zuora-Request-Id:
description: The Zuora internal identifier of the API call.
schema:
type: string
minLength: 36
maxLength: 36
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
tags:
- Commerce
put:
summary: Update a product rate plan
description: |
Updates an existing Product Rate Plan (PRP) in the Product Catalog.
Use this API to update core plan fields such as name, description, grade, and effective dates.
operationId: updateProductRatePlan
tags:
- Commerce
parameters:
- $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding'
- $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding'
- $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'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdatePlanRequest'
example:
id: 5758b1d5a589840e0e6855e1c2ce014d
name: Bronze Plan
description: Basic version of our software service
grade: 1
startDate: '2025-09-10'
endDate: '2043-08-16'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/UpdatePlanResponse'
examples:
response:
value:
activeCurrencies:
- USD
attributes: []
contextFilters: []
createTime: '2025-02-24T01:20:44.000+00:00'
createdBy: 8a90a2fd8030ea2e018032b11d3a3f06
customFields: {}
description: Basic version of our software service
displayName: ''
endDate: '2027-01-01'
entitlements: []
externalIdSourceSystem: ''
externalRateplanId: []
id: 38660706ef2f48cfb5222f7dde491895
name: Bronze Plan
netsuite: {}
organizationLabels: []
productId: 8a90aac8948deebf01949098b7790326
productRatePlanCharges:
- id: 99e226fec45943f4b80ed7bcf6d595d7
name: disc_currency
chargeType: recurring
chargeModel: discount_percentage
triggerEvent: contract_effective
billCycle:
period: bill_cycle_period_quarter
periodAlignment: align_to_term_start
type: term_start_day
pricing:
discountPercentages:
USD: 10
tiers: []
prepayment:
creditOption: time_based
rollover: false
rolloverApply: apply_last
rolloverPeriodLength: 0
rolloverPeriods: 0
validityPeriod: subscription_term
taxMode: non_taxable
taxable: false
createdById: 8a90a2fd8030ea2e018032b11d3a3f06
createdTime: '2025-02-24T01:21:51.000+00:00'
updatedById: 8a90a2fd8030ea2e018032b11d3a3f06
updatedTime: '2025-02-24T01:21:51.000+00:00'
- id: fe9b0e764dca4178a11c0e471e5dc0d8
name: prepay_currency
chargeType: recurring
chargeModel: flat_fee
listPriceBase: Per_Billing_Period
triggerEvent: contract_effective
billCycle:
period: bill_cycle_period_quarter
periodAlignment: align_to_term_start
timing: in_advance
type: term_start_day
pricing:
flatAmounts:
USD: 30
tiers: []
prepayment:
creditOption: consumption_based
operationType: prepaid_operation_type_topup
rollover: false
rolloverApply: apply_last
rolloverPeriodLength: 0
rolloverPeriods: 0
validityPeriod: quarter
taxMode: non_taxable
taxable: false
createdById: 8a90a2fd8030ea2e018032b11d3a3f06
createdTime: '2025-02-24T01:21:23.000+00:00'
updatedById: 8a90a2fd8030ea2e018032b11d3a3f06
updatedTime: '2025-02-24T01:21:23.000+00:00'
productRatePlanNumber: PRP-00000172
startDate: '2025-09-10'
state: active
status: ACTIVE
updateTime: '2025-10-23T05:16:28.334+00:00'
updatedBy: 53c162482f054f3ca08e1ec82dccfec9
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/rate-limits/) for more information.
schema:
type: string
RateLimit-Remaining:
description: The number of requests remaining in the time window closest to quota exhaustion.
schema:
type: number
RateLimit-Reset:
description: The number of seconds until the quota resets for the time window closest to exhaustion.
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
'400':
description: Request Errors or Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/CommonResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ProxyUnauthorizedResponse'
examples:
response:
value:
message: Authentication error
headers:
Content-Encoding:
schema:
type: string
WWW-Authenticate:
schema:
type: string
description: |
The value of this header is:
```
Basic realm=Zuora API, ZSession realm=Zuora API, Bearer realm=Zuora API
```
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
response:
value:
reasons:
- code: SystemError
message: internal server error
/commerce/plans/query:
post:
description: |
Retrieve details of a **single** product rate plan (PRP) from the Product Catalog. You can expand associated product rate plan charges for each plan.
This operation is a **strict lookup** and **requires** `product_rate_plan_key`. It does **not** support `attributes` or other list-style filters.
To browse or filter plans (including by `attributes`), use the "Query product rate plans" operation (`POST /commerce/plans/list`).
operationId: queryCommerceProductRatePlans
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_Zuora_Entity_Ids_Single'
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Org_Ids'
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Track_Id'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/QueryChargeRequest'
examples:
byPlanIdExpandCharges:
summary: Query a single PRP by key and expand charges
value:
product_rate_plan_key: 572a2efe711b449e80cbef94419bc050
expand:
product_rate_plan_charges: true
byPlanKeyNoExpand:
summary: Query a single PRP by key (no expansion)
value:
product_rate_plan_key: 11dc762a07064ce496af73ff4cfb5614
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CreateChargeResponse'
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'400':
content:
application/json:
examples:
response:
value:
Errors:
- Code: INVALID_VALUE
Message: The account number 123xProxy is invalid.
Success: false
schema:
$ref: '#/components/schemas/ProxyBadRequestResponse'
description: Bad Request
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'401':
content:
application/json:
examples:
response:
value:
message: Authentication error
schema:
$ref: '#/components/schemas/ProxyUnauthorizedResponse'
description: Unauthorized
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information.
schema:
type: number
WWW-Authenticate:
description: |
The value of this header is:
```
Basic realm=Zuora API, ZSession realm=Zuora API, Bearer realm=Zuora API
```
schema:
enum:
- Basic realm=Zuora API, ZSession realm=Zuora API, Bearer realm=Zuora API
type: string
Zuora-Request-Id:
description: |
The Zuora internal identifier of the API call. You cannot control the value of this header.
schema:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
summary: Query product rate plan details
tags:
- Commerce
/commerce/plans/list:
post:
summary: Query product rate plans
description: |
Queries product rate plans (PRPs) from the Product Catalog using filters such as plan ID, name, or product ID.
You can optionally expand related Product Rate Plan Charges (PRPCs) in the response.
operationId: queryCommercePlansList
tags:
- Commerce
parameters:
- $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding'
- $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding'
- $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'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ListPlansRequest'
example:
filters:
- field: prp_id
operator: EQ
value: 38660706ef2f48cfb5222f7dde491895
expand:
product_rate_plan_charges: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ListPlansResponse'
examples:
response:
value:
values:
- id: 38660706ef2f48cfb5222f7dde491895
createdBy: 8a90a2fd8030ea2e018032b11d3a3f06
createTime: '2025-02-24T01:21:23.000+00:00'
updatedBy: 8a90a2fd8030ea2e018032b11d3a3f06
updateTime: '2025-02-24T01:21:23.000+00:00'
displayName: Bronze Plan
name: Bronze Plan
description: Basic version of our software service
productId: 8a90aac8948deebf01949098b7790326
startDate: '2025-09-10'
endDate: '2027-01-01'
state: active
status: ACTIVE
activeCurrencies:
- USD
productRatePlanNumber: PRP-00000172
productRatePlanCharges:
- id: fe9b0e764dca4178a11c0e471e5dc0d8
productRatePlanChargeNumber: PRPC-00000279
name: prepay_currency
chargeType: recurring
chargeModel: flat_fee
listPriceBase: Per_Billing_Period
triggerEvent: contract_effective
unitOfMeasure: Each
defaultQuantity: 1
endDateCondition: subscription_end
upToPeriodsType: billing_periods
upToPeriods: 0
billCycle:
period: bill_cycle_period_quarter
periodAlignment: align_to_term_start
timing: in_advance
type: term_start_day
pricing:
flatAmounts:
USD: 30
tiers: []
pricingSummary:
- USD30
taxMode: non_taxable
taxable: false
createdById: 8a90a2fd8030ea2e018032b11d3a3f06
createdTime: '2025-02-24T01:21:23.000+00:00'
updatedById: 8a90a2fd8030ea2e018032b11d3a3f06
updatedTime: '2025-02-24T01:21:23.000+00:00'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/CommonResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ProxyUnauthorizedResponse'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/commerce/products/{product_key}:
post:
description: |
Retrieves detailed information about a specific product by its unique product number or ID.
You can optionally specify related objects to expand in the request body.
operationId: getProductByKey
summary: Retrieve a product by key
parameters:
- $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding'
- $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding'
- $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'
- description: The unique number or ID of the product to be retrieved.
in: path
name: product_key
required: true
schema:
type: string
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
expand:
type: object
description: |
Controls which related objects are expanded and included in the response.
properties:
productRatePlans:
type: boolean
description: When `true`, includes product rate plans in the response.
productRatePlanCharges:
type: boolean
description: When `true`, includes product rate plan charges in the response.
businessContextFilters:
type: boolean
description: When `true`, includes business context filters in the response.
examples:
expand:
summary: Expand related objects
value:
expand:
productRatePlans: true
productRatePlanCharges: true
businessContextFilters: true
responses:
'200':
description: |
OK
content:
application/json:
examples:
response:
value:
id: 7228c9e6fd814e3a9e59bcdf0117e34f
createdBy: 53c162482f054f3ca08e1ec82dccfec9
createdTime: '2025-10-13T07:44:55.000-07:00'
updatedBy: 53c162482f054f3ca08e1ec82dccfec9
updatedTime: '2025-10-13T07:44:55.000-07:00'
name: New prod
description: Example product description
productNumber: PC-00000103
sku: SKU-00000133
startDate: '2024-01-01'
endDate: '2050-12-31'
category: base
customFields: {}
customObjects: null
allowFeatureChanges: false
productRatePlans:
- id: 38660706ef2f48cfb5222f7dde491895
createdBy: 53c162482f054f3ca08e1ec82dccfec9
createTime: '2025-02-24T01:21:23.000+00:00'
updatedBy: 53c162482f054f3ca08e1ec82dccfec9
updateTime: '2025-02-24T01:21:23.000+00:00'
name: Bronze Plan
displayName: Bronze Plan
description: Basic version of our software service
productId: 7228c9e6fd814e3a9e59bcdf0117e34f
startDate: '2025-09-10'
endDate: '2027-01-01'
state: active
status: ACTIVE
activeCurrencies:
- USD
productRatePlanNumber: PRP-00000172
productRatePlanCharges:
- id: fe9b0e764dca4178a11c0e471e5dc0d8
productRatePlanChargeNumber: PRPC-00000279
name: prepay_currency
description: Prepaid recurring software fee
chargeType: recurring
chargeModel: flat_fee
listPriceBase: Per_Billing_Period
specificListPriceBase: 1
triggerEvent: contract_effective
endDateCondition: subscription_end
upToPeriodsType: billing_periods
upToPeriods: 1
billCycle:
period: bill_cycle_period_quarter
periodAlignment: align_to_term_start
timing: in_advance
type: term_start_day
pricing:
flatAmounts:
USD: 30
tiers: []
pricingSummary:
- USD30
taxMode: non_taxable
taxable: false
createdById: 53c162482f054f3ca08e1ec82dccfec9
createdTime: '2025-02-24T01:21:23.000+00:00'
updatedById: 53c162482f054f3ca08e1ec82dccfec9
updatedTime: '2025-02-24T01:21:23.000+00:00'
features: []
netsuite: null
organizationLabels: []
contextFilters: []
legacyFeatures: []
dacTag:
id: 1234567890abcdef
name: Example DAC Tag
error: null
schema:
$ref: '#/components/schemas/GetProductByKeyResponse'
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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
minLength: 36
maxLength: 36
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'500':
description: Internal Server Error
content:
application/json:
examples:
response:
value:
reasons:
- code: SystemError
message: internal server error
schema:
$ref: '#/components/schemas/ErrorResponse'
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: The request limit quota for the time window closest to exhaustion.
schema:
type: string
RateLimit-Remaining:
description: The number of requests remaining in the time window closest to quota exhaustion.
schema:
type: number
RateLimit-Reset:
description: The number of seconds until the quota resets for the time window closest to quota exhaustion.
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
4XX:
description: Request Errors
content:
application/json:
examples:
response:
value:
processId: 738CBB9234B47A47
reasons:
- code: '40010020'
message: Invalid product_key
requestId: d7479cf6-b410-4630-b841-268ccd48f0d2
success: false
schema:
$ref: '#/components/schemas/CommonResponse'
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: The request limit quota for the time window closest to exhaustion.
schema:
type: string
RateLimit-Remaining:
description: The number of requests remaining in the time window closest to quota exhaustion.
schema:
type: number
RateLimit-Reset:
description: The number of seconds until the quota resets for the time window closest to quota exhaustion.
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
tags:
- Commerce
/commerce/legacy/products/list:
post:
summary: Query legacy products from the Product Catalog
description: |
This operation is functionally equivalent to the "Query products from the Product Catalog" operation, except that it returns results
in the **V1 response format**. It is primarily intended for customers migrating from older V1 integrations
who want to use new Commerce capabilities — such as **Dynamic Pricing**—without refactoring their existing integrations.
Unlike the "Query products from the Product Catalog" operation, this operation does not retrieve a different set of products.
It returns the same product catalog data as the newer operation, but formatted in a flattened V1-style response structure that:
- Uses **flattened fields** instead of grouped objects such as `discount_options`, `revenue`, or `bill_cycle`.
- Retains **V1 field names** for easier migration from existing V1 operations, for example:
- Retrieve a product rate plan charge.
- Retrieve a product rate plan.
- Retrieve a product.
- Keeps certain objects, such as `netsuite` and `customFields`, as grouped structures instead of flattening them.
**Recommended Usage**
- Use this operation if you are migrating from V1 APIs and need to maintain compatibility with existing integrations.
- For new integrations, use the "Query products from the Product Catalog" operation instead, as it returns structured responses optimized for the **Commerce** feature.
operationId: queryLegacyProducts
parameters:
- $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding'
- $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding'
- $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'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateProductListLegacyRequest'
examples:
queryById:
summary: Query product by ID and expand plans and charges
value:
filters:
- field: id
operator: EQ
value: 7228c9e6fd814e3a9e59bcdf0117e34f
expand:
product_rate_plans: true
product_rate_plan_charges: true
responses:
'200':
description: Successful query
content:
application/json:
schema:
$ref: '#/components/schemas/CreateProductListLegacyResponse'
examples:
response:
value:
values:
- id: ee2d1ce1036c4dd6ae9d6945565ff7a0
name: New prod
state: active
effectiveStartDate: '2024-01-01'
effectiveEndDate: '2050-12-31'
customFields:
InexedCFTest__c: Test1
nonidxpicklist__c: nidx1
productRatePlans:
- id: c3a52dd029704b7e89274c9e7e8fd99c
name: Demo Rate Plan
state: active
activeCurrencies:
- USD
productRatePlanCharges:
- id: ebcd93dc77b34d20912dbfae5881acff
name: Charge with state 2
type: Recurring
model: PerUnit
uom: Each
billingPeriod: Month
billingTiming: IN_ADVANCE
listPriceBase: Per_Billing_Period
pricing:
- currency: USD
price: 101
tiers: []
attributes:
- name: State
type: String
mapping:
object: account
field: state__c
- name: EffectiveDate
type: Datetime
- id: 5b8ec92e6af64e8fa2d8b9756b9fed10
name: Charge with state 1
type: Recurring
model: PerUnit
uom: Each
billingPeriod: Month
billingTiming: IN_ADVANCE
listPriceBase: Per_Billing_Period
pricing:
- currency: USD
price: 100
tiers: []
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ProxyBadRequestResponse'
examples:
response:
value:
Errors:
- Code: INVALID_VALUE
Message: The account number 123xProxy is invalid.
Success: false
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.
Note that only the following MIME types support gzipped responses: - `application/json` - `application/xml` - `text/html` - `text/csv` - `text/plain`
schema:
type: string
RateLimit-Limit:
description: The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information.
schema:
type: number
WWW-Authenticate:
description: |-
The value of this header is:
``` Basic realm=Zuora API, ZSession realm=Zuora API, Bearer realm=Zuora API ```
schema:
enum:
- Basic realm=Zuora API, ZSession realm=Zuora API, Bearer realm=Zuora API
type: string
Zuora-Request-Id:
description: The Zuora internal identifier of the API call. You cannot control the value of this header.
schema:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ProxyUnauthorizedResponse'
examples:
response:
value:
message: Authentication error
headers:
Content-Encoding:
schema:
type: string
WWW-Authenticate:
description: |
The value of this header is:
```
Basic realm=Zuora API, ZSession realm=Zuora API, Bearer realm=Zuora API
```
schema:
type: string
Zuora-Request-Id:
description: The Zuora internal identifier of the API call.
schema:
type: string
minLength: 36
maxLength: 36
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
tags:
- Commerce
/commerce/tiers:
put:
summary: Update a product rate plan charge tier
description: |
Updates the price and other editable attributes, when supported, for a specific **Product Rate Plan Charge Tier**.
operationId: updateTier
tags:
- Commerce
parameters:
- $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding'
- $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding'
- $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'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateTierRequest'
example:
id: 8fe232784e7946f9aa79cfc8aad30bd9
price: 450
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateTierResponse'
examples:
response:
value:
createdById: 190758cda21c41138233263a951580b3
createdTime: '2025-10-15T19:07:25.000+00:00'
currency: USD
endingUnit: 0
id: 8fe232784e7946f9aa79cfc8aad30bd9
isOveragePrice: false
price: 450
priceFormat: price_format_flat_fee
startingUnit: 0
tier: '1'
updatedById: 190758cda21c41138233263a951580b3
updatedTime: '2025-10-15T20:47:58.000+00:00'
headers:
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/CommonResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ProxyUnauthorizedResponse'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/commerce/purchase-options/list:
post:
description: |
Retrieves one or more product rate plans (PRPs) from the Product Catalog based on specified filters such as product ID or PRP ID.
You can optionally expand related product rate plan charges (PRPCs) in the response.
operationId: queryPurchaseOptionsbyPRPID
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_REQUEST_rejectUnknownFields'
- $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'
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Version'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PurchaseOptionRequest'
examples:
byPlanIdExpandCharges:
summary: Filter by PRP ID and expand charges
value:
filters:
- field: prp_id
operator: EQ
value:
string_value: 8a90f5088799c8ed01879cb4b47a3b1a
expand:
product_rate_plan_charges: true
byProductId:
summary: Filter by Product ID
value:
filters:
- field: product_id
operator: EQ
value:
string_value: 8a90f5088799c8ed01879cb481d83b18
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PurchaseOptionResponse'
examples:
sampleSuccess:
summary: Successful response with one PRP (matches the request above)
value:
error: null
productRatePlans:
- description: ''
endDate: '2026-04-20'
id: 8a90f5088799c8ed01879cb4b47a3b1a
name: New Rate Plan
product:
allowFeatureChanges: false
category: base
contextFilters: []
createdTime: '2023-04-19T20:28:08.000-07:00'
customFields:
prd_text_c__c: a
customObjects: null
description: ''
endDate: '2026-04-20'
features: []
id: 8a90f5088799c8ed01879cb481d83b18
legacyFeatures: []
name: ztax-product
netsuite: null
organizationLabels: []
productNumber: PC-00000037
productRatePlans: []
sku: SKU-00000043
startDate: '2022-04-04'
state: product_active
productId: 8a90f5088799c8ed01879cb481d83b18
productRatePlanCharges:
- accounting:
accountsReceivableAccount: Accounts Receivable
accountsReceivableAccountType: AccountsReceivable
attributes: []
billCycle:
period: bill_cycle_period_month
periodAlignment: align_to_charge
timing: in_advance
type: default_from_customer
chargeModel: flat_fee
chargeType: recurring
createdById: 2c92c8fb7a2d26b6017a2eaa64c72dea
customFieldId: '3687818732'
customFields:
IncludeTowardsMinimumCommitmentAmount__c: null
ProductType__c: null
TrueUpChargeLevel__c: null
TrueUpCharge__c: null
aaa__c: null
deliverySchedule:
frequency: delivery_frequency_unspecified
friday: false
monday: false
saturday: false
sunday: false
thursday: false
tuesday: false
wednesday: false
description: ''
discountOptions:
applyDetails: []
applyTo: []
applyToBillingPeriodPartially: false
reflectDiscountInNetAmount: false
rollover: false
stackedDiscount: false
drawdown: {}
endDateCondition: subscription_end
upToPeriodsType: billing_periods
upToPeriods: 0
listPriceBase: Per_Billing_Period
specificListPriceBase: 0
id: 8a90876c8799b81801879cb516f8400b
name: New Component
pricing:
adjustments: {}
discountAmounts: {}
discountPercentages: {}
flatAmounts:
USD: 100
maxAmounts: {}
metadata: {}
minAmounts: {}
percentages: {}
tiers: []
unitAmounts: {}
pricingSummary:
- USD100
revenue:
excludeItemBillingFromRevenueAccounting: false
excludeItemBookingFromRevenueAccounting: false
legacyReporting: false
revenueRecognitionCode: USD
revenueRecognitionRuleName: Recognize upon invoicing
taxMode: tax_exclusive
taxable: true
triggerEvent: contract_effective
updatedTime: '2023-04-19T20:28:46.000+00:00'
productRatePlanNumber: PRP-00000001
startDate: '2022-04-20'
state: active
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'400':
content:
application/json:
examples:
response:
value:
Errors:
- Code: INVALID_VALUE
Message: The account number 123xProxy is invalid.
Success: false
schema:
$ref: '#/components/schemas/ProxyBadRequestResponse'
description: Bad Request
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'401':
content:
application/json:
examples:
response:
value:
message: Authentication error
schema:
$ref: '#/components/schemas/ProxyUnauthorizedResponse'
description: Unauthorized
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information.
schema:
type: number
WWW-Authenticate:
description: |
The value of this header is:
```
Basic realm=Zuora API, ZSession realm=Zuora API, Bearer realm=Zuora API
```
schema:
enum:
- Basic realm=Zuora API, ZSession realm=Zuora API, Bearer realm=Zuora API
type: string
Zuora-Request-Id:
description: |
The Zuora internal identifier of the API call. You cannot control the value of this header.
schema:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
summary: Query purchase options by PRP ID
tags:
- Commerce
/v1/accounts:
post:
description: |
Creates a customer account with a payment method, a bill-to contact,
and optional sold-to and ship-to contacts. Request and response field descriptions and sample code are provided. Use this operation to optionally create a subscription,
invoice for that subscription, and collect payment through the default payment method. The transaction is atomic; if any part fails for any reason, the entire
transaction is rolled back.
This operation is CORS Enabled, so you can use client-side Javascript to invoke the call.
### Notes
1. The account is created in active status.
2. If the `autoPay` field is set to `true` in the request, you must provide one of the `paymentMethod`, `creditCard`, or `hpmCreditCardPaymentMethodId`
field, but not multiple. The one provided becomes the default payment method
for this account. If the credit card information is declined or cannot be verified,
no account is created.
3. Customer accounts created with this call are automatically
be set to Auto Pay.
4. If the `invoiceDeliveryPrefsEmail` field is not specified
in the request, the account's email delivery preference is always automatically
set to `false`, no matter whether the `workEmail` or `personalEmail` field
is specified.
### Defaults for customerAcceptanceDate and serviceActivationDate
Default values for **customerAcceptanceDate** and **serviceActivationDate** are set as follows.
| | serviceActivationDate(SA) specified | serviceActivationDate (SA) NOT specified |
| ------------- |:------------- | :-----|
| customerAcceptanceDate (CA) specified| SA uses value in the request call; CA uses value in the request call| CA uses value in the request call;SA uses CE as default |
| customerAcceptanceDate (CA) NOT specified | SA uses value in the request call; CA uses SA as default | SA and CA use CE as default |
This call supports a subset of the functionality of our [Create an order](https://developer.zuora.com/v1-api-reference/api/operation/POST_Order/) call.
For use cases where you create a subscription and a billing account at the same time, we recommend using "Create an order" instead of this call.
The Orders call has the following advantages:
- Provides options for managing the entire subscription lifecycle from creation through to cancellation using different order actions.
- Allows the creation or modifying of multiple subscriptions in a single order.
- Allows a single order to combine both recurring subscription digital goods or services with order line items for physical goods.
- Orders are treated as atomic transactions. If any part fails, the entire order, subscription, and billing account creation are rolled back.
You should use this call if you need to create a standalone billing account, and create orders, subscriptions, standalone invoices, or dynamic usage charges later.
There are no deprecation plans for this call and we will continue to support this call for existing users.
operationId: POST_Account
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_Zuora_Track_Id'
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Entity_Ids_Single'
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Org_Ids'
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Version'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/POSTAccountType'
required: true
responses:
'200':
content:
application/json:
examples:
response:
value:
success: true
accountId: 8ad087d2909293cb0190964171da0999
accountNumber: A00000214
billToContactId: 8ad087d2909293cb019096417222099b
soldToContactId: 8ad087d2909293cb01909641723e099e
schema:
$ref: '#/components/schemas/POSTAccountResponseType'
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'500':
content:
application/json:
examples:
response:
value:
reasons:
- code: SystemError
message: internal server error
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal Server Error
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
4XX:
content:
application/json:
examples:
response:
value:
processId: 738CBB9234B47A47
reasons:
- code: '58730222'
message: orderDate may not be null
requestId: d7479cf6-b410-4630-b841-268ccd48f0d2
success: false
schema:
$ref: '#/components/schemas/CommonResponse'
description: Request Errors
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
summary: Create an account
tags:
- Accounts
/v1/accounts/{account-key}:
delete:
description: |
Deletes a specific account asynchronously.
**Notes and Limitations:**
- For account deletion, the system will start a backend job to remove all transactions under the accounts and change the status of the accounts to 'Cancelled'. This backend job is asynchronous and will take some time, depending on the job size.
- An account cannot be deleted when the account is either the invoice owner or the subscription owner of a subscription and the subscription's invoice owner and subscription owner are two different accounts. An exception to this limitation is if the Enable Force Deletion for Account? setting is set to `Yes`, you can force delete an account that is the subscription owner of a subscription while the invoice owner is a different account. Force deleting this account deletes all its subscriptions, but the relevant invoices will not be impacted.
- An account cannot be deleted if this account has ever been involved in an Owner Transfer amendment or order action, either as the current owner or as the previous owner.
operationId: DELETE_Account
parameters:
- $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding'
- $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding'
- $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'
- description: Account number or account ID.
in: path
name: account-key
required: true
schema:
type: string
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Version'
responses:
'200':
content:
application/json:
examples:
response:
value:
id: 40288ae9600808280160081dc9c13f15
jobId: 40288ae9600808280160081db1533506
jobStatus: Pending
success: true
schema:
$ref: '#/components/schemas/DeleteAccountResponseType'
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'500':
content:
application/json:
examples:
response:
value:
reasons:
- code: SystemError
message: internal server error
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal Server Error
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
4XX:
content:
application/json:
examples:
response:
value:
processId: 738CBB9234B47A47
reasons:
- code: '58730222'
message: orderDate may not be null
requestId: d7479cf6-b410-4630-b841-268ccd48f0d2
success: false
schema:
$ref: '#/components/schemas/CommonResponse'
description: Request Errors
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
summary: Delete an account
tags:
- Accounts
get:
description: |
Retrieves basic information about a customer account.
This operation is a quick retrieval that doesn't include the account's subscriptions, invoices, payments, or usage details. Use Get account summary to get more detailed information about an account.
operationId: GET_Account
parameters:
- $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding'
- $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding'
- $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'
- description: Account number or account ID.
in: path
name: account-key
required: true
schema:
type: string
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Version'
responses:
'200':
content:
application/json:
examples:
response:
value:
basicInfo:
accountNumber: A00000001
batch: Batch1
communicationProfileId: 303d186840e611df817c002185d714e1
crmId: ''
id: 402892c74c9193cd014c91d35b0a0132
invoiceTemplateId: null
name: Test
notes: ''
partnerAccount: false
profileNumber: CP-00000012
salesRep: ''
sequenceSetId: null
status: Active
summaryStatementTemplateId: ff808081298c6e5401298c7a845c007b
billToContact:
address1: ''
address2: ''
city: ''
country: null
county: null
fax: ''
firstName: Test
homePhone: ''
id: 2c9081a03c6d7b51013c6d7e46c80a17
lastName: Test
mobilePhone: ''
nickname: ''
otherPhone: ''
otherPhoneType: null
personalEmail: ''
state: ''
taxRegion: null
workEmail: contact@example.com
workPhone: ''
zipCode: ''
billingAndPayment:
additionalEmailAddresses:
- contact1@example.com
- contact2@example.com
autoPay: true
billCycleDay: 1
currency: USD
defaultPaymentMethodId: 2c93808457d787030157e03220ec4fad
invoiceDeliveryPrefsEmail: true
invoiceDeliveryPrefsPrint: false
paymentMethodCascadingConsent: false
paymentGateway: TestGateway
paymentTerm: Net 30
einvoiceProfile:
businessCategory: B2B
businessName: legal business name
businessNumber: '20002039'
businessNumberSchemeId: '88'
enabled: true
endpointId: '8992'
endpointSchemeId: '88'
taxRegisterNumber: TAX393999
metrics:
balance: 0
contractedMrr: -900
creditBalance: 0
totalInvoiceBalance: 0
metricsData:
- balance: 0
contractedMrr: -900
currency: USD
reservedPaymentAmount: 900
totalDebitMemoBalance: 0
totalInvoiceBalance: 0
unappliedCreditMemoAmount: 0
unappliedPaymentAmount: 0
- balance: 0
contractedMrr: -900
currency: EUR
reservedPaymentAmount: -900
totalDebitMemoBalance: 0
totalInvoiceBalance: 0
unappliedCreditMemoAmount: 0
unappliedPaymentAmount: 0
soldToContact:
address1: ''
address2: ''
city: ''
country: null
county: null
fax: ''
firstName: Test
homePhone: ''
id: 2c9081a03c6d7b51013c6d7e46cf0a18
lastName: Test
mobilePhone: ''
nickname: ''
otherPhone: ''
otherPhoneType: null
personalEmail: ''
state: ''
taxRegion: null
workEmail: contact@example.com
workPhone: ''
zipCode: ''
success: true
schema:
$ref: '#/components/schemas/GETAccountType'
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'500':
content:
application/json:
examples:
response:
value:
reasons:
- code: SystemError
message: internal server error
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal Server Error
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
4XX:
content:
application/json:
examples:
response:
value:
processId: 738CBB9234B47A47
reasons:
- code: '58730222'
message: orderDate may not be null
requestId: d7479cf6-b410-4630-b841-268ccd48f0d2
success: false
schema:
$ref: '#/components/schemas/CommonResponse'
description: Request Errors
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
summary: Retrieve an account
tags:
- Accounts
put:
description: |
Updates a customer account by specifying the account-key.
### Notes
1. Only the fields to be changed should be specified. Any field that is not included in the request body will not be changed.
2. If an empty field is submitted with this operation, the corresponding field in the account is emptied.
3. Email addresses: If no email addresses are specified, no change is made to the email addresses or to the email delivery preference. If either the **personalEmail** or **workEmail** of **billToContact** is specified (or both), the system updates the corresponding email address(es) and the email delivery preference is set to `true`. (In that case, emails go to the **workEmail** address, if it exists, or else the **personalEmail**.) On the other hand, if as a result of this call both of the email addresses for the account are empty, the email delivery preference is set to `false`.
4. The Bill To, Sold To, and Ship To contacts are separate contact entities. However, if you set the `soldToSameAsBillTo` field to `true` when creating an account, the Bill To and Sold To contacts will refer to the same contact entity. As a result, updating either contact will update both. The same behavior applies to the `shipToSameAsBillTo` field and the Ship To contact. In this case, if you want to update only one of the contacts, you must create a new contact and then update the Bill To, Sold To, or Ship To contact to reference the newly created one.
operationId: PUT_Account
parameters:
- $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding'
- $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding'
- $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'
- description: Account number or account ID.
in: path
name: account-key
required: true
schema:
type: string
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Version'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PUTAccountType'
required: true
responses:
'200':
content:
application/json:
examples:
response:
value:
success: true
schema:
$ref: '#/components/schemas/CommonResponse'
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'500':
content:
application/json:
examples:
response:
value:
reasons:
- code: SystemError
message: internal server error
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal Server Error
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
4XX:
content:
application/json:
examples:
response:
value:
processId: 738CBB9234B47A47
reasons:
- code: '58730222'
message: orderDate may not be null
requestId: d7479cf6-b410-4630-b841-268ccd48f0d2
success: false
schema:
$ref: '#/components/schemas/CommonResponse'
description: Request Errors
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
summary: Update an account
tags:
- Accounts
/v1/accounts/{account-key}/payment-methods:
get:
description: |
Retrieves the payment methods of the specified customer account.
**Note:** This operation also supports retrieving custom payment methods created through the [Open Payment Method](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/MB_Set_up_custom_payment_gateways_and_payment_methods) service.
operationId: GET_AcountPaymentMethods
parameters:
- $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding'
- $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding'
- $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'
- description: Account number or account ID.
in: path
name: account-key
required: true
schema:
type: string
- description: Indicates whether to only retrieve the default payment method of the account. The default value is `false`. If this parameter is set to `true`, only the default payment method is retrieved.
in: query
name: isDefaultOnly
required: false
schema:
type: boolean
- description: Indicates whether to only retrieve the active payment methods of the account. The default value is `false`. If this parameter is set to `true`, only the active payment methods are retrieved.
in: query
name: isActiveOnly
required: false
schema:
type: boolean
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Version'
responses:
'200':
content:
application/json:
examples:
response:
value:
ach:
- AA_PICKLIST__c: null
accountHolderInfo:
accountHolderName: null
addressLine1: DSDFD
addressLine2: ''
city: Example City
country: United States
email: test@test.com
phone: '2554444'
state: Example State
zipCode: '123456'
accountKey: 4028839f7ca29000017ca29c1ce8003f
bankABACode: '110000000'
bankAccountName: Test
bankAccountNumber: '********6789'
bankAccountType: Checking
bankIdentificationNumber: null
bankName: Chase
createdBy: 402881e522cf4f9b0122cf5d82860002
createdDate: '2021-10-27 05:32:19'
deviceSessionId: null
existingMandate: null
id: 4028839f7cc14262017cc1bca9eb0008
ipAddress: null
isDefault: false
lastFailedSaleTransactionDate: null
lastTransaction: Approved
lastTransactionDateTime: '2021-10-27 05:32:19'
lastTransactionStatus: Approved
mandateInfo:
existingMandateStatus: null
mandateCreationDate: null
mandateId: null
mandateReason: null
mandateReceivedStatus: null
mandateStatus: null
mandateUpdateDate: null
maxConsecutivePaymentFailures: null
numConsecutiveFailures: 0
paymentRetryWindow: null
status: Active
totalNumberOfErrorPayments: 0
totalNumberOfProcessedPayments: 0
type: ACH
updatedBy: 402881e522cf4f9b0122cf5d82860002
updatedDate: '2021-11-10 00:50:12'
useDefaultRetryRule: true
creditcard:
- AA_PICKLIST__c: null
accountHolderInfo:
accountHolderName: John Smith
addressLine1: ABC
addressLine2: EFT
city: Example City
country: United States
email: example@google.com
phone: '86123456789'
state: Example State
zipCode: '123456'
accountKey: 4028839f7ca29000017ca29c1ce8003f
bankIdentificationNumber: '411111'
cardNumber: '************1111'
createdBy: 402881e522cf4f9b0122cf5d82860002
createdDate: '2021-11-15 18:59:08'
creditCardType: Visa
deviceSessionId: null
existingMandate: null
expirationMonth: 11
expirationYear: 2027
id: 4028839f7d26a155017d26af16ef0001
identityNumber: '97370192024'
ipAddress: null
isDefault: true
lastFailedSaleTransactionDate: null
lastTransaction: Approved
lastTransactionDateTime: '2021-11-15 18:59:08'
lastTransactionStatus: Approved
mandateInfo:
mitConsentAgreementRef: null
mitConsentAgreementSrc: null
mitProfileAction: null
mitProfileAgreedOn: null
mitProfileType: null
mitTransactionId: null
maxConsecutivePaymentFailures: null
numConsecutiveFailures: 0
paymentRetryWindow: null
status: Active
totalNumberOfErrorPayments: 0
totalNumberOfProcessedPayments: 0
type: CreditCard
updatedBy: 402881e522cf4f9b0122cf5d82860002
updatedDate: '2021-11-15 18:59:08'
useDefaultRetryRule: true
creditcardreferencetransaction:
- AA_PICKLIST__c: null
accountHolderInfo:
accountHolderName: ''
addressLine1: ''
addressLine2: ''
city: ''
country: null
email: ''
phone: null
state: ''
zipCode: ''
accountKey: 4028839f7ca29000017ca29c1ce8003f
bankIdentificationNumber: null
cardNumber: null
createdBy: 402881e522cf4f9b0122cf5d82860002
createdDate: '2021-11-03 22:35:59'
creditCardType: Visa
deviceSessionId: null
existingMandate: null
expirationMonth: 11
expirationYear: 2021
id: 4028839f7ce8c530017ce9725e2c0003
ipAddress: null
isDefault: false
lastFailedSaleTransactionDate: null
lastTransaction: Approved
lastTransactionDateTime: '2021-11-03 22:35:59'
lastTransactionStatus: Approved
mandateInfo:
mitConsentAgreementRef: null
mitConsentAgreementSrc: null
mitProfileAction: null
mitProfileAgreedOn: null
mitProfileType: null
mitTransactionId: null
maxConsecutivePaymentFailures: null
numConsecutiveFailures: 0
paymentRetryWindow: null
secondTokenId: FGDSDF
status: Active
tokenId: ABCE
totalNumberOfErrorPayments: 0
totalNumberOfProcessedPayments: 0
type: CreditCardReferenceTransaction
updatedBy: 402881e522cf4f9b0122cf5d82860002
updatedDate: '2021-11-03 22:35:59'
useDefaultRetryRule: true
debitcard:
- AA_PICKLIST__c: null
accountHolderInfo:
accountHolderName: John Smith
addressLine1: 1051 E Hillsdale Blvd
addressLine2: ''
city: Tynan
country: United States
email: smith@example.com
phone: ''
state: California
zipCode: '45101'
accountKey: 4028839f7ca29000017ca29c1ce8003f
bankIdentificationNumber: '588888'
cardNumber: '************8888'
createdBy: 402881e522cf4f9b0122cf5d82860002
createdDate: '2021-11-01 00:01:52'
creditCardType: Electron
deviceSessionId: null
existingMandate: null
expirationMonth: 11
expirationYear: 2021
id: 4028839f7cd92a6b017cda4defd00006
ipAddress: null
isDefault: false
lastFailedSaleTransactionDate: null
lastTransaction: Approved
lastTransactionDateTime: '2021-11-01 00:01:53'
lastTransactionStatus: Approved
mandateInfo:
mitConsentAgreementRef: null
mitConsentAgreementSrc: null
mitProfileAction: null
mitProfileAgreedOn: null
mitProfileType: null
mitTransactionId: null
maxConsecutivePaymentFailures: null
numConsecutiveFailures: 0
paymentRetryWindow: null
status: Active
totalNumberOfErrorPayments: 0
totalNumberOfProcessedPayments: 0
type: CreditCard
updatedBy: 402881e522cf4f9b0122cf5d82860002
updatedDate: '2021-11-01 00:01:52'
useDefaultRetryRule: true
defaultPaymentMethodId: 4028839f7d26a155017d26af16ef0001
paymentGateway: null
success: true
schema:
$ref: '#/components/schemas/GETAccountPaymentMethodType'
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'500':
content:
application/json:
examples:
response:
value:
reasons:
- code: SystemError
message: internal server error
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal Server Error
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
4XX:
content:
application/json:
examples:
response:
value:
processId: 738CBB9234B47A47
reasons:
- code: '58730222'
message: orderDate may not be null
requestId: d7479cf6-b410-4630-b841-268ccd48f0d2
success: false
schema:
$ref: '#/components/schemas/CommonResponse'
description: Request Errors
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
summary: List payment methods of an account
tags:
- Accounts
/v1/accounts/{account-key}/payment-methods/cascading:
get:
summary: Retrieve configuration of cascading payment methods for an account
description: |
Zuora provides the Cascading Payment Method feature to dynamically retry the failed payment with alternative payment methods according to a predefined priority list. Use this API operation to retrieve the configuration information for Cascading Payment Method of a specified account, including the cascading consent value and the priority list of payment methods.
Before you use this API operation, ensure that the Cascading Payment Method feature is enabled. For more information about the Cascading Payment Method feature, see Cascade payment methods.
operationId: GetAccountPaymentMethodCascading
parameters:
- $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding'
- $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding'
- $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'
- description: Account ID.
in: path
name: account-key
required: true
schema:
type: string
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Version'
responses:
'200':
content:
application/json:
examples:
response:
value:
consent: true
priorities:
- paymentMethodId: 2c92c0f95be68649015bf14e001f2760
order: 1
- paymentMethodId: 2c92c0f95be68649015bf14e001f2761
order: 2
- paymentMethodId: 2c92c0f95be68649015bf14e001f2762
order: 3
success: true
schema:
$ref: '#/components/schemas/GetCascadingPaymentMethodsConfigurationResponse'
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'500':
content:
application/json:
examples:
response:
value:
reasons:
- code: SystemError
message: internal server error
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal Server Error
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
4XX:
content:
application/json:
examples:
response:
value:
processId: 738CBB9234B47A47
reasons:
- code: '58730222'
message: orderDate may not be null
requestId: d7479cf6-b410-4630-b841-268ccd48f0d2
success: false
schema:
$ref: '#/components/schemas/CommonResponse'
description: Request Errors
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
tags:
- Accounts
put:
summary: Configure cascading payment methods for an account
description: |
Zuora provides the Cascading Payment Method feature to dynamically retry the failed payment with alternative payment methods according to a predefined priority list. Use this API operation to configure the cascading consent for a specified account and set up the priority list of payment methods to be used in Cascading Payment Method.
Before you use this API operation, ensure that the Cascading Payment Method feature is enabled. For more information about the Cascading Payment Method feature, see Cascade payment methods.
operationId: PutAccountPaymentMethodCascading
parameters:
- $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding'
- $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding'
- $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'
- description: Account ID.
in: path
name: account-key
required: true
schema:
type: string
- $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Version'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PutCascadingPaymentMethodsConfigurationRequest'
required: true
responses:
'200':
content:
application/json:
examples:
response:
value:
success: true
schema:
$ref: '#/components/schemas/CommonResponse'
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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:
maxLength: 36
minLength: 36
type: string
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
Concurrency-Limit-Type:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type'
Concurrency-Limit-Limit:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit'
Concurrency-Limit-Remaining:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining'
'500':
content:
application/json:
examples:
response:
value:
reasons:
- code: SystemError
message: internal server error
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal Server Error
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
4XX:
content:
application/json:
examples:
response:
value:
processId: 738CBB9234B47A47
reasons:
- code: '58730222'
message: orderDate may not be null
requestId: d7479cf6-b410-4630-b841-268ccd48f0d2
success: false
schema:
$ref: '#/components/schemas/CommonResponse'
description: Request Errors
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.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
schema:
type: string
RateLimit-Limit:
description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. '
schema:
type: number
Zuora-Request-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId'
Zuora-Track-Id:
$ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId'
tags:
- Accounts
/v1/accounts/{account-key}/payment-methods/default:
get:
description: |-
Retrieves the default payment method of the specified customer account.
**Notes:** **Note:** The value of this column is optional, but the column header is required.
| No | | PRODUCT_RATE_PLAN_CHARGE_ID | Enter a product rate plan charge number so that you can charge your customer with a dynamic usage charge for the corresponding uploaded usage record.**Note:** The value of this column is optional, but the column header is required. To use this field, you must set the `X-Zuora-WSDL-Version` request header to `146` or higher. Otherwise, an error occurs.
| No | | SUBSCRIPTION_ID | Enter the subscription number or subscription name. If you created the subscription in the Zuora application, Zuora created a number automatically in a format similar to A-S00000001. If you do not provide a value for this field, the associated usage will be added to all subscriptions for the specified Account that use this Unit Of Measure. If your Accounts can have multiple subscriptions and you do not want double or triple counting of usage, you must specify the Subscription or Charge ID in each usage record.**Note:** The value of this column is optional, but the column header is required.
| No | | CHARGE_ID | Enter the charge number (not the charge name). You can see the charge ID, e.g., C-00000001, when you add your rate plan to your subscription and view your individual charges. If your Accounts can have multiple subscriptions and you do not want double or triple counting of usage, you must specify the specific Subscription or Charge ID in each usage record. This field is related to the Charge Number on the subscription rate plan.**Note:** The value of this column is optional, but the column header is required.
| No | | DESCRIPTION | Enter a description for the charge. | No | | UNIQUE_KEY | Enter a specific identifier for this usage record. **Note**: This Heading is supported by the following features: Prepaid with Drawdown, and Unbilled Usage. See Upload usage record with unique key for more information. | No | operationId: POST_Usage 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_Zuora_Track_Id' - $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Entity_Ids_Single' - $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Org_Ids' - $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Version' requestBody: content: multipart/form-data: schema: properties: file: description: | The usage data to import. The supported formats are excel, csv, and zip. format: binary type: string required: - file type: object required: true responses: '200': content: application/json: examples: response: value: checkImportStatus: /v1/usage/2c92c8f83dcbd8b1013dcce1159900cc/status size: 316 success: true schema: $ref: '#/components/schemas/POSTUsageResponseType' 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. Note that only the following MIME types support gzipped responses: - `application/json` - `application/xml` - `text/html` - `text/csv` - `text/plain` schema: type: string RateLimit-Limit: description: | The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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: maxLength: 36 minLength: 36 type: string Zuora-Track-Id: $ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId' Concurrency-Limit-Type: $ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type' Concurrency-Limit-Limit: $ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit' Concurrency-Limit-Remaining: $ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining' '500': content: application/json: examples: response: value: reasons: - code: SystemError message: internal server error schema: $ref: '#/components/schemas/ErrorResponse' description: Internal Server Error 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. Note that only the following MIME types support gzipped responses: - `application/json` - `application/xml` - `text/html` - `text/csv` - `text/plain` schema: type: string RateLimit-Limit: description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. ' schema: type: number Zuora-Request-Id: $ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId' Zuora-Track-Id: $ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId' 4XX: content: application/json: examples: response: value: processId: 738CBB9234B47A47 reasons: - code: '58730222' message: orderDate may not be null requestId: d7479cf6-b410-4630-b841-268ccd48f0d2 success: false schema: $ref: '#/components/schemas/CommonResponse' description: Request Errors 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. Note that only the following MIME types support gzipped responses: - `application/json` - `application/xml` - `text/html` - `text/csv` - `text/plain` schema: type: string RateLimit-Limit: description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. ' schema: type: number Zuora-Request-Id: $ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId' Zuora-Track-Id: $ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId' summary: Upload a usage file tags: - Usage x-code-samples: - label: Curl lang: curl source: | curl -X POST -H "Authorization: Bearer f21f017e4724445d8647b1f0de7ed6f1" -F "file=@UsageData.csv" "https://rest.zuora.com/v1/usage" /v1/invoices/invoice-item/{invoice-item-id}/usage-rate-detail: get: description: | Use this REST API operation to retrieve the usage rate detail for an invoice item to understand how the total amount is calculated. The information is the same as the Rate Detail presented on [PDF invoices](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/IA_Invoices/Create_a_custom_invoice_template/DD_Display_Usage_Charge_Breakdown#How_UsageSummary.RateDetail_is_displayed_on_invoices). **Notes and limitations:** - Do not support the Overage Charge Model, Tiered with Overage Charge Model, and Multi-attribute Pricing Charge Model. - Do not support invoices in `Cancelled` or `Reversed` status. - Do not support Active rating. - In terms of rating group options, only the [Usage rating by billing period](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Rating/Usage_Rating_by_Group#Usage_rating_by_billing_period) is supported. - Do not support [On-demand usage rating](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Rating/On-demand_Usage_Rating). - Tax calculation is not involved. operationId: GET_Usage_Rate_Detail_By_Invoice_Item parameters: - $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding' - $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding' - $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' - description: Invoice item ID. For example, `402880e57f725d85017f7267c4ad002b`. Available through Data Source export. in: path name: invoice-item-id required: true schema: type: string - $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Version' responses: '200': content: application/json: examples: response: value: data: amountWithoutTax: 58 chargeNumber: C-00000001 invoiceId: 402880e57f725d85017f7267c44c0028 invoiceItemId: 402880e57f725d85017f7267c4ad002b invoiceNumber: INV00000007 listPrice: | Tier / From / To / List Price / Price Format 1 / 0 / 9 / 0.00 / Per Unit 2 / 10 / 20 / 1.00 / Per Unit 3 / 21 / 30 / 2.00 / Flat Fee 4 / 31 / / 3.00 / Per Unit quantity: 45 rateDetail: |- Tier 1: 0-9, 9 Each(s) x $0.00/Each = $0.00 Tier 2: 10-20, 11 Each(s) x $1.00/Each = $11.00 Tier 3: 21-30, $2.00 Flat Fee Tier 4: >=31, 15 Each(s) x $3.00/Each = $45.00 Total = $58.00 servicePeriod: 03/01/2022-03/31/2022 uom: Each success: true schema: $ref: '#/components/schemas/GETUsageRateDetailWrapper' 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. Note that only the following MIME types support gzipped responses: - `application/json` - `application/xml` - `text/html` - `text/csv` - `text/plain` schema: type: string RateLimit-Limit: description: | The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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: maxLength: 36 minLength: 36 type: string Zuora-Track-Id: $ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId' Concurrency-Limit-Type: $ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type' Concurrency-Limit-Limit: $ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit' Concurrency-Limit-Remaining: $ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining' '500': content: application/json: examples: response: value: reasons: - code: SystemError message: internal server error schema: $ref: '#/components/schemas/ErrorResponse' description: Internal Server Error 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. Note that only the following MIME types support gzipped responses: - `application/json` - `application/xml` - `text/html` - `text/csv` - `text/plain` schema: type: string RateLimit-Limit: description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. ' schema: type: number Zuora-Request-Id: $ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId' Zuora-Track-Id: $ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId' 4XX: content: application/json: examples: response: value: processId: 738CBB9234B47A47 reasons: - code: '58730222' message: orderDate may not be null requestId: d7479cf6-b410-4630-b841-268ccd48f0d2 success: false schema: $ref: '#/components/schemas/CommonResponse' description: Request Errors 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. Note that only the following MIME types support gzipped responses: - `application/json` - `application/xml` - `text/html` - `text/csv` - `text/plain` schema: type: string RateLimit-Limit: description: 'The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. ' schema: type: number Zuora-Request-Id: $ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_RequestId' Zuora-Track-Id: $ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId' summary: Retrieve usage rate detail for an invoice item tags: - Usage /v1/object/usage: post: description: Creates a usage record. operationId: Object_POSTUsage 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_REQUEST_rejectUnknownFields' - $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' - $ref: '#/components/parameters/GLOBAL_HEADER_X_Zuora_WSDL_Version' - $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Version' requestBody: content: application/json: schema: $ref: '#/components/schemas/ProxyCreateUsage' required: true responses: '200': content: application/json: examples: response: value: Id: 8ad08ae29085a77b0190908bfdd67abb Success: true schema: $ref: '#/components/schemas/ProxyCreateOrModifyResponse' 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. Note that only the following MIME types support gzipped responses: - `application/json` - `application/xml` - `text/html` - `text/csv` - `text/plain` schema: type: string RateLimit-Limit: description: | The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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: maxLength: 36 minLength: 36 type: string Zuora-Track-Id: $ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId' Concurrency-Limit-Type: $ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type' Concurrency-Limit-Limit: $ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit' Concurrency-Limit-Remaining: $ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining' '400': content: application/json: examples: response: value: Errors: - Code: INVALID_VALUE Message: The account number 123xProxy is invalid. Success: false schema: $ref: '#/components/schemas/ProxyBadRequestResponse' 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. Note that only the following MIME types support gzipped responses: - `application/json` - `application/xml` - `text/html` - `text/csv` - `text/plain` schema: type: string RateLimit-Limit: description: | The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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: maxLength: 36 minLength: 36 type: string Zuora-Track-Id: $ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId' Concurrency-Limit-Type: $ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type' Concurrency-Limit-Limit: $ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit' Concurrency-Limit-Remaining: $ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining' '401': content: application/json: examples: response: value: message: Authentication error schema: $ref: '#/components/schemas/ProxyUnauthorizedResponse' 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. Note that only the following MIME types support gzipped responses: - `application/json` - `application/xml` - `text/html` - `text/csv` - `text/plain` schema: type: string RateLimit-Limit: description: | The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. schema: type: number WWW-Authenticate: description: | The value of this header is: ``` Basic realm=Zuora API, ZSession realm=Zuora API, Bearer realm=Zuora API ``` schema: enum: - Basic realm=Zuora API, ZSession realm=Zuora API, Bearer realm=Zuora API type: string Zuora-Request-Id: description: | The Zuora internal identifier of the API call. You cannot control the value of this header. schema: maxLength: 36 minLength: 36 type: string Zuora-Track-Id: $ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId' Concurrency-Limit-Type: $ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type' Concurrency-Limit-Limit: $ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit' Concurrency-Limit-Remaining: $ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining' summary: 'CRUD: Create a usage record' tags: - Usage /v1/object/usage/{id}: delete: description: Deletes a usage record. Usage records that are associated with a dynamic pricing usage charge cannot be deleted with this legacy Billing endpoint. When a delete request targets such a record, the operation fails and the usage record is not removed. Operations on dynamic pricing usage are supported only via Mediation-driven flows. operationId: Object_DELETEUsage parameters: - $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding' - $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding' - $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' - description: Object id in: path name: id required: true schema: type: string - $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Version' responses: '200': content: application/json: schema: $ref: '#/components/schemas/ProxyDeleteResponse' 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. Note that only the following MIME types support gzipped responses: - `application/json` - `application/xml` - `text/html` - `text/csv` - `text/plain` schema: type: string RateLimit-Limit: description: | The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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: maxLength: 36 minLength: 36 type: string Zuora-Track-Id: $ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId' Concurrency-Limit-Type: $ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type' Concurrency-Limit-Limit: $ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit' Concurrency-Limit-Remaining: $ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining' '401': content: application/json: examples: response: value: message: Authentication error schema: $ref: '#/components/schemas/ProxyUnauthorizedResponse' description: Unauthorized 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. Note that only the following MIME types support gzipped responses: - `application/json` - `application/xml` - `text/html` - `text/csv` - `text/plain` schema: type: string RateLimit-Limit: description: | The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. schema: type: number WWW-Authenticate: description: | The value of this header is: ``` Basic realm=Zuora API, ZSession realm=Zuora API, Bearer realm=Zuora API ``` schema: enum: - Basic realm=Zuora API, ZSession realm=Zuora API, Bearer realm=Zuora API type: string Zuora-Request-Id: description: | The Zuora internal identifier of the API call. You cannot control the value of this header. schema: maxLength: 36 minLength: 36 type: string Zuora-Track-Id: $ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId' Concurrency-Limit-Type: $ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type' Concurrency-Limit-Limit: $ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit' Concurrency-Limit-Remaining: $ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining' summary: 'CRUD: Delete a usage record' tags: - Usage get: description: Retrieve a usage record. operationId: Object_GETUsage parameters: - $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding' - $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding' - $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' - description: Object fields to return in: query name: fields required: false schema: type: string - description: Object id in: path name: id required: true schema: type: string - $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Version' responses: '200': content: application/json: examples: response: value: AccountId: 2c92c0f956bc8fb40156d502fc3718b1 AccountNumber: A00000030 ChargeId: 2c92c0f956bc8fcb0156d5039e275aa9 ChargeNumber: C-00000229 CreatedById: 2c92c0f958fffd7d015914aeefc71a5d CreatedDate: '2019-07-18T15:36:43.000+08:00' Description: test Id: 2c92c0f86bf50ca0016c040309316ca4 Quantity: 9 RbeStatus: Pending SourceType: API StartDateTime: '2017-12-01T23:41:36.000+08:00' SubmissionDateTime: '2019-07-18T15:36:43.000+08:00' SubscriptionId: 2c92c0f956bc8fcb0156d5039e0a5aa0 SubscriptionNumber: A-S00000100 UOM: Each UpdatedById: 2c92c0f958fffd7d015914aeefc71a5d UpdatedDate: '2019-07-18T15:36:43.000+08:00' schema: $ref: '#/components/schemas/ProxyGetUsage' 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. Note that only the following MIME types support gzipped responses: - `application/json` - `application/xml` - `text/html` - `text/csv` - `text/plain` schema: type: string RateLimit-Limit: description: | The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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: maxLength: 36 minLength: 36 type: string Zuora-Track-Id: $ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId' Concurrency-Limit-Type: $ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type' Concurrency-Limit-Limit: $ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit' Concurrency-Limit-Remaining: $ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining' '401': content: application/json: examples: response: value: message: Authentication error schema: $ref: '#/components/schemas/ProxyUnauthorizedResponse' description: Unauthorized 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. Note that only the following MIME types support gzipped responses: - `application/json` - `application/xml` - `text/html` - `text/csv` - `text/plain` schema: type: string RateLimit-Limit: description: | The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. schema: type: number WWW-Authenticate: description: | The value of this header is: ``` Basic realm=Zuora API, ZSession realm=Zuora API, Bearer realm=Zuora API ``` schema: enum: - Basic realm=Zuora API, ZSession realm=Zuora API, Bearer realm=Zuora API type: string Zuora-Request-Id: description: | The Zuora internal identifier of the API call. You cannot control the value of this header. schema: maxLength: 36 minLength: 36 type: string Zuora-Track-Id: $ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId' Concurrency-Limit-Type: $ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type' Concurrency-Limit-Limit: $ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit' Concurrency-Limit-Remaining: $ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining' '404': content: application/json: examples: response: value: done: true records: {} size: 0 schema: $ref: '#/components/schemas/ProxyNoDataResponse' description: '' 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. Note that only the following MIME types support gzipped responses: - `application/json` - `application/xml` - `text/html` - `text/csv` - `text/plain` schema: type: string RateLimit-Limit: description: | The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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: maxLength: 36 minLength: 36 type: string Zuora-Track-Id: $ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId' Concurrency-Limit-Type: $ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type' Concurrency-Limit-Limit: $ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit' Concurrency-Limit-Remaining: $ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining' summary: 'CRUD: Retrieve a usage record' tags: - Usage put: description: Updates a usage record. Updating usage records that are associated with a dynamic pricing usage charge is not supported through this endpoint. The request fails and the record is not updated. Use Mediation-based flows to manage such usage. operationId: Object_PUTUsage parameters: - $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding' - $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding' - $ref: '#/components/parameters/GLOBAL_REQUEST_rejectUnknownFields' - $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' - description: Object id in: path name: id required: true schema: type: string - $ref: '#/components/parameters/GLOBAL_HEADER_Zuora_Version' requestBody: content: application/json: schema: $ref: '#/components/schemas/ProxyModifyUsage' required: true responses: '200': content: application/json: examples: response: value: Id: 8ad08ae29085a77b0190908bfdd67abb Success: true schema: $ref: '#/components/schemas/ProxyCreateOrModifyResponse' 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. Note that only the following MIME types support gzipped responses: - `application/json` - `application/xml` - `text/html` - `text/csv` - `text/plain` schema: type: string RateLimit-Limit: description: | The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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: maxLength: 36 minLength: 36 type: string Zuora-Track-Id: $ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId' Concurrency-Limit-Type: $ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type' Concurrency-Limit-Limit: $ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit' Concurrency-Limit-Remaining: $ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining' '401': content: application/json: examples: response: value: message: Authentication error schema: $ref: '#/components/schemas/ProxyUnauthorizedResponse' description: Unauthorized 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. Note that only the following MIME types support gzipped responses: - `application/json` - `application/xml` - `text/html` - `text/csv` - `text/plain` schema: type: string RateLimit-Limit: description: | The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/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://developer.zuora.com/docs/guides/rate-limits/) for more information. schema: type: number WWW-Authenticate: description: | The value of this header is: ``` Basic realm=Zuora API, ZSession realm=Zuora API, Bearer realm=Zuora API ``` schema: enum: - Basic realm=Zuora API, ZSession realm=Zuora API, Bearer realm=Zuora API type: string Zuora-Request-Id: description: | The Zuora internal identifier of the API call. You cannot control the value of this header. schema: maxLength: 36 minLength: 36 type: string Zuora-Track-Id: $ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Zuora_TrackId' Concurrency-Limit-Type: $ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type' Concurrency-Limit-Limit: $ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit' Concurrency-Limit-Remaining: $ref: '#/components/headers/GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining' summary: 'CRUD: Update a usage record' tags: - Usage /meters/run/{meterId}/{version}: post: tags: - Meters summary: Run a specific version of a meter description: | Executes a specific version of a meter in Zuora Mediation. You can choose to run it with either a local file or event store source by providing optional configurations. operationId: runSpecificVersionOfMeter parameters: - name: meterId in: path required: true description: The ID of the meter to run. schema: type: string - name: version in: path required: true description: The version of the meter to run. schema: type: string - name: Content-Type in: header required: true description: Specify the content type of the request body. Use application/json. schema: type: string default: application/json - $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding' - $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding' - $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' requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/RunMeterVersionRequest' responses: '200': description: Successful meter run content: application/json: schema: $ref: '#/components/schemas/RunMeterVersionResponse' examples: success: summary: Meter run success example value: success: true data: id: '5468' sessionId: R-00005468 jobId: da0b43468d6a41eaad03e559d6aecceb meterId: 2470 version: 0.0.1 revision: 1 runType: 1 runTypeDescription: NORMAL startTime: '2025-03-31T09:17:21.192927441Z' status: 10 statusDescription: INITIALIZING canExportSummary: false hasLineageEnabled: false '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ProxyBadRequestResponse' '401': description: Unauthorized request content: application/json: schema: $ref: '#/components/schemas/ProxyBadRequestResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /meters/debug/{meterId}/{version}: post: tags: - Meters summary: Test a specific version of a meter description: Test a specific version of a meter in Zuora Mediation without executing a full run. It supports multiple input methods, including uploaded files, sample files, and manual test data. This is useful for validating meter logic and transformations before meter run. operationId: testSpecificVersionOfMeter parameters: - name: meterId in: path description: The ID of the meter to be tested. required: true schema: type: integer - name: version in: path description: The version of the meter to be tested. required: true schema: type: string - name: Content-Type in: header required: true description: Specify the content type of the request body. Use application/json. schema: type: string default: application/json - $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding' - $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding' - $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' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TestSpecificMeterRequest' responses: '200': description: Successfully tested meter version. content: application/json: schema: $ref: '#/components/schemas/TestSpecificMeterResponse' '400': description: Bad Request - Invalid or missing parameters. content: application/json: schema: $ref: '#/components/schemas/ProxyBadRequestResponse' '401': description: Unauthorized - Authentication failed. content: application/json: schema: $ref: '#/components/schemas/MediationErrorResponse' '500': description: Internal Server Error - Unexpected error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /meters/{meterId}/summary: post: tags: - Meters summary: Retrieve summary data for a meter description: Retrieves summary data for a specific meter in Zuora Mediation, providing a rolled-up view of a meter run or time window. The API supports grouping by Operator ID, Error Code, or Session ID, and allows optional filters such as Query From Time, Query To Time, Operator IDs, and Session IDs. The API returns aggregated output and error counts per group and includes validation with detailed error responses for invalid parameters or formats. operationId: retrieveMeterSummaryData parameters: - name: meterId in: path description: The ID of the meter. required: true schema: type: integer format: int64 - name: Content-Type in: header required: true description: Specify the content type of the request body. Use application/json. schema: type: string default: application/json - $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding' - $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding' - $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' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateSpecificMeterSummaryRequest' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/CreateSpecificMeterSummaryResponse' example: success: true data: requestId: 91d46fea-67de-4abe-9cc3-6ef076bbb7ea requestTime: '2025-11-20T16:41:27.858661268Z' query: runType: NORMAL sessionIds: null operatorIds: null groupBy: - sessionId queryFromTime: null queryToTime: null output: - dimensions: sessionId: R-00002283 output: 10000000 totalErrorCount: 0 - dimensions: sessionId: R-00002340 output: 10000000 totalErrorCount: 0 previousPage: null nextPage: null '400': description: Bad Request - Invalid or missing parameters. content: application/json: schema: $ref: '#/components/schemas/ProxyBadRequestResponse' '401': description: Unauthorized - Authentication failed. content: application/json: schema: $ref: '#/components/schemas/MediationErrorResponse' '500': description: Internal Server Error - Unexpected error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /meters/{meterId}/{version}/runStatus: get: tags: - Meters summary: Retrieve the run status of a specific meter version description: Retrieves the current run status of a specific meter version in Zuora Mediation. It returns an integer code indicating the status, such as `RUNNING`, `COMPLETED`, or `FAILED`, which helps monitor the meter's execution state. operationId: getRunStatusOfSpecificMeterVersion parameters: - name: meterId in: path required: true description: ID of the meter. schema: type: integer - name: version in: path required: true description: Version of the meter. schema: type: string - name: Content-Type in: header required: true description: Specify the content type of the request body. Use application/json. schema: type: string default: application/json - $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding' - $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding' - $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': description: Successful response with run status data content: application/json: schema: $ref: '#/components/schemas/RunStatusResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ProxyBadRequestResponse' '404': description: Meter not found content: application/json: schema: $ref: '#/components/schemas/MediationErrorResponse' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /meters/{meterId}/auditTrail/entries: get: tags: - Meters summary: Retrieve the audit trail entries for a meter description: Retrieves the audit trail entries for a specific meter in Zuora Mediation. The API provides detailed, record-level information about what happened during processing, including Payload and error details, operator information, and the trace ID/event ID. operationId: getAuditTrailEntriesForMeter parameters: - name: meterId in: path required: true description: ID of the meter. schema: type: integer format: int64 - name: exportType in: query required: true description: Type of the export. `SAMPLE` indicates an export of success records, `ERROR` indicates an export of error records. schema: type: string enum: - SAMPLE - ERROR - name: runType in: query required: true description: Specifies the type of run. `DEBUG` indicates a test run, `NORMAL` indicates a live run. schema: type: string enum: - DEBUG - NORMAL - name: sessionId in: query required: false description: | A specific session ID. example: R-000001 schema: type: string - name: queryFromTime in: query required: true description: | The minimum timestamp of the audit trail data. The standard used is ISO 8601 with timezones. schema: type: string example: 2025-07-18 T00:00:00Z - name: queryToTime in: query required: true description: | The maximum timestamp of the audit trail data. The standard used is ISO 8601 with timezones. schema: type: string example: 2025-07-18 T00:00:00Z - name: operatorId in: query required: false description: | The ID of the operator. The Operator ID is displayed for each operator node, for both current meters and historic runs. On the Mediation UI, click on a test ID or session ID to see the details of the run. schema: type: string - name: pageSize in: query required: false description: | Page size for pagination. schema: type: integer format: int32 default: 30 maximum: 500 - name: cursor in: query required: false description: | nextPage token from previous response. schema: type: string example: W3sib3JkZXJ= - name: Content-Type in: header required: true description: Specify the content type of the request body. Use application/json. schema: type: string default: application/json - $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding' - $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding' - $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': description: OK content: application/json: schema: $ref: '#/components/schemas/GetAuditTrailResponse' example: success: true data: - errorTime: '1753296408775' errorCode: '' errorMessage: '' payload: event time: '2025-07-01' charge number: C-00000017 qty: 10 ratedAmount: '10.0' eventId: 601f65ca-67f5-11f0-9e3a-5d9d6cbeef3e|0 traceId: 601f65ca-67f5-11f0-9e3a-5d9d6cbeef3e|0_a_b_e_d_o7normal operatorType: BILLING-RATING operatorName: Rating operatorId: 15004c16-6242-4f50-9faf-cb1a0fe6e0f5 previousPage: null nextPage: eyJjdXJzb3IiOi4uLn0= '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ProxyBadRequestResponse' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /meters/{meterId}/auditTrail/export: get: tags: - Meters summary: Retrieve the list of export jobs for a meter description: Retrieves the list of previously initiated export jobs for a specific meter in Zuora Mediation. The API supports advanced filtering by time range, run status, run type, export type, session IDs, and operator IDs. Use the returned `status` and `fileList` fields to determine whether a job is complete and which files to download. Then use the "Retrieve the presigned URL for an export job" API operation with each `fileKey` in `fileList` to obtain the download URLs. operationId: getAuditTrailExportJobs parameters: - name: meterId in: path required: true description: ID of the meter. schema: type: integer format: int64 - name: exportType in: query required: false description: Type of the export. `SAMPLE` indicates an export of success records, `ERROR` indicates an export of error records. schema: type: string enum: - SAMPLE - ERROR - name: sessionIds in: query required: false description: | The session IDs of the meter run. For example, `R-000001, R-000002`. schema: type: array items: type: string - name: pageSize in: query required: false description: | Page size for pagination. schema: type: integer format: int32 default: 30 maximum: 100 - name: page in: query required: false description: | The page number. schema: type: integer format: int32 default: 1 - name: Content-Type in: header required: true description: Specify the content type of the request body. Use application/json. schema: type: string default: application/json - $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding' - $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding' - $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': description: OK content: application/json: schema: $ref: '#/components/schemas/GetAuditTrailExportResponse' example: success: true data: page: 1 pageSize: 5 jobs: - requestId: cd3367fb-019d-4600-863f-07c51b7c9e10 meterId: 709 query: operatorIds: [] exportType: SAMPLE runType: NORMAL queryToTime: '2025-11-20T23:59:59Z' queryFromTime: '2025-11-13T07:02:11Z' format: csv statuses: null sessionIds: [] status: FINISHED count: 15001524 creationTime: '2025-11-20T16:40:58Z' completionTime: '2025-11-20T16:49:01Z' fileList: - cd3367fb-019d-4600-863f-07c51b7c9e10/audit_trail.csv previousPage: null nextPage: null '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ProxyBadRequestResponse' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' post: tags: - Meters summary: Create a job to export audit trail data for a meter description: Creates a background job to export the audit trail entries for a specific meter in Zuora Mediation. This API is for large-scale, offline access to audit data. Only one export job is processed per tenant at a time, and each export has a record limit, for example, up to 5 million rows per report. Use the returned requestId with the "Retrieve the list of export jobs for a meter" API operation to track the job status and retrieve the generated file names from `fileList`, then download them using the "Retrieve the presigned URL for an export job" API operation. operationId: createAuditTrailExportJob parameters: - name: meterId in: path description: The ID of the meter. required: true schema: type: integer format: int64 - name: exportType in: query required: true description: Type of the export. `SAMPLE` indicates an export of success records, `ERROR` indicates an export of error records. schema: type: string enum: - SAMPLE - ERROR - name: runType in: query required: true description: Specifies the type of run. `DEBUG` indicates a test run, `NORMAL` indicates a live run. schema: type: string enum: - DEBUG - NORMAL - name: sessionIds in: query required: false description: | A list of specific run IDs to export. For example, `R-000001, R-000002`. schema: type: array items: type: string - name: runStatuses in: query required: false description: | Filters audit entries by their run status. If omitted, all statuses are included. Statuses are case-sensitive. Possible values: - NEVER_RUN - TESTING - TESTING_FAILED - TESTING_PASSED - RUNNING - PAUSED - COMPLETED - FAILED - CANCELED - INITIALIZING - USAGE_PUSHING - PUSH_COMPLETED - CONSUME_COMPLETED schema: type: array items: type: string - name: operatorIds in: query required: false description: | A list of operator IDs to filter by. The Operator ID is displayed for each operator node, for both current meters and historic runs. On the Mediation UI, click on a test ID or session ID to see the details of the run. schema: type: array items: type: string - name: queryFromTime in: query required: true description: | The minimum timestamp for the data to be exported. The standard used is ISO 8601 with timezones. example: 2025-07-01T00:00:00+0530 schema: type: string - name: queryToTime in: query required: true description: | The maximum timestamp for the data to be exported. The standard used is ISO 8601 with timezones. example: 2025-07-01T00:00:00+0530 schema: type: string - name: format in: query required: false description: | The required format for the exported data. Only the csv format is supported. schema: type: string default: csv - name: Content-Type in: header required: true description: Specify the content type of the request body. Use application/json. schema: type: string default: application/json - $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding' - $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding' - $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': description: OK content: application/json: schema: $ref: '#/components/schemas/ExportAuditTrailResponse' example: success: true data: requestId: cd3367fb-019d-4600-863f-07c51b7c9e10 previousPage: null nextPage: null '400': description: Bad Request - Invalid or missing parameters. content: application/json: schema: $ref: '#/components/schemas/ProxyBadRequestResponse' '401': description: Unauthorized - Authentication failed. content: application/json: schema: $ref: '#/components/schemas/MediationErrorResponse' '500': description: Internal Server Error - Unexpected error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /meters/auditTrail/presignedUrl: get: tags: - Meters summary: Retrieve the presigned URL for an export job description: Returns a pre-signed URL that you can use to download a specific export file (usually from object storage such as S3). The `fileKey` corresponds to one entry from the `fileList` array in the List API. Use the returned URL in the data field directly in a browser or via a HTTP client to download the export file. operationId: getPresignedURLForMeterExport parameters: - name: fileKey in: query required: true description: The file key of the export file to download. schema: type: string - name: Content-Type in: header required: true description: Specify the content type of the request body. Use application/json. schema: type: string default: application/json - $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding' - $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding' - $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': description: OK content: application/json: schema: $ref: '#/components/schemas/GetPresignedURLResponse' example: success: true data: https://s3.us-west-2.amazonaws.com/example-bucket/tenant-exports/12345/audit-trail/export-2025-01-01/errors_SAMPLE.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAEXAMPLE123456789%2F20250101%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20250101T000000Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=0000000000000000000000000000000000000000000000000000000000000000 '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ProxyBadRequestResponse' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /meters/export/{meterId}: get: tags: - Meters summary: Export details of a specific meter description: | The Export Meter operation exports the full definition of a specific meter in Zuora Mediation, including metadata, all versions, event schemas, and operator configurations (source, processor, sink). It's useful for reviewing, backing up, or replicating meter setups across environments. operationId: exportSpecificMeter parameters: - name: meterId in: path required: true description: ID of the meter to export. schema: type: string - name: Content-Type in: header required: true description: Specify the content type of the request body. Use application/json. schema: type: string default: application/json - $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding' - $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding' - $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': description: Successful response with meter export data content: application/json: schema: $ref: '#/components/schemas/ExportMeterResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ProxyBadRequestResponse' '404': description: Meter not found content: application/json: schema: $ref: '#/components/schemas/MediationErrorResponse' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /meters/import: post: tags: - Meters summary: Import a meter definition description: | Import a meter definition into Zuora Mediation using a file exported from the Export Meter API. operationId: importMeterDefinition requestBody: required: true content: multipart/form-data: schema: $ref: '#/components/schemas/ImportMeterRequest' parameters: - in: header name: Content-Type required: true schema: type: string example: multipart/form-data description: Content type for the request body. - $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding' - $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding' - $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': description: Successful import of meter definition content: application/json: schema: $ref: '#/components/schemas/ImportMeterResponse' '400': description: Invalid request content: application/json: schema: $ref: '#/components/schemas/ProxyBadRequestResponse' '401': description: Unauthorized access content: application/json: schema: $ref: '#/components/schemas/MediationErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /meters/files: post: tags: - Meters summary: Upload a file description: | Uploads and stores a file in Zuora Mediation for use in meter processing. Supported formats include CSV, Excel, and JSON. You can specify metadata like headers, delimiters, sheets, and data ranges. operationId: uploadMeteringFile requestBody: content: multipart/form-data: schema: type: object required: - file properties: file: type: string format: binary description: The file to store hasHeader: type: boolean description: Indicates if the file has a header (for CSV/Excel) firstRow: type: integer description: Indicates where the first row starts (for CSV format) delimiter: type: string description: Delimiter to separate values (for CSV format) sheet: type: string description: The sheet where data lives (for Excel) dataRange: type: string description: The data range in the sheet (for Excel) resolveFileNameConflict: type: boolean description: Whether to generate a UUID file name targetFolder: type: string description: The target folder to store the file overwriteExistingFile: type: boolean description: Whether to overwrite an existing file responses: '200': description: File successfully uploaded content: application/json: schema: $ref: '#/components/schemas/CreateFileResponse' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ProxyBadRequestResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ProxyUnauthorizedResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /usage/bulk/{meterGlobalId}: post: summary: Ingest usage events for a meter tags: - Meters description: | Ingests usage events directly into Zuora Mediation in real time. You can send a single event or batch multiple events in a JSON array to optimize throughput. Each event must conform to the meter's event schema. This operation is supported only for meters that use the Streaming API as their source in Zuora Mediation. You can use this API to bulk-ingest events into a meter only when the meter's source is configured as a Streaming API operator. For meters that use other sources, use the appropriate ingestion mechanism for that source instead. operationId: ingestUsageEvents parameters: - name: Content-Type in: header required: true description: Specify the content type of the request body. Use application/json. schema: type: string default: application/json - $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding' - $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding' - $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: meterGlobalId in: path required: true description: The global ID of the meter. schema: type: string requestBody: description: A JSON object or an array of objects representing usage events. Each event must conform to the event schema defined in your meter. required: true content: application/json: schema: oneOf: - $ref: '#/components/schemas/StreamingEvent' - type: array items: $ref: '#/components/schemas/StreamingEvent' responses: '200': description: Usage event(s) ingested successfully. content: application/json: schema: $ref: '#/components/schemas/StreamingIngestionSuccessResponse' '400': description: Bad request due to validation or business logic errors. content: application/json: schema: $ref: '#/components/schemas/ProxyBadRequestResponse' '401': description: Unauthorized request. content: application/json: schema: $ref: '#/components/schemas/StreamingIngestionAuthError' '404': description: Resource not found. content: application/json: schema: $ref: '#/components/schemas/StreamingIngestionAuthError' '413': description: Payload too large. content: application/json: schema: $ref: '#/components/schemas/StreamingIngestionAuthError' '429': description: Too many requests. content: application/json: schema: $ref: '#/components/schemas/StreamingIngestionAuthError' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /meters/events/bulkDelete: post: tags: - Meters summary: Bulk delete events from an event store description: | Allows you to delete multiple events from an event store in Zuora Mediation using a file that lists the event IDs to be removed. It is useful for cleaning up or correcting data in bulk. operationId: bulkDeleteEventsFromEventStore parameters: - name: Content-Type in: header required: true description: Specify the content type of the request. Use multipart/form-data. schema: type: string - $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding' - $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding' - $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' requestBody: required: true content: multipart/form-data: schema: $ref: '#/components/schemas/BulkDeleteEventRequest' responses: '200': description: Successful response with query ID content: application/json: schema: $ref: '#/components/schemas/BulkDeleteEventResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ProxyBadRequestResponse' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /meters/events/stores/{id}/jobs/latest: get: tags: - Meters summary: Retrieve the latest query job of a specific event store description: Retrieves the most recent query job executed on a specific event store in Zuora Mediation. It returns metadata such as query type (e.g., DELETE), status, record counts, and timestamps. operationId: getLatestQueryJobOfSpecificEventStore parameters: - name: id in: path required: true description: ID of the event store. schema: type: integer - name: Content-Type in: header required: true description: Specify the content type of the request. Use application/json. schema: type: string default: application/json - $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding' - $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding' - $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': description: Successful response with latest event store query job details content: application/json: schema: $ref: '#/components/schemas/LatestEventStoreJobResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ProxyBadRequestResponse' '404': description: Event store not found content: application/json: schema: $ref: '#/components/schemas/MediationErrorResponse' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /meters/event-store-queries: post: tags: - Meters summary: Submit an event store query description: Submits a SQL-style asynchronous query to the Event Store to retrieve and inspect metering events for validation, troubleshooting, and reconciliation. The API returns a `queryId` that can be used to poll and fetch paginated results. operationId: submitEventStoreQuery parameters: - name: Content-Type in: header required: true description: Specify the content type of the request body. Use application/json. schema: type: string default: application/json - $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding' - $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding' - $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' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubmitEventStoreQueryRequest' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/SubmitEventStoreQueryResponse' example: success: true data: queryId: b9a5b91ab34c42b1b9399c0e76245e3f7f76610637ec4d17abdcd4214493814e previousPage: 'null' nextPage: 'null' '400': description: Bad Request - Invalid or missing parameters. content: application/json: schema: $ref: '#/components/schemas/ProxyBadRequestResponse' '401': description: Unauthorized - Authentication failed. content: application/json: schema: $ref: '#/components/schemas/MediationErrorResponse' '500': description: Internal Server Error - Unexpected error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /meters/event-store-queries/{queryId}: get: tags: - Meters summary: Retrieve the results for an event store query description: Retrieves paginated result rows and column metadata for a previously submitted Event Store query using its `queryId`, including total row count, row-level field values, and readiness status. Query execution is asynchronous. operationId: getQueryResultsForEventStore parameters: - name: queryId in: path required: true description: ID of the query. schema: type: string - name: pageSize in: query required: false description: | Page size for pagination. schema: type: integer format: int32 default: 20 maximum: 50 - name: page in: query required: false description: | The page number. schema: type: integer format: int32 default: 1 - name: Content-Type in: header required: true description: Specify the content type of the request body. Use application/json. schema: type: string default: application/json - $ref: '#/components/parameters/GLOBAL_HEADER_Accept_Encoding' - $ref: '#/components/parameters/GLOBAL_HEADER_Content_Encoding' - $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': description: OK content: application/json: schema: $ref: '#/components/schemas/GetQueryResultsResponse' examples: Successful query results: value: success: true data: totalCount: 1 columns: - name: value 1 logicalType: type: VARCHAR nullable: true length: 2147483647 comment: null - name: value 2 logicalType: type: VARCHAR nullable: true length: 2147483647 comment: null rows: - kind: INSERT fields: - 10 - 20% ready: true Failed query execution: value: success: true data: isFailed: true message:*customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
description: |
Container for custom fields of a Product object.
title: productFieldsCustom
type: object
ProxyGetProduct:
allOf:
- properties:
AllowFeatureChanges:
description: |
Controls whether to allow your users to add or remove features while creating or amending a subscription.
**Values**: true, false (default)
type: boolean
Category:
description: |
Category of the product. Used by Zuora Quotes Guided Product Selector.
**Values**:
- Base Products
- Add On Services
- Miscellaneous Products
maxLength: 100
type: string
CreatedById:
description: |
The automatically generated ID of the Zuora user who created the `Product` object.
maxLength: 32
type: string
CreatedDate:
description: |
The date when the `Product` object was created.
format: date-time
type: string
Description:
description: |
A description of the product.
maxLength: 500
type: string
EffectiveEndDate:
description: |
The date when the product expires and can't be subscribed to anymore, in `yyyy-mm-dd` format.
format: date
type: string
EffectiveStartDate:
description: |
The date when the product becomes available and can be subscribed to, in `yyyy-mm-dd` format.
format: date
type: string
Id:
description: Object identifier.
type: string
Name:
description: |
The name of the product. This information is displayed in the product catalog pages in the web-based UI.
maxLength: 100
type: string
SKU:
description: |
The unique SKU for the product.
maxLength: 50
type: string
UpdatedById:
description: |
The ID of the last user to update the object.
maxLength: 32
type: string
UpdatedDate:
description: |
The date when the object was last updated.
format: date-time
type: string
type: object
- $ref: '#/components/schemas/ProductObjectNSFields'
- $ref: '#/components/schemas/ProductObjectCustomFields'
ProxyNoDataResponse:
properties:
done:
description: ''
type: boolean
records:
description: ''
items:
type: object
type: array
size:
description: ''
type: integer
type: object
ProxyModifyProduct:
allOf:
- properties:
AllowFeatureChanges:
description: |
Controls whether to allow your users to add or remove features while creating or amending a subscription.
**Values**: true, false (default)
type: boolean
Category:
description: |
Category of the product. Used by Zuora Quotes Guided Product Selector.
**Values**:
- Base Products
- Add On Services
- Miscellaneous Products
maxLength: 100
type: string
Description:
description: |
A description of the product.
maxLength: 500
type: string
EffectiveEndDate:
description: |
The date when the product expires and can't be subscribed to anymore, in `yyyy-mm-dd` format.
format: date
type: string
EffectiveStartDate:
description: |
The date when the product becomes available and can be subscribed to, in `yyyy-mm-dd` format.
format: date
type: string
Name:
description: |
The name of the product. This information is displayed in the product catalog pages in the web-based UI.
maxLength: 100
type: string
ProductNumber:
description: |
The natural key of the product.
For existing Product objects that are created before this field is introduced, this field will be null. Use this field to specify a value for only these objects. Zuora also provides a tool to help you automatically backfill this field with tenant ID for your existing product catalog. If you want to use this backfill tool, contact [Zuora Global Support](https://support.zuora.com/).
**Note**: This field is only available if you set the `X-Zuora-WSDL-Version` request header to `133` or later.
maxLength: 100
type: string
SKU:
description: |
The unique SKU for the product.
maxLength: 50
type: string
type: object
- $ref: '#/components/schemas/ProductObjectNSFields'
- $ref: '#/components/schemas/ProductObjectCustomFields'
example:
Description: Portable tablet designed for kids' learning with pre-installed educational apps and games.
ProxyDeleteResponse:
properties:
id:
description: ''
type: string
success:
description: ''
type: boolean
type: object
GETCatalogType:
properties:
nextPage:
description: |
URL to retrieve the next page of the response if it exists; otherwise absent.
format: URL
type: string
products:
description: |
Container for one or more products:
items:
$ref: '#/components/schemas/GETProductType'
type: array
success:
description: |
Returns `true` if the request was processed successfully.
type: boolean
type: object
ErrorResponse:
example:
reasons:
- code: ObjectNotFound
message: Notification definition with id 6e569e1e05f040eda51a927b140c0ac1 does not exist
properties:
reasons:
items:
properties:
code:
description: |
The error code of response.
type: string
message:
description: The detail information of the error response
type: string
type: object
type: array
type: object
CommonResponse:
properties:
processId:
description: |
The ID of the process that handles the operation.
type: string
reasons:
description: |
The container of the error code and message. This field is available only if the `success` field is `false`.
items:
properties:
code:
description: |
The error code of response.
type: string
message:
description: |
The detail information of the error response
type: string
type: object
type: array
requestId:
description: |
Unique identifier of the request.
format: uuid
maxLength: 36
minLength: 36
type: string
success:
description: |
Indicates whether the call succeeded.
type: boolean
type: object
GETProductType:
allOf:
- properties:
category:
description: |
Category of the product. Used by Zuora Quotes Guided Product Selector.
Possible values are:
- Base Products
- Add On Services
- Miscellaneous Products
type: string
description:
description: |
Optional product description.
type: string
effectiveEndDate:
description: |
The date when the product expires and cannot be subscribed to anymore, as `yyyy-mm-dd`.
format: date
type: string
effectiveStartDate:
description: |
The date when the product becomes available and can be subscribed to, as `yyyy-mm-dd`.
format: date
type: string
id:
description: |
Product ID.
type: string
name:
description: |
Product name, up to 100 characters.
type: string
organizationLabels:
description: |
The organization(s) that the object belongs to.
Note: This field is available only when the Multi-Org feature is enabled.
items:
properties:
organizationId:
description: |
The organization ID.
type: string
organizationName:
description: |
The organization name.
type: string
type: object
type: array
productFeatures:
description: |
Container for one or more product features. Only available when the following settings are enabled:
- The Entitlements feature in your tenant
- The Enable Feature Specification in Product and Subscriptions setting in Settings > Billing
items:
$ref: '#/components/schemas/GetProductFeatureType'
type: array
productNumber:
description: |
The natural key of the product.
type: string
productRatePlans:
description: |
URL to retrieve information about all product rate plans of a specific product. For example, `/v1/rateplan/40289f466463d683016463ef8b7301a0/productRatePlan`.
**Note**: The value of this field is a URL only if you are on the latest API version of the Zuora API or set the `Zuora-Version` request header to `230.0` or [a later available version](https://developer.zuora.com/v1-api-reference/api-versions/#minor-version).
Zuora recommends that you use the latest behavior to retrieve product information.
If you set this header to `229.0` or earlier, the value of this field is an array of product rate plan details.
format: URL
type: string
sku:
description: |
Unique product SKU, up to 50 characters.
type: string
tags:
description: ''
type: string
type: object
- $ref: '#/components/schemas/ProductObjectNSFields'
- $ref: '#/components/schemas/ProductObjectCustomFields'
title: products
GetProductFeatureType:
allOf:
- properties:
code:
description: |
Feature code, up to 255 characters long.
type: string
description:
description: |
Feature description.
type: string
id:
description: |
Feature ID.
type: string
name:
description: |
Feature name, up to 255 characters long.
type: string
status:
description: ''
type: string
type: object
- $ref: '#/components/schemas/ProductFeatureObjectCustomFields'
title: productFeatures
ProductFeatureObjectCustomFields:
additionalProperties:
description: |
Custom fields of the Product Feature object. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
description: |
Container for custom fields of a Product Feature object.
title: productFeatureFieldsCustom
type: object
POSTCatalogGroupRequest:
allOf:
- properties:
description:
description: |
The description of the catalog group.
type: string
name:
description: |
The unique name of the catalog group.
type: string
productRatePlans:
description: |
The list of product rate plans to be added to the catalog group.
items:
$ref: '#/components/schemas/POSTorPUTCatalogGroupAddProductRatePlan'
type: array
type:
default: Grading
description: |
The type of the catalog group.
enum:
- Grading
- Display
type: string
type: object
example:
description: description
name: Example
productRatePlans:
- grade: 3
id: 4028e5ab7f1b600c017f1b787d5d01cf
- grade: 2
id: 4028e5ab7f1b600c017f1b787d5d01ac
type: Grading
CatalogGroupResponse:
properties:
catalogGroupNumber:
description: |
The automatically generated number of the catalog group with the CG- perfix. For example, CG-00000001.
type: string
description:
description: |
The description of the catalog group.
type: string
id:
description: |
The ID of the catalog group.
type: string
name:
description: |
The name of the catalog group.
type: string
productRatePlans:
description: |
The list of product rate plans in the catalog group.
items:
$ref: '#/components/schemas/GETCatalogGroupProductRatePlanResponse'
type: array
type:
description: |
The type of the catalog group.
enum:
- Grading
- Display
type: string
title: catalogGroups
type: object
GETCatalogGroupProductRatePlanResponse:
properties:
description:
description: |
The description of the product rate plan.
type: string
effectiveEndDate:
description: |
The effective end Date of the product rate plan.
type: string
effectiveStartDate:
description: |
The effective start date of the product rate plan.
type: string
grade:
description: |
The grade of the product rate plan.
type: number
id:
description: |
The ID of the product rate plan.
type: string
name:
description: |
The name of the product rate plan.
type: string
organizationLabels:
description: |
The organization(s) that the object belongs to.
Note: This field is available only when the Multi-Org feature is enabled.
items:
properties:
organizationId:
description: |
The organization ID.
type: string
organizationName:
description: |
The organization name.
type: string
type: object
type: array
status:
description: |
The status of the product rate plan.
enum:
- Active
- Expired
- NotStarted
type: string
title: productRatePlans
type: object
POSTorPUTCatalogGroupAddProductRatePlan:
allOf:
- properties:
grade:
description: |
The grade that is assigned for the product rate plan. The value of this field must be a positive integer. The greater the value, the higher the grade.
A product rate plan to be added to a Grading catalog group must have one grade. You can specify a grade for a product rate plan in this request or update the product rate plan individually.
type: number
id:
description: |
The unique ID of the product rate plan.
type: string
type: object
example:
grade: 3
id: 4028e5ab7f1b600c017f1b787d5d01cf
title: productRatePlans
ListAllCatalogGroupsResponse:
properties:
catalogGroups:
description: |
The list of catalog groups that are retrieved..
items:
$ref: '#/components/schemas/CatalogGroupResponse'
type: array
nextPage:
description: |
URL to retrieve the next page of the response if it exists; otherwise absent.
format: URL
type: string
type: object
PUTCatalogGroup:
allOf:
- properties:
add:
description: |
The list of product rate plans to be added to the catalog group.
items:
$ref: '#/components/schemas/POSTorPUTCatalogGroupAddProductRatePlan'
title: add
type: array
description:
description: |
The description of the catalog group.
type: string
name:
description: |
The unique name of the catalog group.
type: string
remove:
description: |
The list of product rate plans to be removed from the catalog group.
items:
$ref: '#/components/schemas/PUTCatalogGroupRemoveProductRatePlan'
type: array
type: object
example:
add:
- grade: 3
id: 4028e5ab7f1b600c017f1b787d5d01cf
- grade: 2
id: 4028e5ab7f1b600c017f1b787d5d01ac
description: description
name: name
remove:
- id: 4028e5ab7f1b600c017f1b787d5d01cf
- id: 4028e5ab7f1b600c017f1b787d5d01ac
PUTCatalogGroupRemoveProductRatePlan:
allOf:
- properties:
id:
description: |
The unique ID of the product rate plan to be removed from the catalog group.
type: string
type: object
example:
id: 4028e5ab7f1b600c017f1b787d5d01cf
title: remove
GETProductRatePlansResponse:
properties:
nextPage:
description: |
URL to retrieve the next page of the response if it exists; otherwise absent.
format: URL
type: string
productRatePlans:
description: |
Container for one or more products.
items:
$ref: '#/components/schemas/GETProductRatePlanType'
type: array
success:
description: |
Returns `true` if the request was processed successfully.
type: boolean
type: object
GETProductRatePlanType:
allOf:
- properties:
description:
description: |
Rate plan description.
type: string
effectiveEndDate:
description: |
Final date the rate plan is active, as `yyyy-mm-dd`. After this date, the rate plan status is `Expired`.
format: date
type: string
effectiveStartDate:
description: |
First date the rate plan is active (i.e., available to be subscribed to), as `yyyy-mm-dd`. Before this date, the status is `NotStarted`.
format: date
type: string
grade:
description: |
The grade of the product rate plan.
**Note**: This field is in the **Early Adopter** phase. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available. If you want to join this early adopter program, submit a request at [Zuora Global Support](http://support.zuora.com/).
type: number
id:
description: |
Unique product rate-plan ID.
type: string
name:
description: |
Name of the product rate-plan charge. (Not required to be unique.)
type: string
productRatePlanCharges:
description: |
Field attributes describing the product rate plan charges:
items:
$ref: '#/components/schemas/GETProductRatePlanChargeType'
type: array
productRatePlanNumber:
description: |
The natural key of the product rate plan.
type: string
status:
description: |
The status of the product rate plan.
enum:
- Active
- Expired
- NotStarted
type: string
type: object
- $ref: '#/components/schemas/ProductRatePlanObjectNSFields'
- $ref: '#/components/schemas/ProductRatePlanObjectCustomFields'
title: productRatePlans
GETProductRatePlanChargeType:
allOf:
- properties:
applyDiscountTo:
description: |
Specifies where (to what charge type) the discount will be applied. These field values are case-sensitive.
Permissible values:
- RECURRING
- USAGE
- ONETIMERECURRING
- ONETIMEUSAGE
- RECURRINGUSAGE
- ONETIMERECURRINGUSAGE
type: string
billingDay:
description: |
The bill cycle day (BCD) for the charge. The BCD determines which day of the month or week the customer is billed. The BCD value in the account can override the BCD in this object.
type: string
billingPeriod:
description: |
The billing period for the charge. The start day of the billing period is also called the bill cycle day (BCD).
Values:
- Month
- Quarter
- Annual
- Semi_Annual
- Specific Months
- Week
- Specific_Weeks
type: string
billingPeriodAlignment:
description: |
Aligns charges within the same subscription if multiple charges begin on different dates.
Possible values:
- AlignToCharge
- AlignToSubscriptionStart
- AlignToTermStart
type: string
billingTiming:
description: |
The billing timing for the charge. You can choose to bill for charges in advance or in arrears.
Values:
- In Advance
- In Arrears
**Note:** This feature is in Limited Availability. If you wish to have access to the feature, submit a request at [Zuora Global Support](https://support.zuora.com).
type: string
chargeFunction:
description: |
**Note**: This field is only available if you have the Prepaid with Drawdown or Minimum Commitment feature enabled.
To use this field, you must set the `X-Zuora-WSDL-Version` request header to `141` or higher. Otherwise, an error occurs.
This field defines what type of charge it is:
* Standard: Normal charge with no Prepayment or Commitment or Drawdown.
* Prepayment: For recurring charges. Unit or currency based prepaid charge.
* CommitmentTrueUp: For recurring charges. Currency based minimum commitment charge.
* Drawdown: For usage charges. Drawdown from prepaid funds.
* DrawdownAndCreditCommitment: For usage charges. Drawdown from prepaid funds and then credit to minimum commitment funds.
* CreditCommitment: For usage charges. Credit to minimum commitment funds.
enum:
- Standard
- Prepayment
- CommitmentTrueUp
- Drawdown
- CreditCommitment
- DrawdownAndCreditCommitment
type: string
commitmentType:
description: |
**Note**: This field is only available if you have the Prepaid with Drawdown feature enabled.
To use this field, you must set the `X-Zuora-WSDL-Version` request header to `133` or higher. Otherwise, an error occurs.
This field defines the type of commitment. A prepaid charge can be `UNIT` or `CURRENCY`. A minimum commitment(in-arrears) charge can only be `CURRENCY` type. For topup(recurring or one-time) charges, this field indicates what type of funds are created.
* If UNIT, it will create a fund with given prepaidUom.
* If CURRENCY, it will create a fund with the currency amount calculated in list price.
For drawdown(usage) charges, this field indicates what type of funds are drawdown from that created from topup charges.
enum:
- UNIT
- CURRENCY
type: string
chargeModelConfigurations:
description: This field is for Zuora Internal Use only. See the **pricing** field for the same information as this field.
type: object
creditOption:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
The way to calculate credit. See [Credit Option](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge#Credit_Option) for more information.
enum:
- TimeBased
- ConsumptionBased
- FullCreditBack
type: string
defaultQuantity:
description: |
The default quantity of units. This field is required if you use a per-unit charge model.
format: decimal
type: string
nullable: true
deliverySchedule:
$ref: '#/components/schemas/GETProductRatePlanChargeDeliverySchedule'
description:
description: |
Usually a brief line item summary of the Rate Plan Charge.
type: string
discountClass:
description: |
The class that the discount belongs to. The discount class defines the order in which discount product rate plan charges are applied.
For more information, see [Manage Discount Classes](https://knowledgecenter.zuora.com/BC_Subscription_Management/Product_Catalog/B_Charge_Models/Manage_Discount_Classes).
type: string
nullable: true
discountLevel:
description: |
The level of the discount.
Values:
- RatePlan
- Subscription
- Account
type: string
nullable: true
drawdownRate:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
The [conversion rate](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_drawdown_charge#UOM_Conversion) between Usage UOM and Drawdown UOM for a [drawdown charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_drawdown_charge). Must be a positive number (>0).
type: number
drawdownUom:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
Unit of measurement for a [drawdown charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_drawdown_charge).
type: string
endDateCondition:
description: |
Defines when the charge ends after the charge trigger date. If the subscription ends before the charge end date, the charge ends when the subscription ends. But if the subscription end date is subsequently changed through a Renewal, or Terms and Conditions amendment, the charge will end on the charge end date.
Values:
- Subscription_End
- Fixed_Period
type: string
excludeItemBillingFromRevenueAccounting:
description: |
The flag to exclude the related invoice items, invoice item adjustments, credit memo items, and debit memo items from revenue accounting.
**Note**: This field is only available if you have the Order to Revenue or Billing - Revenue Integration feature enabled.
type: boolean
excludeItemBookingFromRevenueAccounting:
description: |
The flag to exclude the related rate plan charges and order line items from revenue accounting.
**Note**: This field is only available if you have the Order to Revenue or Billing - Revenue Integration feature enabled.
type: boolean
financeInformation:
description: |
Container for finance information of a rate plan charge.
properties:
adjustmentLiabilityAccountingCode:
description: |
The accounting code for adjustment liability.
**Note**: This field is only available if you have the RevPro Integration feature enabled.
type: string
adjustmentLiabilityAccountingCodeType:
description: |
The type associated with the adjustment liability accounting code.
**Note**: This field is only available if you have the RevPro Integration feature enabled.
type: string
adjustmentRevenueAccountingCode:
description: |
The accounting code for adjustment revenue.
**Note**: This field is only available if you have the RevPro Integration feature enabled.
type: string
adjustmentRevenueAccountingCodeType:
description: |
The type associated with the adjustment revenue accounting code.
**Note**: This field is only available if you have the RevPro Integration feature enabled.
type: string
contractAssetAccountingCode:
description: |
The accounting code for contract asset.
**Note**: This field is only available if you have the RevPro Integration feature enabled.
type: string
contractAssetAccountingCodeType:
description: |
The type associated with the contract asset accounting code.
**Note**: This field is only available if you have the RevPro Integration feature enabled.
type: string
contractLiabilityAccountingCode:
description: |
The accounting code for contract liability.
**Note**: This field is only available if you have the RevPro Integration feature enabled.
type: string
contractLiabilityAccountingCodeType:
description: |
The type associated with the contract liability accounting code.
**Note**: This field is only available if you have the RevPro Integration feature enabled.
type: string
contractRecognizedRevenueAccountingCode:
description: |
The accounting code for contract recognized revenue.
**Note**: This field is only available if you have the RevPro Integration feature enabled.
type: string
contractRecognizedRevenueAccountingCodeType:
description: |
The type associated with the contract recognized revenue accounting code.
**Note**: This field is only available if you have the RevPro Integration feature enabled.
type: string
deferredRevenueAccountingCode:
description: |
The accounting code for deferred revenue, such as Monthly Recurring Liability.
type: string
deferredRevenueAccountingCodeType:
description: |
The type associated with the deferred revenue accounting code, such as Deferred Revenue.
type: string
nullable: true
recognizedRevenueAccountingCode:
description: |
The accounting code for recognized revenue, such as Monthly Recurring Charges or Overage Charges.
type: string
recognizedRevenueAccountingCodeType:
description: |
The type associated with the recognized revenue accounting code, such as Sales Revenue or Sales Discount.
type: string
nullable: true
unbilledReceivablesAccountingCode:
description: |
The accounting code for unbilled receivables.
**Note**: This field is only available if you have the RevPro Integration feature enabled.
type: string
unbilledReceivablesAccountingCodeType:
description: |
The type associated with the unbilled receivables accounting code.
**Note**: This field is only available if you have the RevPro Integration feature enabled.
type: string
title: financeInformation
type: object
formula:
description: |
The pricing formula to calculate the actual rating amount for each usage record.
This field is only available for the usage-based charges that use the Multi-Attribute Pricing charge model. The charge model is available for customers with Enterprise and Nine editions by default. If you are a Growth customer, see [Zuora Editions](https://docs.zuora.com/en/entitlements/current-entitlements/zuora-editions) for pricing information.
type: string
id:
description: |
Unique product rate-plan charge ID.
type: string
includedUnits:
description: |
Specifies the number of units in the base set of units when the charge model is Overage.
format: decimal
type: string
isAllocationEligible:
description: |
This field is used to identify if the charge segment is allocation
eligible in revenue recognition.
**Note**: The field is only available if you have the Order to Revenue feature enabled. To enable this field, submit a request at Zuora Global Support.
type: boolean
isPrepaid:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
Indicates whether this charge is a prepayment (topup) charge or a drawdown charge. Values: `true` or `false`.
type: boolean
isRollover:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
The value is either "true" or "false". It determines whether the rollover fields are needed.
type: boolean
isStackedDiscount:
description: |
**Note**: This field is only applicable to the Discount - Percentage charge model.
To use this field, you must set the `X-Zuora-WSDL-Version` request header to 130 or higher. Otherwise, an error occurs.
This field indicates whether the discount is to be calculated as stacked discount. Possible values are as follows:
- `true`: This is a stacked discount, which should be calculated by stacking with other discounts.
- `false`: This is not a stacked discount, which should be calculated in sequence with other discounts.
For more information, see [Stacked discounts](https://knowledgecenter.zuora.com/Zuora_Billing/Products/Product_Catalog/B_Charge_Models/B_Discount_Charge_Models).
type: boolean
isUnbilled:
description: |
This field is used to dictate how to perform the accounting during
revenue recognition.
**Note**: The field is only available if you have the Order to Revenue feature enabled. To enable this field, submit a request at Zuora Global Support.
type: boolean
listPriceBase:
description: |
The list price base for the product rate plan charge.
This field is only applicable for recurring charges.
enum:
- Per_Billing_Period
- Per_Month
- Per_Week
- Per_Year
- Per_Specific_Months
type: string
maxQuantity:
description: |
Specifies the maximum number of units for this charge. Use this field and the `minQuantity` field to create a range of units allowed in a product rate plan charge.
format: decimal
type: string
minQuantity:
description: |
Specifies the minimum number of units for this charge. Use this field and the `maxQuantity` field to create a range of units allowed in a product rate plan charge.
format: decimal
type: string
model:
description: |
Charge model which determines how charges are calculated. Charge models must be individually activated in Zuora Billing administration.
Possible values are:
- `FlatFee`
- `PerUnit`
- `Overage`
- `Volume`
- `Tiered`
- `TieredWithOverage`
- `DiscountFixedAmount`
- `DiscountPercentage`
- `Delivery` (available only if you have the Delivery Pricing charge model enabled)
- `MultiAttributePricing` (available only if you have the Multi-Attribute Pricing charge model enabled. The charge model is available for customers with Enterprise and Nine editions by default. If you are a Growth customer, see [Zuora Editions](https://docs.zuora.com/en/entitlements/current-entitlements/zuora-editions) for pricing information.)
- `PreratedPerUnit` (available only if you have the Pre-rated Per Unit Pricing charge model enabled. The charge model is available for customers with Enterprise and Nine editions by default. If you are a Growth customer, see [Zuora Editions](https://docs.zuora.com/en/entitlements/current-entitlements/zuora-editions) for pricing information.)
- `PreratedPricing` (available only if you have the Pre-rated Pricing charge model enabled. The charge model is available for customers with Enterprise and Nine editions by default. If you are a Growth customer, see [Zuora Editions](https://docs.zuora.com/en/entitlements/current-entitlements/zuora-editions) for pricing information.)
- `HighWatermarkVolumePricing` (available only if you have the High Water Mark Volume Pricing charge model enabled. The charge model is available for customers with Enterprise and Nine editions by default. If you are a Growth customer, see [Zuora Editions](https://docs.zuora.com/en/entitlements/current-entitlements/zuora-editions) for pricing information.)
- `HighWatermarkTieredPricing` (available only if you have the High Water Mark Tiered Pricing charge model enabled. The charge model is available for customers with Enterprise and Nine editions by default. If you are a Growth customer, see [Zuora Editions](https://docs.zuora.com/en/entitlements/current-entitlements/zuora-editions) for pricing information.)
The value of the `pricing` field contains details about these charge models and the value of `pricingSummary` field contains their associated pricing summary values.
type: string
name:
description: |
Name of the product rate-plan charge. (Not required to be unique.)
type: string
numberOfPeriods:
description: |
Specifies the number of periods to use when calculating charges in an overage smoothing charge model. This field is ued when overage smoothing model is `RollingWindow` or `Rollover`.
format: int64
type: integer
nullable: true
overageCalculationOption:
description: |
Value specifies when to calculate overage charges.
Values:
- EndOfSmoothingPeriod
- PerBillingPeriod
- null
type: string
nullable: true
overageUnusedUnitsCreditOption:
description: |
Determines whether to credit the customer with unused units of usage.
Values:
- NoCredit
- CreditBySpecificRate
type: string
nullable: true
prepaidOperationType:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
The type of this charge. It is either a prepayment (topup) charge or a drawdown charge.
enum:
- topup
- drawdown
- null
type: string
nullable: true
prepaidQuantity:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
The number of units included in a [prepayment charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge). Must be a positive number (>0).
type: number
nullable: true
prepaidTotalQuantity:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
The total amount of units that end customers can use during a validity period when they subscribe to a [prepayment charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge).
type: number
nullable: true
prepaidUom:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
Unit of measurement for a [prepayment charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge).
type: string
nullable: true
prepayPeriods:
description: |
The number of periods to which prepayment is set.
**Note:** This field is only available if you already have the prepayment feature enabled. The prepayment feature is deprecated and available only for backward compatibility. Zuora does not support enabling this feature anymore.
format: int64
type: integer
nullable: true
priceChangeOption:
description: |
Applies an automatic price change when a termed subscription is renewed and the following applies:
1. AutomatedPriceChange setting is on
2. Charge type is not one-time
3. Charge model is not discount fixed amount
Values:
- NoChange (default)
- SpecificPercentageValue
- UseLatestProductCatalogPricing
type: string
nullable: true
priceIncreasePercentage:
description: |
Specifies the percentage to increase or decrease the price of a termed subscription's renewal. Use this field if you set the `PriceChangeOption` value to `SpecificPercentageValue`.
1. AutomatedPriceChange setting is on
2. Charge type is not one-time
3. Charge model is not discount fixed amount
Values: a decimal between -100 and 100
format: decimal
type: string
nullable: true
pricing:
description: |
One or more price charge models with attributes that further describe the model.
Some attributes show as null values when not applicable.
items:
$ref: '#/components/schemas/GETProductRatePlanChargePricingType'
type: array
pricingSummary:
description: |
A concise description of the charge model and pricing that is suitable to show to your customers.
When the rate plan charge model is `Tiered` and multi-currency is enabled, this field includes an array of string of each currency, and each string of currency includes tier price description separated by comma.
When the rate plan charge model is `DiscountPercentage`, this field does not include currency.
When the rate plan charge model is not `DiscountPercentage`, this field includes the currency.
For the following charge models, the value of this field is an empty string:
- Multi-Attribute Pricing
- High Water Mark Tiered Pricing
- High Water Mark Volume Pricing
- Pre-Rated Per Unit Pricing
- Pre-Rated Pricing
The charge models are available for customers with Enterprise and Nine editions by default. If you are a Growth customer, see [Zuora Editions](https://docs.zuora.com/en/entitlements/current-entitlements/zuora-editions) for pricing information.
items:
type: string
type: array
productChargeDefinitions:
description: |
A link to retrieve product charge definitions of this charge.
type: string
productDiscountApplyDetails:
description: |
Container for the application details about a discount product rate plan charge.
Only discount product rate plan charges have values in this field.
items:
$ref: '#/components/schemas/GETProductDiscountApplyDetailsType'
type: array
productRatePlanChargeNumber:
description: |
The natural key of the product rate plan charge.
type: string
ratingGroup:
description: |
Specifies a rating group based on which usage records are rated.
Possible values:
- `ByBillingPeriod` (default): The rating is based on all the usages in a billing period.
- `ByUsageStartDate`: The rating is based on all the usages on the same usage start date.
- `ByUsageRecord`: The rating is based on each usage record.
- `ByUsageUpload`: The rating is based on all the usages in a uploaded usage file (`.xls` or `.csv`).
- `ByGroupId`: The rating is based on all the usages in a custom group.
**Note:**
- The `ByBillingPeriod` value can be applied for all charge models.
- The `ByUsageStartDate`, `ByUsageRecord`, and `ByUsageUpload` values can only be applied for per unit, volume pricing, and tiered pricing charge models.
- The `ByGroupId` value is only available if you have the Active Rating feature enabled.
- Use this field only for Usage charges. One-Time Charges and Recurring Charges return `NULL`.
type: string
nullable: true
revRecCode:
description: |
Associates this product rate plan charge with a specific revenue recognition code. The value is a valid revenue recognition code.
maxLength: 70
type: string
nullable: true
revRecTriggerCondition:
description: |
Specifies when revenue recognition begins.
enum:
- ContractEffectiveDate
- ServiceActivationDate
- CustomerAcceptanceDate
- null
maxLength: 22
type: string
nullable: true
revenueRecognitionRuleName:
description: |
The name of the revenue recognition rule governing the revenue schedule.
type: string
rolloverApply:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
This field defines the priority of rollover, which is either first or last.
enum:
- ApplyFirst
- ApplyLast
type: string
rolloverPeriodLength:
default: null
description: |
**Note**: This field is only available if you have the [Prepaid with
Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown)
feature enabled.
Use this field when you want to set the rollover fund's period length shorter than the prepayment charge's validity period. In this case, you must set the `rolloverPeriods` field to 1. For example, you can define the rollover fund's period length as 5 months, shorter than the prepayment charge's validity period: a year.
type: integer
rolloverPeriods:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
This field defines the number of rollover periods, it is restricted to 3.
type: number
smoothingModel:
description: |
Specifies the smoothing model for an overage smoothing charge model or an tiered with overage model, which is an advanced type of a usage model that avoids spikes in usage charges. If a customer's usage spikes in a single period, then an overage smoothing model eases overage charges by considering usage and multiple periods.
One of the following values shows which smoothing model will be applied to the charge when `Overage` or `Tiered with Overage` is used:
- `RollingWindow` considers a number of periods to smooth usage. The rolling window starts and increments forward based on billing frequency. When allowed usage is met, then period resets and a new window begins.
- `Rollover` considers a fixed number of periods before calculating usage. The net balance at the end of a period is unused usage, which is carried over to the next period's balance.
type: string
nullable: true
specificBillingPeriod:
description: |
When the billing period is set to `Specific` Months then this positive integer reflects the number of months for billing period charges.
format: int64
type: integer
nullable: true
specificListPriceBase:
description: |
The number of months for the list price base of the charge. The value of this field is `null` if you do not set the value of the `listPriceBase` field to `Per_Specific_Months`.
type: integer
nullable: true
taxCode:
description: |
Specifies the tax code for taxation rules; used by Zuora Tax.
type: string
taxMode:
description: |
Specifies how to define taxation for the charge; used by Zuora Tax.
enum:
- TaxExclusive
- TaxInclusive
- null
type: string
nullable: true
taxable:
description: |
Specifies whether the charge is taxable; used by Zuora Tax. Possible values are:`true`, `false`.
type: boolean
triggerEvent:
description: |
Specifies when to start billing the customer for the charge.
Values: one of the following:
- `ContractEffective` is the date when the subscription's contract goes into effect and the charge is ready to be billed.
- `ServiceActivation` is the date when the services or products for a subscription have been activated and the customers have access.
- `CustomerAcceptance` is when the customer accepts the services or products for a subscription.
- `SpecificDate` is the date specified.
type: string
type:
description: |
The type of charge. Possible values are: `OneTime`, `Recurring`, `Usage`.
type: string
uom:
description: |
Describes the Units of Measure (uom) configured in **Settings > Billing** for the productRatePlanCharges.
Values: `Each`, `License`, `Seat`, or `null`
type: string
nullable: true
upToPeriods:
description: |
Specifies the length of the period during which the charge is active. If this period ends before the subscription ends, the charge ends when this period ends.
If the subscription end date is subsequently changed through a Renewal, or Terms and Conditions amendment, the charge end date will change accordingly up to the original period end.
format: int64
type: integer
nullable: true
upToPeriodsType:
description: |
The period type used to define when the charge ends.
enum:
- Billing_Periods
- Days
- Weeks
- Months
- Years
- null
type: string
nullable: true
usageRecordRatingOption:
description: |
Determines how Zuora processes usage records for per-unit usage charges.
type: string
nullable: true
useDiscountSpecificAccountingCode:
description: |
Determines whether to define a new accounting code for the new discount charge.
Values: `true`, `false`
type: boolean
nullable: true
useTenantDefaultForPriceChange:
description: |
Shows the tenant-level percentage uplift value for an automatic price change to a termed subscription's renewal. You set the tenant uplift value in the web-based UI: **Settings > Billing > Define Default Subscription Settings**.
Values: `true`, `false`
type: boolean
validityPeriodType:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
The period in which the prepayment units are valid to use as defined in a [prepayment charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge).
enum:
- SUBSCRIPTION_TERM
- ANNUAL
- SEMI_ANNUAL
- QUARTER
- MONTH
type: string
type: object
- $ref: '#/components/schemas/ProductRatePlanChargeObjectNSFields'
- $ref: '#/components/schemas/ProductRatePlanChargeObjectCustomFields'
title: productRatePlanCharges
ProductRatePlanObjectNSFields:
description: |
Container for Product Rate Plan fields provided by the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
properties:
BillingPeriod__NS:
description: |
Billing period associated with the corresponding item in NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
enum:
- Monthly
- Quarterly
- Annual
- Semi-Annual
type: string
Class__NS:
description: |
Class associated with the corresponding item in NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
maxLength: 255
type: string
Department__NS:
description: |
Department associated with the corresponding item in NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
maxLength: 255
type: string
IncludeChildren__NS:
description: |
Specifies whether the corresponding item in NetSuite is visible under child subsidiaries. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
enum:
- 'Yes'
- 'No'
type: string
IntegrationId__NS:
description: |
ID of the corresponding object in NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
maxLength: 255
type: string
IntegrationStatus__NS:
description: |
Status of the product rate plan's synchronization with NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
maxLength: 255
type: string
ItemType__NS:
description: |
Type of item that is created in NetSuite for the product rate plan. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
enum:
- Inventory
- Non Inventory
- Service
type: string
Location__NS:
description: |
Location associated with the corresponding item in NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
maxLength: 255
type: string
MultiCurrencyPrice__NS:
description: |
Multi-currency price associated with the corresponding item in NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
maxLength: 255
type: string
Price__NS:
description: |
Price associated with the corresponding item in NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
maxLength: 255
type: string
Subsidiary__NS:
description: |
Subsidiary associated with the corresponding item in NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
maxLength: 255
type: string
SyncDate__NS:
description: |
Date when the product rate plan was synchronized with NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
maxLength: 255
type: string
title: productRatePlanFieldsNS
type: object
ProductRatePlanObjectCustomFields:
additionalProperties:
description: |
Custom fields of the Product Rate Plan object. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
description: |
Container for custom fields of a Product Rate Plan object.
title: ProductRatePlanCustomFields
type: object
GETProductRatePlanChargeDeliverySchedule:
description: |
The delivery schedule information of this charge. Only when this charge is using Delivery Pricing charge model
properties:
frequency:
description: |
The frequency of the delivery. Only supports weekly now
enum:
- Weekly
type: string
friday:
description: |
The flag to indicate should the delivery happen on Friday
type: boolean
monday:
description: |
The flag to indicate should the delivery happen on Monday
type: boolean
saturday:
description: |
The flag to indicate should the delivery happen on Saturday
type: boolean
sunday:
description: |
The flag to indicate should the delivery happen on Sunday
type: boolean
thursday:
description: |
The flag to indicate should the delivery happen on Thursday
type: boolean
tuesday:
description: |
The flag to indicate should the delivery happen on Tuesday
type: boolean
wendesday:
description: |
The flag to indicate should the delivery happen on Wendesday
type: boolean
title: deliverySchedule
type: object
GETProductRatePlanChargePricingType:
properties:
currency:
description: |
Currency used by the charge model. For example: USD or EUR
type: string
discountAmount:
description: |
Value subtracted from price in currency specified. Used only when the charge model is DiscountFixedAmount.
format: decimal
type: string
discountPercentage:
description: |
Percent discount applied to the price. Used only when the charge model is DiscountPercentage.
format: decimal
type: string
includedUnits:
description: |
Specifies the number of units in the base set of units when the charge model is Overage.
format: decimal
type: string
overagePrice:
description: |
Price per unit when base set of units is exceeded. Used only when charge model is Overage or Tiered with Overage.
format: decimal
type: string
price:
description: |
The decimal value that applies when the charge model is not tiered
format: decimal
type: string
tiers:
description: |
Container for one or many defined tier ranges with distinct pricing. Applies when model is `Tiered`, `TieredWithOverage`, or `Volume`
items:
$ref: '#/components/schemas/GETProductRatePlanChargePricingTierType'
type: array
title: pricing
type: object
GETProductDiscountApplyDetailsType:
properties:
appliedProductRatePlanChargeId:
description: |
The ID of the product rate plan charge that the discount product rate plan charge applies to.
type: string
appliedProductRatePlanId:
description: |
The ID of the product rate plan that the discount product rate plan charge applies to.
type: string
title: productDiscountApplyDetails
type: object
ProductRatePlanChargeObjectNSFields:
description: |
Container for Product Rate Plan Charge fields provided by the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
properties:
Class__NS:
description: |
Class associated with the corresponding item in NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
maxLength: 255
type: string
DeferredRevAccount__NS:
description: |
Deferrred revenue account associated with the corresponding item in NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
maxLength: 255
type: string
Department__NS:
description: |
Department associated with the corresponding item in NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
maxLength: 255
type: string
IncludeChildren__NS:
description: |
Specifies whether the corresponding item in NetSuite is visible under child subsidiaries. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
enum:
- 'Yes'
- 'No'
type: string
IntegrationId__NS:
description: |
ID of the corresponding object in NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
maxLength: 255
type: string
IntegrationStatus__NS:
description: |
Status of the product rate plan charge's synchronization with NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
maxLength: 255
type: string
ItemType__NS:
description: |
Type of item that is created in NetSuite for the product rate plan charge. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
enum:
- Inventory
- Non Inventory
- Service
type: string
Location__NS:
description: |
Location associated with the corresponding item in NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
maxLength: 255
type: string
RecognizedRevAccount__NS:
description: |
Recognized revenue account associated with the corresponding item in NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
maxLength: 255
type: string
RevRecEnd__NS:
description: |
End date condition of the corresponding item in NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
enum:
- Charge Period Start
- Rev Rec Trigger Date
- Use NetSuite Rev Rec Template
type: string
RevRecStart__NS:
description: |
Start date condition of the corresponding item in NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
enum:
- Charge Period Start
- Rev Rec Trigger Date
- Use NetSuite Rev Rec Template
type: string
RevRecTemplateType__NS:
description: |
Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
maxLength: 255
type: string
Subsidiary__NS:
description: |
Subsidiary associated with the corresponding item in NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
maxLength: 255
type: string
SyncDate__NS:
description: |
Date when the product rate plan charge was synchronized with NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
maxLength: 255
type: string
title: productRatePlanChargeFieldsNS
type: object
ProductRatePlanChargeObjectCustomFields:
additionalProperties:
description: |
Custom fields of the Product Rate Plan Charge object. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
description: |
Container for custom fields of a Product Rate Plan Charge object.
title: productRatePlanChargeFieldsCustom
type: object
GETProductRatePlanChargePricingTierType:
properties:
endingUnit:
description: |
Decimal defining end of tier range.
format: decimal
type: string
price:
description: |
The decimal value of the tiered charge model. If the charge model is not a tiered type then this price field will be null and the price field directly under the productRatePlanCharges applies.
format: decimal
type: string
priceFormat:
description: |
Tier price format.
Allowed values:
- flat fee
- per unit
type: string
startingUnit:
description: |
Decimal defining start of tier range.
format: decimal
type: string
tier:
description: |
Unique number of the tier.
format: int64
type: integer
title: tiers
type: object
GETProductRatePlanWithExternalIdResponse:
properties:
ExternalIdSourceSystem:
description: |
The combination of `externallyManagedPlanId` and `externalIdSourceSystem` is the unique identifier for the rate plan purchased on a third-party store. This field is used to represent a subscription rate plan created through third-party stores.
type: string
description:
description: |
The short description of the product rate plan.
type: string
effectiveEndDate:
description: |
The end date of the product rate plan.
format: date
type: string
effectiveStartDate:
description: |
The start date of the product rate plan.
format: date
type: string
externallyManagedPlanIds:
description: |
The unique identifier for the product rate plan in a third-party store. This field is used to represent a rate plan created through third-party stores.
items:
type: string
type: array
grade:
description: |
The grade of the product rate plan.
**Note**: This field is in the **Early Adopter** phase. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available. If you want to join this early adopter program, submit a request at [Zuora Global Support](http://support.zuora.com/).
type: number
id:
description: |
The unique product rate plan ID.
type: string
name:
description: |
The name of the product rate plan.
type: string
organizationLabels:
description: |
The organization(s) that the object belongs to.
Note: This field is available only when the Multi-Org feature is enabled.
items:
properties:
organizationId:
description: |
The organization ID.
type: string
organizationName:
description: |
The organization name.
type: string
type: object
type: array
productRatePlanNumber:
description: |
The natural key of the product rate plan.
type: string
status:
description: |
The status of the product rate plan.
enum:
- Active
- Expired
- NotStarted
type: string
success:
description: |
Returns `true` if the request was processed successfully.
type: boolean
type: object
GETProductRatePlanWithExternalIdMultiResponse:
type: object
properties:
productRatePlans:
description: |
A list of product rate plans associated with the product.
Each rate plan defines a set of charges and billing conditions that determine how a product is priced and billed.
type: array
items:
type: object
properties:
id:
description: |
The unique product rate plan ID.
type: string
status:
description: |
The status of the product rate plan.
enum:
- Active
- Expired
- NotStarted
type: string
name:
description: |
The name of the product rate plan.
type: string
description:
description: |
The short description of the product rate plan.
type: string
effectiveStartDate:
description: |
The start date of the product rate plan.
format: date
type: string
effectiveEndDate:
description: |
The end date of the product rate plan.
format: date
type: string
externalIdSourceSystem:
description: |
The combination of `externallyManagedPlanId` and `externalIdSourceSystem` is the unique identifier for the rate plan purchased on a third-party store. This field is used to represent a subscription rate plan created through third-party stores.
type: string
externallyManagedPlanIds:
description: |
The unique identifier for the product rate plan in a third-party store. This field is used to represent a rate plan created through third-party stores.
type: array
items:
type: string
productRatePlanNumber:
description: |
A unique, human-readable identifier for the product rate plan. This value is typically auto-generated by Zuora but can also be set explicitly by the customer.
This field is required and should never be null.
type: string
grade:
description: |
The grade of the product rate plan.
**Note**: This field is in the **Early Adopter** phase. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available. If you want to join this early adopter program, submit a request at [Zuora Global Support](http://support.zuora.com/).
type: number
organizationLabels:
description: |
The organization(s) that the object belongs to.
Note: This field is available only when the Multi-Org feature is enabled.
items:
properties:
organizationId:
description: |
The organization ID.
type: string
organizationName:
description: |
The organization name.
type: string
type: object
type: array
success:
description: |
Returns `true` if the request was processed successfully.
type: boolean
ProxyCreateProductRatePlan:
allOf:
- properties:
ActiveCurrencies:
description: |
A list of 3-letter currency codes representing active currencies for the product rate plan. Use a comma to separate each currency code.
When creating a product rate plan, you can use this field to specify default currency and at most four other active currencies.
items:
type: string
type: array
Description:
description: |
A description of the product rate plan.
maxLength: 500
type: string
EffectiveEndDate:
description: |
The date when the product rate plan expires and can't be subscribed to, in `yyyy-mm-dd` format.
format: date
maxLength: 29
type: string
EffectiveStartDate:
description: |
The date when the product rate plan becomes available and can be subscribed to, in `yyyy-mm-dd` format.
format: date
maxLength: 29
type: string
ExternalIdSourceSystem:
description: |
The ID of the external source system.
**Note:** To use this field, you must set the `X-Zuora-WSDL-Version` request header to `130` or later. Otherwise, an error occurs.
type: string
ExternalRatePlanIds:
description: |
An external ID of the product rate plan to be added. You can use this field to specify a product rate plan that is imported from an external system.
If you want to update to multiple values, use a comma separated string.
**Note:** To use this field, you must set the `X-Zuora-WSDL-Version` request header to `130` or later. Otherwise, an error occurs.
type: string
Grade:
description: |
The grade that is assigned for the product rate plan. The value of this field must be a positive integer. The greater the value, the higher the grade.
A product rate plan to be added to a Grading catalog group must have one grade. You can specify a grade for a product rate plan in this request or update the product rate plan individually.
**Notes**:
- To use this field, you must set the `X-Zuora-WSDL-Version` request header to `116` or later. Otherwise, an error occurs.
- This field is in the **Early Adopter** phase. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available. If you want to join this early adopter program, submit a request at [Zuora Global Support](http://support.zuora.com/).
type: number
Name:
description: |
The name of the product rate plan. The name doesn't have to be unique in a Product Catalog, but the name has to be unique within a product.
maxLength: 255
type: string
ProductId:
description: |
The ID of the product that contains the product rate plan.
maxLength: 32
type: string
ProductRatePlanNumber:
description: |
The natural key of the product rate plan.
**Possible values**:
- leave null for automatically generated string
- an alphanumeric string of 100 characters or fewer
**Note**: This field is only available if you set the `X-Zuora-WSDL-Version` request header to `133` or later.
maxLength: 100
type: string
required:
- Name
- ProductId
type: object
- $ref: '#/components/schemas/ProductRatePlanObjectNSFields'
- $ref: '#/components/schemas/ProductRatePlanObjectCustomFields'
example:
Name: Basic Plan
Description: monthly plan
ProductId: 8ad081dd90c4bdwafe0190desada8f9b15
ActiveCurrencies: USD
EffectiveStartDate: '2020-10-20'
EffectiveEndDate: '2030-10-20'
ExternalIdSourceSystem: extsys
ExternalRatePlanIds: ext01,ext02
ProxyGetProductRatePlan:
allOf:
- properties:
ActiveCurrencies:
description: |
A list of 3-letter currency codes representing active currencies for the product rate plan.
This field cannot be queried in conjunction with any other fields except `id` at the same time.
items:
type: string
type: array
CreatedById:
description: |
The automatically generated ID of the Zuora user who created the `ProductRatePlan` object.
maxLength: 32
type: string
CreatedDate:
description: |
The date when the `ProductRatePlan` object was created.
format: date-time
maxLength: 29
type: string
Description:
description: |
A description of the product rate plan.
maxLength: 500
type: string
EffectiveEndDate:
description: |
The date when the product rate plan expires and can't be subscribed to, in `yyyy-mm-dd` format.
format: date
maxLength: 29
type: string
EffectiveStartDate:
description: |
The date when the product rate plan becomes available and can be subscribed to, in `yyyy-mm-dd` format.
format: date
maxLength: 29
type: string
Grade:
description: |
The grade that is assigned for the product rate plan.
**Notes**:
- To use this field, you must set the `X-Zuora-WSDL-Version` request header to `116` or later. Otherwise, an error occurs.
- This field is in the **Early Adopter** phase. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available. If you want to join this early adopter program, submit a request at [Zuora Global Support](http://support.zuora.com/).
type: number
Id:
description: Object identifier.
type: string
Name:
description: |
The name of the product rate plan. The name doesn't have to be unique in a Product Catalog, but the name has to be unique within a product.
maxLength: 255
type: string
ProductId:
description: |
The ID of the product that contains the product rate plan.
maxLength: 32
type: string
UpdatedById:
description: |
The automatically generated ID of the last user to update the object.
maxLength: 32
type: string
UpdatedDate:
description: |
The date when the object was last updated.
format: date-time
maxLength: 29
type: string
type: object
- $ref: '#/components/schemas/ProductRatePlanObjectNSFields'
- $ref: '#/components/schemas/ProductRatePlanObjectCustomFields'
ProxyModifyProductRatePlan:
allOf:
- properties:
ActiveCurrencies:
description: |
A list of 3-letter currency codes representing active currencies for the product rate plan. Use a comma to separate each currency code.
If the request body contains this field, the value of this field must contain the desired list of active currencies. The new list can never have more than four differences from the existing list.
This field cannot be used to modify the status of more than four currencies in a single request. For example, in a single request, you can only activate four currencies, or deactivate four currencies, or activate two and deactivate two. Making more than four changes to currencies always requires more than one call.
When specifying this field in the update request, you must provide the full list of active currencies you want, not just incremental changes. For each active currency update, provide the following currencies in the list:
Current active currencies + at most four changes (additions or deletions)
items:
type: string
type: array
Description:
description: |
A description of the product rate plan.
maxLength: 500
type: string
EffectiveEndDate:
description: |
The date when the product rate plan expires and can't be subscribed to, in `yyyy-mm-dd` format.
format: date
maxLength: 29
type: string
EffectiveStartDate:
description: |
The date when the product rate plan becomes available and can be subscribed to, in `yyyy-mm-dd` format.
format: date
maxLength: 29
type: string
ExternalIdSourceSystem:
description: |
The ID of the external source system.
**Note:** To use this field, you must set the `X-Zuora-WSDL-Version` request header to `130` or later. Otherwise, an error occurs.
type: string
ExternalRatePlanIds:
description: |
An external ID of the product rate plan to be added. You can use this field to specify a product rate plan that is imported from an external system.
If you want to update to multiple values, use a comma separated string.
**Note:** To use this field, you must set the `X-Zuora-WSDL-Version` request header to `130` or later. Otherwise, an error occurs.
type: string
Grade:
description: |
The grade that is assigned for the product rate plan. The value of this field must be a positive integer. The greater the value, the higher the grade.
A product rate plan to be added to a Grading catalog group must have one grade. You can specify a grade for a product rate plan in this request or update the product rate plan individually.
**Notes**:
- To use this field, you must set the `X-Zuora-WSDL-Version` request header to `116` or later. Otherwise, an error occurs.
- This field is in the **Early Adopter** phase. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available. If you want to join this early adopter program, submit a request at [Zuora Global Support](http://support.zuora.com/).
type: number
Name:
description: |
The name of the product rate plan. The name doesn't have to be unique in a Product Catalog, but the name has to be unique within a product.
maxLength: 255
type: string
ProductId:
description: |
The ID of the product that contains the product rate plan.
maxLength: 32
type: string
ProductRatePlanNumber:
description: |
The natural key of the product rate plan.
For existing Product Rate Plan objects that are created before this field is introduced, this field will be null. Use this field to specify a value for only these objects. Zuora also provides a tool to help you automatically backfill this field with tenant ID for your existing product catalog. If you want to use this backfill tool, contact [Zuora Global Support](https://support.zuora.com/).
**Note**: This field is only available if you set the `X-Zuora-WSDL-Version` request header to `133` or later.
maxLength: 100
type: string
type: object
- $ref: '#/components/schemas/ProductRatePlanObjectNSFields'
- $ref: '#/components/schemas/ProductRatePlanObjectCustomFields'
example:
Name: Monthly Plan2
Description: monthly plan
ProductId: 8ad081dd90c4bafe0190desada8f9b154b
ActiveCurrencies: USD
ExternalIdSourceSystem: extsys9
ExternalRatePlanIds: ext01
POSTRatePlanDefinitionRequest:
example:
productRatePlanChargeId: 2c9890e489f227bd0189f22f3482001f
productRatePlanChargeNumber: PRPC-00000001
productRatePlanId: 2c9890678b1ca909018b1caea5c30000
productRatePlanNumber: PRP-00000008
properties:
productRatePlanChargeId:
description: |
The unique ID of the product rate plan charge to be used in the product rate plan.
type: string
productRatePlanChargeNumber:
description: |
The unique number (natural key) of the product rate plan charge to be used in the product rate plan.
type: string
productRatePlanId:
description: |
The unique ID of the product rate plan that uses this rate plan definition.
type: string
productRatePlanNumber:
description: |
The unique number (natural key) of the product rate plan that uses this rate plan definition.
type: string
type: object
POSTRatePlanDefinitionResponse:
properties:
id:
description: |
The unique ID of the product charge definition.
type: string
success:
description: |
Indicates whether the request succeeded.
type: boolean
type: object
GETProductRatePlanDefinitionsResponse:
properties:
productRatePlanDefinitions:
description: |
The list of the product rate plan definitions that are retrieved.
items:
properties:
id:
description: |
The unique ID of the product rate plan definition.
type: string
productRatePlanChargeId:
description: |
The unique ID of the product charge in this rate plan definition.
type: string
productRatePlanChargeName:
description: |
Th name of the product charge in this rate plan definition.
type: string
productRatePlanChargeNumber:
description: |
The unique number (natural key) of the product charge in this rate plan definition.
type: string
productRatePlanId:
description: |
The unique ID of the product rate plan that uses this rate plan definition.
type: string
productRatePlanName:
description: |
Th name of the product rate plan that uses this rate plan definition.
type: string
productRatePlanNumber:
description: |
The unique number (natural key) of the product rate plan that uses this rate plan definition.
type: string
title: productRatePlanDefinitions
type: object
type: array
success:
description: |
Indicates whether the request succeeded.
type: boolean
type: object
GETProductRatePlanDefinitionResponse:
properties:
id:
description: |
The unique ID of the product rate plan definition.
type: string
productRatePlanChargeId:
description: |
The unique ID of the product charge in this rate plan definition.
type: string
productRatePlanChargeName:
description: |
Th name of the product charge in this rate plan definition.
type: string
productRatePlanChargeNumber:
description: |
The unique number (natural key) of the product charge in this rate plan definition.
type: string
productRatePlanId:
description: |
The unique ID of the product rate plan that uses this rate plan definition.
type: string
productRatePlanName:
description: |
Th name of the product rate plan that uses this rate plan definition.
type: string
productRatePlanNumber:
description: |
The unique number (natural key) of the product rate plan that uses this rate plan definition.
type: string
success:
description: |
Indicates whether the request succeeded.
type: boolean
type: object
GETProductRatePlanChargeResponse:
properties:
applyDiscountTo:
description: |
Indicates which type of charge the discount charge applies to.
enum:
- ONETIME
- RECURRING
- USAGE
- ONETIMERECURRING
- ONETIMEUSAGE
- RECURRINGUSAGE
- ONETIMERECURRINGUSAGE
- null
type: string
nullable: true
billingDay:
description: |
The bill cycle type for this charge.
type: string
billingPeriod:
description: |
The billing period for this charge.
type: string
billingPeriodAlignment:
description: |
The billing period alignment setting for this charge.
enum:
- AlignToCharge
- AlignToSubscriptionStart
- AlignToTermStart
- AlignToTermEnd
type: string
billingTiming:
description: |
The billing timing for this charge.
enum:
- IN_ADVANCE
- IN_ARREARS
type: string
chargeFunction:
description: |
**Note**: This field is only available if you have the Prepaid with Drawdown or Minimum Commitment feature enabled.
To use this field, you must set the `X-Zuora-WSDL-Version` request header to `141` or higher. Otherwise, an error occurs.
This field defines what type of charge it is:
* Standard: Normal charge with no Prepayment or Commitment or Drawdown.
* Prepayment: For recurring charges. Unit or currency based prepaid charge.
* CommitmentTrueUp: For recurring charges. Currency based minimum commitment charge.
* Drawdown: For usage charges. Drawdown from prepaid funds.
* DrawdownAndCreditCommitment: For usage charges. Drawdown from prepaid funds and then credit to minimum commitment funds.
* CreditCommitment: For usage charges. Credit to minimum commitment funds.
enum:
- Standard
- Prepayment
- CommitmentTrueUp
- Drawdown
- CreditCommitment
- DrawdownAndCreditCommitment
type: string
commitmentType:
description: |
**Note**: This field is only available if you have the Prepaid with Drawdown feature enabled.
To use this field, you must set the `X-Zuora-WSDL-Version` request header to `133` or higher. Otherwise, an error occurs.
This field defines the type of commitment. A prepaid charge can be `UNIT` or `CURRENCY`. A minimum commitment(in-arrears) charge can only be `CURRENCY` type. For topup(recurring or one-time) charges, this field indicates what type of funds are created.
* If UNIT, it will create a fund with given prepaidUom.
* If CURRENCY, it will create a fund with the currency amount calculated in list price.
For drawdown(usage) charges, this field indicates what type of funds are drawdown from that created from topup charges.
enum:
- UNIT
- CURRENCY
type: string
customFields:
$ref: '#/components/schemas/ProductRatePlanChargeObjectCustomFields'
defaultQuantity:
description: |
The default quantity.
This field is applicable only for one-time and recurring charges.
type: number
nullable: true
deliverySchedule:
$ref: '#/components/schemas/GETDeliverySchedule'
description:
description: |
The description for this charge.
type: string
discountClass:
description: |
The class that the discount belongs to. The discount class defines the order in which discount product rate plan charges are applied.
For more information, see [Manage Discount Classes](https://knowledgecenter.zuora.com/BC_Subscription_Management/Product_Catalog/B_Charge_Models/Manage_Discount_Classes).
type: string
nullable: true
discountLevel:
description: |
The application scope of the discount charge. For example, if the value of this field is `subscription` and the value of the `applyDiscountTo` field is `RECURRING`, the discount charge applies to all recurring charges in the same subscription as the discount charge.
enum:
- rateplan
- subscription
- account
- null
type: string
nullable: true
endDateCondition:
description: |
The end date condition for this charge.
enum:
- Subscription_End
- One_Time
- Fixed_Period
- Specific_End_Date
type: string
excludeItemBillingFromRevenueAccounting:
type: boolean
description: |
Indicates whether to exclude the related invoice items, invoice item adjustments, credit memo items, and debit memo items from revenue accounting.
**Note**: This field is only available if you have the Order to Revenue or Billing - Revenue Integration feature enabled.
excludeItemBookingFromRevenueAccounting:
type: boolean
description: |
Indicates whether to exclude the related rate plan charges and order line items from revenue accounting.
**Note**: This field is only available if you have the Order to Revenue or Billing - Revenue Integration feature enabled.
isAllocationEligible:
type: boolean
description: |
Indicates whether the charge segment is allocation eligible in revenue recognition. The default value is `false`.
**Values**: `true`, `false`
**Note**: The field is only available if you have the Order to Revenue feature enabled. To enable this field, submit a request at Zuora Global Support.
isUnbilled:
type: boolean
description: |
Specifies how to perform the accounting during revenue recognition. The default value is `false`.
**Values**: `true`, `false`
**Note**: The field is only available if you have the Order to Revenue feature enabled. To enable this field, submit a request at Zuora Global Support.
productCategory:
type: string
description: |
This field is used to maintain the product category for integration with Zuora Revenue.
**Note**: This field is available only if you have the Additional Revenue Fields property enabled.
productClass:
type: string
description: |
This field is used to maintain the product class for integration with Zuora Revenue.
**Note**: This field is available only if you have the Additional Revenue Fields property enabled.
productFamily:
type: string
description: |
This field is used to maintain the product family for integration with Zuora Revenue.
**Note**: This field is available only if you have the Additional Revenue Fields property enabled.
productLine:
type: string
description: |
This field is used to maintain the product line for integration with Zuora Revenue.
**Note**: This field is available only if you have the Additional Revenue Fields property enabled.
prorationOption:
description: |
**Note**: This field is only available if you have the Charge Level Proration feature enabled. For more information, see Usage charge proration and Charge level proration option for a recurring charge.
To use this field, you must set the `X-Zuora-WSDL-Version` request header to `135` or higher. Otherwise, an error occurs.
You can use this field to specify the charge-level proration option for a usage charge or recurring charge. The tenant-level proration option will be overridden.
* `NoProration`: charge-level proration option that you can set for a usage charge. This option means to not use any proration, which is the default current system behavior for a usage charge.
* `TimeBasedProration`: charge-level proration option that you can set for a usage charge. This option means to prorate the usage charge amount using the actual number of days if the billing period is a partial period.
* `DefaultFromTenantSetting`: charge-level proration option that you can set for a recurring charge. This option means to follow the customer billing rule proration setting.
* `ChargeFullPeriod`: charge-level proration option that you can set for a recurring charge. This options means to charge the full period amount for a partial billing period. Note that this setting means that there is no proration for either collecting or refunding. Even if you cancel the recurring charge in the middle of a billing period, there is no refund for this billing period.
enum:
- NoProration
- TimeBasedProration
- DefaultFromTenantSetting
- ChargeFullPeriod
type: string
reflectDiscountInNetAmount:
type: boolean
default: false
description: |
When you apply percentage discounts to either of the following charges, you need to set the `reflectDiscountInNetAmount` field on your discount charge to `true`, to enable calculating and displaying the net amount of the following charges in Zuora Revenue.
* delivery pricing charge
* prepayment charge
* drawdown charge
Note the following:
* If you are an Order to Revenue customer, when you set the `reflectDiscountInNetAmount` field to `true`, you must also set both the `excludeItemBookingFromRevenueAccounting` and `excludeItemBillingFromRevenueAccounting` fields to `true`.
* If you are a Billing - Revenue Integration customer, you must set the `reflectDiscountInNetAmount` field to `false`, otherwise an error will be returned. Billing - Revenue Integration does not support discounts on the preceding charges.
* If you are a Zuora Billing customer who does not enable the Order to Revenue or Billing - Revenue Integration feature, when you apply percentage discounts to the preceding charges, you also need to set the `reflectDiscountInNetAmount` field to `true`.
revenueRecognitionTiming:
description: |
Specifies the type of revenue recognition timing.
Predefined options are listed as enum values in this API Reference.
Other options might also be avaliable depending on
the revenue recognition policy configuration in the Zuora Billing UI.
**Note**: This field is only available if you have the Order to Revenue feature enabled.
maxLength: 200
type: string
enum:
- Upon Billing Document Posting Date
- Upon Order Activation Date
revenueAmortizationMethod:
description: |
Specifies the type of revenue amortization method.
Predefined options are listed as enum values in this API Reference.
Other options might also be avaliable depending on
the revenue recognition policy configuration in the Zuora Billing UI.
**Note**: This field is only available if you have the Order to Revenue feature enabled.
maxLength: 200
type: string
enum:
- Immediate
- Ratable Using Start And End Dates
numberOfPeriods:
description: |
Specifies the number of periods to use when calculating charges in an overage smoothing charge model.
This field is ued when overage smoothing model is `RollingWindow` or `Rollover`.
format: int64
type: integer
nullable: true
financeInformation:
description: |
Container for the finance information of a product rate plan charge.
properties:
accountsReceivableAccountingCode:
description: |
The accounting code for accounts receivable.
type: string
nullable: true
accountsReceivableAccountingCodeType:
description: |
The type of the accounting code for accounts receivable.
type: string
nullable: true
adjustmentLiabilityAccountingCode:
description: |
The accounting code for adjustment liability.
**Note**: This field is only available if you have the Zuora Billing - Revenue Integration feature enabled.
type: string
nullable: true
adjustmentLiabilityAccountingCodeType:
description: |
The type associated with the adjustment liability accounting code.
**Note**: This field is only available if you have the Zuora Billing - Revenue Integration feature enabled.
type: string
nullable: true
adjustmentRevenueAccountingCode:
description: |
The accounting code for adjustment revenue.
**Note**: This field is only available if you have the Zuora Billing - Revenue Integration feature enabled.
type: string
nullable: true
adjustmentRevenueAccountingCodeType:
description: |
The type associated with the adjustment revenue accounting code.
**Note**: This field is only available if you have the Zuora Billing - Revenue Integration feature enabled.
type: string
nullable: true
contractAssetAccountingCode:
description: |
The accounting code for contract asset.
**Note**: This field is only available if you have the Zuora Billing - Revenue Integration feature enabled.
type: string
nullable: true
contractAssetAccountingCodeType:
description: |
The type associated with the contract asset accounting code.
**Note**: This field is only available if you have the Zuora Billing - Revenue Integration feature enabled.
type: string
nullable: true
contractLiabilityAccountingCode:
description: |
The accounting code for contract liability.
**Note**: This field is only available if you have the Zuora Billing - Revenue Integration feature enabled.
type: string
nullable: true
contractLiabilityAccountingCodeType:
description: |
The type associated with the contract liability accounting code.
**Note**: This field is only available if you have the Zuora Billing - Revenue Integration feature enabled.
type: string
nullable: true
contractRecognizedRevenueAccountingCode:
description: |
The accounting code for contract recognized revenue.
**Note**: This field is only available if you have the Zuora Billing - Revenue Integration feature enabled.
type: string
nullable: true
contractRecognizedRevenueAccountingCodeType:
description: |
The type associated with the contract recognized revenue accounting code.
**Note**: This field is only available if you have the Zuora Billing - Revenue Integration feature enabled.
type: string
nullable: true
deferredRevenueAccountingCode:
description: |
The accounting code for deferred revenue, such as Monthly Recurring Liability.
type: string
nullable: true
deferredRevenueAccountingCodeType:
description: |
The type associated with the deferred revenue accounting code, such as Deferred Revenue.
type: string
nullable: true
recognizedRevenueAccountingCode:
description: |
The accounting code for recognized revenue, such as Monthly Recurring Charges or Overage Charges.
type: string
nullable: true
recognizedRevenueAccountingCodeType:
description: |
The type associated with the recognized revenue accounting code, such as Sales Revenue or Sales Discount.
type: string
nullable: true
unbilledReceivablesAccountingCode:
description: |
The accounting code for unbilled receivables.
**Note**: This field is only available if you have the Zuora Billing - Revenue Integration feature enabled.
type: string
nullable: true
unbilledReceivablesAccountingCodeType:
description: |
The type associated with the unbilled receivables accounting code.
**Note**: This field is only available if you have the Zuora Billing - Revenue Integration feature enabled.
type: string
nullable: true
title: financeInformation
type: object
id:
description: |
The unique ID of the product rate plan charge.
type: string
isStackedDiscount:
description: |
**Note**: This field is only applicable to the Discount - Percentage charge model.
To use this field, you must set the `X-Zuora-WSDL-Version` request header to 130 or higher. Otherwise, an error occurs.
This field indicates whether the discount is to be calculated as stacked discount. Possible values are as follows:
- `true`: This is a stacked discount, which should be calculated by stacking with other discounts.
- `false`: This is not a stacked discount, which should be calculated in sequence with other discounts.
For more information, see [Stacked discounts](https://knowledgecenter.zuora.com/Zuora_Billing/Products/Product_Catalog/B_Charge_Models/B_Discount_Charge_Models).
type: boolean
listPriceBase:
description: |
The base of list price.
This field is applicable only for recurring charges.
**Note**: The `Per_Year` enum value is available only if you have the Annual List Price feature enabled.
enum:
- Per_Billing_Period
- Per_Month
- Per_Week
- Per_Year
type: string
model:
description: |
Determines how to calculate charges. Charge models must be individually activated in Zuora Billing administration.
enum:
- DiscountFixedAmount
- DiscountPercentage
- FlatFee
- PerUnit
- Overage
- Tiered
- TieredwithOverage
- Volume
- Delivery
- MultiAttributePricing
- PreratedPerUnit
- PreratedPricing
- HighWatermarkVolumePricing
- HighWatermarkTieredPricing
type: string
name:
description: |
The name of the product rate plan charge.
type: string
numberOfPeriod:
description: |
Indicates the number of periods to use when calculating charges in an overage smoothing charge model. The valid value is a positive whole number.
format: int64
type: integer
overageCalculationOption:
description: |
Determines when to calculate overage charges. If the value of the `smoothingMode` field is not specified, the value of this field is ignored.
**Values**:
- `EndOfSmoothingPeriod`: This option is used by default. The overage is charged at the end of the smoothing period.
- `PerBillingPeriod`: The overage is charged on-demand rather than waiting until the end of the smoothing period.
enum:
- EndOfSmoothingPeriod
- PerBillingPeriod
- null
type: string
nullable: true
overageUnusedUnitsCreditOption:
description: |
Determines whether to credit the customer with unused units of usage.
enum:
- NoCredit
- CreditBySpecificRate
- null
type: string
nullable: true
priceChangeOption:
default: NoChange
description: |
Applies an automatic price change when a termed subscription is renewed.
enum:
- NoChange
- SpecificPercentageValue
- UseLatestProductCatalogPricing
- null
type: string
nullable: true
priceIncreaseOption:
description: |
Applies an automatic price change when a termed subscription is renewed.
enum:
- FromTenantPercentageValue
- SpecificPercentageValue
type: string
priceIncreasePercentage:
description: |
Specifies the percentage to increase or decrease the price of a termed subscription's renewal. Use this field if you set the `priceIncreaseOption` field to `SpecificPercentageValue`.
**Character limit**: 16
**Values**: a decimal value between -100 and 100
format: double
type: number
nullable: true
pricing:
description: |
Container for the prices of the product rate plan charge.
items:
$ref: '#/components/schemas/GETRatePlanChargePricing'
type: array
pricingSummary:
description: |
A concise description of the charge model and pricing that is suitable to show to your customers.
When the rate plan charge model is `Tiered` and multi-currency is enabled, this field includes an array of string of each currency, and each string of currency includes tier price description separated by comma.
When the rate plan charge model is `DiscountPercentage`, this field does not include currency.
When the rate plan charge model is not `DiscountPercentage`, this field includes the currency.
For the following charge models, the value of this field is an empty string:
- Multi-Attribute Pricing
- High Water Mark Tiered Pricing
- High Water Mark Volume Pricing
- Pre-Rated Per Unit Pricing
- Pre-Rated Pricing
The charge models are available for customers with Enterprise and Nine editions by default. If you are a Growth customer, see [Zuora Editions](https://docs.zuora.com/en/entitlements/current-entitlements/zuora-editions) for pricing information.
items:
type: string
type: array
productChargeDefinitions:
description: |
A link to retrieve product charge definitions of this charge.
type: string
productDiscountApplyDetails:
description: |
Container for the application details about a discount product rate plan charge.
Only discount product rate plan charges have values in this field.
items:
$ref: '#/components/schemas/GETProductDiscountApplyDetailsType'
type: array
productRatePlanChargeNumber:
description: |
The number of this product rate plan charge.
type: string
nullable: true
ratingGroup:
default: ByBillingPeriod
description: |
Specifies a rating group based on which usage records are rated.
Possible values:
- `ByBillingPeriod`: The rating is based on all the usages in a billing period.
- `ByUsageStartDate`: The rating is based on all the usages on the same usage start date.
- `ByUsageRecord`: The rating is based on each usage record.
- `ByUsageUpload`: The rating is based on all the usages in a uploaded usage file (`.xls` or `.csv`).
- `ByGroupId`: The rating is based on all the usages in a custom group.
**Notes:**
- The `ByBillingPeriod` value can be applied for all charge models.
- The `ByUsageStartDate`, `ByUsageRecord`, and `ByUsageUpload` values can only be applied for per unit, volume pricing, and tiered pricing charge models.
- The `ByGroupId` value is only available if you have the Active Rating feature enabled.
- Use this field only for Usage charges. One-Time Charges and Recurring Charges return `NULL`.
enum:
- ByBillingPeriod
- ByUsageStartDate
- ByUsageRecord
- ByUsageUpload
- ByGroupId
- null
type: string
nullable: true
recognizedRevenueAccount:
description: |
The name of the recognized revenue account for this charge.
- Required when the Allow Blank Accounting Code setting is No.
- Optional when the Allow Blank Accounting Code setting is Yes.
This feature is in **Limited Availability**. If you wish to have access to the feature, submit a request at [Zuora Global Support](http://support.zuora.com/).
maxLength: 100
type: string
revRecCode:
description: |
Associates this product rate plan charge with a specific revenue recognition code.
maxLength: 70
type: string
nullable: true
revRecTriggerCondition:
description: |
Specifies when revenue recognition begins.
enum:
- ContractEffectiveDate
- ServiceActivationDate
- CustomerAcceptanceDate
- null
type: string
nullable: true
revenueRecognitionRuleName:
description: |
Determines when to recognize the revenue for this charge.
enum:
- Recognize upon invoicing
- Recognize daily over time
type: string
smoothingModel:
description: |
Specifies the smoothing model for an overage smoothing charge model.
enum:
- RollingWindow
- Rollover
- null
type: string
nullable: true
specificBillingPeriod:
description: |
The specific number of billing periods for this charge.
type: number
nullable: true
specificListPriceBase:
description: |
The number of months for the list price base of the charge. The value of this field is `null` if you do not set the value of the `listPriceBase` field to `Per_Specific_Months`.
format: int32
maximum: 200
minimum: 1
type: integer
nullable: true
success:
description: |
Indicates whether the request succeeded.
type: boolean
taxCode:
description: |
Specifies the tax code for taxation rules. This field is required when the `taxable` field is set to `true`.
**Note**: This value affects the tax calculation of the rate plan charge.
maxLength: 64
type: string
taxMode:
description: |
Determines how to define taxation for the charge. This field is required when the `taxable` field is set to `true`.
**Note**: This value affects the tax calculation of the rate plan charge.
enum:
- TaxExclusive
- TaxInclusive
- null
type: string
nullable: true
taxable:
description: |
Determines whether the charge is taxable. When set to `true`, the `taxMode` and `taxCode` fields are required when creating or updating th Product Rate Plan Charge object.
**Character limit**: 5
**Values**: `true`, `false`
**Note**: This value affects the tax calculation of rate plan charges that come from the `ProductRatePlanCharge`.
type: boolean
triggerEvent:
description: |
Specifies when to start billing the customer for the charge.
**Values**:
- `ContractEffective` is the date when the subscription's contract goes into effect and the charge is ready to be billed.
- `ServiceActivation` is the date when the services or products for a subscription have been activated and the customers have access.
- `CustomerAcceptance` is when the customer accepts the services or products for a subscription.
enum:
- ContractEffective
- ServiceActivation
- CustomerAcceptance
type: string
type:
description: |
Specifies the type of charge.
enum:
- OneTime
- Recurring
- Usage
type: string
uom:
description: |
Indicates the units of measure (UOM) that is configured in **Settings > Billing** for the product rate plan charge.
type: string
nullable: true
upToPeriods:
description: |
The number of up-to-periods value for this charge.
type: number
nullable: true
upToPeriodsType:
description: |
The up-to-periods type setting for this charge.
enum:
- Billing_Periods
- Days
- Weeks
- Months
- Years
- null
type: string
nullable: true
usageRecordRatingOption:
default: EndOfBillingPeriod
description: |
Determines how Zuora processes usage records for per-unit usage charges.
enum:
- EndOfBillingPeriod
- OnDemand
- null
type: string
nullable: true
useDiscountSpecificAccountingCode:
description: |
Determines whether to define a new accounting code for the new discount charge.
**Character limit**: 5
**Values**: `true`, `false`
type: boolean
nullable: true
useTenantDefaultForPriceChange:
description: |
Applies the tenant-level percentage uplift value for an automatic price change to a termed subscription's renewal.
**Character limit**: 5
**Values**: `true`, `false`
type: boolean
applyToBillingPeriodPartially:
description: |
Allow the discount duration to be aligned with the billing period partially.
**Note**: You must enable the [Enhanced Discount](https://knowledgecenter.zuora.com/Zuora_Billing/Build_products_and_prices/Basic_concepts_and_terms/B_Charge_Models/D_Manage_Enhanced_Discount) feature to access this field.
type: boolean
isPrepaid:
description: |
Indicates whether this charge is a prepayment (topup) charge or a
drawdown charge.
**Note**: This field is only available if you have the [Prepaid with
Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown)
feature enabled.
**Values**: `true` or `false`.
type: boolean
prepaidOperationType:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
The type of this charge. It is either a prepayment (topup) charge or a drawdown charge.
enum:
- topup
- drawdown
- null
type: string
nullable: true
prepaidQuantity:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
The number of units included in a [prepayment charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge). Must be a positive number (>0).
type: number
nullable: true
prepaidTotalQuantity:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
The total amount of units that end customers can use during a validity period when they subscribe to a [prepayment charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge).
type: number
nullable: true
prepaidUom:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
Unit of measurement for a [prepayment charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge).
type: string
nullable: true
validityPeriodType:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
The period in which the prepayment units are valid to use as defined in a [prepayment charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge).
enum:
- SUBSCRIPTION_TERM
- ANNUAL
- SEMI_ANNUAL
- QUARTER
- MONTH
type: string
drawdownRate:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
The [conversion rate](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_drawdown_charge#UOM_Conversion) between Usage UOM and Drawdown UOM for a [drawdown charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_drawdown_charge). Must be a positive number (>0).
type: number
nullable: true
drawdownUom:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
Unit of measurement for a [drawdown charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_drawdown_charge).
type: string
nullable: true
creditOption:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
The way to calculate credit. See [Credit Option](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge#Credit_Option) for more information.
enum:
- TimeBased
- ConsumptionBased
- FullCreditBack
type: string
isRollover:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
The value is either "true" or "false". It determines whether the rollover fields are needed.
type: boolean
rolloverApply:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
This field defines the priority of rollover, which is either first or last.
enum:
- ApplyFirst
- ApplyLast
type: string
rolloverPeriodLength:
default: null
description: |
**Note**: This field is only available if you have the [Prepaid with
Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown)
feature enabled.
Use this field when you want to set the rollover fund's period length shorter than the prepayment charge's validity period. In this case, you must set the `rolloverPeriods` field to 1. For example, you can define the rollover fund's period length as 5 months, shorter than the prepayment charge's validity period: a year.
type: integer
rolloverPeriods:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
This field defines the number of rollover periods, it is restricted to 3.
type: number
formula:
description: |
The price lookup formula defined for the product rate plan charge, which is used to identify
the correct and relevant charge definition based on the context.
For more information, see Price lookup in Attribute-based Pricing.
**Note**: This field is available only if the Attribute-based Pricing feature is enabled.
type: string
type: object
GETDeliverySchedule:
properties:
frequency:
description: |
The frequency of the delivery. Only weekly delivery is supported now.
enum:
- Weekly
type: string
friday:
description: |
The flag to indicate whether the delivery happens on Friday.
type: boolean
monday:
description: |
The flag to indicate whether the delivery happens on Monday.
type: boolean
saturday:
description: |
The flag to indicate whether the delivery happens on Saturday.
type: boolean
sunday:
description: |
The flag to indicate whether the delivery happens on Sunday.
type: boolean
thursday:
description: |
The flag to indicate whether the delivery happens on Thursday.
type: boolean
tuesday:
description: |
The flag to indicate whether the delivery happens on Tuesday.
type: boolean
wednesday:
description: |
The flag to indicate whether the delivery happens on Wendesday.
type: boolean
title: deliverySchedule
type: object
nullable: true
GETRatePlanChargePricing:
properties:
currency:
description: |
The currency for the price.
type: string
discountAmount:
description: |
The specific amount for a fixed discount. This field is applicable for charges based on the Discount-Fixed Amount charge model.
format: double
type: number
nullable: true
discountPercentage:
description: |
The percentage of discount for a percentage discount. This field is applicable for charges based on the Discount-Percentage charge model.
format: double
type: number
nullable: true
includedUnits:
description: |
The number of units included in this price item.
This field is only applicable for charges based on the Overage Pricing charge model.
type: number
nullable: true
overagePrice:
description: |
The overage price of the price item.
This field is only applicable for charges based on the Overage Pricing or Tiered with Overage Pricing charge model.
type: number
nullable: true
price:
description: |
The price.
This field is only applicable for charges based on the following charge models:
- Flat Fee
- Per Unit
- Delivery Pricing
type: number
tiers:
description: |
Container for the tiers of the price item.
This field is only applicable for charges based on the following charge models:
- Tiered Pricing
- Volume Pricing
- Tiered with Overage Pricing
items:
$ref: '#/components/schemas/GETRatePlanChargePricingTier'
type: array
nullable: true
type: object
GETRatePlanChargePricingTier:
description: |
Array of product rate plan charge tiers.
You should specify all relevant fields of all tiers, including pricing information for each currency.
For each currency, ensure that the tiers appear in ascending order of `StartingUnit`.
For example:
```
[
{
"StartingUnit": "1",
"EndingUnit": "150",
"Currency": "USD",
"Price": 1.95,
"PriceFormat": "Per Unit"
},
{
"StartingUnit": "151",
"EndingUnit": "300",
"Currency": "USD",
"Price": 1.45,
"PriceFormat": "Per Unit"
},
{
"StartingUnit": "1",
"EndingUnit": "150",
"Currency": "EUR",
"Price": 1.75,
"PriceFormat": "Per Unit"
},
{
"StartingUnit": "151",
"EndingUnit": "300",
"Currency": "EUR",
"Price": 1.30,
"PriceFormat": "Per Unit"
}
]
```
items:
properties:
currency:
description: |
The code corresponding to the currency for the price tier.
type: string
discountAmount:
description: |
The specific amount for a fixed discount. This field is applicable for charges based on the Discount-Fixed Amount charge model.
format: double
type: number
discountPercentage:
description: |
The percentage of discount for a percentage discount. This field is applicable for charges based on the Discount-Percentage charge model.
format: double
type: number
endingUnit:
description: |
The end number of a range of units for the tier. This field is applicable for charges based on the Tiered Pricing or Tiered with Overage Pricing charge model.
format: double
type: number
overagePrice:
description: |
Indicates whether the price is an overage price, which is the price when usage surpasses the last defined tier.
format: double
type: number
price:
description: |
The price of the tier if the charge is a flat fee, or the price of each unit in the tier if the charge model is tiered pricing.
format: double
type: number
startingUnit:
description: |
The starting number of a range of units for the tier. This field is applicable for charges based on the Tiered Pricing or Tiered with Overage Pricing charge model.
format: double
type: number
type: object
type: array
ProxyCreateProductRatePlanCharge:
allOf:
- properties:
AccountingCode:
description: |
The accounting code for the charge. Accounting codes group transactions that contain similar accounting attributes.
maxLength: 100
type: string
ApplyDiscountTo:
description: |
Specifies the type of charges that you want a specific discount to apply to. All field values are case sensitive and in all-caps.
enum:
- ONETIME (1)
- RECURRING (2)
- USAGE (4)
- ONETIMERECURRING (3)
- ONETIMEUSAGE (5)
- RECURRINGUSAGE (6)
- ONETIMERECURRINGUSAGE (7)
type: string
BillCycleDay:
description: |
Sets the bill cycle day (BCD) for the charge. The BCD determines which day of the month customer is billed. The BCD value in the account can override the BCD in this object.
**Character limit**: 2
**Values**: a valid BCD integer, 1 - 31
format: int32
type: integer
BillCycleType:
description: |
Specifies how to determine the billing day for the charge.
**Notes**:
- If you set this field to `SpecificDayofMonth`, you must specify which day of the month as the billing day for the charge in the BillCycleDay field.
- If you set this field to `SpecificDayofWeek`, you must specify which day of the week as the billing day for the charge in the WeeklyBillCycleDay field.
- By default, `TermStartDay` and `TermEndDay` are only available for prepayment charges. But you can reach out to Zuora Global Support to request enabling it for non-prepaid recurring charges. Meanwhile, note the following rules applies to these options:
- The Term End Day option of the Billing Day field must be coupled with the Align to Term End option of the Billing Period Alignment field.
- For prepaid charges, the Term Start Day option of the Billing Day field must be coupled with the existing Align to Term Start option of the Billing Period Alignment field.
- For non-prepaid recurring charges: If Billing Day is set to Term Start Day, Billing Period Alignment must be Align to Term Start; If Billing Day is set to Term End Day, Billing Period Alignment can be set to other values.
enum:
- DefaultFromCustomer
- SpecificDayofMonth
- SubscriptionStartDay
- ChargeTriggerDay
- SpecificDayofWeek
- TermStartDay
- TermEndDay
type: string
BillingPeriod:
description: |
The billing period for the charge. The start day of the billing period is also called the bill cycle day (BCD).
**Notes**:
- Specify the number of months or weeks in the SpecificBillingPeriod field if you set this field to `Specific Months` or `Specific Weeks`.
- The `Subscription Term` value is in **Limited Availability**.
enum:
- Month
- Quarter
- Annual
- Semi-Annual
- Specific Months
- Subscription Term
- Week
- Specific Weeks
- Specific Days
type: string
BillingPeriodAlignment:
description: |
Aligns charges within the same subscription if multiple charges begin on different dates.
**Note:** The `AlignToTermEnd` value is only available for prepayment charges by default. Reach out to Zuora Global Support to enable it for non-prepaid recurring charges.
enum:
- AlignToCharge
- AlignToSubscriptionStart
- AlignToTermStart
- AlignToTermEnd
type: string
BillingTiming:
description: |
The billing timing for the charge. You can choose to bill in advance or in arrears for recurring charge types. This field is not used in one-time or usage based charge types.
This feature is in **Limited Availability**. If you wish to have access to the feature, submit a request at [Zuora Global Support](http://support.zuora.com/).
enum:
- In Advance
- In Arrears
type: string
ChargeFunction:
description: |
**Note**: This field is only available if you have the Prepaid with Drawdown or Minimum Commitment feature enabled.
To use this field, you must set the `X-Zuora-WSDL-Version` request header to `141` or higher. Otherwise, an error occurs.
This field defines what type of charge it is:
* Standard: Normal charge with no Prepayment or Commitment or Drawdown.
* Prepayment: For recurring charges. Unit or currency based prepaid charge.
* CommitmentTrueUp: For recurring charges. Currency based minimum commitment charge.
* Drawdown: For usage charges. Drawdown from prepaid funds.
* DrawdownAndCreditCommitment: For usage charges. Drawdown from prepaid funds and then credit to minimum commitment funds.
* CreditCommitment: For usage charges. Credit to minimum commitment funds.
enum:
- Standard
- Prepayment
- CommitmentTrueUp
- Drawdown
- CreditCommitment
- DrawdownAndCreditCommitment
type: string
CommitmentType:
description: |
**Note**: This field is only available if you have the Prepaid with Drawdown feature enabled.
To use this field, you must set the `X-Zuora-WSDL-Version` request header to `133` or higher. Otherwise, an error occurs.
This field defines the type of commitment. A prepaid charge can be `UNIT` or `CURRENCY`. A minimum commitment(in-arrears) charge can only be `CURRENCY` type. For topup(recurring or one-time) charges, this field indicates what type of funds are created.
* If UNIT, it will create a fund with given prepaidUom.
* If CURRENCY, it will create a fund with the currency amount calculated in list price.
For drawdown(usage) charges, this field indicates what type of funds are drawdown from that created from topup charges.
enum:
- UNIT
- CURRENCY
type: string
ChargeModel:
description: |
Determines how to calculate charges. Charge models must be individually activated in Zuora Billing administration.
**Notes:**
- The `Delivery Pricing` value is available only if you have the Delivery Pricing charge model enabled. The minimal required WSDL version is 128.
- The `MultiAttributePricing` value is available only if you have the Multi-Attribute Pricing charge model enabled. The charge model is available for customers with Enterprise and Nine editions by default. If you are a Growth customer, see [Zuora Editions](https://docs.zuora.com/en/entitlements/current-entitlements/zuora-editions) for pricing information. The minimal required WSDL version is 102.
- The `PreratedPerUnit` and value is available only if you have the Pre-rated Per Unit Pricing charge model enabled. The charge model is available for customers with Enterprise and Nine editions by default. If you are a Growth customer, see [Zuora Editions](https://docs.zuora.com/en/entitlements/current-entitlements/zuora-editions) for pricing information. The minimal required WSDL version is 102.
- The `PreratedPricing` value is available only if you have the Pre-rated Pricing charge model enabled. The charge model is available for customers with Enterprise and Nine editions by default. If you are a Growth customer, see [Zuora Editions](https://docs.zuora.com/en/entitlements/current-entitlements/zuora-editions) for pricing information. The minimal required WSDL version is 102.
- The `HighWatermarkVolumePricing`value is available only if you have the High Water Mark Volume Pricing charge model enabled. The charge model is available for customers with Enterprise and Nine editions by default. If you are a Growth customer, see [Zuora Editions](https://docs.zuora.com/en/entitlements/current-entitlements/zuora-editions) for pricing information. The minimal required WSDL version is 102.
- The `HighWatermarkTieredPricing` value is available only if you have the High Water Mark Tiered Pricing charge model enabled. The charge model is available for customers with Enterprise and Nine editions by default. If you are a Growth customer, see [Zuora Editions](https://docs.zuora.com/en/entitlements/current-entitlements/zuora-editions) for pricing information. The minimal required WSDL version is 102.
enum:
- Discount-Fixed Amount
- Discount-Percentage
- Flat Fee Pricing
- Per Unit Pricing
- Overage Pricing
- Tiered Pricing
- Tiered with Overage Pricing
- Volume Pricing
- Delivery Pricing
- MultiAttributePricing
- PreratedPerUnit
- PreratedPricing`
- HighWatermarkVolumePricing
- HighWatermarkTieredPricing
type: string
ChargeModelConfiguration:
$ref: '#/components/schemas/ProxyCreateOrModifyProductRatePlanChargeChargeModelConfiguration'
ChargeType:
description: |
Specifies the type of charge.
enum:
- OneTime
- Recurring
- Usage
type: string
CreditOption:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
To use this field, you must set the `X-Zuora-WSDL-Version` request header to 114 or higher. Otherwise, an error occurs.
The way to calculate credit. See [Credit Option](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge#Credit_Option) for more information.
enum:
- TimeBased
- ConsumptionBased
- FullCreditBack
type: string
DefaultQuantity:
description: |
The default quantity of units, such as the number of authors in a hosted wiki service. This field is required if you use a per-unit pricing model.
**Character limit**: 16
**Values**: a valid quantity value.
**Note:** When the `ChargeModel` field is set to `Tiered Pricing` or `Volume Pricing`, if this field is not specified, the value will default to `0`.
format: double
type: number
DeferredRevenueAccount:
description: |
The name of the deferred revenue account for this charge.
This feature is in **Limited Availability**. If you wish to have access to the feature, submit a request at [Zuora Global Support](http://support.zuora.com/).
maxLength: 100
type: string
DeliverySchedule:
$ref: '#/components/schemas/ProxyCreateOrModifyDeliverySchedule'
Description:
description: |
A description of the charge.
maxLength: 500
type: string
DiscountLevel:
description: |
Specifies if the discount applies to just the product rate plan, the entire subscription, or to any activity in the account.
enum:
- rateplan
- subscription
- account
type: string
DrawdownRate:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
To use this field, you must set the `X-Zuora-WSDL-Version` request header to 114 or higher. Otherwise, an error occurs.
The [conversion rate](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_drawdown_charge#UOM_Conversion) between Usage UOM and Drawdown UOM for a [drawdown charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_drawdown_charge). See [Fields related to Prepaid with Drawdown](https://knowledgecenter.zuora.com/Central_Platform/API/G_SOAP_API/E1_SOAP_API_Object_Reference/ProductRatePlanCharge#Fields_related_to_Prepaid_with_Drawdown) for more information.
type: number
DrawdownUom:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
To use this field, you must set the `X-Zuora-WSDL-Version` request header to 114 or higher. Otherwise, an error occurs.
Unit of measurement for a [drawdown charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_drawdown_charge).
type: string
EndDateCondition:
default: SubscriptionEnd
description: |
Defines when the charge ends after the charge trigger date.
**Values**:
- `SubscriptionEnd`: The charge ends on the subscription end date after a specified period based on the trigger date of the charge.
- `FixedPeriod`: The charge ends after a specified period based on the trigger date of the charge. If you set this field to `FixedPeriod`, you must specify the length of the period and a period type by defining the `UpToPeriods` and `UpToPeriodsType` fields.
**Note**: If the subscription ends before the charge end date, the charge ends when the subscription ends. But if the subscription end date is subsequently changed through a Renewal, or Terms and Conditions amendment, the charge will end on the charge end date.
enum:
- SubscriptionEnd
- FixedPeriod
type: string
ExcludeItemBillingFromRevenueAccounting:
default: false
description: |
The flag to exclude the related invoice items, invoice item adjustments, credit memo items, and debit memo items from revenue accounting.
**Notes**:
- To use this field, you must set the `X-Zuora-WSDL-Version` request header to `115` or later. Otherwise, an error occurs.
- This field is only available if you have the Order to Revenue or Billing - Revenue Integration feature enabled.
type: boolean
ExcludeItemBookingFromRevenueAccounting:
default: false
description: |
The flag to exclude the related rate plan charges and order line items from revenue accounting.
**Notes**:
- To use this field, you must set the `X-Zuora-WSDL-Version` request header to `115` or later. Otherwise, an error occurs.
- This field is only available if you have the Order to Revenue or Billing - Revenue Integration feature enabled.
type: boolean
IncludedUnits:
description: |
Specifies the number of units in the base set of units.
**Character limit**: 16
**Values**: a positive decimal value
format: double
type: number
IsAllocationEligible:
description: |
Indicates whether the charge segment is allocation eligible in revenue recognition. The default value is `False`.
**Values**: `True`, `False`
**Notes**:
- The field is only available if you have the Order to Revenue feature enabled. To enable this field, submit a request at Zuora Global Support.
- To use this field, you must set the `X-Zuora-WSDL-Version` request header to 132 or later.
type: boolean
IsPrepaid:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
To use this field, you must set the `X-Zuora-WSDL-Version` request header to 114 or higher. Otherwise, an error occurs.
Indicates whether this charge is a prepayment (topup) charge or a drawdown charge.
**Values**: `true` or `false`.
type: boolean
IsRollover:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
To use this field, you must set the `X-Zuora-WSDL-Version` request header to 114 or higher. Otherwise, an error occurs.
The value is either "True" or "False". It determines whether the rollover fields are needed.
type: boolean
IsStackedDiscount:
description: |
**Note**: This field is only applicable to the Discount - Percentage charge model.
To use this field, you must set the `X-Zuora-WSDL-Version` request header to 130 or higher. Otherwise, an error occurs.
This field indicates whether the discount is to be calculated as stacked discount. Possible values are as follows:
- `True`: This is a stacked discount, which should be calculated by stacking with other discounts.
- `False`: This is not a stacked discount, which should be calculated in sequence with other discounts.
For more information, see [Stacked discounts](https://knowledgecenter.zuora.com/Zuora_Billing/Products/Product_Catalog/B_Charge_Models/B_Discount_Charge_Models).
type: boolean
IsUnbilled:
description: |
Specifies how to perform the accounting during revenue recognition. The default value is `False`.
**Values**: `True`, `False`
**Notes**:
- The field is only available if you have the Order to Revenue feature enabled. To enable this field, submit a request at Zuora Global Support.
- To use this field, you must set the `X-Zuora-WSDL-Version` request header to 132 or later.
type: boolean
LegacyRevenueReporting:
description: ''
type: boolean
ListPriceBase:
description: |
The list price base for the product rate plan charge.
**Note**: If the `ListBasePrice` field is not set in the request, the system will use the `BillingPeriod` value as the default value.
enum:
- Per Billing Period
- Per Month
- Per Week
- Per Year
- Per Specific Months
type: string
MaxQuantity:
description: |
Specifies the maximum number of units for this charge. Use this field and the `MinQuantity` field to create a range of units allowed in a product rate plan charge.
**Character limit**: 16
**Values**: a positive decimal value
format: double
type: number
MinQuantity:
description: |
Specifies the minimum number of units for this charge. Use this field and the `MaxQuantity` field to create a range of units allowed in a product rate plan charge.
**Character limit**: 16
**Values**: a positive decimal value
format: double
type: number
Name:
description: |
The name of the product rate plan charge.
maxLength: 100
type: string
NumberOfPeriod:
description: |
Specifies the number of periods to use when calculating charges in an overage smoothing charge model. The valid value is a positive whole number.
format: int64
type: integer
OverageCalculationOption:
description: |
Determines when to calculate overage charges. If the value of the SmoothingMode field is not specified, the value of this field is ignored.
**Values**:
- `EndOfSmoothingPeriod`: This option is used by default. The overage is charged at the end of the smoothing period.
- `PerBillingPeriod`: The overage is charged on-demand rather than waiting until the end of the smoothing period.
enum:
- EndOfSmoothingPeriod
- PerBillingPeriod
type: string
OverageUnusedUnitsCreditOption:
description: |
Determines whether to credit the customer with unused units of usage.
enum:
- NoCredit
- CreditBySpecificRate
- null
type: string
nullable: true
PrepaidOperationType:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
To use this field, you must set the `X-Zuora-WSDL-Version` request header to 114 or higher. Otherwise, an error occurs.
The type of this charge. It is either a prepayment (topup) charge or a drawdown charge.
enum:
- topup
- drawdown
type: string
PrepaidQuantity:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
To use this field, you must set the `X-Zuora-WSDL-Version` request header to 114 or higher. Otherwise, an error occurs.
The number of units included in a [prepayment charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge). Must be a positive number.
type: number
PrepaidTotalQuantity:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
To use this field, you must set the `X-Zuora-WSDL-Version` request header to 114 or higher. Otherwise, an error occurs.
The total amount of units that end customers can use during a validity period when they subscribe to a [prepayment charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge).
type: number
PrepaidUom:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
To use this field, you must set the `X-Zuora-WSDL-Version` request header to 114 or higher. Otherwise, an error occurs.
Unit of measurement for a [prepayment charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge).
type: string
PriceChangeOption:
default: NoChange
description: |
Applies an automatic price change when a termed subscription is renewed.
enum:
- NoChange
- SpecificPercentageValue
- UseLatestProductCatalogPricing
type: string
PriceIncreaseOption:
description: |
Applies an automatic price change when a termed subscription is renewed.
enum:
- FromTenantPercentageValue
- SpecificPercentageValue
type: string
PriceIncreasePercentage:
description: |
Specifies the percentage to increase or decrease the price of a termed subscription's renewal. Use this field if you set the value to `SpecificPercentageValue`.
**Character limit**: 16
**Values**: a decimal value between -100 and 100
format: double
type: number
nullable: true
ProductCategory:
description: |
This field is used to maintain the product category for integration with Zuora Revenue.
**Notes**:
- This field is available only if you have the Additional Revenue Fields property enabled.
- To use this field, you must set the `X-Zuora-WSDL-Version` request header to 132 or later.
type: string
ProductClass:
description: |
This field is used to maintain the product class for integration with Zuora Revenue.
**Notes**:
- This field is available only if you have the Additional Revenue Fields property enabled.
- To use this field, you must set the `X-Zuora-WSDL-Version` request header to 132 or later.
type: string
ProductFamily:
description: |
This field is used to maintain the product family for integration with Zuora Revenue.
**Notes**:
- This field is available only if you have the Additional Revenue Fields property enabled.
- To use this field, you must set the `X-Zuora-WSDL-Version` request header to 132 or later.
type: string
ProductLine:
description: |
This field is used to maintain the product line for integration with Zuora Revenue.
**Notes**:
- This field is available only if you have the Additional Revenue Fields property enabled.
- To use this field, you must set the `X-Zuora-WSDL-Version` request header to 132 or later.
type: string
ReflectDiscountInNetAmount:
type: boolean
default: false
description: |
When you apply percentage discounts to either of the following charges, you need to set the `ReflectDiscountInNetAmount` field on your discount charge to `true`, to enable calculating and displaying the net amount of the following charges in Zuora Revenue.
* delivery pricing charge
* prepayment charge
* drawdown charge
Note the following:
* If you are an Order to Revenue customer, when you set the `ReflectDiscountInNetAmount` field to `true`, you must also set both the `ExcludeItemBookingFromRevenueAccounting` and `ExcludeItemBillingFromRevenueAccounting` fields to `true`.
* If you are a Billing - Revenue Integration customer, you must set the `ReflectDiscountInNetAmount` field to `false`, otherwise an error will be returned. Billing - Revenue Integration does not support discounts on the preceding charges.
* If you are a Zuora Billing customer who does not enable the Order to Revenue or Billing - Revenue Integration feature, when you apply percentage discounts to the preceding charges, you also need to set the `ReflectDiscountInNetAmount` field to `true`.
RevenueRecognitionTiming:
description: |
Specifies the type of revenue recognition timing.
Predefined options are listed as enum values in this API Reference.
Other options might also be avaliable depending on
the revenue recognition policy configuration in the Zuora Billing UI.
**Note**: This field is only available if you have the Order to Revenue feature enabled.
maxLength: 200
type: string
enum:
- Upon Billing Document Posting Date
- Upon Order Activation Date
RevenueAmortizationMethod:
description: |
Specifies the type of revenue amortization method.
Predefined options are listed as enum values in this API Reference.
Other options might also be avaliable depending on
the revenue recognition policy configuration in the Zuora Billing UI.
**Note**: This field is only available if you have the Order to Revenue feature enabled.
maxLength: 200
type: string
enum:
- Immediate
- Ratable Using Start And End Dates
ProductRatePlanChargeNumber:
description: |
The natural key of the product rate plan charge.
**Values**:
- leave null for automatically generated string
- an alphanumeric string of 100 characters or fewer
**Note**: This field is only available if you set the `X-Zuora-WSDL-Version` request header to `133` or later.
maxLength: 100
type: string
ProductRatePlanChargeTierData:
$ref: '#/components/schemas/ProxyCreateOrModifyProductRatePlanChargeTierData'
ProductRatePlanId:
description: |
The ID of the product rate plan associated with this product rate plan charge.
maxLength: 32
type: string
ProrationOption:
description: |
**Note**: This field is only available if you have the Charge Level Proration feature enabled. For more information, see Usage charge proration and Charge level proration option for a recurring charge.
To use this field, you must set the `X-Zuora-WSDL-Version` request header to `135` or higher. Otherwise, an error occurs.
You can use this field to specify the charge-level proration option for a usage charge or recurring charge. The tenant-level proration option will be overridden.
* `NoProration`: charge-level proration option that you can set for a usage charge. This option means to not use any proration, which is the default current system behavior for a usage charge.
* `TimeBasedProration`: charge-level proration option that you can set for a usage charge. This option means to prorate the usage charge amount using the actual number of days if the billing period is a partial period.
* `DefaultFromTenantSetting`: charge-level proration option that you can set for a recurring charge. This option means to follow the customer billing rule proration setting.
* `ChargeFullPeriod`: charge-level proration option that you can set for a recurring charge. This options means to charge the full period amount for a partial billing period. Note that this setting means that there is no proration for either collecting or refunding. Even if you cancel the recurring charge in the middle of a billing period, there is no refund for this billing period.
enum:
- NoProration
- TimeBasedProration
- DefaultFromTenantSetting
- ChargeFullPeriod
type: string
RatingGroup:
default: ByBillingPeriod
description: |
Specifies a rating group based on which usage records are rated.
Possible values:
- `ByBillingPeriod`: The rating is based on all the usages in a billing period.
- `ByUsageStartDate`: The rating is based on all the usages on the same usage start date.
- `ByUsageRecord`: The rating is based on each usage record.
- `ByUsageUpload`: The rating is based on all the usages in a uploaded usage file (`.xls` or `.csv`).
- `ByGroupId`: The rating is based on all the usages in a custom group.
**Notes:**
- The `ByBillingPeriod` value can be applied for all charge models.
- The `ByUsageStartDate`, `ByUsageRecord`, and `ByUsageUpload` values can only be applied for per unit, volume pricing, and tiered pricing charge models.
- The `ByGroupId` value is only available if you have the Active Rating feature enabled.
- Use this field only for Usage charges. One-Time Charges and Recurring Charges return `NULL`.
enum:
- ByBillingPeriod
- ByUsageStartDate
- ByUsageRecord
- ByUsageUpload
- ByGroupId
- null
type: string
nullable: true
RecognizedRevenueAccount:
description: |
The name of the recognized revenue account for this charge.
- Required when the Allow Blank Accounting Code setting is No.
- Optional when the Allow Blank Accounting Code setting is Yes.
This feature is in **Limited Availability**. If you wish to have access to the feature, submit a request at [Zuora Global Support](http://support.zuora.com/).
maxLength: 100
type: string
RevRecCode:
description: |
Associates this product rate plan charge with a specific revenue recognition code.
maxLength: 70
type: string
nullable: true
RevRecTriggerCondition:
description: |
Specifies when revenue recognition begins.
enum:
- ContractEffectiveDate
- ServiceActivationDate
- CustomerAcceptanceDate
- null
type: string
nullable: true
RevenueRecognitionRuleName:
description: |
Determines when to recognize the revenue for this charge.
enum:
- Recognize upon invoicing
- Recognize daily over time
type: string
RolloverApply:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
To use this field, you must set the `X-Zuora-WSDL-Version` request header to 114 or higher. Otherwise, an error occurs.
This field defines the priority of rollover, which is either first or last.
enum:
- ApplyFirst
- ApplyLast
type: string
RolloverPeriods:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
To use this field, you must set the `X-Zuora-WSDL-Version` request header to 114 or higher. Otherwise, an error occurs.
This field defines the number of rollover periods, it is restricted to 3.
type: number
SmoothingModel:
description: |
Specifies the smoothing model for an overage smoothing charge model.
enum:
- RollingWindow
- Rollover
- null
type: string
nullable: true
SpecificBillingPeriod:
description: |
Customizes the number of months or weeks for the charges billing period. This field is required if you set the value of the BillingPeriod field to `Specific Months` or `Specific Weeks`.
The valid value is a positive integer.
format: int64
type: integer
nullable: true
SpecificListPriceBase:
description: |
The number of months for the list price base of the charge. This field is required if you set the value of the `ListPriceBase` field to `Per Specific Months`. The value must be a positive integer between **1** and **120** inclusive.
**Notes**:
- This field is available only if you have the Annual List Price feature enabled.
- To use this field, you must set the `X-Zuora-WSDL-Version` request header to `129` or later. Otherwise, an error occurs.
- The value of this field is `null` if you do not set the value of the `ListPriceBase` field to `Per Specific Months`.
format: int32
maximum: 120
minimum: 1
example: 12
type: integer
nullable: true
TaxCode:
description: |
Specifies the tax code for taxation rules. Required when the Taxable field is set to `True`.
**Note**: This value affects the tax calculation of rate plan charges that come from the `ProductRatePlanCharge`.
maxLength: 64
type: string
TaxMode:
description: |
Determines how to define taxation for the charge. Required when the Taxable field is set to `True`.
**Note**: This value affects the tax calculation of rate plan charges that come from the `ProductRatePlanCharge`.
enum:
- TaxExclusive
- TaxInclusive
- null
type: string
nullable: true
Taxable:
description: |
Determines whether the charge is taxable. When set to `True`, the TaxMode and TaxCode fields are required when creating or updating th ProductRatePlanCharge object.
**Character limit**: 5
**Values**: `True`, `False`
**Note**: This value affects the tax calculation of rate plan charges that come from the `ProductRatePlanCharge`.
type: boolean
TriggerEvent:
description: |
Specifies when to start billing the customer for the charge.
**Values**:
- `ContractEffective` is the date when the subscription's contract goes into effect and the charge is ready to be billed.
- `ServiceActivation` is the date when the services or products for a subscription have been activated and the customers have access.
- `CustomerAcceptance` is when the customer accepts the services or products for a subscription.
enum:
- ContractEffective
- ServiceActivation
- CustomerAcceptance
type: string
UOM:
description: |
Specifies a configured unit to measure usage.
**Note**: You must specify this field when creating the following charge models:
- Per Unit Pricing
- Volume Pricing
- Overage Pricing
- Tiered Pricing
- Tiered with Overage Pricing
maxLength: 25
type: string
nullable: true
UpToPeriods:
description: |
Specifies the length of the period during which the charge is active. If this period ends before the subscription ends, the charge ends when this period ends.
**Character limit**: 5
**Values**: a whole number between 0 and 65535, exclusive
**Notes**:
- You must use this field together with the `UpToPeriodsType` field to specify the time period. This field is applicable only when the `EndDateCondition` field is set to `FixedPeriod`.
- If the subscription end date is subsequently changed through a Renewal, or Terms and Conditions amendment, the charge end date will change accordingly up to the original period end.
format: int64
type: integer
nullable: true
UpToPeriodsType:
default: Billing Periods
description: |
The period type used to define when the charge ends.
**Notes**:
- You must use this field together with the `UpToPeriods` field to specify the time period.
- This field is applicable only when the `EndDateCondition` field is set to `FixedPeriod`.
enum:
- Billing Periods
- Days
- Weeks
- Months
- Years
- null
type: string
nullable: true
UsageRecordRatingOption:
default: EndOfBillingPeriod
description: |
Determines how Zuora processes usage records for per-unit usage charges.
enum:
- EndOfBillingPeriod
- OnDemand
- null
type: string
nullable: true
UseDiscountSpecificAccountingCode:
description: |
Determines whether to define a new accounting code for the new discount charge.
**Character limit**: 5
**Values**: `True`, `False`
type: boolean
nullable: true
UseTenantDefaultForPriceChange:
description: |
Applies the tenant-level percentage uplift value for an automatic price change to a termed subscription's renewal.
**Character limit**: 5
**Values**: `true`, `false`
type: boolean
ValidityPeriodType:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
To use this field, you must set the `X-Zuora-WSDL-Version` request header to 114 or higher. Otherwise, an error occurs.
The period in which the prepayment units are valid to use as defined in a [prepayment charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge).
enum:
- SUBSCRIPTION_TERM
- ANNUAL
- SEMI_ANNUAL
- QUARTER
- MONTH
type: string
WeeklyBillCycleDay:
description: |
Specifies which day of the week as the bill cycle day (BCD) for the charge.
This feature is in **Limited Availability**. If you wish to have access to the feature, submit a request at [Zuora Global Support](http://support.zuora.com/).
enum:
- Sunday
- Monday
- Tuesday
- Wednesday
- Thursday
- Friday
- Saturday
type: string
ApplyToBillingPeriodPartially:
description: |
Allow the discount duration to be aligned with the billing period partially.
**Note**: You must enable the [Enhanced Discount](https://knowledgecenter.zuora.com/Zuora_Billing/Build_products_and_prices/Basic_concepts_and_terms/B_Charge_Models/D_Manage_Enhanced_Discount) feature to access this field.
type: boolean
RolloverPeriodLength:
default: null
description: |
**Note**: This field is only available if you have the [Prepaid with
Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown)
feature enabled.
To use this field, you must set the `X-Zuora-WSDL-Version` request
header to 137 or higher. Otherwise, an error occurs.
Use this field when you want to set the rollover fund's period length shorter than the prepayment charge's validity period. In this case, you must set the `rolloverPeriods` field to 1. For example, you can define the rollover fund's period length as 5 months, shorter than the prepayment charge's validity period: a year.
type: integer
Formula:
description: |
The price lookup formula defined for the product rate plan charge, which is used to identify the correct and relevant charge definition based on the context.
For more information, see Price lookup in Attribute-based Pricing.
**Notes**:
- This field is available only if the Attribute-based Pricing feature is enabled.
- To use this field, you must set the `X-Zuora-WSDL-Version` request header to 138 or higher.
type: string
required:
- BillCycleType
- BillingPeriod
- ChargeModel
- ChargeType
- Name
- ProductRatePlanChargeTierData
- ProductRatePlanId
- TriggerEvent
- UseDiscountSpecificAccountingCode
type: object
- $ref: '#/components/schemas/ProductRatePlanChargeObjectNSFields'
- $ref: '#/components/schemas/ProductRatePlanChargeObjectCustomFields'
example:
Name: One-Time charge
ProductRatePlanId: 8ad08ae290c4bb470190dedf752745af
ChargeType: OneTime
ChargeModel: Flat Fee Pricing
ProductRatePlanChargeTierData:
ProductRatePlanChargeTier:
- Price: 10
TriggerEvent: ContractEffective
ProxyCreateOrModifyProductRatePlanChargeChargeModelConfiguration:
description: |
Container for charge model configuration data.
**Notes**:
- This field is only available if you have the Pre-Rated Pricing or Multi-Attribute Pricing charge models enabled. These charge models are available for customers with Enterprise and Nine editions by default. If you are a Growth customer, see [Zuora Editions](https://docs.zuora.com/en/entitlements/current-entitlements/zuora-editions) for pricing information.
- To use this field, you must set the `X-Zuora-WSDL-Version` request header to `102` or later. Otherwise, an error occurs with "Code: INVALID_VALUE".
properties:
ConfigurationItem:
description: |
An array of Charge Model Configuration Key-Value pairs.
items:
$ref: '#/components/schemas/ProxyCreateOrModifyProductRatePlanChargeChargeModelConfigurationItem'
type: array
title: ChargeModelConfiguration
type: object
ProxyCreateOrModifyDeliverySchedule:
properties:
frequency:
description: |
The frequency of the delivery. Only supports weekly now
enum:
- Weekly
type: string
friday:
description: |
The flag to indicate should the delivery happen on Friday
type: boolean
monday:
description: |
The flag to indicate should the delivery happen on Monday
type: boolean
saturday:
description: |
The flag to indicate should the delivery happen on Saturday
type: boolean
sunday:
description: |
The flag to indicate should the delivery happen on Sunday
type: boolean
thursday:
description: |
The flag to indicate should the delivery happen on Thursday
type: boolean
tuesday:
description: |
The flag to indicate should the delivery happen on Tuesday
type: boolean
wendesday:
description: |
The flag to indicate should the delivery happen on Wendesday
type: boolean
title: DeliverySchedule
type: object
ProxyCreateOrModifyProductRatePlanChargeTierData:
description: |
Container for pricing information associated with the product rate plan charge.
properties:
ProductRatePlanChargeTier:
description: |
Array of product rate plan charge tiers.
You should specify all relevant fields of all tiers, including pricing information for each currency.
For each currency, ensure that the tiers appear in ascending order of `StartingUnit`.
For example:
```
[
{
"StartingUnit": "1",
"EndingUnit": "150",
"Currency": "USD",
"Price": 1.95,
"PriceFormat": "Per Unit"
},
{
"StartingUnit": "151",
"EndingUnit": "300",
"Currency": "USD",
"Price": 1.45,
"PriceFormat": "Per Unit"
},
{
"StartingUnit": "1",
"EndingUnit": "150",
"Currency": "EUR",
"Price": 1.75,
"PriceFormat": "Per Unit"
},
{
"StartingUnit": "151",
"EndingUnit": "300",
"Currency": "EUR",
"Price": 1.30,
"PriceFormat": "Per Unit"
}
]
```
items:
properties:
Currency:
description: |
The code corresponding to the currency for the tier's price.
type: string
DiscountAmount:
description: |
The specific amount for a fixed discount. Required if the charge model of the product rate plan charge is `Discount-Fixed Amount`.
format: double
type: number
DiscountPercentage:
description: |
The percentage of discount for a percentage discount. Required if the charge model of the product rate plan charge is `Discount-Percentage`.
format: double
type: number
EndingUnit:
description: |
The end number of a range of units for the tier. Required if the charge model of the product rate plan charge is `Tiered Pricing` or `Tiered with Overage Pricing`.
format: double
type: number
IsOveragePrice:
description: |
Indicates if the price is an overage price, which is the price when usage surpasses the last defined tier.
type: boolean
Price:
description: |
The price of the tier if the charge is a flat fee, or the price of each unit in the tier if the charge model is tiered pricing.
format: double
type: number
PriceFormat:
description: |
Indicates if pricing is a flat fee or is per unit. This field is for tiered and volume pricing models only.
enum:
- Flat Fee
- Per Unit
type: string
StartingUnit:
description: |
The starting number of a range of units for the tier. Required if the charge model of the product rate plan charge is `Tiered Pricing` or `Tiered with Overage Pricing`.
format: double
type: number
type: object
type: array
title: productRatePlanChargeTierData
type: object
ProxyCreateOrModifyProductRatePlanChargeChargeModelConfigurationItem:
properties:
Key:
description: |
The name of the field that is specified for a specific charge model.
Configuration keys supported are as follows:
* `formula` (only available if you have the Multi-Attribute Pricing charge model enabled. The charge model is available for customers with Enterprise and Nine editions by default. If you are a Growth customer, see [Zuora Editions](https://docs.zuora.com/en/entitlements/current-entitlements/zuora-editions) for pricing information.)
* `customFieldPerUnitRate` (only available if you have the Pre-Rated Per Unit Pricing charge model enabled. The charge model is available for customers with Enterprise and Nine editions by default. If you are a Growth customer, see [Zuora Editions](https://docs.zuora.com/en/entitlements/current-entitlements/zuora-editions) for pricing information.)
* `customFieldTotalAmount` (only available if you have the Pre-Rated Pricing model enabled. The charge model is available for customers with Enterprise and Nine editions by default. If you are a Growth customer, see [Zuora Editions](https://docs.zuora.com/en/entitlements/current-entitlements/zuora-editions) for pricing information.)
type: string
Value:
description: |
The value of the field that is specified in the `Key` field.
Possible values are follows:
* A valid pricing formula to calculate actual rating amount for each usage record. For example, `usageQuantity()*10`. Use it with Key `formula` when the Multi-Attribute Pricing charge model is used. The charge model is available for customers with Enterprise and Nine editions by default. If you are a Growth customer, see [Zuora Editions](https://docs.zuora.com/en/entitlements/current-entitlements/zuora-editions) for pricing information.
* A name of a usage custom field that carries the per-unit rate for a usage record. For example, `perUnitRate__c`. Use it with Key `customFieldPerUnitRate` when the Pre-Rated Per Unit Pricing charge model is used. The charge model is available for customers with Enterprise and Nine editions by default. If you are a Growth customer, see [Zuora Editions](https://docs.zuora.com/en/entitlements/current-entitlements/zuora-editions) for pricing information.
* A name of a usage custom field that carries the total amount for a usage record. For example, `totalAmount__c`. Use it with Key `customFieldTotalAmount` when the Pre-Rated Pricing model is used. The charge model is available for customers with Enterprise and Nine editions by default. If you are a Growth customer, see [Zuora Editions](https://docs.zuora.com/en/entitlements/current-entitlements/zuora-editions) for pricing information.
type: string
required:
- Key
- Value
title: ConfigurationItem
type: object
ProxyGetProductRatePlanCharge:
allOf:
- properties:
AccountingCode:
description: |
The accounting code for the charge. Accounting codes group transactions that contain similar accounting attributes.
maxLength: 100
type: string
ApplyDiscountTo:
description: |
Specifies the type of charges that you want a specific discount to apply to. All field values are case sensitive and in all-caps.
enum:
- ONETIME (1)
- RECURRING (2)
- USAGE (4)
- ONETIMERECURRING (3)
- ONETIMEUSAGE (5)
- RECURRINGUSAGE (6)
- ONETIMERECURRINGUSAGE (7)
type: string
BillCycleDay:
description: |
Sets the bill cycle day (BCD) for the charge. The BCD determines which day of the month customer is billed. The BCD value in the account can override the BCD in this object.
**Character limit**: 2
**Values**: a valid BCD integer, 1 - 31
format: int32
type: integer
BillCycleType:
description: |
Specifies how to determine the billing day for the charge.
enum:
- DefaultFromCustomer
- SpecificDayofMonth
- SubscriptionStartDay
- ChargeTriggerDay
- SpecificDayofWeek
- TermStartDay
- TermEndDay
type: string
BillingPeriod:
description: |
The billing period for the charge. The start day of the billing period is also called the bill cycle day (BCD).
enum:
- Month
- Quarter
- Annual
- Semi-Annual
- Specific Months
- Subscription Term
- Week
- Specific Weeks
- Specific Days
type: string
BillingPeriodAlignment:
description: |
Aligns charges within the same subscription if multiple charges begin on different dates.
enum:
- AlignToCharge
- AlignToSubscriptionStart
- AlignToTermStart
- AlignToTermEnd
type: string
BillingTiming:
description: |
The billing timing for the charge. You can choose to bill in advance or in arrears for recurring charge types. This field is not used in one-time or usage based charge types.
This feature is in **Limited Availability**. If you wish to have access to the feature, submit a request at [Zuora Global Support](http://support.zuora.com/).
enum:
- In Advance
- In Arrears
type: string
ChargeFunction:
description: |
**Note**: This field is only available if you have the Prepaid with Drawdown or Minimum Commitment feature enabled.
To use this field, you must set the `X-Zuora-WSDL-Version` request header to `141` or higher. Otherwise, an error occurs.
This field defines what type of charge it is:
* Standard: Normal charge with no Prepayment or Commitment or Drawdown.
* Prepayment: For recurring charges. Unit or currency based prepaid charge.
* CommitmentTrueUp: For recurring charges. Currency based minimum commitment charge.
* Drawdown: For usage charges. Drawdown from prepaid funds.
* DrawdownAndCreditCommitment: For usage charges. Drawdown from prepaid funds and then credit to minimum commitment funds.
* CreditCommitment: For usage charges. Credit to minimum commitment funds.
enum:
- Standard
- Prepayment
- CommitmentTrueUp
- Drawdown
- CreditCommitment
- DrawdownAndCreditCommitment
type: string
CommitmentType:
description: |
**Note**: This field is only available if you have the Prepaid with Drawdown feature enabled.
To use this field, you must set the `X-Zuora-WSDL-Version` request header to `133` or higher. Otherwise, an error occurs.
This field defines the type of commitment. A prepaid charge can be `UNIT` or `CURRENCY`. A minimum commitment(in-arrears) charge can only be `CURRENCY` type. For topup(recurring or one-time) charges, this field indicates what type of funds are created.
* If UNIT, it will create a fund with given prepaidUom.
* If CURRENCY, it will create a fund with the currency amount calculated in list price.
For drawdown(usage) charges, this field indicates what type of funds are drawdown from that created from topup charges.
enum:
- UNIT
- CURRENCY
type: string
ChargeModel:
description: |
Determines how to calculate charges. Charge models must be individually activated in Zuora Billing administration.
enum:
- Discount-Fixed Amount
- Discount-Percentage
- Flat Fee Pricing
- Per Unit Pricing
- Overage Pricing
- Tiered Pricing
- Tiered with Overage Pricing
- Volume Pricing
- Delivery Pricing
- MultiAttributePricing
- PreratedPerUnit
- PreratedPricing`
- HighWatermarkVolumePricing
- HighWatermarkTieredPricing
type: string
ChargeType:
description: |
Specifies the type of charge.
enum:
- OneTime
- Recurring
- Usage
type: string
CreatedById:
description: |
The automatically generated ID of the Zuora user who created the `ProductRatePlanCharge` object.
maxLength: 32
type: string
CreatedDate:
description: |
The date when the `ProductRatePlanCharge` object was created.
format: date-time
maxLength: 29
type: string
DefaultQuantity:
description: |
The default quantity of units, such as the number of authors in a hosted wiki service. This field is required if you use a per-unit pricing model.
**Character limit**: 16
**Values**: a valid quantity value.
**Note**: When `ChargeModel` is `Tiered Pricing` or `Volume Pricing`, if this field is not specified, the value will default to `0`.
format: double
type: number
DeferredRevenueAccount:
description: |
The name of the deferred revenue account for this charge.
This feature is in **Limited Availability**. If you wish to have access to the feature, submit a request at [Zuora Global Support](http://support.zuora.com/).
maxLength: 100
type: string
Description:
description: |
A description of the charge.
maxLength: 500
type: string
DiscountLevel:
description: |
Specifies if the discount applies to just the product rate plan, the entire subscription, or to any activity in the account.
enum:
- rateplan
- subscription
- account
type: string
EndDateCondition:
default: SubscriptionEnd
description: |
Defines when the charge ends after the charge trigger date.
**Values**:
- `SubscriptionEnd`: The charge ends on the subscription end date after a specified period based on the trigger date of the charge.
- `FixedPeriod`: The charge ends after a specified period based on the trigger date of the charge. If you set this field to `FixedPeriod`, you must specify the length of the period and a period type by defining the `UpToPeriods` and `UpToPeriodsType` fields.
**Note**: If the subscription ends before the charge end date, the charge ends when the subscription ends. But if the subscription end date is subsequently changed through a Renewal, or Terms and Conditions amendment, the charge will end on the charge end date.
enum:
- SubscriptionEnd
- FixedPeriod
type: string
ExcludeItemBillingFromRevenueAccounting:
description: |
The flag to exclude the related invoice items, invoice item adjustments, credit memo items, and debit memo items from revenue accounting.
**Notes**:
- To use this field, you must set the `X-Zuora-WSDL-Version` request header to `115` or later. Otherwise, an error occurs.
- This field is only available if you have the Order to Revenue or Billing - Revenue Integration feature enabled.
type: boolean
ExcludeItemBookingFromRevenueAccounting:
description: |
The flag to exclude the related rate plan charges and order line items from revenue accounting.
**Notes**:
- To use this field, you must set the `X-Zuora-WSDL-Version` request header to `115` or later. Otherwise, an error occurs.
- This field is only available if you have the Order to Revenue or Billing - Revenue Integration feature enabled.
type: boolean
Id:
description: Object identifier.
type: string
IncludedUnits:
description: |
Specifies the number of units in the base set of units.
**Character limit**: 16
**Values**: a positive decimal value
format: double
type: number
LegacyRevenueReporting:
description: ''
type: boolean
ListPriceBase:
description: |
The list price base for the product rate plan charge.
enum:
- Per Billing Period
- Per Month
- Per Week
- Per Year
- Per Specific Months
type: string
MaxQuantity:
description: |
Specifies the maximum number of units for this charge. Use this field and the `MinQuantity` field to create a range of units allowed in a product rate plan charge.
**Character limit**: 16
**Values**: a positive decimal value
format: double
type: number
MinQuantity:
description: |
Specifies the minimum number of units for this charge. Use this field and the `MaxQuantity` field to create a range of units allowed in a product rate plan charge.
**Character limit**: 16
**Values**: a positive decimal value
format: double
type: number
Name:
description: |
The name of the product rate plan charge.
maxLength: 100
type: string
NumberOfPeriod:
description: |
Specifies the number of periods to use when calculating charges in an overage smoothing charge model. The valid value is a positive whole number.
format: int64
type: integer
OverageCalculationOption:
description: |
Determines when to calculate overage charges. If the value of the SmoothingMode field is not specified, the value of this field is ignored.
**Values**:
- `EndOfSmoothingPeriod`: This option is used by default. The overage is charged at the end of the smoothing period.
- `PerBillingPeriod`: The overage is charged on-demand rather than waiting until the end of the smoothing period.
enum:
- EndOfSmoothingPeriod
- PerBillingPeriod
- null
type: string
nullable: true
OverageUnusedUnitsCreditOption:
description: |
Determines whether to credit the customer with unused units of usage.
enum:
- NoCredit
- CreditBySpecificRate
- null
type: string
nullable: true
PriceChangeOption:
default: NoChange
description: |
Applies an automatic price change when a termed subscription is renewed.
enum:
- NoChange
- SpecificPercentageValue
- UseLatestProductCatalogPricing
- null
type: string
nullable: true
PriceIncreasePercentage:
description: |
Specifies the percentage to increase or decrease the price of a termed subscription's renewal. Use this field if you set the value to `SpecificPercentageValue`.
**Character limit**: 16
**Values**: a decimal value between -100 and 100
format: double
type: number
nullable: true
ProductRatePlanId:
description: |
The ID of the product rate plan associated with this product rate plan charge.
maxLength: 32
type: string
ProrationOption:
description: |
**Note**: This field is only available if you have the Charge Level Proration feature enabled. For more information, see Usage charge proration and Charge level proration option for a recurring charge.
To use this field, you must set the `X-Zuora-WSDL-Version` request header to `135` or higher. Otherwise, an error occurs.
You can use this field to specify the charge-level proration option for a usage charge or recurring charge. The tenant-level proration option will be overridden.
* `NoProration`: charge-level proration option that you can set for a usage charge. This option means to not use any proration, which is the default current system behavior for a usage charge.
* `TimeBasedProration`: charge-level proration option that you can set for a usage charge. This option means to prorate the usage charge amount using the actual number of days if the billing period is a partial period.
* `DefaultFromTenantSetting`: charge-level proration option that you can set for a recurring charge. This option means to follow the customer billing rule proration setting.
* `ChargeFullPeriod`: charge-level proration option that you can set for a recurring charge. This options means to charge the full period amount for a partial billing period. Note that this setting means that there is no proration for either collecting or refunding. Even if you cancel the recurring charge in the middle of a billing period, there is no refund for this billing period.
enum:
- NoProration
- TimeBasedProration
- DefaultFromTenantSetting
- ChargeFullPeriod
type: string
RatingGroup:
description: |
A rating group based on which usage records are rated. Only applicable to Usage charges.
Possible values:
- `ByBillingPeriod`: The rating is based on all the usages in a billing period.
- `ByUsageStartDate`: The rating is based on all the usages on the same usage start date.
- `ByUsageRecord`: The rating is based on each usage record.
- `ByUsageUpload`: The rating is based on all the usages in a uploaded usage file (`.xls` or `.csv`).
- `ByGroupId`: The rating is based on all the usages in a custom group.
For more information, see [Usage rating by group](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Usage/Usage_Rating_by_Group).
enum:
- ByBillingPeriod
- ByUsageStartDate
- ByUsageRecord
- ByUsageUpload
- ByGroupId
- null
type: string
nullable: true
RecognizedRevenueAccount:
description: |
The name of the recognized revenue account for this charge.
- Required when the Allow Blank Accounting Code setting is No.
- Optional when the Allow Blank Accounting Code setting is Yes.
This feature is in **Limited Availability**. If you wish to have access to the feature, submit a request at [Zuora Global Support](http://support.zuora.com/).
maxLength: 100
type: string
RevRecCode:
description: |
Associates this product rate plan charge with a specific revenue recognition code.
maxLength: 70
type: string
nullable: true
RevRecTriggerCondition:
description: |
Specifies when revenue recognition begins.
enum:
- ContractEffectiveDate
- ServiceActivationDate
- CustomerAcceptanceDate
- null
type: string
nullable: true
RevenueRecognitionRuleName:
description: |
Determines when to recognize the revenue for this charge.
enum:
- Recognize upon invoicing
- Recognize daily over time
type: string
SmoothingModel:
description: |
Specifies the smoothing model for an overage smoothing charge model.
enum:
- RollingWindow
- Rollover
- null
type: string
nullable: true
SpecificBillingPeriod:
description: |
Customizes the number of months or weeks for the charges billing period. This field is required if you set the value of the BillingPeriod field to `Specific Months` or `Specific Weeks`.
The valid value is a positive integer.
format: int64
type: integer
nullable: true
SpecificListPriceBase:
type: integer
nullable: true
description: |
The number of months for the list price base of the charge. The value of this field is `null` if you do not set the value of the `ListPriceBase` field to `Per Specific Months`.
**Notes**:
- This field is available only if you have the Annual List Price feature enabled.
- To use this field, you must set the `X-Zuora-WSDL-Version` request header to `129` or later. Otherwise, an error occurs.
- The value of this field is `null` if you do not set the value of the `ListPriceBase` field to `Per Specific Months`.
TaxCode:
description: |
Specifies the tax code for taxation rules. Required when the Taxable field is set to `True`.
**Note**: This value affects the tax calculation of rate plan charges that come from the `ProductRatePlanCharge`.
maxLength: 64
type: string
TaxMode:
description: |
Determines how to define taxation for the charge. Required when the Taxable field is set to `True`.
**Note**: This value affects the tax calculation of rate plan charges that come from the `ProductRatePlanCharge`.
enum:
- TaxExclusive
- TaxInclusive
- null
type: string
nullable: true
Taxable:
description: |
Determines whether the charge is taxable. When set to `True`, the TaxMode and TaxCode fields are required when creating or updating th ProductRatePlanCharge object.
**Character limit**: 5
**Values**: `True`, `False`
**Note**: This value affects the tax calculation of rate plan charges that come from the `ProductRatePlanCharge`.
type: boolean
TriggerEvent:
description: |
Specifies when to start billing the customer for the charge.
**Values**:
- `ContractEffective` is the date when the subscription's contract goes into effect and the charge is ready to be billed.
- `ServiceActivation` is the date when the services or products for a subscription have been activated and the customers have access.
- `CustomerAcceptance` is when the customer accepts the services or products for a subscription.
enum:
- ContractEffective
- ServiceActivation
- CustomerAcceptance
type: string
UOM:
description: |
Specifies the units to measure usage.
**Note**: You must specify this field when creating the following charge models:
- Per Unit Pricing
- Volume Pricin
- Overage Pricing
- Tiered Pricing
- Tiered with Overage Pricing
maxLength: 25
type: string
nullable: true
UpToPeriods:
description: |
Specifies the length of the period during which the charge is active. If this period ends before the subscription ends, the charge ends when this period ends.
**Character limit**: 5
**Values**: a whole number between 0 and 65535, exclusive
**Notes**:
- You must use this field together with the `UpToPeriodsType` field to specify the time period. This field is applicable only when the `EndDateCondition` field is set to `FixedPeriod`.
- If the subscription end date is subsequently changed through a Renewal, or Terms and Conditions amendment, the charge end date will change accordingly up to the original period end.
format: int64
type: integer
nullable: true
UpToPeriodsType:
default: Billing Periods
description: |
The period type used to define when the charge ends.
**Notes**:
- You must use this field together with the `UpToPeriods` field to specify the time period.
- This field is applicable only when the `EndDateCondition` field is set to `FixedPeriod`.
enum:
- Billing Periods
- Days
- Weeks
- Months
- Years
- null
type: string
nullable: true
UpdatedById:
description: |
The ID of the last user to update the object.
maxLength: 32
type: string
UpdatedDate:
description: |
The date when the object was last updated.
format: date-time
maxLength: 29
type: string
UseDiscountSpecificAccountingCode:
description: |
Determines whether to define a new accounting code for the new discount charge.
**Character limit**: 5
**Values**: `True`, `False`
type: boolean
nullable: true
UseTenantDefaultForPriceChange:
description: |
Applies the tenant-level percentage uplift value for an automatic price change to a termed subscription's renewal.
**Character limit**: 5
**Values**: `true`, `false`
type: boolean
WeeklyBillCycleDay:
description: |
Specifies which day of the week as the bill cycle day (BCD) for the charge.
This feature is in **Limited Availability**. If you wish to have access to the feature, submit a request at [Zuora Global Support](http://support.zuora.com/).
enum:
- Sunday
- Monday
- Tuesday
- Wednesday
- Thursday
- Friday
- Saturday
type: string
IsAllocationEligible:
description: |
Indicates whether the charge segment is allocation eligible in revenue recognition. The default value is `False`.
**Values**: `True`, `False`
**Notes**:
- The field is only available if you have the Order to Revenue feature enabled. To enable this field, submit a request at Zuora Global Support.
- To use this field, you must set the `X-Zuora-WSDL-Version` request header to 132 or later.
type: boolean
IsUnbilled:
description: |
Specifies how to perform the accounting during revenue recognition. The default value is `False`.
**Values**: `True`, `False`
**Notes**:
- The field is only available if you have the Order to Revenue feature enabled. To enable this field, submit a request at Zuora Global Support.
- To use this field, you must set the `X-Zuora-WSDL-Version` request header to 132 or later.
type: boolean
ProductCategory:
description: |
This field is used to maintain the product category for integration with Zuora Revenue.
**Notes**:
- This field is available only if you have the Additional Revenue Fields property enabled.
- To use this field, you must set the `X-Zuora-WSDL-Version` request header to 132 or later.
type: string
ProductClass:
description: |
This field is used to maintain the product class for integration with Zuora Revenue.
**Notes**:
- This field is available only if you have the Additional Revenue Fields property enabled.
- To use this field, you must set the `X-Zuora-WSDL-Version` request header to 132 or later.
type: string
ProductFamily:
description: |
This field is used to maintain the product family for integration with Zuora Revenue.
**Notes**:
- This field is available only if you have the Additional Revenue Fields property enabled.
- To use this field, you must set the `X-Zuora-WSDL-Version` request header to 132 or later.
type: string
ProductLine:
description: |
This field is used to maintain the product line for integration with Zuora Revenue.
**Notes**:
- This field is available only if you have the Additional Revenue Fields property enabled.
- To use this field, you must set the `X-Zuora-WSDL-Version` request header to 132 or later.
type: string
ReflectDiscountInNetAmount:
type: boolean
default: false
description: |
When you apply percentage discounts to either of the following charges, you need to set the `ReflectDiscountInNetAmount` field on your discount charge to `true`, to enable calculating and displaying the net amount of the following charges in Zuora Revenue.
* delivery pricing charge
* prepayment charge
* drawdown charge
Note the following:
* If you are an Order to Revenue customer, when you set the `ReflectDiscountInNetAmount` field to `true`, you must also set both the `ExcludeItemBookingFromRevenueAccounting` and `ExcludeItemBillingFromRevenueAccounting` fields to `true`.
* If you are a Billing - Revenue Integration customer, you must set the `ReflectDiscountInNetAmount` field to `false`, otherwise an error will be returned. Billing - Revenue Integration customers are not supported with net amount.
* If you are a Zuora Billing customer who does not enable the Order to Revenue or Billing - Revenue Integration feature, when you apply percentage discounts to the preceding charges, you also need to set the `ReflectDiscountInNetAmount` field to `true`.
RevenueRecognitionTiming:
description: |
Specifies the type of revenue recognition timing.
Predefined options are listed as enum values in this API Reference.
Other options might also be avaliable depending on
the revenue recognition policy configuration in the Zuora Billing UI.
**Note**: This field is only available if you have the Order to Revenue feature enabled.
maxLength: 200
type: string
enum:
- Upon Billing Document Posting Date
- Upon Order Activation Date
RevenueAmortizationMethod:
description: |
Specifies the type of revenue amortization method.
Predefined options are listed as enum values in this API Reference.
Other options might also be avaliable depending on
the revenue recognition policy configuration in the Zuora Billing UI.
**Note**: This field is only available if you have the Order to Revenue feature enabled.
maxLength: 200
type: string
enum:
- Immediate
- Ratable Using Start And End Dates
ApplyToBillingPeriodPartially:
description: |
Allow the discount duration to be aligned with the billing period partially.
**Note**: You must enable the [Enhanced Discount](https://knowledgecenter.zuora.com/Zuora_Billing/Build_products_and_prices/Basic_concepts_and_terms/B_Charge_Models/D_Manage_Enhanced_Discount) feature to access this field.
type: boolean
Formula:
description: |
The price lookup formula defined for the product rate plan charge, which is used to identify
the correct and relevant charge definition based on the context.
For more information, see Price lookup in Attribute-based Pricing.
**Notes**:
- This field is available only if the Attribute-based Pricing feature is enabled.
- To use this field, you must set the `X-Zuora-WSDL-Version` request header to 138 or higher.
type: string
type: object
- $ref: '#/components/schemas/ProductRatePlanChargeObjectNSFields'
- $ref: '#/components/schemas/ProductRatePlanChargeObjectCustomFields'
ProxyModifyProductRatePlanCharge:
allOf:
- properties:
AccountingCode:
description: |
The accounting code for the charge. Accounting codes group transactions that contain similar accounting attributes.
maxLength: 100
type: string
ApplyDiscountTo:
description: |
Specifies the type of charges that you want a specific discount to apply to. All field values are case sensitive and in all-caps.
enum:
- ONETIME (1)
- RECURRING (2)
- USAGE (4)
- ONETIMERECURRING (3)
- ONETIMEUSAGE (5)
- RECURRINGUSAGE (6)
- ONETIMERECURRINGUSAGE (7)
type: string
BillCycleDay:
description: |
Sets the bill cycle day (BCD) for the charge. The BCD determines which day of the month customer is billed. The BCD value in the account can override the BCD in this object.
**Character limit**: 2 **Values**: a valid BCD integer, 1 - 31
format: int32
type: integer
BillCycleType:
description: |
Specifies how to determine the billing day for the charge.
**Notes**:
- If you set this field to `SpecificDayofMonth`, you must specify which day of the month as the billing day for the charge in the BillCycleDay field.
- If you set this field to `SpecificDayofWeek`, you must specify which day of the week as the billing day for the charge in the WeeklyBillCycleDay field.
- By default, `TermStartDay` and `TermEndDay` are only available for prepayment charges. But you can reach out to Zuora Global Support to request enabling it for non-prepaid recurring charges. Meanwhile, note the following rules applies to these options:
- The Term End Day option of the Billing Day field must be coupled with the Align to Term End option of the Billing Period Alignment field.
- For prepaid charges, the Term Start Day option of the Billing Day field must be coupled with the existing Align to Term Start option of the Billing Period Alignment field.
- For non-prepaid recurring charges: If Billing Day is set to Term Start Day, Billing Period Alignment must be Align to Term Start; If Billing Day is set to Term End Day, Billing Period Alignment can be set to other values.
enum:
- DefaultFromCustomer
- SpecificDayofMonth
- SubscriptionStartDay
- ChargeTriggerDay
- SpecificDayofWeek
- TermStartDay
- TermEndDay
type: string
BillingPeriod:
description: |
The billing period for the charge. The start day of the billing period is also called the bill cycle day (BCD).
**Notes**:
- Specify the number of months or weeks in the SpecificBillingPeriod field if you set this field to `Specific Months` or `Specific Weeks`.
- The `Subscription Term` value is in **Limited Availability**.
enum:
- Month
- Quarter
- Annual
- Semi-Annual
- Specific Months
- Subscription Term
- Week
- Specific Weeks
- Specific Days
type: string
BillingPeriodAlignment:
description: |
Aligns charges within the same subscription if multiple charges begin on different dates.
**Note:** The `AlignToTermEnd` value is only available for prepayment charges by default. Reach out to Zuora Global Support to enable it for non-prepaid recurring charges.
enum:
- AlignToCharge
- AlignToSubscriptionStart
- AlignToTermStart
- AlignToTermEnd
type: string
BillingTiming:
description: |
The billing timing for the charge. You can choose to bill in advance or in arrears for recurring charge types. This field is not used in one-time or usage based charge types.
This feature is in **Limited Availability**. If you wish to have access to the feature, submit a request at [Zuora Global Support](http://support.zuora.com/).
enum:
- In Advance
- In Arrears
type: string
ChargeFunction:
description: |
**Note**: This field is only available if you have the Prepaid with Drawdown or Minimum Commitment feature enabled.
To use this field, you must set the `X-Zuora-WSDL-Version` request header to `141` or higher. Otherwise, an error occurs.
This field defines what type of charge it is:
* Standard: Normal charge with no Prepayment or Commitment or Drawdown.
* Prepayment: For recurring charges. Unit or currency based prepaid charge.
* CommitmentTrueUp: For recurring charges. Currency based minimum commitment charge.
* Drawdown: For usage charges. Drawdown from prepaid funds.
* DrawdownAndCreditCommitment: For usage charges. Drawdown from prepaid funds and then credit to minimum commitment funds.
* CreditCommitment: For usage charges. Credit to minimum commitment funds.
enum:
- Standard
- Prepayment
- CommitmentTrueUp
- Drawdown
- CreditCommitment
- DrawdownAndCreditCommitment
type: string
CommitmentType:
description: |
**Note**: This field is only available if you have the Prepaid with Drawdown feature enabled.
To use this field, you must set the `X-Zuora-WSDL-Version` request header to `133` or higher. Otherwise, an error occurs.
This field defines the type of commitment. A prepaid charge can be `UNIT` or `CURRENCY`. A minimum commitment(in-arrears) charge can only be `CURRENCY` type. For topup(recurring or one-time) charges, this field indicates what type of funds are created.
* If UNIT, it will create a fund with given prepaidUom.
* If CURRENCY, it will create a fund with the currency amount calculated in list price.
For drawdown(usage) charges, this field indicates what type of funds are drawdown from that created from topup charges.
enum:
- UNIT
- CURRENCY
type: string
ChargeModel:
description: |
Determines how to calculate charges. Charge models must be individually activated in Zuora Billing administration.
**Notes:**
- The `Delivery Pricing` value is available only if you have the Delivery Pricing charge model enabled.
- The `MultiAttributePricing` value is available only if you have the Multi-Attribute Pricing charge model enabled. The charge model is available for customers with Enterprise and Nine editions by default. If you are a Growth customer, see [Zuora Editions](https://docs.zuora.com/en/entitlements/current-entitlements/zuora-editions) for pricing information.
- The `PreratedPerUnit` and value is available only if you have the Pre-rated Per Unit Pricing charge model enabled. The charge model is available for customers with Enterprise and Nine editions by default. If you are a Growth customer, see [Zuora Editions](https://docs.zuora.com/en/entitlements/current-entitlements/zuora-editions) for pricing information.
- The `PreratedPricing` value is available only if you have the Pre-rated Pricing charge model enabled. The charge model is available for customers with Enterprise and Nine editions by default. If you are a Growth customer, see [Zuora Editions](https://docs.zuora.com/en/entitlements/current-entitlements/zuora-editions) for pricing information.
- The `HighWatermarkVolumePricing`value is available only if you have the High Water Mark Volume Pricing charge model enabled. The charge model is available for customers with Enterprise and Nine editions by default. If you are a Growth customer, see [Zuora Editions](https://docs.zuora.com/en/entitlements/current-entitlements/zuora-editions) for pricing information.
- The `HighWatermarkTieredPricing` value is available only if you have the High Water Mark Tiered Pricing charge model enabled. The charge model is available for customers with Enterprise and Nine editions by default. If you are a Growth customer, see [Zuora Editions](https://docs.zuora.com/en/entitlements/current-entitlements/zuora-editions) for pricing information.
enum:
- Discount-Fixed Amount
- Discount-Percentage
- Flat Fee Pricing
- Per Unit Pricing
- Overage Pricing
- Tiered Pricing
- Tiered with Overage Pricing
- Volume Pricing
- Delivery Pricing
- MultiAttributePricing
- PreratedPerUnit
- PreratedPricing`
- HighWatermarkVolumePricing
- HighWatermarkTieredPricing
type: string
ChargeModelConfiguration:
$ref: '#/components/schemas/ProxyCreateOrModifyProductRatePlanChargeChargeModelConfiguration'
CreditOption:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
To use this field, you must set the `X-Zuora-WSDL-Version` request header to 114 or higher. Otherwise, an error occurs.
The way to calculate credit. See [Credit Option](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge#Credit_Option) for more information.
enum:
- TimeBased
- ConsumptionBased
- FullCreditBack
type: string
DefaultQuantity:
description: |
The default quantity of units, such as the number of authors in a hosted wiki service. This field is required if you use a per-unit pricing model.
**Character limit**: 16
**Values**: a valid quantity value.
**Note:** When the `ChargeModel` field is set to `Tiered Pricing` or `Volume Pricing`, if this field is not specified, the value will default to `0`.
format: double
type: number
DeferredRevenueAccount:
description: |
The name of the deferred revenue account for this charge.
**Note**: `AccountingCode` value is mandatory to update this field. Specify the same accounting code name as given in the `AccountingCode`.
maxLength: 100
type: string
DeliverySchedule:
$ref: '#/components/schemas/ProxyCreateOrModifyDeliverySchedule'
Description:
description: |
A description of the charge.
maxLength: 500
type: string
DiscountLevel:
description: |
Specifies if the discount applies to just the product rate plan, the entire subscription, or to any activity in the account.
enum:
- rateplan
- subscription
- account
type: string
DrawdownRate:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
To use this field, you must set the `X-Zuora-WSDL-Version` request header to 114 or higher. Otherwise, an error occurs.
The [conversion rate](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_drawdown_charge#UOM_Conversion) between Usage UOM and Drawdown UOM for a [drawdown charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_drawdown_charge). See [Fields related to Prepaid with Drawdown](https://knowledgecenter.zuora.com/Central_Platform/API/G_SOAP_API/E1_SOAP_API_Object_Reference/ProductRatePlanCharge#Fields_related_to_Prepaid_with_Drawdown) for more information.
type: number
DrawdownUom:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
To use this field, you must set the `X-Zuora-WSDL-Version` request header to 114 or higher. Otherwise, an error occurs.
Unit of measurement for a [drawdown charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_drawdown_charge).
type: string
EndDateCondition:
default: SubscriptionEnd
description: |
Defines when the charge ends after the charge trigger date.
**Values**:
- `SubscriptionEnd`: The charge ends on the subscription end date after a specified period based on the trigger date of the charge.
- `FixedPeriod`: The charge ends after a specified period based on the trigger date of the charge. If you set this field to `FixedPeriod`, you must specify the length of the period and a period type by defining the `UpToPeriods` and `UpToPeriodsType` fields.
**Note**: If the subscription ends before the charge end date, the charge ends when the subscription ends. But if the subscription end date is subsequently changed through a Renewal, or Terms and Conditions amendment, the charge will end on the charge end date.
enum:
- SubscriptionEnd
- FixedPeriod
type: string
ExcludeItemBillingFromRevenueAccounting:
default: false
description: |
The flag to exclude the related invoice items, invoice item adjustments, credit memo items, and debit memo items from revenue accounting.
**Notes**:
- To use this field, you must set the `X-Zuora-WSDL-Version` request header to `115` or later. Otherwise, an error occurs.
- This field is only available if you have the Order to Revenue or Billing - Revenue Integration feature enabled.
type: boolean
ExcludeItemBookingFromRevenueAccounting:
default: false
description: |
The flag to exclude the related rate plan charges and order line items from revenue accounting.
**Notes**:
- To use this field, you must set the `X-Zuora-WSDL-Version` request header to `115` or later. Otherwise, an error occurs.
- This field is only available if you have the Order to Revenue or Billing - Revenue Integration feature enabled.
type: boolean
IncludedUnits:
description: |
Specifies the number of units in the base set of units.
**Character limit**: 16
**Values**: a positive decimal value
format: double
type: number
IsAllocationEligible:
description: |
Indicates whether the charge segment is allocation eligible in revenue recognition. The default value is `False`.
**Values**: `True`, `False`
**Notes**:
- The field is only available if you have the Order to Revenue feature enabled. To enable this field, submit a request at Zuora Global Support.
- To use this field, you must set the `X-Zuora-WSDL-Version` request header to 132 or later.
type: boolean
IsPrepaid:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
To use this field, you must set the `X-Zuora-WSDL-Version` request header to 114 or higher. Otherwise, an error occurs.
Indicates whether this charge is a prepayment (topup) charge or a drawdown charge.
**Values**: `true` or `false`.
type: boolean
IsRollover:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
To use this field, you must set the `X-Zuora-WSDL-Version` request header to 114 or higher. Otherwise, an error occurs.
The value is either "True" or "False". It determines whether the rollover fields are needed.
type: boolean
IsStackedDiscount:
description: |
**Note**: This field is only applicable to the Discount - Percentage charge model.
To use this field, you must set the `X-Zuora-WSDL-Version` request header to 130 or higher. Otherwise, an error occurs.
This field indicates whether the discount is to be calculated as stacked discount. Possible values are as follows:
- `True`: This is a stacked discount, which should be calculated by stacking with other discounts.
- `False`: This is not a stacked discount, which should be calculated in sequence with other discounts.
For more information, see [Stacked discounts](https://knowledgecenter.zuora.com/Zuora_Billing/Products/Product_Catalog/B_Charge_Models/B_Discount_Charge_Models).
type: boolean
IsUnbilled:
description: |
Specifies how to perform the accounting during revenue recognition. The default value is `False`.
**Values**: `True`, `False`
**Notes**:
- The field is only available if you have the Order to Revenue feature enabled. To enable this field, submit a request at Zuora Global Support.
- To use this field, you must set the `X-Zuora-WSDL-Version` request header to 132 or later.
type: boolean
LegacyRevenueReporting:
description: ''
type: boolean
ListPriceBase:
description: |
The list price base for the product rate plan charge.
enum:
- Per Billing Period
- Per Month
- Per Week
- Per Year
- Per Specific Months
type: string
MaxQuantity:
description: |
Specifies the maximum number of units for this charge. Use this field and the `MinQuantity` field to create a range of units allowed in a product rate plan charge.
**Character limit**: 16
**Values**: a positive decimal value
format: double
type: number
MinQuantity:
description: |
Specifies the minimum number of units for this charge. Use this field and the `MaxQuantity` field to create a range of units allowed in a product rate plan charge.
**Character limit**: 16
**Values**: a positive decimal value
format: double
type: number
Name:
description: |
The name of the product rate plan charge.
maxLength: 100
type: string
NumberOfPeriod:
description: |
Specifies the number of periods to use when calculating charges in an overage smoothing charge model. The valid value must be a positive whole number.
format: int64
type: integer
OverageCalculationOption:
description: |
Determines when to calculate overage charges. If the value of the SmoothingMode field is not specified, the value of this field is ignored.
**Values**:
- `EndOfSmoothingPeriod`: This option is used by default. The overage is charged at the end of the smoothing period.
- `PerBillingPeriod`: The overage is charged on-demand rather than waiting until the end of the smoothing period.
enum:
- EndOfSmoothingPeriod
- PerBillingPeriod
- null
type: string
nullable: true
OverageUnusedUnitsCreditOption:
description: |
Determines whether to credit the customer with unused units of usage.
enum:
- NoCredit
- CreditBySpecificRate
- null
type: string
nullable: true
PrepaidQuantity:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
To use this field, you must set the `X-Zuora-WSDL-Version` request header to 114 or higher. Otherwise, an error occurs.
The number of units included in a [prepayment charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge). Must be a positive number.
type: number
PrepaidUom:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
To use this field, you must set the `X-Zuora-WSDL-Version` request header to 114 or higher. Otherwise, an error occurs.
Unit of measurement for a [prepayment charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge).
type: string
PriceChangeOption:
default: NoChange
description: |
Applies an automatic price change when a termed subscription is renewed.
enum:
- NoChange
- SpecificPercentageValue
- UseLatestProductCatalogPricing
- null
type: string
nullable: true
PriceIncreaseOption:
description: |
Applies an automatic price change when a termed subscription is renewed.
enum:
- FromTenantPercentageValue
- SpecificPercentageValue
type: string
PriceIncreasePercentage:
description: |
Specifies the percentage to increase or decrease the price of a termed subscription's renewal. Use this field if you set the value to `SpecificPercentageValue`.
**Character limit**: 16
**Values**: a decimal value between -100 and 100
format: double
type: number
nullable: true
ProductCategory:
description: |
This field is used to maintain the product category for integration with Zuora Revenue.
**Notes**:
- This field is available only if you have the Additional Revenue Fields property enabled.
- To use this field, you must set the `X-Zuora-WSDL-Version` request header to 132 or later.
type: string
ProductClass:
description: |
This field is used to maintain the product class for integration with Zuora Revenue.
**Notes**:
- This field is available only if you have the Additional Revenue Fields property enabled.
- To use this field, you must set the `X-Zuora-WSDL-Version` request header to 132 or later.
type: string
ProductFamily:
description: |
This field is used to maintain the product family for integration with Zuora Revenue.
**Notes**:
- This field is available only if you have the Additional Revenue Fields property enabled.
- To use this field, you must set the `X-Zuora-WSDL-Version` request header to 132 or later.
type: string
ProductLine:
description: |
This field is used to maintain the product line for integration with Zuora Revenue.
**Notes**:
- This field is available only if you have the Additional Revenue Fields property enabled.
- To use this field, you must set the `X-Zuora-WSDL-Version` request header to 132 or later.
type: string
ProrationOption:
description: |
**Note**: This field is only available if you have the Charge Level Proration feature enabled. For more information, see Usage charge proration and Charge level proration option for a recurring charge.
To use this field, you must set the `X-Zuora-WSDL-Version` request header to `135` or higher. Otherwise, an error occurs.
You can use this field to specify the charge-level proration option for a usage charge or recurring charge. The tenant-level proration option will be overridden.
* `NoProration`: charge-level proration option that you can set for a usage charge. This option means to not use any proration, which is the default current system behavior for a usage charge.
* `TimeBasedProration`: charge-level proration option that you can set for a usage charge. This option means to prorate the usage charge amount using the actual number of days if the billing period is a partial period.
* `DefaultFromTenantSetting`: charge-level proration option that you can set for a recurring charge. This option means to follow the customer billing rule proration setting.
* `ChargeFullPeriod`: charge-level proration option that you can set for a recurring charge. This options means to charge the full period amount for a partial billing period. Note that this setting means that there is no proration for either collecting or refunding. Even if you cancel the recurring charge in the middle of a billing period, there is no refund for this billing period.
enum:
- NoProration
- TimeBasedProration
- DefaultFromTenantSetting
- ChargeFullPeriod
type: string
RevenueRecognitionTiming:
description: |
Specifies the type of revenue recognition timing.
Predefined options are listed as enum values in this API Reference.
Other options might also be avaliable depending on
the revenue recognition policy configuration in the Zuora Billing UI.
To use this field, you must set the `X-Zuora-WSDL-Version` request header to 140 or higher. Otherwise, an error occurs.
**Note**: This field is only available if you have the Order to Revenue feature enabled.
maxLength: 200
type: string
enum:
- Upon Billing Document Posting Date
- Upon Order Activation Date
RevenueAmortizationMethod:
description: |
Specifies the type of revenue amortization method.
Predefined options are listed as enum values in this API Reference.
Other options might also be avaliable depending on
the revenue recognition policy configuration in the Zuora Billing UI.
To use this field, you must set the `X-Zuora-WSDL-Version` request header to 140 or higher. Otherwise, an error occurs.
**Note**: This field is only available if you have the Order to Revenue feature enabled.
maxLength: 200
type: string
enum:
- Immediate
- Ratable Using Start And End Dates
ProductRatePlanChargeNumber:
description: |
The natural key of the product rate plan charge.
For existing Product Rate Plan Charge objects that are created before this field is introduced, this field will be null. Use this field to specify a value for only these objects. Zuora also provides a tool to help you automatically backfill this field with tenant ID for your existing product catalog. If you want to use this backfill tool, contact [Zuora Global Support](https://support.zuora.com/).
**Note**: This field is only available if you set the `X-Zuora-WSDL-Version` request header to `133` or later.
maxLength: 100
type: string
ProductRatePlanChargeTierData:
$ref: '#/components/schemas/ProxyCreateOrModifyProductRatePlanChargeTierData'
ProductRatePlanId:
description: |
The ID of the product rate plan associated with this product rate plan charge.
maxLength: 32
type: string
RatingGroup:
default: ByBillingPeriod
description: |
Specifies a rating group based on which usage records are rated.
Possible values:
- `ByBillingPeriod`: The rating is based on all the usages in a billing period.
- `ByUsageStartDate`: The rating is based on all the usages on the same usage start date.
- `ByUsageRecord`: The rating is based on each usage record.
- `ByUsageUpload`: The rating is based on all the usages in a uploaded usage file (`.xls` or `.csv`).
- `ByGroupId`: The rating is based on all the usages in a custom group.
**Note:**
- The `ByBillingPeriod` value can be applied for all charge models.
- The `ByUsageStartDate`, `ByUsageRecord`, and `ByUsageUpload` values can only be applied for per unit, volume pricing, and tiered pricing charge models.
- The `ByGroupId` value is only available if you have the Active Rating feature enabled.
- Use this field only for Usage charges. One-Time Charges and Recurring Charges return `NULL`.
enum:
- ByBillingPeriod
- ByUsageStartDate
- ByUsageRecord
- ByUsageUpload
- ByGroupId
- null
type: string
nullable: true
RecognizedRevenueAccount:
description: |
The name of the recognized revenue account for this charge.
- Required when the Allow Blank Accounting Code setting is No.
- Optional when the Allow Blank Accounting Code setting is Yes.
This feature is in **Limited Availability**. If you wish to have access to the feature, submit a request at [Zuora Global Support](http://support.zuora.com/).
maxLength: 100
type: string
RevRecCode:
description: |
Associates this product rate plan charge with a specific revenue recognition code.
maxLength: 70
type: string
nullable: true
RevRecTriggerCondition:
description: |
Specifies when revenue recognition begins.
enum:
- ContractEffectiveDate
- ServiceActivationDate
- CustomerAcceptanceDate
- null
type: string
nullable: true
RevenueRecognitionRuleName:
description: |
Determines when to recognize the revenue for this charge.
enum:
- Recognize upon invoicing
- Recognize daily over time
type: string
RolloverApply:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
To use this field, you must set the `X-Zuora-WSDL-Version` request header to 114 or higher. Otherwise, an error occurs.
This field defines the priority of rollover, which is either first or last.
enum:
- ApplyFirst
- ApplyLast
type: string
RolloverPeriods:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
To use this field, you must set the `X-Zuora-WSDL-Version` request header to 114 or higher. Otherwise, an error occurs.
This field defines the number of rollover periods, it is restricted to 3.
type: number
SmoothingModel:
description: |
Specifies the smoothing model for an overage smoothing charge model.
enum:
- RollingWindow
- Rollover
- null
type: string
nullable: true
SpecificBillingPeriod:
description: |
Customizes the number of months or weeks for the charges billing period. This field is required if you set the value of the BillingPeriod field to `Specific Months` or `Specific Weeks`.
The valid value is a positive integer.
format: int64
type: integer
nullable: true
SpecificListPriceBase:
description: |
The number of months for the list price base of the charge. This field is required if you set the value of the `ListPriceBase` field to `Per Specific Months`.
**Notes**:
- This field is available only if you have the Annual List Price feature enabled.
- To use this field, you must set the `X-Zuora-WSDL-Version` request header to `129` or later. Otherwise, an error occurs.
- The value of this field is `null` if you do not set the value of the `ListPriceBase` field to `Per Specific Months`.
format: int32
maximum: 200
minimum: 1
type: integer
nullable: true
TaxCode:
description: |
Specifies the tax code for taxation rules. Required when the Taxable field is set to `True`.
**Note**: This value affects the tax calculation of rate plan charges that come from the `ProductRatePlanCharge`.
maxLength: 64
type: string
TaxMode:
description: |
Determines how to define taxation for the charge. Required when the Taxable field is set to `True`.
**Note**: This value affects the tax calculation of rate plan charges that come from the `ProductRatePlanCharge`.
enum:
- TaxExclusive
- TaxInclusive
- null
type: string
nullable: true
Taxable:
description: |
Determines whether the charge is taxable. When set to `True`, the TaxMode and TaxCode fields are required when creating or updating th ProductRatePlanCharge object.
**Character limit**: 5
**Values**: `True`, `False`
**Note**: This value affects the tax calculation of rate plan charges that come from the `ProductRatePlanCharge`.
type: boolean
TriggerEvent:
description: |
Specifies when to start billing the customer for the charge.
**Values**:
- `ContractEffective` is the date when the subscription's contract goes into effect and the charge is ready to be billed.
- `ServiceActivation` is the date when the services or products for a subscription have been activated and the customers have access.
- `CustomerAcceptance` is when the customer accepts the services or products for a subscription.
enum:
- ContractEffective
- ServiceActivation
- CustomerAcceptance
type: string
UOM:
description: |
Specifies the units to measure usage.
**Note**: You must specify this field when creating the following charge models:
- Per Unit Pricing
- Volume Pricing
- Overage Pricing
- Tiered Pricing
- Tiered with Overage Pricing
maxLength: 25
type: string
nullable: true
UpToPeriods:
description: |
Specifies the length of the period during which the charge is active. If this period ends before the subscription ends, the charge ends when this period ends.
**Character limit**: 5
**Values**: a whole number between 0 and 65535, exclusive
**Notes**:
- You must use this field together with the `UpToPeriodsType` field to specify the time period. This field is applicable only when the `EndDateCondition` field is set to `FixedPeriod`.
- If the subscription end date is subsequently changed through a Renewal, or Terms and Conditions amendment, the charge end date will change accordingly up to the original period end.
format: int64
type: integer
nullable: true
UpToPeriodsType:
default: Billing Periods
description: |
The period type used to define when the charge ends.
**Notes**:
- You must use this field together with the `UpToPeriods` field to specify the time period.
- This field is applicable only when the `EndDateCondition` field is set to `FixedPeriod`.
enum:
- Billing Periods
- Days
- Weeks
- Months
- Years
- null
type: string
nullable: true
UsageRecordRatingOption:
default: EndOfBillingPeriod
description: |
Determines how Zuora processes usage records for per-unit usage charges.
enum:
- EndOfBillingPeriod
- OnDemand
- null
type: string
nullable: true
UseDiscountSpecificAccountingCode:
description: |
Determines whether to define a new accounting code for the new discount charge.
**Character limit**: 5
**Values**: `True`, `False`
type: boolean
nullable: true
UseTenantDefaultForPriceChange:
description: |
Applies the tenant-level percentage uplift value for an automatic price change to a termed subscription's renewal.
**Character limit**: 5
**Values**: `true`, `false`
type: boolean
ValidityPeriodType:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
To use this field, you must set the `X-Zuora-WSDL-Version` request header to 114 or higher. Otherwise, an error occurs.
The period in which the prepayment units are valid to use as defined in a [prepayment charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge).
enum:
- SUBSCRIPTION_TERM
- ANNUAL
- SEMI_ANNUAL
- QUARTER
- MONTH
type: string
WeeklyBillCycleDay:
description: |
Specifies which day of the week as the bill cycle day (BCD) for the charge.
This feature is in **Limited Availability**. If you wish to have access to the feature, submit a request at [Zuora Global Support](http://support.zuora.com/).
enum:
- Sunday
- Monday
- Tuesday
- Wednesday
- Thursday
- Friday
- Saturday
type: string
ApplyToBillingPeriodPartially:
description: |
Allow the discount duration to be aligned with the billing period partially.
**Note**: You must enable the [Enhanced Discount](https://knowledgecenter.zuora.com/Zuora_Billing/Build_products_and_prices/Basic_concepts_and_terms/B_Charge_Models/D_Manage_Enhanced_Discount) feature to access this field.
type: boolean
RolloverPeriodLength:
default: null
description: |
**Note**: This field is only available if you have the [Prepaid with
Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown)
feature enabled.
To use this field, you must set the `X-Zuora-WSDL-Version` request
header to 137 or higher. Otherwise, an error occurs.
Use this field when you want to set the rollover fund's period length shorter than the prepayment charge's validity period. In this case, you must set the `rolloverPeriods` field to 1. For example, you can define the rollover fund's period length as 5 months, shorter than the prepayment charge's validity period: a year.
type: integer
Formula:
description: |
The price lookup formula defined for the product rate plan charge, which is used to identify
the correct and relevant charge definition based on the context.
For more information, see Price lookup in Attribute-based Pricing.
**Notes**:
- This field is available only if the Attribute-based Pricing feature is enabled.
- To use this field, you must set the `X-Zuora-WSDL-Version` request header to 138 or higher.
type: string
required:
- BillCycleType
- BillingPeriod
- ChargeModel
- ProductRatePlanChargeTierData
- ProductRatePlanId
- TriggerEvent
- UseDiscountSpecificAccountingCode
type: object
- $ref: '#/components/schemas/ProductRatePlanChargeObjectNSFields'
- $ref: '#/components/schemas/ProductRatePlanChargeObjectCustomFields'
example:
Name: One-Time charge
POSTChargeDefinitionRequest:
example:
productRatePlanChargeId: edcab92612893256dce329d0b377000e
effectiveStartDate: '2024-01-01 00:00:00'
effectiveEndDate: '2025-01-01 00:00:00'
listPriceBase: Per_Billing_Period
prices:
- currency: USD
price: 12
properties:
billingPeriod:
description: |
The billing period for the product charge definition.
type: string
billingTiming:
description: |
The billing timing setting for the product charge definition.
enum:
- IN_ADVANCE
- IN_ARREARS
type: string
chargeModel:
description: |
Determines how to calculate charges. Charge models must be individually activated in Zuora Billing administration.
enum:
- DiscountFixedAmount
- DiscountPercentage
- FlatFee
- PerUnit
- Tiered
- Volume
- Delivery
type: string
defaultQuantity:
description: |
The default quantity.
This field is applicable only for one-time and recurring charges.
type: number
nullable: true
effectiveEndDate:
description: |
The effective end date of the product charge definition.
format: date-time
type: string
effectiveStartDate:
description: |
The effective start date of the product charge definition.
format: date-time
type: string
listPriceBase:
description: |
The list price base.
This field is applicable only for recurring charges.
**Note**: The `Per_Year` enum value is available only if you have the Annual List Price feature enabled.
enum:
- Per_Billing_Period
- Per_Month
- Per_Week
- Per_Year
type: string
prices:
description: |
Container for the prices of the product charge definition.
items:
$ref: '#/components/schemas/POSTProductChargeDefinitionPricing'
type: array
productRatePlanChargeId:
description: |
The unique ID of the charge of the charge definition.
type: string
productRatePlanChargeNumber:
description: |
The unique number (natural key) of the charge of the charge definition.
type: string
productRatePlanId:
description: |
The unique ID of the product rate plan that uses this charge definition.
type: string
productRatePlanNumber:
description: |
The unique number (natural key) of the product rate plan that uses this charge definition.
type: string
specificBillingPeriod:
description: |
The specific number of billing periods for the product charge definition.
type: number
nullable: true
specificListPriceBase:
description: |
The number of months for the list price base of the charge definition.
This field is `null` if the `listPriceBase` field is not set to `Per_Specific_Months`.
format: int32
maximum: 200
minimum: 1
type: integer
nullable: true
taxCode:
description: |
Specifies the tax code for taxation rules. This field is required when the `Taxable` field is set to `True`.
**Note**: This value affects the tax calculation of the charge.
maxLength: 64
type: string
taxMode:
description: |
Determines how to define taxation for the charge. This field is required when the `Taxable` field is set to `True`.
**Note**: This value affects the tax calculation of the charge.
enum:
- TaxExclusive
- TaxInclusive
- null
type: string
nullable: true
taxable:
description: |
Determines whether the charge definition is taxable. When this field is set to `True`, the `TaxMode` and `TaxCode` fields are required.
**Character limit**: 5
**Values**: `True`, `False`
**Note**: This value affects the tax calculation of the charge.
type: boolean
term:
description: |
The number of periods of a termed subscription that is eligible for this charge definition. This field is applicable when the `termType` field is set to `TERMED`,
and is to be used together with the `termPeriodType` field.
type: number
nullable: true
termPeriodType:
description: |
Specifies the period type for the subscription term that is eligible for this charge definition.
enum:
- Month
- Year
- Day
- Week
- null
type: string
nullable: true
termType:
description: |
The type of the subscription that is eligible for this charge definition.
enum:
- TERMED
- EVERGREEN
- null
type: string
nullable: true
uom:
description: |
Describes the unit of measure (UOM) configured in **Settings > Billing** for the charge.
type: string
nullable: true
title: productChargeDefinitions
type: object
POSTChargeDefinitionResponse:
properties:
chargeDefinitionId:
description: |
The unique ID of the product charge definition.
type: string
chargeDefinitionNumber:
description: |
The unique number (natural key) of the product charge definition.
type: string
success:
description: |
Indicates whether the request succeeded.
type: boolean
type: object
POSTProductChargeDefinitionPricing:
properties:
currency:
description: |
The currency for the price.
type: string
discountAmount:
description: |
The specific amount for a fixed discount. The field is applicable only for charges based on the Discount-Fixed Amount charge model.
format: double
type: number
discountPercentage:
description: |
The percentage of discount for a percentage discount. The field is applicable only for charges based on the Discount-Percentage charge model.
format: double
type: number
price:
description: |
The price of this item.
This field is only applicable for charges based on the following charge models:
- Flat Fee
- Per Unit
- Delivery Pricing
type: number
tiers:
description: |
Container for the tiers of the price item.
This field is only applicable for charges based on the following charge models:
- Tiered Pricing
- Volume Pricing
You must specify all relevant fields of all tiers, including pricing information for each currency.
For each currency, ensure that the tiers appear in ascending order of `StartingUnit`.
For example:
```
[
{
"startingUnit": "1",
"endingUnit": "150",
"currency": "USD",
"price": 1.95,
"priceFormat": "Per Unit"
},
{
"startingUnit": "151",
"endingUnit": "300",
"currency": "USD",
"price": 1.45,
"priceFormat": "Per Unit"
},
{
"startingUnit": "1",
"endingUnit": "150",
"currency": "EUR",
"price": 1.75,
"priceFormat": "Per Unit"
},
{
"startingUnit": "151",
"endingUnit": "300",
"currency": "EUR",
"price": 1.30,
"priceFormat": "Per Unit"
}
]
```
items:
$ref: '#/components/schemas/POSTChargeDefinitionPricingTier'
type: array
title: prices
type: object
POSTChargeDefinitionPricingTier:
description: |
An array of charge pricing tier.
items:
properties:
currency:
description: |
The code corresponding to the currency for the tier's price.
type: string
endingUnit:
description: |
The end number of a range of units for the tier. This field is required for charges based on the Tiered Pricing or Tiered with Overage Pricing charge model.
format: double
type: number
price:
description: |
The price of the tier if the price format is flat fee, or the price of each unit in the tier if the price format is per unit.
format: double
type: number
priceFormat:
description: |
The price format of the tier.
enum:
- Flat Fee
- Per Unit
type: string
startingUnit:
description: |
The starting number of a range of units for the tier. This field is required for charges based on the Tiered Pricing or Tiered with Overage Pricing charge model.
format: double
type: number
type: object
title: pricingTiers
type: array
GETProductChargeDefinitionsResponse:
properties:
chargeDefinitions:
description: |
The list of the product charge definitions that are retrieved.
items:
properties:
applyDiscountTo:
description: |
Indicates which type of charge the discount charge applies to.
enum:
- ONETIME
- RECURRING
- USAGE
- ONETIMERECURRING
- ONETIMEUSAGE
- RECURRINGUSAGE
- ONETIMERECURRINGUSAGE
- null
type: string
nullable: true
billingDay:
description: |
The bill cycle type for the charge.
type: string
billingPeriod:
description: |
The billing period for the product charge definition.
type: string
billingPeriodAlignment:
description: |
The billing period alignment setting for the charge.
enum:
- AlignToCharge
- AlignToSubscriptionStart
- AlignToTermStart
- AlignToTermEnd
type: string
billingTiming:
description: |
The billing timing setting for the product charge definition.
enum:
- IN_ADVANCE
- IN_ARREARS
type: string
chargeModel:
description: |
Determines how to calculate charges. Charge models must be individually activated in Zuora Billing administration.
enum:
- DiscountFixedAmount
- DiscountPercentage
- FlatFee
- PerUnit
- Overage
- Tiered
- TieredWithOverage
- Volume
- Delivery
- MultiAttributePricing
- PreratedPerUnit
- PreratedPricing
- HighWatermarkVolumePricing
- HighWatermarkTieredPricing
type: string
chargeType:
description: |
Indicates the type of charge.
enum:
- OneTime
- Recurring
- Usage
type: string
customFields:
$ref: '#/components/schemas/ProductChargeDefinitionObjectCustomFields'
defaultQuantity:
description: |
The default quantity.
This field is applicable only for one-time and recurring charges.
type: number
nullable: true
deliverySchedule:
$ref: '#/components/schemas/GETDeliverySchedule'
description:
description: |
The description for the charge.
type: string
discountClass:
description: |
The class that the discount belongs to. The discount class defines the order in which discount product rate plan charges are applied.
For more information, see [Manage Discount Classes](https://knowledgecenter.zuora.com/BC_Subscription_Management/Product_Catalog/B_Charge_Models/Manage_Discount_Classes).
type: string
nullable: true
discountLevel:
description: |
The application scope of the discount charge. For example, if the value of this field is `subscription` and the value of the `applyDiscountTo` field is `RECURRING`, the discount charge applies to all recurring charges in the same subscription as the discount charge.
enum:
- rateplan
- subscription
- account
- null
type: string
nullable: true
effectiveEndDate:
description: |
The effective end date of the product charge definition.
format: date-time
type: string
effectiveStartDate:
description: |
The effective start date of the product charge definition.
format: date-time
type: string
endDateCondition:
description: |
The end date condition for this charge.
enum:
- Subscription_End
- One_Time
- Fixed_Period
- Specific_End_Date
type: string
excludeItemBillingFromRevenueAccounting:
type: boolean
description: |
Indicates whether to exclude the related invoice items, invoice item adjustments, credit memo items, and debit memo items from revenue accounting.
**Note**: This field is only available if you have the Order to Revenue or Billing - Revenue Integration feature enabled.
excludeItemBookingFromRevenueAccounting:
type: boolean
description: |
Indicates whether to exclude the related rate plan charges and order line items from revenue accounting.
**Note**: This field is only available if you have the Order to Revenue or Billing - Revenue Integration feature enabled.
isAllocationEligible:
type: boolean
description: |
Indicates whether the charge segment is allocation eligible in revenue recognition. The default value is `false`.
**Values**: `true`, `false`
**Note**: The field is only available if you have the Order to Revenue feature enabled. To enable this field, submit a request at Zuora Global Support.
isUnbilled:
type: boolean
description: |
Specifies how to perform the accounting during revenue recognition. The default value is `false`.
**Values**: `true`, `false`
**Note**: The field is only available if you have the Order to Revenue feature enabled. To enable this field, submit a request at Zuora Global Support.
productCategory:
type: string
description: |
This field is used to maintain the product category for integration with Zuora Revenue.
**Note**: This field is available only if you have the Additional Revenue Fields property enabled.
productClass:
type: string
description: |
This field is used to maintain the product class for integration with Zuora Revenue.
**Note**: This field is available only if you have the Additional Revenue Fields property enabled.
productFamily:
type: string
description: |
This field is used to maintain the product family for integration with Zuora Revenue.
**Note**: This field is available only if you have the Additional Revenue Fields property enabled.
productLine:
type: string
description: |
This field is used to maintain the product line for integration with Zuora Revenue.
**Note**: This field is available only if you have the Additional Revenue Fields property enabled.
revenueRecognitionTiming:
description: |
Specifies the type of revenue recognition timing.
Predefined options are listed as enum values in this API Reference.
Other options might also be avaliable depending on
the revenue recognition policy configuration in the Zuora Billing UI.
**Note**: This field is only available if you have the Order to Revenue feature enabled.
maxLength: 200
type: string
enum:
- Upon Billing Document Posting Date
- Upon Order Activation Date
revenueAmortizationMethod:
description: |
Specifies the type of revenue amortization method.
Predefined options are listed as enum values in this API Reference.
Other options might also be avaliable depending on
the revenue recognition policy configuration in the Zuora Billing UI.
**Note**: This field is only available if you have the Order to Revenue feature enabled.
maxLength: 200
type: string
enum:
- Immediate
- Ratable Using Start And End Dates
numberOfPeriods:
description: |
Specifies the number of periods to use when calculating charges in an overage smoothing charge model.
This field is ued when overage smoothing model is `RollingWindow` or `Rollover`.
format: int64
type: integer
nullable: true
financeInformation:
description: |
Container for finance information of the rate plan charge.
properties:
accountsReceivableAccountingCode:
description: |
The accounting code for accounts receivable.
type: string
nullable: true
accountsReceivableAccountingCodeType:
description: |
The type of the accounting code for accounts receivable.
type: string
nullable: true
adjustmentLiabilityAccountingCode:
description: |
The accounting code for adjustment liability.
**Note**: This field is only available if you have the Zuora Billing - Revenue Integration feature enabled.
type: string
adjustmentLiabilityAccountingCodeType:
description: |
The type associated with the adjustment liability accounting code.
**Note**: This field is only available if you have the Zuora Billing - Revenue Integration feature enabled.
type: string
nullable: true
adjustmentRevenueAccountingCode:
description: |
The accounting code for adjustment revenue.
**Note**: This field is only available if you have the Zuora Billing - Revenue Integration feature enabled.
type: string
adjustmentRevenueAccountingCodeType:
description: |
The type associated with the adjustment revenue accounting code.
**Note**: This field is only available if you have the Zuora Billing - Revenue Integration feature enabled.
type: string
nullable: true
contractAssetAccountingCode:
description: |
The accounting code for contract asset.
**Note**: This field is only available if you have the Zuora Billing - Revenue Integration feature enabled.
type: string
contractAssetAccountingCodeType:
description: |
The type associated with the contract asset accounting code.
**Note**: This field is only available if you have the Zuora Billing - Revenue Integration feature enabled.
type: string
contractLiabilityAccountingCode:
description: |
The accounting code for contract liability.
**Note**: This field is only available if you have the Zuora Billing - Revenue Integration feature enabled.
type: string
contractLiabilityAccountingCodeType:
description: |
The type associated with the contract liability accounting code.
**Note**: This field is only available if you have the Zuora Billing - Revenue Integration feature enabled.
type: string
contractRecognizedRevenueAccountingCode:
description: |
The accounting code for contract recognized revenue.
**Note**: This field is only available if you have the Zuora Billing - Revenue Integration feature enabled.
type: string
contractRecognizedRevenueAccountingCodeType:
description: |
The type associated with the contract recognized revenue accounting code.
**Note**: This field is only available if you have the Zuora Billing - Revenue Integration feature enabled.
type: string
deferredRevenueAccountingCode:
description: |
The accounting code for deferred revenue, such as Monthly Recurring Liability.
type: string
deferredRevenueAccountingCodeType:
description: |
The type associated with the deferred revenue accounting code, such as Deferred Revenue.
type: string
nullable: true
recognizedRevenueAccountingCode:
description: |
The accounting code for recognized revenue, such as Monthly Recurring Charges or Overage Charges.
type: string
recognizedRevenueAccountingCodeType:
description: |
The type associated with the recognized revenue accounting code, such as Sales Revenue or Sales Discount.
type: string
nullable: true
unbilledReceivablesAccountingCode:
description: |
The accounting code for unbilled receivables.
**Note**: This field is only available if you have the Zuora Billing - Revenue Integration feature enabled.
type: string
unbilledReceivablesAccountingCodeType:
description: |
The type associated with the unbilled receivables accounting code.
**Note**: This field is only available if you have the Zuora Billing - Revenue Integration feature enabled.
type: string
title: financeInformation
type: object
isDefault:
description: |
Indicates whether this charge definition is the default one for the charge.
type: boolean
isStackedDiscount:
description: |
**Note**: This field is only applicable to the Discount - Percentage charge model.
To use this field, you must set the `X-Zuora-WSDL-Version` request header to 130 or higher. Otherwise, an error occurs.
This field indicates whether the discount is to be calculated as stacked discount. Possible values are as follows:
- `True`: This is a stacked discount, which should be calculated by stacking with other discounts.
- `False`: This is not a stacked discount, which should be calculated in sequence with other discounts.
For more information, see [Stacked discounts](https://knowledgecenter.zuora.com/Zuora_Billing/Products/Product_Catalog/B_Charge_Models/B_Discount_Charge_Models).
type: boolean
listPriceBase:
description: |
The list price base.
This field is applicable only for recurring charges.
**Note**: The `Per_Year` enum value is available only if you have the Annual List Price feature enabled.
enum:
- Per_Billing_Period
- Per_Month
- Per_Week
- Per_Year
type: string
numberOfPeriod:
description: |
Indicates the number of periods to use when calculating charges in an overage smoothing charge model. The valid value is a positive whole number.
format: int64
type: integer
overageCalculationOption:
description: |
Determines when to calculate overage charges. If the value of the `SmoothingMode` field is not specified, the value of this field is ignored.
**Values**:
- `EndOfSmoothingPeriod`: This option is used by default. The overage is charged at the end of the smoothing period.
- `PerBillingPeriod`: The overage is charged on-demand rather than waiting until the end of the smoothing period.
enum:
- EndOfSmoothingPeriod
- PerBillingPeriod
- null
type: string
nullable: true
overageUnusedUnitsCreditOption:
description: |
Determines whether to credit the customer with unused units of usage.
enum:
- NoCredit
- CreditBySpecificRate
- null
type: string
nullable: true
priceChangeOption:
default: NoChange
description: |
Applies an automatic price change when a termed subscription is renewed.
enum:
- NoChange
- SpecificPercentageValue
- UseLatestProductCatalogPricing
- null
type: string
nullable: true
priceIncreaseOption:
description: |
Applies an automatic price change when a termed subscription is renewed.
enum:
- FromTenantPercentageValue
- SpecificPercentageValue
type: string
priceIncreasePercentage:
description: |
Specifies the percentage to increase or decrease the price of a termed subscription's renewal. Use this field if you set the `priceIncreaseOption` value to `SpecificPercentageValue`.
**Character limit**: 16
**Values**: a decimal value between -100 and 100
format: double
type: number
nullable: true
prices:
description: |
Container for the prices of the product charge definition.
items:
$ref: '#/components/schemas/GETProductChargeDefinitionPricing'
type: array
productChargeDefinitionId:
description: |
The unique ID of the product charge definition.
type: string
productChargeDefinitionNumber:
description: |
The unique number (natural key) of the product charge definition.
type: string
productDiscountApplyDetails:
description: |
Container for the application details about a discount product rate plan charge.
Only discount product rate plan charges have values for this field.
items:
$ref: '#/components/schemas/GETProductDiscountApplyDetailsType'
type: array
productRatePlanChargeId:
description: |
The unique ID of the product charge of the charge definition.
type: string
productRatePlanChargeNumber:
description: |
The unique number (natural key) of the product charge of the charge definition.
type: string
nullable: true
productRatePlanId:
description: |
The unique ID of the product rate plan that uses this charge definition.
type: string
nullable: true
productRatePlanName:
description: |
Th name of the product rate plan that uses this charge definition.
type: string
nullable: true
productRatePlanNumber:
description: |
The unique number (natural key) of the product rate plan that uses this charge definition.
type: string
nullable: true
ratingGroup:
default: ByBillingPeriod
description: |
The rating group based on which usage records are rated.
Possible values:
- `ByBillingPeriod`: The rating is based on all the usages in a billing period.
- `ByUsageStartDate`: The rating is based on all the usages on the same usage start date.
- `ByUsageRecord`: The rating is based on each usage record.
- `ByUsageUpload`: The rating is based on all the usages in a uploaded usage file (`.xls` or `.csv`).
- `ByGroupId`: The rating is based on all the usages in a custom group.
**Notes:**
- The `ByBillingPeriod` value can be applied for all charge models.
- The `ByUsageStartDate`, `ByUsageRecord`, and `ByUsageUpload` values can only be applied for Per Unit, Volume Pricing, and Tiered Pricing charge models.
- The `ByGroupId` value is only available if you have the Active Rating feature enabled.
- Use this field only for Usage charges. One-time charges and recurring charges return `NULL`.
enum:
- ByBillingPeriod
- ByUsageStartDate
- ByUsageRecord
- ByUsageUpload
- ByGroupId
- null
type: string
nullable: true
recognizedRevenueAccount:
description: |
The name of the recognized revenue account for this charge.
- Required when the Allow Blank Accounting Code setting is No.
- Optional when the Allow Blank Accounting Code setting is Yes.
This feature is in **Limited Availability**. If you wish to have access to the feature, submit a request at [Zuora Global Support](http://support.zuora.com/).
maxLength: 100
type: string
revRecCode:
description: |
Associates this product rate plan charge with a specific revenue recognition code.
maxLength: 70
type: string
nullable: true
revRecTriggerCondition:
description: |
Indicates when revenue recognition begins.
enum:
- ContractEffectiveDate
- ServiceActivationDate
- CustomerAcceptanceDate
- null
type: string
nullable: true
revenueRecognitionRuleName:
description: |
Determines when to recognize the revenue for this charge.
enum:
- Recognize upon invoicing
- Recognize daily over time
type: string
smoothingModel:
description: |
Indicates the smoothing model for an overage smoothing charge model.
enum:
- RollingWindow
- Rollover
- null
type: string
nullable: true
specificBillingPeriod:
description: |
The specific number of billing period for the product charge definition.
type: number
nullable: true
specificListPriceBase:
description: |
The number of months for the list price base of the charge definition.
This field is `null` if the `listPriceBase` field is not set to `Per_Specific_Months`.
format: int32
maximum: 200
minimum: 1
type: integer
nullable: true
taxCode:
description: |
Specifies the tax code for taxation rules.
**Note**: This value affects the tax calculation of the rate plan charge.
maxLength: 64
type: string
taxMode:
description: |
Determines how to define taxation for the charge.
**Note**: This value affects the tax calculation of the rate plan charge.
enum:
- TaxExclusive
- TaxInclusive
- null
type: string
nullable: true
taxable:
description: |
Determines whether the charge definition is taxable.
**Character limit**: 5
**Values**: `true`, `false`
**Note**: This value affects the tax calculation of the rate plan charge.
type: boolean
term:
description: |
The number of periods of a termed subscription that is eligible for this charge definition. This field is applicable when the `termType` field is set to `TERMED`,
and is to be used together with the `termPeriodType` field.
type: number
nullable: true
termPeriodType:
description: |
The period type for the subscription term that is eligible for this charge definition.
enum:
- Month
- Year
- Day
- Week
- null
type: string
nullable: true
termType:
description: |
The type of the subscription that is eligible for this charge definition.
enum:
- TERMED
- EVERGREEN
- null
type: string
nullable: true
triggerEvent:
description: |
Specifies when to start billing the customer for the charge definition.
**Values**:
- `ContractEffective` is the date when the subscription's contract goes into effect and the charge is ready to be billed.
- `ServiceActivation` is the date when the services or products for a subscription have been activated and the customers have access.
- `CustomerAcceptance` is when the customer accepts the services or products for a subscription.
enum:
- ContractEffective
- ServiceActivation
- CustomerAcceptance
type: string
uom:
description: |
Indicates the unit of measure (UOM) that is configured in **Settings > Billing** for the product rate plan charge.
type: string
nullable: true
upToPeriods:
description: |
The number of up-to periods for this charge.
type: number
nullable: true
upToPeriodsType:
description: |
The up-to-periods type for this charge.
enum:
- Billing_Periods
- Days
- Weeks
- Months
- Years
- null
type: string
nullable: true
usageRecordRatingOption:
default: EndOfBillingPeriod
description: |
Determines how Zuora processes usage records for per-unit usage charges.
enum:
- EndOfBillingPeriod
- OnDemand
- null
type: string
nullable: true
useDiscountSpecificAccountingCode:
description: |
Determines whether to define a new accounting code for the new discount charge.
**Character limit**: 5
**Values**: `true`, `false`
type: boolean
nullable: true
useTenantDefaultForPriceChange:
description: |
Applies the tenant-level percentage uplift value for an automatic price change to a termed subscription's renewal.
**Character limit**: 5
**Values**: `true`, `false`
type: boolean
title: chargeDefinitions
type: object
type: array
success:
description: |
Indicates whether the request succeeded.
type: boolean
type: object
ProductChargeDefinitionObjectCustomFields:
additionalProperties:
description: |
Custom fields of the Product Charge Definition object. The name of each custom field has the form of *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
description: |
Container for custom fields of a Product Charge Definition object.
title: productChargeDefinitionFieldsCustom
type: object
GETProductChargeDefinitionPricing:
properties:
currency:
description: |
The currency for the price.
type: string
discountAmount:
description: |
The specific amount for a fixed discount. The field is applicable only for charges based on the Discount-Fixed Amount charge model.
format: double
type: number
discountPercentage:
description: |
The percentage of discount for a percentage discount. The field is applicable only for charges based on the Discount-Percentage charge model.
format: double
type: number
includedUnits:
description: |
The number of units included in this price item.
This field is only applicable for charges based on the Overage Pricing charge model.
type: number
overagePrice:
description: |
The overage price of the price item.
This field is only applicable for charges based on the Overage Pricing or Tiered with Overage Pricing charge model.
type: number
price:
description: |
The price of this item.
This field is only applicable for charges based on the following charge models:
- Flat Fee
- Per Unit
- Delivery Pricing
type: number
tiers:
description: |
Container for the tiers of the price item.
This field is only applicable for charges based on the following charge models:
- Tiered Pricing
- Volume Pricing
- Tiered with Overage Pricing
items:
$ref: '#/components/schemas/GETChargeDefinitionPricingTier'
type: array
title: prices
type: object
GETChargeDefinitionPricingTier:
description: |
An array of charge pricing tiers.
items:
properties:
currency:
description: |
The code corresponding to the currency for the tier's price.
type: string
discountAmount:
description: |
The specific amount for a fixed discount. The field is applicable only for charges based on the Discount-Fixed Amount charge model.
format: double
type: number
discountPercentage:
description: |
The percentage of discount for a percentage discount. The field is applicable only for charges based on the Discount-Percentage charge model.
format: double
type: number
endingUnit:
description: |
The end number of a range of units for the tier. The field is applicable only for charges based on the Tiered Pricing or Tiered with Overage Pricing charge model.
format: double
type: number
overagePrice:
description: |
Indicates whether the price is an overage price, which is the price when usage surpasses the last defined tier.
format: double
type: number
price:
description: |
The price of the tier if the price format is flat fee, or the price of each unit in the tier if the price format is per unit.
format: double
type: number
startingUnit:
description: |
The starting number of a range of units for the tier. The field is applicable only for charges based on the Tiered Pricing or Tiered with Overage Pricing charge model.
format: double
type: number
type: object
title: pricingTiers
type: array
POSTChargeDefinitionRequestBulk:
example:
productChargeDefinitions:
- productRatePlanChargeId: edcab92612893256dce329d0b377000e
effectiveStartDate: '2024-01-01 00:00:00'
effectiveEndDate: '2025-01-01 00:00:00'
listPriceBase: Per_Billing_Period
prices:
- currency: USD
price: 18
properties:
productChargeDefinitions:
description: |
Container for the array of product charge definition.
items:
$ref: '#/components/schemas/POSTChargeDefinitionRequest'
type: array
type: object
POSTChargeDefinitionBulkResponse:
type: object
properties:
summary:
description: |
Summary of the results of the bulk operation.
type: object
properties:
successCount:
description: |
The number of product charge definitions successfully created.
type: integer
failureCount:
description: |
The number of product charge definitions that are not created.
type: integer
failures:
description: |
An array containing the index of each failed charge definition.
Each index is zero-based, and refers to the position of the invalid product charge definition in the bulk payload.
type: array
items:
type: integer
additionalProperties: false
results:
description: |
The list of newly created product charge definitions or errors.
type: array
items:
type: object
properties:
success:
type: boolean
description: Indicates whether the charge definition is successfully created.
chargeDefinitionId:
description: |
The unique ID of the product charge definition.
This value is available only if this product charge definition is successfully created.
type: string
chargeDefinitionNumber:
description: |
The unique number (natural key) of the product charge definition.
This value is available only if this product charge definition is successfully created.
type: string
processId:
description: |
The ID of the process that handles the operation.
This value is available only if this product charge definition is not created.
type: string
reasons:
description: |
Array of data containing the error code and reasons for failure.
This value is available only if this product charge definition is not created.
type: array
items:
type: object
properties:
message:
type: string
description: Message explaining the reason for the error.
code:
type: string
description: Specifies the error code associated with the error.
example: '400'
additionalProperties: false
success:
description: |
Indicates whether the request succeeded.
type: boolean
additionalProperties: false
PUTProductChargeDefinitionBulkRequest:
example:
productChargeDefinitions:
- productChargeDefinitionKey: CD-00052014
prices:
- currency: USD
price: 22
properties:
productChargeDefinitions:
description: |
The list of updated product charge definitions.
items:
$ref: '#/components/schemas/PUTBulkProductChargeDefinitionRequest'
type: array
type: object
PUTBulkProductChargeDefinitionRequest:
properties:
billingPeriod:
description: |
The override value of the billingPeriod for the product charge definition.
type: string
billingTiming:
description: |
The override value of the billingTiming for the product charge definition.
enum:
- IN_ADVANCE
- IN_ARREARS
type: string
chargeModel:
description: |
Determines how to calculate charges. Charge models must be individually activated in Zuora Billing administration.
enum:
- DiscountFixedAmount
- DiscountPercentage
- FlatFee
- PerUnit
- Tiered
- Volume
- Delivery
type: string
defaultQuantity:
description: |
The default quantity.
This field is applicable only for one-time and recurring charges.
type: number
listPriceBase:
description: |
The list price base.
This field is applicable only for recurring charges.
**Note**: The `Per_Year` enum value is available only if you have the Annual List Price feature enabled.
enum:
- Per_Billing_Period
- Per_Month
- Per_Week
- Per_Year
type: string
prices:
description: |
Container for the new prices to override the existing prices of the product charge definition.
items:
$ref: '#/components/schemas/POSTProductChargeDefinitionPricing'
type: array
productChargeDefinitionKey:
description: |
The unique number or ID of the product charge definition to be updated.
type: string
specificBillingPeriod:
description: |
The override value of the specificBillingPeriod for the product charge definition.
type: number
nullable: true
specificListPriceBase:
description: |
The number of months for the list price base of the charge definition.
The field is `null` if the `listPriceBase` field is not set to `Per_Specific_Months`.
format: int32
maximum: 200
minimum: 1
type: integer
nullable: true
taxCode:
description: |
Specifies the tax code for taxation rules. This field is equired when the `Taxable` field is set to `True`.
**Note**: This value affects the tax calculation of the charge.
maxLength: 64
type: string
taxMode:
description: |
Determines how to define taxation for the charge. This field is equired when the `taxable` field is set to `true`.
**Note**: This value affects the tax calculation of the charge.
enum:
- TaxExclusive
- TaxInclusive
- null
type: string
nullable: true
taxable:
description: |
Determines whether the charge definition is taxable. When this field is set to `true`, the `taxMode` and `taxCode` fields are required.
**Character limit**: 5
**Values**: `true`, `false`
**Note**: This value affects the tax calculation of the charge.
type: boolean
term:
description: |
The number of periods of a termed subscription that is eligible for this charge definition. This field is applicable when the `termType` field is set to `TERMED`,
and is to be used together with the `termPeriodType` field.
type: number
nullable: true
termPeriodType:
description: |
Specifies the period type for the subscription term that is eligible for this charge definition.
enum:
- Month
- Year
- Day
- Week
- null
type: string
nullable: true
termType:
description: |
The type of the subscription that is eligible for this charge definition.
enum:
- TERMED
- EVERGREEN
- null
type: string
nullable: true
uom:
description: |
Describes the unit of measure (UOM) configured in **Settings > Billing**.
**Values**: `Each`, `License`, `Seat`, or `null`
type: string
nullable: true
type: object
GETProductChargeDefinitionResponse:
properties:
applyDiscountTo:
description: |
Indicates which type of charge the discount charge applies to.
enum:
- ONETIME
- RECURRING
- USAGE
- ONETIMERECURRING
- ONETIMEUSAGE
- RECURRINGUSAGE
- ONETIMERECURRINGUSAGE
- null
type: string
nullable: true
billingDay:
description: |
The bill cycle type for the charge.
type: string
billingPeriod:
description: |
The billing period for the product charge definition.
type: string
billingPeriodAlignment:
description: |
The billing period alignment setting for the charge.
enum:
- AlignToCharge
- AlignToSubscriptionStart
- AlignToTermStart
- AlignToTermEnd
type: string
billingTiming:
description: |
The billing timing setting for the product charge definition.
enum:
- IN_ADVANCE
- IN_ARREARS
type: string
chargeModel:
description: |
Determines how to calculate charges. Charge models must be individually activated in Zuora Billing administration.
enum:
- DiscountFixedAmount
- DiscountPercentage
- FlatFee
- PerUnit
- Overage
- Tiered
- TieredWithOverage
- Volume
- Delivery
- MultiAttributePricing
- PreratedPerUnit
- PreratedPricing
- HighWatermarkVolumePricing
- HighWatermarkTieredPricing
type: string
chargeType:
description: |
Indicates the type of charge.
enum:
- OneTime
- Recurring
- Usage
type: string
customFields:
$ref: '#/components/schemas/ProductChargeDefinitionObjectCustomFields'
defaultQuantity:
description: |
The default quantity.
This field is applicable only for one-time and recurring charges.
type: number
nullable: true
deliverySchedule:
$ref: '#/components/schemas/GETDeliverySchedule'
description:
description: |
The description for the charge.
type: string
discountClass:
description: |
The class that the discount belongs to. The discount class defines the order in which discount product rate plan charges are applied.
For more information, see [Manage Discount Classes](https://knowledgecenter.zuora.com/BC_Subscription_Management/Product_Catalog/B_Charge_Models/Manage_Discount_Classes).
type: string
nullable: true
discountLevel:
description: |
The application scope of the discount charge. For example, if the value of this field is `subscription` and the value of the `applyDiscountTo` field is `RECURRING`, the discount charge applies to all recurring charges in the same subscription as the discount charge.
enum:
- rateplan
- subscription
- account
- null
type: string
nullable: true
effectiveEndDate:
description: |
The effective end date of the product charge definition.
format: date-time
type: string
effectiveStartDate:
description: |
The effective start date of the product charge definition.
format: date-time
type: string
endDateCondition:
description: |
The end date condition for this charge.
enum:
- Subscription_End
- One_Time
- Fixed_Period
- Specific_End_Date
type: string
financeInformation:
description: |
Container for finance information of the rate plan charge.
properties:
accountsReceivableAccountingCode:
description: |
The accounting code for accounts receivable.
type: string
nullable: true
accountsReceivableAccountingCodeType:
description: |
The type of the accounting code for accounts receivable.
type: string
nullable: true
adjustmentLiabilityAccountingCode:
description: |
The accounting code for adjustment liability.
**Note**: This field is only available if you have the Zuora Billing - Revenue Integration feature enabled.
type: string
adjustmentLiabilityAccountingCodeType:
description: |
The type associated with the adjustment liability accounting code.
**Note**: This field is only available if you have the Zuora Billing - Revenue Integration feature enabled.
type: string
adjustmentRevenueAccountingCode:
description: |
The accounting code for adjustment revenue.
**Note**: This field is only available if you have the Zuora Billing - Revenue Integration feature enabled.
type: string
adjustmentRevenueAccountingCodeType:
description: |
The type associated with the adjustment revenue accounting code.
**Note**: This field is only available if you have the Zuora Billing - Revenue Integration feature enabled.
type: string
contractAssetAccountingCode:
description: |
The accounting code for contract asset.
**Note**: This field is only available if you have the Zuora Billing - Revenue Integration feature enabled.
type: string
contractAssetAccountingCodeType:
description: |
The type associated with the contract asset accounting code.
**Note**: This field is only available if you have the Zuora Billing - Revenue Integration feature enabled.
type: string
contractLiabilityAccountingCode:
description: |
The accounting code for contract liability.
**Note**: This field is only available if you have the Zuora Billing - Revenue Integration feature enabled.
type: string
contractLiabilityAccountingCodeType:
description: |
The type associated with the contract liability accounting code.
**Note**: This field is only available if you have the Zuora Billing - Revenue Integration feature enabled.
type: string
contractRecognizedRevenueAccountingCode:
description: |
The accounting code for contract recognized revenue.
**Note**: This field is only available if you have the Zuora Billing - Revenue Integration feature enabled.
type: string
contractRecognizedRevenueAccountingCodeType:
description: |
The type associated with the contract recognized revenue accounting code.
**Note**: This field is only available if you have the Zuora Billing - Revenue Integration feature enabled.
type: string
deferredRevenueAccountingCode:
description: |
The accounting code for deferred revenue, such as Monthly Recurring Liability.
type: string
deferredRevenueAccountingCodeType:
description: |
The type associated with the deferred revenue accounting code, such as Deferred Revenue.
type: string
nullable: true
recognizedRevenueAccountingCode:
description: |
The accounting code for recognized revenue, such as Monthly Recurring Charges or Overage Charges.
type: string
recognizedRevenueAccountingCodeType:
description: |
The type associated with the recognized revenue accounting code, such as Sales Revenue or Sales Discount.
type: string
nullable: true
unbilledReceivablesAccountingCode:
description: |
The accounting code for unbilled receivables.
**Note**: This field is only available if you have the Zuora Billing - Revenue Integration feature enabled.
type: string
unbilledReceivablesAccountingCodeType:
description: |
The type associated with the unbilled receivables accounting code.
**Note**: This field is only available if you have the Zuora Billing - Revenue Integration feature enabled.
type: string
title: financeInformation
type: object
isDefault:
description: |
Indicates whether this charge definition is the default one for the charge.
type: boolean
isStackedDiscount:
description: |
**Note**: This field is only applicable to the Discount - Percentage charge model.
To use this field, you must set the `X-Zuora-WSDL-Version` request header to 130 or higher. Otherwise, an error occurs.
This field indicates whether the discount is to be calculated as stacked discount. Possible values are as follows:
- `True`: This is a stacked discount, which should be calculated by stacking with other discounts.
- `False`: This is not a stacked discount, which should be calculated in sequence with other discounts.
For more information, see [Stacked discounts](https://knowledgecenter.zuora.com/Zuora_Billing/Products/Product_Catalog/B_Charge_Models/B_Discount_Charge_Models).
type: boolean
numberOfPeriods:
description: |
Specifies the number of periods to use when calculating charges in an overage smoothing charge model.
This field is ued when overage smoothing model is `RollingWindow` or `Rollover`.
format: int64
type: integer
nullable: true
listPriceBase:
description: |
The list price base.
This field is applicable only for recurring charges.
**Note**: The `Per_Year` enum value is available only if you have the Annual List Price feature enabled.
enum:
- Per_Billing_Period
- Per_Month
- Per_Week
- Per_Year
type: string
numberOfPeriod:
description: |
Indicates the number of periods to use when calculating charges in an overage smoothing charge model. The valid value is a positive whole number.
format: int64
type: integer
overageCalculationOption:
description: |
Determines when to calculate overage charges. If the value of the `SmoothingMode` field is not specified, the value of this field is ignored.
**Values**:
- `EndOfSmoothingPeriod`: This option is used by default. The overage is charged at the end of the smoothing period.
- `PerBillingPeriod`: The overage is charged on-demand rather than waiting until the end of the smoothing period.
enum:
- EndOfSmoothingPeriod
- PerBillingPeriod
- null
type: string
nullable: true
overageUnusedUnitsCreditOption:
description: |
Determines whether to credit the customer with unused units of usage.
enum:
- NoCredit
- CreditBySpecificRate
- null
type: string
nullable: true
priceChangeOption:
default: NoChange
description: |
Applies an automatic price change when a termed subscription is renewed.
enum:
- NoChange
- SpecificPercentageValue
- UseLatestProductCatalogPricing
- null
type: string
nullable: true
priceIncreaseOption:
description: |
Applies an automatic price change when a termed subscription is renewed.
enum:
- FromTenantPercentageValue
- SpecificPercentageValue
type: string
priceIncreasePercentage:
description: |
Specifies the percentage to increase or decrease the price of a termed subscription's renewal. Use this field if you set the `priceIncreaseOption` value to `SpecificPercentageValue`.
**Character limit**: 16
**Values**: a decimal value between -100 and 100
format: double
type: number
nullable: true
prices:
description: |
Container for the prices of the product charge definition.
items:
$ref: '#/components/schemas/GETProductChargeDefinitionPricing'
type: array
productChargeDefinitionId:
description: |
The unique ID of the product charge definition.
type: string
productChargeDefinitionNumber:
description: |
The unique number (natural key) of the product charge definition.
type: string
productDiscountApplyDetails:
description: |
Container for the application details about a discount product rate plan charge.
Only discount product rate plan charges have values for this field.
items:
$ref: '#/components/schemas/GETProductDiscountApplyDetailsType'
type: array
productRatePlanChargeId:
description: |
The unique ID of the product charge of the charge definition.
type: string
productRatePlanChargeNumber:
description: |
The unique number (natural key) of the product charge of the charge definition.
type: string
nullable: true
productRatePlanId:
description: |
The unique ID of the product rate plan that uses this charge definition.
type: string
nullable: true
productRatePlanName:
description: |
Th name of the product rate plan that uses this charge definition.
type: string
nullable: true
productRatePlanNumber:
description: |
The unique number (natural key) of the product rate plan that uses this charge definition.
type: string
nullable: true
ratingGroup:
default: ByBillingPeriod
description: |
The rating group based on which usage records are rated.
Possible values:
- `ByBillingPeriod`: The rating is based on all the usages in a billing period.
- `ByUsageStartDate`: The rating is based on all the usages on the same usage start date.
- `ByUsageRecord`: The rating is based on each usage record.
- `ByUsageUpload`: The rating is based on all the usages in a uploaded usage file (`.xls` or `.csv`).
- `ByGroupId`: The rating is based on all the usages in a custom group.
**Notes:**
- The `ByBillingPeriod` value can be applied for all charge models.
- The `ByUsageStartDate`, `ByUsageRecord`, and `ByUsageUpload` values can only be applied for Per Unit, Volume Pricing, and Tiered Pricing charge models.
- The `ByGroupId` value is only available if you have the Active Rating feature enabled.
- Use this field only for Usage charges. One-time charges and recurring charges return `NULL`.
enum:
- ByBillingPeriod
- ByUsageStartDate
- ByUsageRecord
- ByUsageUpload
- ByGroupId
- null
type: string
nullable: true
recognizedRevenueAccount:
description: |
The name of the recognized revenue account for this charge.
- Required when the Allow Blank Accounting Code setting is No.
- Optional when the Allow Blank Accounting Code setting is Yes.
This feature is in **Limited Availability**. If you wish to have access to the feature, submit a request at [Zuora Global Support](http://support.zuora.com/).
maxLength: 100
type: string
revRecCode:
description: |
Associates this product rate plan charge with a specific revenue recognition code.
maxLength: 70
type: string
nullable: true
revRecTriggerCondition:
description: |
Indicates when revenue recognition begins.
enum:
- ContractEffectiveDate
- ServiceActivationDate
- CustomerAcceptanceDate
- null
type: string
nullable: true
revenueRecognitionRuleName:
description: |
Determines when to recognize the revenue for this charge.
enum:
- Recognize upon invoicing
- Recognize daily over time
type: string
smoothingModel:
description: |
Indicates the smoothing model for an overage smoothing charge model.
enum:
- RollingWindow
- Rollover
- null
type: string
nullable: true
specificBillingPeriod:
description: |
The specific number of billing period for the product charge definition.
type: number
nullable: true
specificListPriceBase:
description: |
The number of months for the list price base of the charge definition.
This field is `null` if the `listPriceBase` field is not set to `Per_Specific_Months`.
format: int32
maximum: 200
minimum: 1
type: integer
nullable: true
success:
description: |
Indicates whether the request succeeded.
type: boolean
taxCode:
description: |
Specifies the tax code for taxation rules.
**Note**: This value affects the tax calculation of the rate plan charge.
maxLength: 64
type: string
taxMode:
description: |
Determines how to define taxation for the charge.
**Note**: This value affects the tax calculation of the rate plan charge.
enum:
- TaxExclusive
- TaxInclusive
- null
type: string
nullable: true
taxable:
description: |
Determines whether the charge definition is taxable.
**Character limit**: 5
**Values**: `True`, `False`
**Note**: This value affects the tax calculation of the rate plan charge.
type: boolean
term:
description: |
The number of periods of a termed subscription that is eligible for this charge definition. This field is applicable when the `termType` field is set to `TERMED`,
and is to be used together with the `termPeriodType` field.
type: number
nullable: true
termPeriodType:
description: |
The period type for the subscription term that is eligible for this charge definition.
enum:
- Month
- Year
- Day
- Week
- null
type: string
nullable: true
termType:
description: |
The type of the subscription that is eligible for this charge definition.
enum:
- TERMED
- EVERGREEN
- null
type: string
nullable: true
triggerEvent:
description: |
Specifies when to start billing the customer for the charge definition.
**Values**:
- `ContractEffective` is the date when the subscription's contract goes into effect and the charge is ready to be billed.
- `ServiceActivation` is the date when the services or products for a subscription have been activated and the customers have access.
- `CustomerAcceptance` is when the customer accepts the services or products for a subscription.
enum:
- ContractEffective
- ServiceActivation
- CustomerAcceptance
type: string
uom:
description: |
Indicates the unit of measure (UOM) that is configured in **Settings > Billing** for the product rate plan charge.
type: string
nullable: true
upToPeriods:
description: |
The number of up-to periods for this charge.
type: number
nullable: true
upToPeriodsType:
description: |
The up-to-periods type for this charge.
enum:
- Billing_Periods
- Days
- Weeks
- Months
- Years
- null
type: string
nullable: true
usageRecordRatingOption:
default: EndOfBillingPeriod
description: |
Determines how Zuora processes usage records for per-unit usage charges.
enum:
- EndOfBillingPeriod
- OnDemand
- null
type: string
nullable: true
useDiscountSpecificAccountingCode:
description: |
Determines whether to define a new accounting code for the new discount charge.
**Character limit**: 5
**Values**: `true`, `false`
type: boolean
nullable: true
useTenantDefaultForPriceChange:
description: |
Applies the tenant-level percentage uplift value for an automatic price change to a termed subscription's renewal.
**Character limit**: 5
**Values**: `true`, `false`
type: boolean
excludeItemBillingFromRevenueAccounting:
type: boolean
description: |
Indicates whether to exclude the related invoice items, invoice item adjustments, credit memo items, and debit memo items from revenue accounting.
**Note**: This field is only available if you have the Order to Revenue or Billing - Revenue Integration feature enabled.
excludeItemBookingFromRevenueAccounting:
type: boolean
description: |
Indicates whether to exclude the related rate plan charges and order line items from revenue accounting.
**Note**: This field is only available if you have the Order to Revenue or Billing - Revenue Integration feature enabled.
isAllocationEligible:
type: boolean
description: |
Indicates whether the charge segment is allocation eligible in revenue recognition. The default value is `false`.
**Values**: `true`, `false`
**Note**: The field is only available if you have the Order to Revenue feature enabled. To enable this field, submit a request at Zuora Global Support.
isUnbilled:
type: boolean
description: |
Specifies how to perform the accounting during revenue recognition. The default value is `false`.
**Values**: `true`, `false`
**Note**: The field is only available if you have the Order to Revenue feature enabled. To enable this field, submit a request at Zuora Global Support.
productCategory:
type: string
description: |
This field is used to maintain the product category for integration with Zuora Revenue.
**Note**: This field is available only if you have the Additional Revenue Fields property enabled.
productClass:
type: string
description: |
This field is used to maintain the product class for integration with Zuora Revenue.
**Note**: This field is available only if you have the Additional Revenue Fields property enabled.
productFamily:
type: string
description: |
This field is used to maintain the product family for integration with Zuora Revenue.
**Note**: This field is available only if you have the Additional Revenue Fields property enabled.
productLine:
type: string
description: |
This field is used to maintain the product line for integration with Zuora Revenue.
**Note**: This field is available only if you have the Additional Revenue Fields property enabled.
revenueRecognitionTiming:
description: |
Specifies the type of revenue recognition timing.
Predefined options are listed as enum values in this API Reference.
Other options might also be avaliable depending on
the revenue recognition policy configuration in the Zuora Billing UI.
**Note**: This field is only available if you have the Order to Revenue feature enabled.
maxLength: 200
type: string
enum:
- Upon Billing Document Posting Date
- Upon Order Activation Date
revenueAmortizationMethod:
description: |
Specifies the type of revenue amortization method.
Predefined options are listed as enum values in this API Reference.
Other options might also be avaliable depending on
the revenue recognition policy configuration in the Zuora Billing UI.
**Note**: This field is only available if you have the Order to Revenue feature enabled.
maxLength: 200
type: string
enum:
- Immediate
- Ratable Using Start And End Dates
type: object
PUTProductChargeDefinitionRequest:
example:
prices:
- currency: USD
price: 20
properties:
billingPeriod:
description: |
The override value of the billingPeriod for the product charge definition.
type: string
billingTiming:
description: |
The override value of the billingTiming for the product charge definition.
enum:
- IN_ADVANCE
- IN_ARREARS
type: string
chargeModel:
description: |
Determines how to calculate charges. Charge models must be individually activated in Zuora Billing administration.
enum:
- DiscountFixedAmount
- DiscountPercentage
- FlatFee
- PerUnit
- Tiered
- Volume
- Delivery
type: string
defaultQuantity:
description: |
The default quantity.
This field is applicable only for one-time and recurring charges.
type: number
nullable: true
effectiveEndDate:
description: |
The effective end date of the product charge definition.
format: date-time
type: string
effectiveStartDate:
description: |
The effective start date of the product charge definition.
format: date-time
type: string
listPriceBase:
description: |
The list price base.
This field is applicable only for recurring charges.
**Note**: The `Per_Year` enum value is available only if you have the Annual List Price feature enabled.
enum:
- Per_Billing_Period
- Per_Month
- Per_Week
- Per_Year
type: string
prices:
description: |
Container for the new prices to override the existing prices of the product charge definition.
items:
$ref: '#/components/schemas/POSTProductChargeDefinitionPricing'
type: array
specificBillingPeriod:
description: |
The override value of the specificBillingPeriod for the product charge definition.
type: number
nullable: true
specificListPriceBase:
description: |
The number of months for the list price base of the charge definition.
The field is `null` if the `listPriceBase` field is not set to `Per_Specific_Months`.
format: int32
maximum: 200
minimum: 1
type: integer
nullable: true
taxCode:
description: |
Specifies the tax code for taxation rules. This field is equired when the `Taxable` field is set to `True`.
**Note**: This value affects the tax calculation of the charge.
maxLength: 64
type: string
taxMode:
description: |
Determines how to define taxation for the charge. This field is equired when the `Taxable` field is set to `True`.
**Note**: This value affects the tax calculation of the charge.
enum:
- TaxExclusive
- TaxInclusive
- null
type: string
nullable: true
taxable:
description: |
Determines whether the charge definition is taxable. When this field is set to `True`, the `TaxMode` and `TaxCode` fields are required.
**Character limit**: 5
**Values**: `True`, `False`
**Note**: This value affects the tax calculation of the charge.
type: boolean
term:
description: |
The number of periods of a termed subscription that is eligible for this charge definition. This field is applicable when the `termType` field is set to `TERMED`,
and is to be used together with the `termPeriodType` field.
type: number
nullable: true
termPeriodType:
description: |
Specifies the period type for the subscription term that is eligible for this charge definition.
enum:
- Month
- Year
- Day
- Week
- null
type: string
nullable: true
termType:
description: |
The type of the subscription that is eligible for this charge definition.
enum:
- TERMED
- EVERGREEN
- null
type: string
nullable: true
uom:
description: |
Describes the unit of measure (UOM) configured in **Settings > Billing**.
**Values**: `Each`, `License`, `Seat`, or `null`
type: string
nullable: true
type: object
ProxyGetProductRatePlanChargeTier:
properties:
CreatedById:
description: |
The ID of the Zuora user who created the ProductRatePlanChargeTier object.
maxLength: 32
type: string
CreatedDate:
description: |
The date when the ProductRatePlanChargeTier object was created.
format: date-time
maxLength: 29
type: string
Currency:
description: |
The valid code corresponding to the currency for the tier's price.
maxLength: 3
type: string
EndingUnit:
description: |
The end number of a range of units for the tier.
**Character limit**: 16
**Values**: any positive decimal value
format: double
type: number
Id:
description: Object identifier.
type: string
Price:
description: |
The price of the tier if the charge is a flat fee, or the price of each unit in the tier if the charge model is tiered pricing.
**Character limit**: 16
**Values**: a valid currency value
format: double
type: number
PriceFormat:
description: |
Indicates if pricing is a flat fee or is per unit. This field is for tiered and volume pricing models only.
**Values**: `FlatFee`, `PerUnit`
**Note:** The values `Flat Fee` and `Per Unit` (with spaces) is valid for create or update calls.
maxLength: 8
type: string
StartingUnit:
description: |
The starting number of a range of units for the tier.
**Character limit**: 16
**Values**: any positive decimal value
format: double
type: number
Tier:
description: |
A unique number that identifies the tier that the price applies to.
**Character limit**: 20
**Values**: automatically generated
format: int32
type: integer
UpdatedById:
description: |
The ID of the user who last updated the product rate plan charge tier.
maxLength: 32
type: string
UpdatedDate:
description: |
The date when the product rate plan charge tier was last updated.
format: date-time
maxLength: 29
type: string
type: object
ProxyModifyProductRatePlanChargeTier:
example:
Price: 1.99
properties:
Price:
description: |
The price of the tier if the charge is a flat fee, or the price of each unit in the tier if the charge model is tiered pricing.
type: number
format: double
PriceFormat:
description: |
Indicates if pricing is a flat fee or is per unit. This field is for tiered and volume pricing models only.
**Note:** The values `Flat Fee` and `Per Unit` (with spaces) is valid for create or update calls.
enum:
- Flat Fee
- Per Unit
maxLength: 8
type: string
DiscountPercentage:
description: |
The percentage of discount for a percentage discount. This field is required if the value for `ProductRatePlanCharge.ChargeModel` is `Discount-Percentage`.
**Values:** A decimal value between -100 and 100, exclusive
minimum: -100
exclusiveMinimum: true
maximum: 100
exclusiveMaximum: true
type: number
format: double
DiscountAmount:
description: |
The specific amount for a fixed discount. This field is required if the value for `ProductRatePlanCharge.ChargeModel` is `Discount-Fixed Amount`.
**Values:** Any positive decimal value.
type: number
format: double
type: object
RevproAccountingCodes:
example:
adjustmentLiabilityAccount: adjustL-1
adjustmentRevenueAccount: adjustRev-1
contractAssetAccount: CA-2
contractLiabilityAccount: CL-2
productRatePlanChargeId: 2c92c0f962470b8101624b869fcd45fc
recognizedRevenueAccount: ContractRevRec-1
unbilledReceivablesAccount: unbilledR-1
properties:
adjustmentLiabilityAccount:
description: The name of the account where the Account Type is "Adjustment Liability".
maxLength: 100
type: string
adjustmentRevenueAccount:
description: The name of the account where the Account Type is "Adjustment Revenue".
maxLength: 100
type: string
contractAssetAccount:
description: The name of the account where the Account Type is "Contract Asset".
maxLength: 100
type: string
contractLiabilityAccount:
description: The name of the account where the Account Type is "Contract Liability".
maxLength: 100
type: string
productRatePlanChargeId:
description: The ID of your product rate plan charge.
type: string
recognizedRevenueAccount:
description: The name of the account where the Account Type is "Recognized Revenue".
maxLength: 100
type: string
unbilledReceivablesAccount:
description: The name of the account where the Account Type is "Unbilled Receivables".
maxLength: 100
type: string
required:
- productRatePlanChargeId
- contractAssetAccount
- contractLiabilityAccount
- unbilledReceivablesAccount
- adjustmentLiabilityAccount
- recognizedRevenueAccount
- adjustmentRevenueAccount
type: object
PUTRevproAccCodeResponse:
properties:
success:
description: ''
type: boolean
type: object
CreateChargeRequest:
type: object
required:
- charge
properties:
charge:
type: object
description: |
Product rate plan charge (PRPC) definition including pricing model, billing settings, trigger event,
and attribute-based rate cards for Dynamic Pricing.
required:
- charge_model
- charge_type
- name
- unit_of_measure
- bill_cycle
- trigger_event
- product_rate_plan_id
properties:
charge_model:
type: string
description: |
Charge model that determines how the charge is calculated.
enum:
- flat_fee
- per_unit
- overage
- volume
- tiered
- tiered_overage
- discount_fixed_amount
- discount_percentage
- custom_charge_model
- delivery
- minimum_commitment_true_up
- calculated
- high_water_mark_volume_pricing
- high_water_mark_tiered_pricing
- multi_attribute_pricing
- prerated_pricing
- prerated_per_unit
charge_type:
type: string
description: |
Charge category in the catalog.
enum:
- one_time
- recurring
- usage
description:
type: string
description: Human-readable description of the charge.
name:
type: string
description: Name of the charge as displayed in the product catalog.
unit_of_measure:
type: string
description: |
Unit of measure (UOM) used to quantify or price the charge (for example, Each, Seats, Licenses).
default_quantity:
type: number
format: double
description: Default quantity applied when the charge is added, if not specified elsewhere.
end_date_condition:
type: string
description: |
Condition that determines when the charge becomes inactive. Use `subscription_end` when the charge should remain active
until the subscription ends. Duration-based fields such as `up_to_periods` and `up_to_periods_type` do not apply when this value is used.
enum:
- end_date_one_time
- subscription_end
- fixed_period
- specific_end_date
up_to_periods_type:
type: string
description: |
Granularity used with `end_date_condition = fixed_period` to express how long the charge remains active. When `end_date_condition = subscription_end`, this field is ignored.
enum:
- billing_periods
- days
- weeks
- months
- years
example: billing_periods
up_to_periods:
type: integer
format: int32
description: |
Number of periods used with `end_date_condition = fixed_period`. Combined with `up_to_periods_type` to determine the fixed duration of the charge. Ignored when `end_date_condition = subscription_end`.
example: 0
bill_cycle:
type: object
description: |
Billing period configuration that controls frequency, alignment, and timing of billing for this charge.
required:
- period
- period_alignment
- type
properties:
type:
type: string
description: |
Determines how the billing day is selected for this charge.
enum:
- default_from_customer
- specific_day_of_month
- subscription_start_day
- charge_trigger_day
- specific_day_of_week
- term_start_day
- term_end_day
example: default_from_customer
period:
type: string
description: |
Length of each billing period.
enum:
- bill_cycle_period_month
- bill_cycle_period_quarter
- bill_cycle_period_semi_annual
- bill_cycle_period_annual
- bill_cycle_period_eighteen_months
- bill_cycle_period_two_years
- bill_cycle_period_three_years
- bill_cycle_period_five_years
- bill_cycle_period_specific_months
- bill_cycle_period_subscription_term
- bill_cycle_period_week
- bill_cycle_period_specific_weeks
- bill_cycle_period_specific_days
example: bill_cycle_period_month
period_alignment:
type: string
description: |
How the billing period start aligns.
enum:
- align_to_charge
- align_to_subscription_start
- align_to_term_start
- align_to_term_end
example: align_to_charge
timing:
type: string
description: |
When the charge is billed relative to the service period.
enum:
- in_advance
- in_arrears
example: in_advance
day_of_month:
type: integer
minimum: 1
maximum: 31
description: Required when `type` is `specific_day_of_month`.
day_of_week:
type: string
description: |
Used when `type` is `specific_day_of_week`.
enum:
- sunday
- monday
- tuesday
- wednesday
- thursday
- friday
- saturday
list_price_base:
type: string
description: |
List price basis for this charge. This is used when interpreting list prices and, for some models, in conjunction with `specific_list_price_base`.
enum:
- Per_Billing_Period
- Per_Month
- Per_Week
- Per_Year
- Per_Specific_Months
- Per_Validity_Period
example: Per_Billing_Period
specific_list_price_base:
type: number
format: double
description: |
Optional specific value used when `list_price_base` requires an explicit quantity (for example, number of months for `Per_Specific_Months`).
example: 0
trigger_event:
type: string
description: |
Event that makes the charge active on a subscription.
enum:
- contract_effective
- service_activation
- customer_acceptance
- specific_date
product_rate_plan_id:
type: string
description: Identifier of the product rate plan that owns this charge.
specificListPriceBase:
description: |
The number of months for the list price base of the charge. This field is required
if you set the value of the `ListPriceBase` field to `Per Specific Months`.
The value must be a positive integer between **1** and **120** inclusive.
**Notes**:
- This field is available only if you have the Annual List Price feature enabled.
- To use this field, you must set the `X-Zuora-WSDL-Version` request header to `129` or later. Otherwise, an error occurs.
- The value of this field is `null` if you do not set the value of the `ListPriceBase` field to `Per Specific Months`.
format: int32
maximum: 120
minimum: 1
example: 12
type: integer
nullable: true
formula:
type: string
description: Optional formula applied after rate-card lookup to adjust the computed price.
tax_mode:
type: string
description: |
Tax mode for this charge.
enum:
- non_taxable
- tax_exclusive
- tax_inclusive
tax_code:
type: string
description: Tax code used for tax calculation on this charge.
accounting:
$ref: '#/components/schemas/AccountingRequest'
revenue:
type: object
additionalProperties: true
description: |
Revenue recognition configuration, for example, `revenue_recognition_rule_name`, triggers, allocation flags.
custom_fields:
type: object
additionalProperties: true
description: Tenant custom fields on the charge.
attributes:
type: array
description: |
Declares the attribute metadata used by Dynamic Pricing for this charge.
Each entry defines an attribute that pricing rules can reference, along with
its data type and (optionally) a mapping to a Zuora object field used to resolve values at runtime.
Examples: Region, Age, EffectiveDate.
items:
type: object
required:
- name
properties:
name:
type: string
description: Attribute name, for example, Age, Region, EffectiveDate.
type:
type: string
description: Attribute data type.
enum:
- String
- Integer
- Double
- Boolean
- Date
- Datetime
mapping:
type: object
description: |
Optional mapping to a Zuora business object field used to automatically resolve
the attribute value at runtime.
required:
- object
- field
properties:
object:
type: string
description: Target Zuora object, for example, account, subscription.
field:
type: string
description: Field on the target object, for example, age__c.
pricing:
type: object
description: |
Default (charge-level) pricing for the PRPC, used when no rate-card row matches.
The structure depends on the charge_model:
- flat_fee → flat_amounts
- per_unit → unit_amounts
- volume/tiered → tiers
- discount_fixed_amount → discount_amounts
- discount_percentage → discount_percentage
oneOf:
- title: Flat Fee Pricing
type: object
required:
- flat_amounts
properties:
flat_amounts:
type: object
description: Map of currency to flat amount.
additionalProperties:
type: number
example:
USD: 100
- title: Per Unit Pricing
type: object
required:
- unit_amounts
properties:
unit_amounts:
type: object
description: Map of currency to per-unit price.
additionalProperties:
type: number
example:
USD: 2.5
- title: Tiered or Volume Pricing
type: object
required:
- tiers
properties:
tiers:
type: array
description: Tier definitions (volume or tiered) with optional min/max caps.
items:
type: object
required:
- tier
- from
- price_format
properties:
tier:
type: string
description: Tier identifier (e.g., "1", "2").
from:
type: number
description: Lower bound (inclusive).
up_to:
type: number
nullable: true
description: Upper bound (inclusive). Omit/null for open-ended last tier.
price_format:
type: string
description: For example, price_format_per_unit.
unit_amounts:
type: object
description: Per-unit price by currency for this tier.
additionalProperties:
type: number
example:
USD: 2.5
flat_amounts:
type: object
description: Flat amount by currency for this tier (if applicable).
additionalProperties:
type: number
example:
USD: 100
min_amounts:
type: object
description: Minimum billed amount by currency for this tier.
additionalProperties:
type: number
example:
USD: 6.25
max_amounts:
type: object
description: Maximum billed amount by currency for this tier.
additionalProperties:
type: number
example:
USD: 25
- title: Fixed Amount Discount
type: object
required:
- discount_amounts
properties:
discount_amounts:
type: object
description: Map of currency to discount amount.
additionalProperties:
type: number
example:
USD: 10
- title: Percentage Discount
type: object
required:
- discount_percentage
properties:
discount_percentage:
type: number
format: double
description: Discount percentage (e.g., 15 for 15%).
example: 15
rate_cards:
type: array
description: |
Defines the conditional pricing table (**rate cards**) for the PRPC.
Each rate-card entry specifies:
- `attributes`: The match conditions evaluated at runtime.
- `pricing`: The price or rate to apply when the conditions match.
If multiple rows match, Zuora applies the first matching rate card.
If no row matches, the default `pricing` (defined above) is used.
items:
type: object
required:
- attributes
- pricing
properties:
attributes:
type: array
minItems: 1
description: |
Defines the set of match conditions that must all evaluate to true
for this rate-card row to apply. Each condition corresponds to a declared
pricing attribute. Use `between` for range or date-based conditions.
items:
type: object
required:
- name
properties:
name:
type: string
description: Attribute name for the condition (for example, Age, Region, EffectiveDate).
operator:
type: string
description: Comparison operator for the condition.
enum:
- '>'
- '>='
- <
- <=
- '=='
- between
- between-inclusive
value:
description: |
Comparison value. For `between`, provide an array of two values.
The value type must align with the attribute’s declared type.
oneOf:
- type: string
- type: number
- type: boolean
- type: array
items:
oneOf:
- type: string
- type: number
pricing:
type: object
description: |
Pricing configuration returned when this rate-card row matches.
The structure depends on the charge_model:
- flat_fee → flat_amounts
- per_unit → unit_amounts
- volume/tiered → tiers
- discount_fixed_amount → discount_amounts
- discount_percentage → discount_percentage
oneOf:
- title: Flat Fee Pricing
type: object
required:
- flat_amounts
properties:
flat_amounts:
type: object
description: Map of currency to flat amount.
additionalProperties:
type: number
example:
USD: 100
- title: Per Unit Pricing
type: object
required:
- unit_amounts
properties:
unit_amounts:
type: object
description: Map of currency to per-unit price.
additionalProperties:
type: number
example:
USD: 2.5
- title: Tiered or Volume Pricing
type: object
required:
- tiers
properties:
tiers:
type: array
description: Tier definitions (volume or tiered) with optional min/max caps.
items:
type: object
required:
- tier
- from
- price_format
properties:
tier:
type: string
description: Tier identifier (e.g., "1", "2").
from:
type: number
description: Lower bound (inclusive).
up_to:
type: number
nullable: true
description: Upper bound (inclusive). Omit/null for open-ended last tier.
price_format:
type: string
description: For example, price_format_per_unit.
unit_amounts:
type: object
additionalProperties:
type: number
description: Per-unit price by currency for this tier.
flat_amounts:
type: object
additionalProperties:
type: number
description: Flat amount by currency for this tier (if applicable).
min_amounts:
type: object
additionalProperties:
type: number
description: Minimum billed amount by currency for this tier.
max_amounts:
type: object
additionalProperties:
type: number
description: Maximum billed amount by currency for this tier.
CreateChargeResponse:
type: object
additionalProperties: false
properties:
accounting:
$ref: '#/components/schemas/AccountingResponse'
attributes:
type: array
description: Attribute metadata associated with Dynamic Pricing for this charge.
items:
type: object
description: Declared attribute used by Dynamic Pricing.
additionalProperties: true
billCycle:
type: object
properties:
dayOfMonth:
type: integer
description: Specific day of month to bill when type = specific_day_of_month.
period:
type: string
description: |
Billing period length.
periodAlignment:
type: string
description: |
How the billing period start aligns.
timing:
type: string
description: Whether the charge bills before or after the service period.
type:
type: string
description: |
Bill-cycle mode (inherit defaults or set specific day rules).
chargeFunction:
type: string
description: Internal function/category of the charge used by rating.
chargeModel:
type: string
description: Pricing model that determines how the amount is calculated.
chargeType:
type: string
description: Whether the charge recurs, rates usage, or is a one-time fee.
createdById:
type: string
description: User ID that created the charge record.
createdTime:
type: string
format: date-time
description: Timestamp when the charge record was created.
customFields:
type: object
additionalProperties: true
description: Tenant-specific custom field values on the charge.
deliverySchedule:
type: object
description: Day-of-week delivery settings when delivery scheduling is enabled.
properties:
frequency:
type: string
description: |
Delivery frequency label for schedule rules.
friday:
type: boolean
description: Deliver on Friday.
monday:
type: boolean
description: Deliver on Monday.
saturday:
type: boolean
description: Deliver on Saturday.
sunday:
type: boolean
description: Deliver on Sunday.
thursday:
type: boolean
description: Deliver on Thursday.
tuesday:
type: boolean
description: Deliver on Tuesday.
wednesday:
type: boolean
description: Deliver on Wednesday.
discountOptions:
type: object
description: How discount charges apply and interact with other discounts.
properties:
applyDetails:
type: array
items:
type: object
description: Per-target discount application details (if populated).
applyTo:
type: array
items:
type: string
description: Which components or charges the discount applies to.
applyToBillingPeriodPartially:
type: boolean
description: Whether the discount duration can partially align to a period.
reflectDiscountInNetAmount:
type: boolean
description: Whether discounts reduce the net amount on invoices.
rollover:
type: boolean
description: Whether unused discount can roll over to future periods.
stackedDiscount:
type: boolean
description: Whether this discount stacks with other discounts.
drawdown:
type: object
additionalProperties: true
description: Prepaid/drawdown configuration when using prepaid with drawdown.
endDateCondition:
type: string
description: |
Rule for when the charge ends.
upToPeriodsType:
type: string
description: |
Unit used for the fixed period when `endDateCondition` is `fixed_period`, for example, billing periods or days.
upToPeriods:
type: integer
description: |
Number of periods, in units of `upToPeriodsType`, that the charge remains active when `endDateCondition` is `fixed_period`.
extendedPrice:
type: object
additionalProperties: true
description: Calculated extended price details (model-dependent).
id:
type: string
description: Unique identifier of the product rate plan charge (PRPC).
isChargeLevelMinCommit:
type: boolean
description: Whether a minimum commit is enforced at the charge level.
isCommitted:
type: boolean
description: Indicates if the charge definition is committed/finalized.
labels:
type: object
additionalProperties: true
description: Free-form labels/tags attached to the charge.
listPriceBase:
type: string
description: List price basis, for example, Per Billing Period, Per Month, Per Year.
specificListPriceBase:
description: |
The number of months for the list price base of the charge. This field is used
when the value of the `ListPriceBase` field to `Per Specific Months`.
The value must be a positive integer between **1** and **120** inclusive.
**Notes**:
- This field is available only if you have the Annual List Price feature enabled.
- To use this field, you must set the `X-Zuora-WSDL-Version` request header to `129` or later. Otherwise, an error occurs.
- The value of this field is `null` if you do not set the value of the `ListPriceBase` field to `Per Specific Months`.
type: integer
mergedRateCards:
type: array
items:
type: object
description: Effective rate-card rows after merges (if any).
name:
type: string
description: Display name of the charge in the plan.
negotiatedRateCards:
type: array
items:
type: object
description: Customer- or deal-specific rate-card rows applied by negotiation.
netsuite:
type: object
description: NetSuite integration attributes mapped for this charge.
additionalProperties: true
ocmJsonByCurrency:
type: object
additionalProperties: true
description: Offer/OCM metadata keyed by currency (internal use).
organizationLabels:
type: array
items:
type: string
description: Organization-level labels associated with the charge.
overageOptions:
type: object
description: Overage settings for usage charges.
properties:
includedUnits:
type: number
description: Included units before overage starts.
unusedUnitsCreditRates:
type: object
additionalProperties: true
description: Credit rates for unused units (by currency).
prepaid:
type: boolean
description: Indicates whether the charge is prepaid.
prepayment:
type: object
description: Prepayment handling and rollover behavior.
properties:
creditOption:
type: string
description: How prepayment credits are applied (if supported).
rollover:
type: boolean
description: Whether unused prepayment rolls over.
rolloverApply:
type: string
description: Order in which rollover is applied (e.g., apply_last).
rolloverPeriodLength:
type: integer
description: Length of each rollover period.
rolloverPeriods:
type: integer
description: Number of rollover periods allowed.
priceChangeOption:
type: string
description: |
How price changes are applied across renewals/amendments.
pricing:
type: object
description: Default (charge-level) price configuration by model/currency.
properties:
adjustments:
type: object
additionalProperties: true
description: Price adjustments metadata.
discountAmounts:
type: object
additionalProperties:
type: number
description: Fixed discount amounts by currency.
discountPercentages:
type: object
additionalProperties:
type: number
description: Percentage discount values by currency.
flatAmounts:
type: object
additionalProperties:
type: number
description: Flat amounts by currency for flat-fee pricing.
maxAmounts:
type: object
additionalProperties:
type: number
description: Maximum caps by currency.
minAmounts:
type: object
additionalProperties:
type: number
description: Minimum charges by currency.
percentages:
type: object
additionalProperties:
type: number
description: Percentage price values by currency (model-dependent).
tiers:
type: array
items:
type: object
description: Tier definitions for tiered/volume pricing.
unitAmounts:
type: object
additionalProperties:
type: number
description: Per-unit amounts by currency for per-unit/usage pricing.
pricingSummary:
type: array
items:
type: string
description: Human-readable price summary strings, for example, USD100.
pricingWaterfalls:
type: object
additionalProperties: true
description: Detailed pricing/waterfall breakdown (if available).
productChargeDefinitions:
type: array
items:
type: object
description: Underlying charge definitions referenced for pricing lookup.
productRatePlanChargeNumber:
type: string
description: PRPC number.
productRatePlanId:
type: string
description: ID of the plan (PRP) that owns this charge.
prorationOption:
type: string
description: How proration is handled relative to tenant defaults.
rateCards:
type: array
items:
type: object
description: Dynamic Pricing rate-card rows configured on the charge.
revenue:
type: object
description: Revenue policy settings for this charge.
properties:
excludeItemBillingFromRevenueAccounting:
type: boolean
description: If true, item billing is excluded from revenue accounting.
excludeItemBookingFromRevenueAccounting:
type: boolean
description: If true, item booking is excluded from revenue accounting.
legacyReporting:
type: boolean
description: Indicator for legacy revenue reporting behaviors.
revenueRecognitionRuleName:
type: string
description: Name of the revenue rule to apply, for example, "Recognize upon invoicing".
taxCode:
type: string
description: Tax code applied to the charge (for example, a tax category code).
taxMode:
type: string
description: |
Tax mode for the charge.
taxable:
type: boolean
description: Whether the charge is taxable.
triggerEvent:
type: string
description: |
Event that triggers the charge.
unitOfMeasure:
type: string
description: Unit of measure used for pricing (for example, Each, Seats).
updatedById:
type: string
description: User ID that last updated the charge record.
updatedTime:
type: string
format: date-time
description: Timestamp when the charge record was last updated.
useTenantDefaultForPriceChange:
type: boolean
description: Whether tenant defaults govern price change behavior.
example:
accounting:
accountsReceivableAccount: Accounts Receivable
accountsReceivableAccountType: AccountsReceivable
deferredRevenueAccount: Accounts Receivable
deferredRevenueAccountType: AccountsReceivable
recognizedRevenueAccount: Accounts Receivable
recognizedRevenueAccountType: AccountsReceivable
attributes: []
billCycle:
dayOfMonth: 5
period: bill_cycle_period_month
periodAlignment: align_to_charge
timing: in_advance
type: specific_day_of_month
chargeFunction: charge_function_standard
chargeModel: flat_fee
chargeType: recurring
createdById: 53c162482f054f3ca08e1ec82dccfec9
createdTime: '2025-10-13T07:46:02.000+00:00'
customFields: {}
discountOptions:
applyDetails: []
applyTo: []
applyToBillingPeriodPartially: false
reflectDiscountInNetAmount: false
rollover: false
stackedDiscount: false
drawdown: {}
endDateCondition: subscription_end
upToPeriodsType: billing_periods
upToPeriods: 0
extendedPrice: {}
id: ad95b694d2b8442b84dc8ad26561c7d7
isChargeLevelMinCommit: false
isCommitted: false
labels: {}
listPriceBase: Per_Billing_Period
mergedRateCards: []
name: Flat PRPC 1
negotiatedRateCards: []
netsuite: {}
ocmJsonByCurrency: {}
organizationLabels: []
overageOptions:
includedUnits: 0
unusedUnitsCreditRates: {}
prepaid: false
prepayment:
rollover: false
rolloverApply: apply_last
rolloverPeriodLength: 0
rolloverPeriods: 0
priceChangeOption: no_change
pricing:
adjustments: {}
discountAmounts: {}
discountPercentages: {}
flatAmounts:
USD: 100
maxAmounts: {}
minAmounts: {}
percentages: {}
tiers: []
unitAmounts: {}
pricingSummary:
- USD100
pricingWaterfalls: {}
productChargeDefinitions: []
productRatePlanChargeNumber: PRPC-00000279
productRatePlanId: ee2d1ce1036c4dd6ae9d6945565ff7a0
prorationOption: default_from_tenant_setting
rateCards: []
revenue:
excludeItemBillingFromRevenueAccounting: false
excludeItemBookingFromRevenueAccounting: false
legacyReporting: false
revenueRecognitionRuleName: Recognize upon invoicing
taxCode: TAX_EXEMPT
taxMode: non_taxable
taxable: false
triggerEvent: contract_effective
unitOfMeasure: Each
updatedById: 53c162482f054f3ca08e1ec82dccfec9
updatedTime: '2025-10-13T07:46:02.000+00:00'
useTenantDefaultForPriceChange: true
AccountingResponse:
type: object
additionalProperties: false
description: |
Accounting fields returned by the API. `*Type` fields are derived from the tenant's chart of accounts and are read-only.
properties:
accountingCode:
type: string
description: |
An accounting code associated with the charge for reporting or ERP mapping.
Typically a short code or identifier, not the GL account name.
example: PRPC-REV-001
accountsReceivableAccount:
type: string
description: |
Accounts Receivable (AR) account to book invoices for this charge.
Must match an existing account in the tenant's chart of accounts.
accountsReceivableAccountType:
type: string
readOnly: true
description: |
System-derived type/category of the AR account from the chart of accounts.
Examples include "AccountsReceivable".
adjustmentLiabilityAccount:
type: string
maxLength: 100
description: The name of the account where the Account Type is "Adjustment Liability".
example: adjustL-1
adjustmentLiabilityAccountType:
type: string
readOnly: true
description: |
System-derived type/category of the Adjustment Liability account from the chart of accounts.
Examples include "AdjustmentLiability".
adjustmentRevenueAccount:
type: string
maxLength: 100
description: The name of the account where the Account Type is "Adjustment Revenue".
example: adjustRev-1
adjustmentRevenueAccountType:
type: string
readOnly: true
description: |
System-derived type/category of the Adjustment Revenue account from the chart of accounts.
Examples include "AdjustmentRevenue".
contractAssetAccount:
type: string
maxLength: 100
description: The name of the account where the Account Type is "Contract Asset".
example: CA-2
contractAssetAccountType:
type: string
readOnly: true
description: |
System-derived type/category of the Contract Asset account from the chart of accounts.
example: ContractAsset
contractLiabilityAccount:
type: string
maxLength: 100
description: The name of the account where the Account Type is "Contract Liability".
example: CL-2
contractLiabilityAccountType:
type: string
readOnly: true
description: |
System-derived type/category of the Contract Liability account from the chart of accounts.
Examples include "ContractLiability".
contractRecognizedRevenueAccount:
type: string
description: |
Recognized revenue account used specifically for contract-based recognition flows.
Must match an existing account in the tenant's chart of accounts.
contractRecognizedRevenueAccountType:
type: string
readOnly: true
description: |
System-derived type/category of the Contract Recognized Revenue account from the chart of accounts.
example: RecognizedRevenue
deferredRevenueAccount:
type: string
description: |
Deferred revenue (liability) account to book revenue before recognition.
Must match an existing account in the tenant's chart of accounts.
deferredRevenueAccountType:
type: string
readOnly: true
description: |
System-derived type/category of the Deferred Revenue account from the chart of accounts.
example: DeferredRevenue
recognizedRevenueAccount:
type: string
maxLength: 100
description: The name of the account where the Account Type is "Recognized Revenue".
example: ContractRevRec-1
recognizedRevenueAccountType:
type: string
readOnly: true
description: |
System-derived type/category of the Recognized Revenue account from the chart of accounts.
example: RecognizedRevenue
unbilledReceivablesAccount:
type: string
maxLength: 100
description: The name of the account where the Account Type is "Unbilled Receivables".
example: unbilledR-1
unbilledReceivablesAccountType:
type: string
readOnly: true
description: |
System-derived type/category of the Unbilled Receivables account from the chart of accounts.
example: UnbilledReceivables
productRatePlanChargeId:
type: string
description: The ID of your product rate plan charge.
example: 2c92c0f962470b8101624b869fcd45fc
AccountingRequest:
type: object
additionalProperties: false
description: |
Accounting fields accepted on create/update requests. Field names use snake_case.
**Conditional requirement rules**
- If **Allow blank Accounting Codes** = **Yes** → Accounting fields are **optional**.
- If **Allow blank Accounting Codes** = **No** and the tenant **has Zuora Revenue** → **all Accounting fields except `accounting_code` are required**.
- If **Allow blank Accounting Codes** = **No** and the tenant **does NOT have Zuora Revenue** → only `recognized_revenue_account` and `deferred_revenue_account` are required.
These rules apply to **all operations that accept `accounting`** in the payload.
properties:
accounting_code:
type: string
description: |
An accounting code associated with the charge for reporting/ERP mapping. Typically a short code or identifier, not the GL account name.
example: PRPC-REV-001
accounts_receivable_account:
type: string
description: |
Accounts Receivable (AR) account to book invoices for this charge. Must match an existing account in the tenant's chart of accounts.
example: Accounts Receivable
accounts_receivable_account_type:
type: string
description: |
The account type associated with `accounts_receivable_account`. Maps to the `accountsReceivableAccountType` field in the accounting object.
deferred_revenue_account:
type: string
description: |
Deferred revenue (liability) account to book revenue before recognition. Must match an existing account in the tenant's chart of accounts.
example: Deferred Revenue
deferred_revenue_accounting_type:
type: string
description: |
Accounting method/type applied to deferred revenue. Maps to the `deferredRevenueAccountingType` field in the accounting object.
recognized_revenue_account:
type: string
maxLength: 100
description: The name of the account where the Account Type is "Recognized Revenue".
example: ContractRevRec-1
recognized_revenue_account_type:
type: string
description: |
The account type associated with `recognized_revenue_account`. Maps to the `recognizedRevenueAccountType` field in the accounting object.
adjustment_liability_account:
type: string
maxLength: 100
description: The name of the account where the Account Type is "Adjustment Liability".
example: adjustL-1
adjustment_liability_account_type:
type: string
description: |
The account type associated with `adjustment_liability_account`. Maps to the `adjustmentLiabilityAccountType` field in the accounting object.
adjustment_revenue_account:
type: string
maxLength: 100
description: The name of the account where the Account Type is "Adjustment Revenue".
example: adjustRev-1
adjustment_revenue_account_type:
type: string
description: |
The account type associated with `adjustment_revenue_account`. Maps to the `adjustmentRevenueAccountType` field in the accounting object.
contract_asset_account:
type: string
maxLength: 100
description: The name of the account where the Account Type is "Contract Asset".
example: CA-2
contract_asset_account_type:
type: string
description: |
The account type associated with `contract_asset_account`. Maps to the `contractAssetAccountType` field in the accounting object.
contract_liability_account:
type: string
maxLength: 100
description: The name of the account where the Account Type is "Contract Liability".
example: CL-2
contract_liability_account_type:
type: string
description: |
The account type associated with `contract_liability_account`. Maps to the `contractLiabilityAccountType` field in the accounting object.
contract_recognized_revenue_account:
type: string
description: |
Recognized revenue account used specifically for contract-based recognition flows. Must match an existing account in the tenant's chart of accounts.
example: Contract Recognized Revenue
contract_recognized_revenue_account_type:
type: string
description: |
The account type associated with `contract_recognized_revenue_account`. Maps to the `contractRecognizedRevenueAccountType` field in the accounting object.
unbilled_receivables_account:
type: string
maxLength: 100
description: The name of the account where the Account Type is "Unbilled Receivables".
example: unbilledR-1
unbilled_receivables_account_type:
type: string
description: |
The account type associated with `unbilled_receivables_account`. Maps to the `unbilledReceivablesAccountType` field in the accounting object.
example:
accounting_code: PRPC-REV-001
accounts_receivable_account: Accounts Receivable
adjustment_liability_account: adjustL-1
adjustment_revenue_account: adjustRev-1
contract_asset_account: CA-2
contract_liability_account: CL-2
contract_recognized_revenue_account: Contract Recognized Revenue
deferred_revenue_account: Deferred Revenue
recognized_revenue_account: ContractRevRec-1
unbilled_receivables_account: unbilledR-1
UpdateChargeRequest:
type: object
required:
- charge
properties:
charge:
type: object
additionalProperties: false
description: |
Fields to update on the product rate plan charge (PRPC). Only the properties
provided will be considered for update (patch semantics). Unsupported updates
are ignored by the service.
required:
- id
properties:
id:
type: string
description: Unique identifier of the product rate plan charge (PRPC) to update.
example: 9c4867ed55db43a89731605d5654d4ed
name:
type: string
description: Optional new display name for the charge.
description:
type: string
description: Optional new description for the charge.
trigger_event:
type: string
description: Event that triggers the charge (if update is supported).
enum:
- contract_effective
- service_activation
- customer_acceptance
unit_of_measure:
type: string
description: Unit of measure label for the charge, for example, Each, Seat. May be read-only in some tenants.
default_quantity:
type: number
description: Default quantity when the charge is added to a product/offer.
min_quantity:
type: number
description: Optional minimum quantity constraint (if supported).
max_quantity:
type: number
description: Optional maximum quantity constraint (if supported)
list_price_base:
type: string
description: List price basis (e.g., Per_Billing_Period). Typically read-only after creation.
bill_cycle:
type: object
description: Billing period configuration controlling frequency, alignment, and timing.
additionalProperties: false
properties:
type:
type: string
description: Source of the default billing period, for example, default_from_customer, specific_day_of_month.
day_of_month:
type: integer
description: Day of month to bill when type = `specific_day_of_month`.
day_of_week:
type: string
description: Day of week to bill when using weekly modes.
period:
type: string
description: Billing period, for example, bill_cycle_period_month, bill_cycle_period_quarter.
specific_period:
type: string
description: Custom period text when applicable.
period_alignment:
type: string
description: Alignment behavior, for example, align_to_charge, align_to_term_start.
timing:
type: string
description: Indicates whether billing occurs in advance or in arrears.
enum:
- in_advance
- in_arrears
pricing:
type: object
description: |
Default (charge-level) pricing used when no rate-card row matches.
Structure depends on the charge model:
- flat_fee → flat_amounts
- per_unit → unit_amounts
- volume/tiered → tiers
- discount_fixed_amount → discount_amounts
- discount_percentage → discount_percentage
oneOf:
- title: Flat Fee Pricing
type: object
required:
- flat_amounts
properties:
flat_amounts:
type: object
description: Map of currency to flat amount.
additionalProperties:
type: number
example:
USD: 100
- title: Per Unit Pricing
type: object
required:
- unit_amounts
properties:
unit_amounts:
type: object
description: Map of currency to per-unit price.
additionalProperties:
type: number
example:
USD: 2.5
- title: Tiered or Volume Pricing
type: object
required:
- tiers
properties:
tiers:
type: array
description: Tier definitions (volume or tiered) with optional min/max caps.
items:
type: object
required:
- tier
- from
- price_format
properties:
tier:
type: string
description: Tier identifier, for example, "1", "2".
from:
type: number
description: Lower bound (inclusive).
up_to:
type: number
nullable: true
description: Upper bound (inclusive). Omit/null for open-ended last tier.
price_format:
type: string
description: For example, price_format_per_unit or price_format_flat_fee.
unit_amounts:
type: object
description: Per-unit price by currency for this tier.
additionalProperties:
type: number
example:
USD: 2.5
flat_amounts:
type: object
description: Flat amount by currency for this tier (if applicable).
additionalProperties:
type: number
example:
USD: 100
min_amounts:
type: object
description: Minimum billed amount by currency for this tier.
additionalProperties:
type: number
example:
USD: 6.25
max_amounts:
type: object
description: Maximum billed amount by currency for this tier.
additionalProperties:
type: number
example:
USD: 25
- title: Fixed Amount Discount
type: object
required:
- discount_amounts
properties:
discount_amounts:
type: object
description: Map of currency to discount amount.
additionalProperties:
type: number
example:
USD: 10
- title: Percentage Discount
type: object
required:
- discount_percentage
properties:
discount_percentage:
type: number
format: double
description: Discount percentage, for example, 15 for 15%.
example: 15
rate_cards:
type: array
description: |
Conditional pricing rows (rate cards). Each row defines match attributes and a price to apply.
If multiple rows match, the first match wins. If none match, `pricing` is used.
items:
type: object
required:
- attributes
- pricing
properties:
attributes:
type: array
minItems: 1
description: |
Match conditions that must all evaluate to true for the row to apply.
Use `between` for ranges or dates.
items:
type: object
required:
- name
properties:
name:
type: string
description: Attribute name, for example, Age, Region, EffectiveDate.
example: Age
operator:
type: string
description: Comparison operator.
enum:
- '>'
- '>='
- <
- <=
- '=='
- between
- between-inclusive
example: <=
value:
description: |
Comparison value. For `between`, provide an array of two values.
The value type must align with the attribute’s declared type.
oneOf:
- type: string
- type: number
- type: boolean
- type: array
items:
oneOf:
- type: string
- type: number
example: 12
pricing:
type: object
description: |
Price to apply when this row matches. Structure mirrors `pricing` above.
oneOf:
- title: Flat Fee Pricing
type: object
required:
- flat_amounts
properties:
flat_amounts:
type: object
description: Map of currency to flat amount.
additionalProperties:
type: number
example:
USD: 100
- title: Per Unit Pricing
type: object
required:
- unit_amounts
properties:
unit_amounts:
type: object
description: Map of currency to per-unit price.
additionalProperties:
type: number
example:
USD: 180
- title: Tiered or Volume Pricing
type: object
required:
- tiers
properties:
tiers:
type: array
description: Tier definitions (volume or tiered) with optional min/max caps.
items:
type: object
required:
- tier
- from
- price_format
properties:
tier:
type: string
description: Tier identifier, for example, "1", "2".
from:
type: number
description: Lower bound (inclusive).
up_to:
type: number
nullable: true
description: Upper bound (inclusive).
price_format:
type: string
description: For example, price_format_per_unit.
unit_amounts:
type: object
description: Per-unit price by currency for this tier.
additionalProperties:
type: number
flat_amounts:
type: object
description: Flat amount by currency for this tier (if applicable).
additionalProperties:
type: number
min_amounts:
type: object
description: Minimum billed amount by currency for this tier.
additionalProperties:
type: number
max_amounts:
type: object
description: Maximum billed amount by currency for this tier.
additionalProperties:
type: number
- title: Fixed Amount Discount
type: object
required:
- discount_amounts
properties:
discount_amounts:
type: object
description: Map of currency to discount amount.
additionalProperties:
type: number
example:
USD: 10
- title: Percentage Discount
type: object
required:
- discount_percentage
properties:
discount_percentage:
type: number
format: double
description: Discount percentage (e.g., 15 for 15%).
example: 15
tax_code:
type: string
description: Optional tax code to associate with the charge.
tax_mode:
type: string
description: Tax mode, for example, tax_exclusive, non_taxable, if supported.
price_change_option:
type: string
description: How price changes apply on updates, for example, no_change.
use_tenant_default_for_price_change:
type: boolean
description: If true, tenant defaults govern price change behavior.
delivery_schedule:
type: object
description: Day-of-week delivery configuration (if enabled).
additionalProperties: true
prepayment:
type: object
description: Prepayment settings (credit option, rollover, validity).
additionalProperties: true
prepaid:
type: boolean
description: Indicates whether the charge is prepaid.
overage_options:
type: object
description: Overage configuration for usage charges.
additionalProperties: true
accounting:
$ref: '#/components/schemas/AccountingRequest'
revenue:
type: object
description: Revenue recognition settings (rule names, timing).
additionalProperties: true
netsuite:
type: object
description: NetSuite integration attributes for the charge.
additionalProperties: true
custom_fields:
type: object
description: Tenant-specific custom field values on the charge.
additionalProperties: true
labels:
type: object
description: Free-form labels/tags attached to the charge.
additionalProperties: true
organization_labels:
type: array
description: Organization-level labels associated with the charge.
items:
type: object
ocm_json_by_currency:
type: object
description: Offer/OCM metadata keyed by currency (internal use).
additionalProperties: true
attributes:
type: array
description: Attribute declarations for Dynamic Pricing (name/type/mapping).
items:
type: object
required:
- name
properties:
name:
type: string
description: Attribute name, for example, Region, Age, EffectiveDate.
type:
type: string
description: Attribute data type.
enum:
- string
- integer
- double
- boolean
- date
- datetime
mapping:
type: object
description: Optional mapping to resolve values from Zuora objects.
required:
- object
- field
properties:
object:
type: string
description: Target Zuora object, for example, account, subscription.
field:
type: string
description: Field on the target object, for example, age__c.
QueryChargeRequest:
type: object
description: |
Request schema for querying a specific Product Rate Plan Charge (PRPC) by key.
Use this operation to fetch details of a single PRP, optionally expanding related charges.
properties:
product_rate_plan_key:
type: string
description: |
Unique identifier (key) of the Product Rate Plan (PRP) to query. This can be the PRP ID or the PRP number configured in your system.
example: 11dc762a07064ce496af73ff4cfb5614
expand:
type: object
description: |
Optional flags to expand related resources in the response.
properties:
product_rate_plan_charges:
type: boolean
description: Whether to include Product Rate Plan Charges (PRPCs) in the response.
example: true
attributes:
type: array
description: |
Optional attribute values to use when evaluating Dynamic Pricing for the PRP or its charges.
All required attributes must be supplied if the PRP or PRPC is configured to require them.
items:
type: object
required:
- name
properties:
name:
type: string
description: Attribute name, for example, Age, Region, EffectiveDate, AccountContext.
example: Age
value:
description: |
Attribute value used for price evaluation. The value can be a string, number, or boolean, depending on the attribute type.
- Enclose the value in quotation marks ("") if it is a **string**, for example, "Liquidity Provider", "Y", "External".
- Do **not** use quotation marks for **numeric** or **boolean** values, for example, 98, 5, true, false.
example: Liquidity Provider
evaluation_level:
type: string
description: |
Controls how pricing is evaluated for the charge. Supported values: - `LIST_PRICE`: evaluate pricing at the list-price level. - `EXTENDED_PRICE`: evaluate pricing at the extended-price level.
If not specified, the default is `LIST_PRICE`.
enum:
- LIST_PRICE
- EXTENDED_PRICE
example: LIST_PRICE
CreateProductRequest:
type: object
required:
- name
- start_date
- end_date
- category
- plans
properties:
name:
type: string
description: Product name.
example: New prod
sku:
type: string
description: The stock keeping unit (SKU) associated with the product or invoice item.
example: SKU-12345
product_number:
type: string
description: The product number that uniquely identifies the product in the product catalog.
example: PROD-001
start_date:
type: string
format: date
description: Product effective start date (UTC, YYYY-MM-DD).
example: '2024-01-01'
end_date:
type: string
format: date
description: Product effective end date (UTC, YYYY-MM-DD).
example: '2050-12-31'
category:
type: string
description: |
Product category.
enum:
- base
- add_on
- other
example: base
plans:
type: array
description: Product rate plans to create under the product.
minItems: 1
items:
type: object
required:
- name
- start_date
- end_date
- active_currencies
- charges
properties:
name:
type: string
description: Rate plan name.
example: Consumer Bronze Monthly 2
start_date:
type: string
format: date
description: Rate plan effective start date (UTC, YYYY-MM-DD).
example: '2024-01-01'
end_date:
type: string
format: date
description: Rate plan effective end date (UTC, YYYY-MM-DD).
example: '2050-12-31'
active_currencies:
type: array
description: ISO currency codes enabled for this plan.
items:
type: string
minLength: 3
maxLength: 3
example:
- USD
charges:
type: array
description: Charges to create under this rate plan.
minItems: 1
items:
type: object
required:
- name
- charge_type
- charge_model
- bill_cycle
- trigger_event
- end_date_condition
properties:
name:
type: string
description: Charge name.
example: Data Usage Charge
charge_type:
type: string
description: Charge type.
enum:
- one_time
- recurring
- usage
example: usage
charge_model:
type: string
description: Charge model.
enum:
- flat_fee
- per_unit
- overage
- volume
- tiered
- tiered_overage
- discount_fixed_amount
- discount_percentage
- custom_charge_model
- delivery
- minimum_commitment_true_up
- calculated
- high_water_mark_volume_pricing
- high_water_mark_tiered_pricing
- multi_attribute_pricing
- prerated_pricing
- prerated_per_unit
example: per_unit
unit_of_measure:
type: string
description: Unit of measure for per-unit or usage charges.
example: Each
list_price_base:
type: string
description: |
List price base for the charge.
enum:
- Per_Billing_Period
- Per_Month
- Per_Week
- Per_Year
- Per_Specific_Months
- Per_Validity_Period
example: Per_Billing_Period
default_quantity:
type: number
description: Default quantity for this charge on subscriptions created from the plan.
example: 1
min_quantity:
type: number
description: |
Minimum quantity allowed for this charge. Equivalent to the `MinQuantity` field in the legacy v1 Product Rate Plan Charge.
example: 1
max_quantity:
type: number
description: |
Maximum quantity allowed for this charge. Equivalent to the `MaxQuantity` field in the legacy v1 Product Rate Plan Charge.
example: 999999
pricing:
type: object
description: |
Default (standard) pricing defined at the charge level.
Provide exactly one structure per the charge model.
oneOf:
- title: Flat Fee Pricing
type: object
required:
- flat_amounts
properties:
flat_amounts:
type: object
description: Map of currency to flat amount.
additionalProperties:
type: number
example:
USD: 100
- title: Per Unit Pricing
type: object
required:
- unit_amounts
properties:
unit_amounts:
type: object
description: Map of currency to per-unit price.
additionalProperties:
type: number
example:
USD: 5
- title: Tiered or Volume Pricing
type: object
required:
- tiers
properties:
tiers:
type: array
description: Tier definitions (volume or tiered) with optional min/max caps.
items:
type: object
required:
- tier
- from
- price_format
properties:
tier:
type: string
description: Tier identifier (e.g., "1", "2").
from:
type: number
description: Lower bound (inclusive).
up_to:
type: number
nullable: true
description: Upper bound (inclusive). Omit/null for open-ended last tier.
price_format:
type: string
description: Price format for the tier.
enum:
- price_format_flat_fee
- price_format_per_unit
example: price_format_per_unit
unit_amounts:
type: object
description: Per-unit price by currency for this tier.
additionalProperties:
type: number
example:
USD: 2.5
flat_amounts:
type: object
description: Flat amount by currency for this tier (if applicable).
additionalProperties:
type: number
example:
USD: 100
min_amounts:
type: object
description: Minimum billed amount by currency for this tier.
additionalProperties:
type: number
example:
USD: 6.25
max_amounts:
type: object
description: Maximum billed amount by currency for this tier.
additionalProperties:
type: number
example:
USD: 25
- title: Fixed Amount Discount
type: object
required:
- discount_amounts
properties:
discount_amounts:
type: object
description: Map of currency to discount amount.
additionalProperties:
type: number
example:
USD: 10
- title: Percentage Discount
type: object
required:
- discount_percentage
properties:
discount_percentage:
type: number
format: double
description: Discount percentage (e.g., 15 for 15%).
example: 15
bill_cycle:
type: object
description: Billing configuration of the charge.
required:
- type
- period
- period_alignment
properties:
type:
type: string
description: |
Determines how the billing day is selected for this charge.
enum:
- default_from_customer
- specific_day_of_month
- subscription_start_day
- charge_trigger_day
- specific_day_of_week
- term_start_day
- term_end_day
example: default_from_customer
period:
type: string
description: |
Length of each billing period.
enum:
- bill_cycle_period_month
- bill_cycle_period_quarter
- bill_cycle_period_semi_annual
- bill_cycle_period_annual
- bill_cycle_period_eighteen_months
- bill_cycle_period_two_years
- bill_cycle_period_three_years
- bill_cycle_period_five_years
- bill_cycle_period_specific_months
- bill_cycle_period_subscription_term
- bill_cycle_period_week
- bill_cycle_period_specific_weeks
- bill_cycle_period_specific_days
example: bill_cycle_period_month
period_alignment:
type: string
description: |
How the billing period start aligns.
enum:
- align_to_charge
- align_to_subscription_start
- align_to_term_start
- align_to_term_end
example: align_to_charge
timing:
type: string
description: |
When the charge is billed relative to the service period.
enum:
- in_advance
- in_arrears
example: in_arrears
day_of_month:
type: integer
minimum: 1
maximum: 31
description: Required if "type" is `specific_day_of_month`.
example: 5
day_of_week:
type: string
description: |
Used when "type" is `specific_day_of_week`.
enum:
- sunday
- monday
- tuesday
- wednesday
- thursday
- friday
- saturday
specific_period:
type: string
description: |
Optional specific period value when `period` is `bill_cycle_period_specific_months`, `bill_cycle_period_specific_weeks`, or `bill_cycle_period_specific_days`. Equivalent to `SpecificBillingPeriod` in the legacy v1 API.
trigger_event:
type: string
description: |
Event that triggers the charge.
enum:
- contract_effective
- service_activation
- customer_acceptance
- specific_date
example: contract_effective
end_date_condition:
type: string
description: |
Defines when the charge ends.
enum:
- subscription_end
- end_date_one_time
- fixed_period
- specific_end_date
example: subscription_end
up_to_periods_type:
type: string
description: |
Unit of time used when `end_date_condition` = `fixed_period`.
Maps to the duration unit (billing periods, days, weeks, months, years).
enum:
- billing_periods
- days
- weeks
- months
- years
example: billing_periods
up_to_periods:
type: integer
description: |
Number of periods used when `end_date_condition` = `fixed_period`.
example: 0
overage_options:
type: object
description: |
Configuration for overage smoothing and period-based overage calculation. Equivalent to `NumberOfPeriod` and related fields in the legacy v1 API.
properties:
number_of_periods:
type: number
description: |
Number of billing periods used for overage smoothing / calculation.
price_increase_percentage:
type: number
format: double
description: |
Percentage used when `price_change_option` is set to apply a specific percentage price increase. Equivalent to `PriceIncreasePercentage` (v1).
example: 5
price_change_option:
type: string
description: |
Specifies how price changes are handled for future terms when this product or rate plan is amended. Equivalent to `PriceChangeOption` in the legacy v1 API. Examples include `no_change`, `specific_percentage_value`, or `use_latest_product_catalog_pricing`.
enum:
- no_change
- specific_percentage_value
- use_latest_product_catalog_pricing
example: no_change
use_tenant_default_for_price_change:
type: boolean
description: |
When true, uses the tenant-level default setting for price change behavior instead of the charge-level `price_change_option`. Equivalent to `UseTenantDefaultForPriceChange` in the legacy v1 API.
example: true
discount_options:
type: object
description: |
Discount configuration for discount charge models, including "Apply Discount To" and related settings.
properties:
discount_class:
type: string
description: Discount class to associate with this discount charge.
stacked_discount:
type: boolean
description: |
When true, this discount can stack with other discounts.
apply_to:
type: array
description: |
Charge types that this discount applies to. Mirrors the "One-Time / Recurring / Usage" checkboxes in the UI.
items:
type: string
enum:
- one_time
- recurring
- usage
discount_level:
type: string
description: |
Level at which the discount applies (for example, subscription-level or account-level discounts).
enum:
- rate_plan
- subscription
- account
apply_to_billing_period_partially:
type: boolean
description: |
When true, allows the discount to apply to partial billing periods.
specific_accounting_codes:
type: boolean
description: |
When true, uses discount-specific accounting codes instead of inheriting from the discounted charges. Equivalent to `UseDiscountSpecificAccountingCode` in the legacy v1 API.
reflect_discount_in_net_amount:
type: boolean
description: |
When true, discount is reflected directly in the net amount (Apply To Charge Net Amount option in the UI).
rollover:
type: boolean
description: |
Indicates whether unused discount amounts roll over to the next billing period.
apply_details:
type: array
description: |
Explicit list of product charges that this discount applies to when targeting specific charges.
items:
type: object
properties:
applied_product_rate_plan_id:
type: string
description: ID of the target product rate plan.
applied_product_rate_plan_charge_id:
type: string
description: ID of the target product rate plan charge.
accounting:
$ref: '#/components/schemas/AccountingRequest'
CreateProductResponse:
type: object
description: Product created with optional plans and charges.
required:
- id
- name
- category
- startDate
- endDate
- state
properties:
id:
type: string
description: Unique identifier of the product.
example: 7ec58fadb6f84bc18e59c7529058d941
name:
type: string
description: Product name.
example: New prod
category:
type: string
description: Product category, for example, base or add-on.
example: base
description:
type: string
description: Free-form product description.
example: ''
productNumber:
type: string
description: The product number.
example: PC-00000105
sku:
type: string
description: Stock keeping unit for the product.
example: SKU-00000135
startDate:
type: string
format: date
description: Product effective start date, for example, UTC, YYYY-MM-DD.
example: '2024-01-01'
endDate:
type: string
format: date
description: Product effective end date, for example, UTC, YYYY-MM-DD.
example: '2050-12-31'
state:
type: string
description: Current lifecycle state of the product.
example: product_active
allowFeatureChanges:
type: boolean
description: Whether feature changes are allowed for this product.
example: false
features:
type: array
description: List of features associated with the product.
items:
type: object
legacyFeatures:
type: array
description: Legacy feature list retained for backward compatibility.
items:
type: object
additionalProperties: true
contextFilters:
type: array
description: Context filter rules that may restrict product availability.
items:
type: object
organizationLabels:
type: array
description: Key/value style organizational labels applied to the product.
items:
type: object
customFields:
type: object
description: Custom field values on the product.
additionalProperties: true
customObjects:
type: object
nullable: true
description: Custom object payloads linked to the product, if any.
additionalProperties: true
example: null
dacTags:
type: object
description: Data access control or categorization tags for the product.
additionalProperties: true
netsuite:
type: object
nullable: true
description: NetSuite integration metadata (if present).
additionalProperties: true
example: null
createdBy:
type: string
description: ID of the user who created the product.
example: 53c162482f054f3ca08e1ec82dccfec9
createdTime:
type: string
format: date-time
description: Timestamp when the product was created.
example: '2025-10-17T04:02:54.621-07:00'
updatedBy:
type: string
description: ID of the user who last updated the product.
example: 53c162482f054f3ca08e1ec82dccfec9
updatedTime:
type: string
format: date-time
description: Timestamp when the product was last updated.
example: '2025-10-17T04:02:54.621-07:00'
plans:
type: array
description: Rate plans (PRPs) defined under this product.
items:
type: object
required:
- id
- name
- startDate
- endDate
- activeCurrencies
properties:
id:
type: string
description: Unique identifier of the product rate plan (PRP).
example: 572a2efe711b449e80cbef94419bc050
name:
type: string
description: Rate plan display name.
example: Consumer Bronze Monthly
displayName:
type: string
description: Optional alternate display name for the plan.
example: ''
description:
type: string
description: Free-form plan description.
example: ''
startDate:
type: string
format: date
description: Plan effective start date (UTC, YYYY-MM-DD).
example: '2024-01-01'
endDate:
type: string
format: date
description: Plan effective end date (UTC, YYYY-MM-DD).
example: '2050-12-31'
state:
type: string
description: Current lifecycle state of the plan.
example: active
status:
type: string
description: Optional status when present in some responses.
example: ACTIVE
activeCurrencies:
type: array
description: ISO currency codes enabled for this plan.
items:
type: string
example: USD
createTime:
type: string
format: date-time
description: Timestamp when the plan was created.
example: '2025-10-17T04:02:54.655-07:00'
updateTime:
type: string
format: date-time
description: Timestamp when the plan was last updated.
example: '2025-10-17T04:02:54.655-07:00'
createdBy:
type: string
description: ID of the user who created the plan.
example: 53c162482f054f3ca08e1ec82dccfec9
updatedBy:
type: string
description: ID of the user who last updated the plan.
example: 53c162482f054f3ca08e1ec82dccfec9
productId:
type: string
description: ID of the parent product for this plan.
example: 7ec58fadb6f84bc18e59c7529058d941
productRatePlanNumber:
type: string
description: The plan number.
example: PRP-00000198
attributes:
type: array
description: Plan-level attribute metadata.
items:
type: object
contextFilters:
type: array
description: Context filter rules scoped to the plan.
items:
type: object
entitlements:
type: array
description: Entitlements included with the plan.
items:
type: object
externalIdSourceSystem:
type: string
description: Source system identifier for the external plan ID.
example: ''
externalRateplanId:
type: array
description: External plan identifier(s) from other systems.
items:
type: string
netsuite:
type: object
nullable: true
description: NetSuite integration metadata (if present).
additionalProperties: true
example: null
organizationLabels:
type: array
description: Key/value style organizational labels on the plan.
items:
type: object
customFields:
type: object
description: Custom field values on the plan.
additionalProperties: true
productRatePlanCharges:
type: array
description: Charges created under this plan.
items:
type: object
required:
- id
- name
- chargeModel
- chargeType
- billCycle
- pricing
properties:
id:
type: string
description: Unique identifier of the product rate plan charge (PRPC).
example: 42db6ead399a4521bae91b3af469c074
name:
type: string
description: Charge display name within the plan.
example: Flat PRPC
chargeModel:
type: string
description: Pricing model that determines how the amount is calculated.
example: flat_fee
chargeType:
type: string
description: Whether the charge recurs, rates usage, or is a one-time fee.
example: recurring
chargeFunction:
type: string
description: Internal function identifier for the charge.
example: charge_function_standard
productRatePlanChargeNumber:
type: string
description: The charge number.
example: PRPC-00000283
productRatePlanId:
type: string
description: ID of the parent plan for this charge.
example: 572a2efe711b449e80cbef94419bc050
triggerEvent:
type: string
description: Event that triggers the charge to become billable.
example: contract_effective
endDateCondition:
type: string
description: Condition that determines when the charge ends.
example: subscription_end
upToPeriodsType:
type: string
description: |
Unit of time used when `endDateCondition` is `fixed_period`, for
example, billing periods, days, weeks, months, or years.
example: billing_periods
upToPeriods:
type: integer
description: |
Number of periods used when `endDateCondition` is `fixed_period`.
example: 0
listPriceBase:
type: string
description: Basis used for list pricing (if applicable).
example: Per_Billing_Period
specificListPriceBase:
type: number
description: |
Optional override for list price base when billing uses a specific period configuration.
example: 0
billCycle:
type: object
description: Billing configuration of the charge.
properties:
type:
type: string
description: Whether the charge inherits account defaults or uses an override.
example: specific_day_of_month
dayOfMonth:
type: integer
description: Day of month to bill when using a specific day schedule.
example: 5
period:
type: string
description: Billing period length (for example, monthly).
example: bill_cycle_period_month
periodAlignment:
type: string
description: How the billing period start aligns.
example: align_to_charge
timing:
type: string
description: When the charge is billed relative to the service period.
example: in_advance
organizationLabels:
type: array
description: Key/value style organizational labels on the charge.
items:
type: object
accounting:
$ref: '#/components/schemas/AccountingResponse'
discountOptions:
type: object
description: Discount behavior flags configured on the charge.
properties:
applyDetails:
type: array
description: List of granular discount application details.
items:
type: object
applyTo:
type: array
description: Line item categories the discount applies to.
items:
type: string
applyToBillingPeriodPartially:
type: boolean
description: Whether discount applies to partial billing periods.
example: false
reflectDiscountInNetAmount:
type: boolean
description: Whether to reflect discounts in the net amount fields.
example: false
rollover:
type: boolean
description: Whether unapplied discounts roll over.
example: false
stackedDiscount:
type: boolean
description: Whether multiple discounts can stack.
example: false
additionalProperties: true
overageOptions:
type: object
description: Options governing overage behavior for usage charges.
properties:
includedUnits:
type: number
description: Number of units included before overages apply.
example: 0
unusedUnitsCreditRates:
type: object
description: Credit rates for unused units by currency.
additionalProperties:
type: number
prepayment:
type: object
description: Prepayment configuration for the charge (if applicable).
properties:
rollover:
type: boolean
description: Whether unused prepaid amounts roll over.
example: false
rolloverApply:
type: string
description: How rollover amounts are applied.
example: apply_last
rolloverPeriodLength:
type: integer
description: Length of the rollover period.
example: 0
rolloverPeriods:
type: integer
description: Number of rollover periods.
example: 0
prorationOption:
type: string
description: Proration behavior for partial periods.
example: default_from_tenant_setting
priceChangeOption:
type: string
description: How price changes are applied to existing subscriptions.
example: no_change
taxable:
type: boolean
description: Whether the charge is taxable.
example: false
taxMode:
type: string
description: Tax mode classification (present on some responses).
example: non_taxable
prepaid:
type: boolean
description: Whether the charge is prepaid.
example: false
isCommitted:
type: boolean
description: Whether the charge is committed.
example: false
isChargeLevelMinCommit:
type: boolean
description: Whether a minimum commitment is enforced at the charge level.
example: false
useTenantDefaultForPriceChange:
type: boolean
description: Whether tenant default settings apply to price changes.
example: true
labels:
type: object
description: Arbitrary label metadata for the charge.
additionalProperties: true
attributes:
type: array
description: Attribute metadata on the charge (if configured).
items:
type: object
customFields:
type: object
description: Custom field values on the charge.
additionalProperties: true
createdById:
type: string
description: ID of the user who created the charge.
example: 53c162482f054f3ca08e1ec82dccfec9
createdTime:
type: string
format: date-time
description: Timestamp when the charge was created.
example: '2025-10-17T04:02:54.719-07:00'
updatedById:
type: string
description: ID of the user who last updated the charge.
example: 53c162482f054f3ca08e1ec82dccfec9
updatedTime:
type: string
format: date-time
description: Timestamp when the charge was last updated.
example: '2025-10-17T04:02:54.719-07:00'
pricing:
type: object
description: Default (charge-level) pricing returned for the charge.
properties:
adjustments:
type: object
description: Price adjustments by currency or context.
additionalProperties: true
discountAmounts:
type: object
description: Fixed discount amounts by currency.
additionalProperties:
type: number
discountPercentages:
type: object
description: Discount percentages by currency.
additionalProperties:
type: number
flatAmounts:
type: object
description: Flat fee amounts by currency.
additionalProperties:
type: number
example:
USD: 100
maxAmounts:
type: object
description: Maximum amounts by currency (caps).
additionalProperties:
type: number
minAmounts:
type: object
description: Minimum amounts by currency (floors).
additionalProperties:
type: number
percentages:
type: object
description: Percentage values by currency for percentage models.
additionalProperties:
type: number
tiers:
type: array
description: Tier definitions for tiered/volume pricing.
items:
type: object
unitAmounts:
type: object
description: Per-unit prices by currency for usage/per-unit models.
additionalProperties:
type: number
pricingSummary:
type: array
description: Textual summary of pricing for display purposes.
items:
type: string
pricingWaterfalls:
type: object
description: Detailed pricing waterfall data (if available).
additionalProperties: true
productChargeDefinitions:
type: array
description: Charge definition metadata linked to this PRPC.
items:
type: object
rateCards:
type: array
description: Conditional rate card rules configured for the charge.
items:
type: object
revenue:
type: object
description: Revenue recognition metadata for the charge.
properties:
excludeItemBillingFromRevenueAccounting:
type: boolean
description: Whether item billing is excluded from revenue accounting.
example: false
excludeItemBookingFromRevenueAccounting:
type: boolean
description: Whether item booking is excluded from revenue accounting.
example: false
legacyReporting:
type: boolean
description: Whether legacy reporting is enabled.
example: false
revenueRecognitionRuleName:
type: string
description: Revenue recognition rule applied to this charge.
example: Recognize upon invoicing
ocmJsonByCurrency:
type: object
description: Offer/charge metadata keyed by currency.
additionalProperties: true
drawdown:
type: object
description: Drawdown configuration data (if applicable).
additionalProperties: true
extendedPrice:
type: object
description: Extended price metadata (if present).
additionalProperties: true
mergedRateCards:
type: array
description: Merged/compiled rate card entries after evaluation.
items:
type: object
negotiatedRateCards:
type: array
description: Customer-specific negotiated rate card entries.
items:
type: object
additionalProperties: true
UpdateProductRequest:
type: object
description: Request body for updating a product in the Product Catalog.
properties:
id:
type: string
description: Unique identifier of the product to update.
example: 8ad088009840d1c2019855e15c993f2f
name:
type: string
description: Product name.
example: Software Service
description:
type: string
description: Product description.
example: Software service - basic edition
category:
type: string
description: Product category label, for example, base, add-on.
example: base
custom_fields:
type: object
description: |
Custom fields to set on the product. Keys must match configured custom field API names.
Values may be strings, numbers, booleans, or arrays depending on field definition.
additionalProperties: true
example:
HelloBay__c: Updated value
Tags__c:
- AI Powered
- Internet Required
startDate:
type: string
format: date
description: Product effective start date (UTC, YYYY-MM-DD).
example: '2025-05-11'
endDate:
type: string
format: date
description: Product effective end date (UTC, YYYY-MM-DD).
example: '2050-12-10'
required:
- id
UpdateProductResponse:
type: object
description: Product record returned after a successful update.
properties:
id:
type: string
description: Unique identifier of the product.
example: 00c86e3a0595442c88ed9ef8474b10a7
name:
type: string
description: Product name.
example: Amadeus
description:
type: string
description: Product description.
example: Software service - basic edition
category:
type: string
description: Product category label.
example: base
productNumber:
type: string
description: Product number in the catalog.
example: PC-00000095
sku:
type: string
description: Product SKU.
example: SKU-00000122
startDate:
type: string
format: date
description: Product effective start date (UTC, YYYY-MM-DD).
example: '2024-01-08'
endDate:
type: string
format: date
description: Product effective end date (UTC, YYYY-MM-DD).
example: '2050-12-31'
state:
type: string
description: Current product state.
example: product_active
allowFeatureChanges:
type: boolean
description: Whether features on this product can be changed.
example: false
features:
type: array
description: Product features.
items:
type: object
additionalProperties: true
legacyFeatures:
type: array
description: Legacy features associated with this product.
items:
type: object
additionalProperties: true
contextFilters:
type: array
description: Context filters applied to the product.
items:
type: object
additionalProperties: true
customFields:
type: object
description: Custom fields on the product.
additionalProperties: true
customObjects:
type: object
nullable: true
description: Custom objects linked to this product.
additionalProperties: true
netsuite:
type: object
nullable: true
description: Netsuite integration attributes.
additionalProperties: true
organizationLabels:
type: array
description: Organization labels for the product.
items:
type: string
productRatePlans:
type: array
description: Rate plans (PRPs) defined under the product.
items:
type: object
additionalProperties: true
createdBy:
type: string
description: ID of the user who created the product.
example: 8a90a2fd8030ea2e018032b11d3a3f06
createdTime:
type: string
format: date-time
description: Timestamp when the product was created.
example: '2025-08-06T18:11:35.000-07:00'
updatedBy:
type: string
description: ID of the user who last updated the product.
example: 53c162482f054f3ca08e1ec82dccfec9
updatedTime:
type: string
format: date-time
description: Timestamp when the product was last updated.
example: '2025-10-23T04:55:54.000-07:00'
CreatePlanRequest:
type: object
required:
- product_key
- name
- start_date
- end_date
- active_currencies
- charges
properties:
product_key:
type: string
description: The unique identifier of the product under which the plan is created.
example: 6b14067136304e64b090daccae6680cb
name:
type: string
description: The name of the rate plan.
example: New plan
start_date:
type: string
format: date
description: Plan effective start date (UTC, YYYY-MM-DD).
example: '2024-01-01'
end_date:
type: string
format: date
description: Plan effective end date (UTC, YYYY-MM-DD).
example: '2049-12-31'
active_currencies:
type: array
description: ISO currency codes enabled for this plan.
minItems: 1
items:
type: string
minLength: 3
maxLength: 3
example:
- USD
charges:
type: array
description: The list of product rate plan charges to create under the plan.
minItems: 1
items:
type: object
required:
- name
- charge_model
- charge_type
- bill_cycle
- trigger_event
- end_date_condition
- pricing
properties:
name:
type: string
description: The name of the charge.
example: Flat PRPC 1
charge_model:
type: string
description: Charge model that defines how pricing is calculated.
enum:
- flat_fee
- per_unit
- overage
- volume
- tiered
- tiered_overage
- discount_fixed_amount
- discount_percentage
- custom_charge_model
- delivery
- minimum_commitment_true_up
- calculated
- high_water_mark_volume_pricing
- high_water_mark_tiered_pricing
- multi_attribute_pricing
- prerated_pricing
- prerated_per_unit
example: flat_fee
charge_type:
type: string
description: Charge type (recurring, usage, or one-time).
enum:
- one_time
- recurring
- usage
example: recurring
unit_of_measure:
type: string
description: Unit of measure for per-unit or usage charges.
example: Each
list_price_base:
type: string
description: |
Optional list price base, if supported by the charge model.
enum:
- Per_Billing_Period
- Per_Month
- Per_Week
- Per_Year
- Per_Specific_Months
- Per_Validity_Period
example: Per_Billing_Period
specific_list_price_base:
type: number
format: double
description: |
Optional specific value used when `list_price_base` requires an explicit quantity (for example, number of months for `Per_Specific_Months`).
example: 0
pricing:
type: object
description: Defines the pricing for the charge. Provide exactly one structure per charge model.
oneOf:
- title: Flat Fee Pricing
type: object
required:
- flat_amounts
properties:
flat_amounts:
type: object
description: Map of currency to flat amount.
additionalProperties:
type: number
example:
USD: 100
- title: Per Unit Pricing
type: object
required:
- unit_amounts
properties:
unit_amounts:
type: object
description: Map of currency to per-unit price.
additionalProperties:
type: number
example:
USD: 5
- title: Tiered or Volume Pricing
type: object
required:
- tiers
properties:
tiers:
type: array
description: Tier definitions with optional min/max caps.
items:
type: object
required:
- tier
- from
- price_format
properties:
tier:
type: string
description: Tier identifier.
from:
type: number
description: Lower bound (inclusive).
up_to:
type: number
nullable: true
description: Upper bound (inclusive). Null for open-ended last tier.
price_format:
type: string
description: Price format identifier used for the tier.
enum:
- price_format_flat_fee
- price_format_per_unit
example: price_format_per_unit
unit_amounts:
type: object
description: Per-unit price by currency for this tier.
additionalProperties:
type: number
example:
USD: 2.5
flat_amounts:
type: object
description: Flat amount by currency for this tier (if applicable).
additionalProperties:
type: number
example:
USD: 100
min_amounts:
type: object
description: Minimum billed amount by currency for this tier.
additionalProperties:
type: number
example:
USD: 6.25
max_amounts:
type: object
description: Maximum billed amount by currency for this tier.
additionalProperties:
type: number
example:
USD: 25
- title: Fixed Amount Discount
type: object
required:
- discount_amounts
properties:
discount_amounts:
type: object
description: Map of currency to discount amount.
additionalProperties:
type: number
example:
USD: 10
- title: Percentage Discount
type: object
required:
- discount_percentage
properties:
discount_percentage:
type: number
format: double
description: Discount percentage (e.g., 15 for 15%).
example: 15
bill_cycle:
type: object
description: Defines how billing occurs for this charge.
required:
- type
- period
- period_alignment
properties:
type:
type: string
description: |
Determines how the billing day is selected for this charge.
enum:
- default_from_customer
- specific_day_of_month
- subscription_start_day
- charge_trigger_day
- specific_day_of_week
- term_start_day
- term_end_day
example: specific_day_of_month
day_of_month:
type: integer
minimum: 1
maximum: 31
description: Required "when type is specific_day_of_month".
example: 5
day_of_week:
type: string
description: |
Used "when type is specific_day_of_week".
enum:
- sunday
- monday
- tuesday
- wednesday
- thursday
- friday
- saturday
period:
type: string
description: |
Billing period length.
enum:
- bill_cycle_period_month
- bill_cycle_period_quarter
- bill_cycle_period_semi_annual
- bill_cycle_period_annual
- bill_cycle_period_eighteen_months
- bill_cycle_period_two_years
- bill_cycle_period_three_years
- bill_cycle_period_five_years
- bill_cycle_period_specific_months
- bill_cycle_period_subscription_term
- bill_cycle_period_week
- bill_cycle_period_specific_weeks
- bill_cycle_period_specific_days
example: bill_cycle_period_month
period_alignment:
type: string
description: |
How the billing period start aligns.
enum:
- align_to_charge
- align_to_subscription_start
- align_to_term_start
- align_to_term_end
example: align_to_charge
timing:
type: string
description: |
When the charge is billed relative to the service period.
enum:
- in_advance
- in_arrears
example: in_advance
end_date_condition:
type: string
description: |
Defines when the charge ends.
enum:
- subscription_end
- end_date_one_time
- fixed_period
- specific_end_date
example: subscription_end
up_to_periods_type:
type: string
description: |
Granularity used with `end_date_condition = fixed_period` to express how long the charge remains active. When `end_date_condition = subscription_end`, this field is ignored.
enum:
- billing_periods
- days
- weeks
- months
- years
example: billing_periods
up_to_periods:
type: integer
format: int32
description: |
Number of periods used with `end_date_condition = fixed_period`. Combined with `up_to_periods_type` to determine the fixed duration of the charge. Ignored when `end_date_condition = subscription_end`.
example: 0
trigger_event:
type: string
description: |
Event that triggers the charge.
enum:
- contract_effective
- service_activation
- customer_acceptance
- specific_date
example: contract_effective
accounting:
$ref: '#/components/schemas/AccountingRequest'
example:
product_key: 6b14067136304e64b090daccae6680cb
name: New plan
start_date: '2024-01-01'
end_date: '2049-12-31'
active_currencies:
- USD
charges:
- name: Flat PRPC 1
charge_model: flat_fee
charge_type: recurring
pricing:
flat_amounts:
USD: 100
bill_cycle:
type: specific_day_of_month
day_of_month: 5
period_alignment: align_to_charge
period: bill_cycle_period_month
timing: in_advance
end_date_condition: subscription_end
trigger_event: contract_effective
accounting:
accounting_code: PRPC-REV-002
accounts_receivable_account: Accounts Receivable
deferred_revenue_account: Deferred Revenue
recognized_revenue_account: Recognized Revenue
adjustment_liability_account: adjustL-2
adjustment_revenue_account: adjustRev-2
contract_asset_account: CA-3
contract_liability_account: CL-3
contract_recognized_revenue_account: Contract Recognized Revenue
unbilled_receivables_account: unbilledR-2
- name: Flat PRPC 2
charge_model: flat_fee
charge_type: recurring
pricing:
flat_amounts:
USD: 100
bill_cycle:
type: specific_day_of_month
day_of_month: 5
period_alignment: align_to_charge
period: bill_cycle_period_month
timing: in_advance
end_date_condition: subscription_end
trigger_event: contract_effective
accounting:
accounting_code: PRPC-REV-002
accounts_receivable_account: Accounts Receivable
deferred_revenue_account: Deferred Revenue
recognized_revenue_account: Recognized Revenue
adjustment_liability_account: adjustL-2
adjustment_revenue_account: adjustRev-2
contract_asset_account: CA-3
contract_liability_account: CL-3
contract_recognized_revenue_account: Contract Recognized Revenue
unbilled_receivables_account: unbilledR-2
CreatePlanResponse:
type: object
required:
- id
- name
- startDate
- endDate
- activeCurrencies
properties:
id:
type: string
description: The unique identifier of the created plan (product rate plan).
example: ee2d1ce1036c4dd6ae9d6945565ff7a0
name:
type: string
description: Plan display name.
example: New plan
displayName:
type: string
description: The display name of the plan.
example: ''
description:
type: string
description: Free-form plan description.
example: ''
state:
type: string
description: Current lifecycle state of the plan.
example: active
startDate:
type: string
format: date
description: Plan effective start date (UTC, YYYY-MM-DD).
example: '2024-01-01'
endDate:
type: string
format: date
description: Plan effective end date (UTC, YYYY-MM-DD).
example: '2049-12-31'
activeCurrencies:
type: array
description: ISO currency codes enabled for the plan.
items:
type: string
example:
- USD
createTime:
type: string
format: date-time
description: Timestamp when the plan was created.
example: '2025-10-13T07:46:02.314-07:00'
updateTime:
type: string
format: date-time
description: Timestamp when the plan was last updated.
example: '2025-10-13T07:46:02.314-07:00'
createdBy:
type: string
description: User ID that created the plan.
example: 53c162482f054f3ca08e1ec82dccfec9
updatedBy:
type: string
description: User ID that last updated the plan.
example: 53c162482f054f3ca08e1ec82dccfec9
productId:
type: string
description: The product ID (key) this plan belongs to.
example: 7228c9e6fd814e3a9e59bcdf0117e34f
productRatePlanNumber:
type: string
description: Plan number
example: PRP-00000195
customFields:
type: object
description: Custom field values on the plan.
additionalProperties: true
attributes:
type: array
description: Attribute metadata defined at the plan level (if any).
items:
type: object
contextFilters:
type: array
description: Contextual filters used to limit plan applicability.
items:
type: object
entitlements:
type: array
description: Entitlements included with the plan.
items:
type: object
externalIdSourceSystem:
type: string
description: Source system identifier for external integrations.
example: ''
externalRateplanId:
type: array
description: External rate plan identifiers, if any.
items:
type: string
organizationLabels:
type: array
description: Organization-level labels associated with the plan.
items:
type: object
netsuite:
type: object
nullable: true
description: NetSuite integration metadata (if present).
example: null
productRatePlanCharges:
type: array
description: Charges created under this plan.
items:
type: object
required:
- id
- name
- chargeModel
- chargeType
- pricing
- billCycle
properties:
id:
type: string
description: Unique identifier of the product rate plan charge (PRPC).
example: ad95b694d2b8442b84dc8ad26561c7d7
name:
type: string
description: Charge display name within the plan.
example: Flat PRPC 1
chargeModel:
type: string
description: Pricing model that determines how the amount is calculated.
example: flat_fee
chargeType:
type: string
description: Whether the charge recurs, rates usage, or is a one-time fee.
example: recurring
chargeFunction:
type: string
description: Internal function identifier for the charge.
example: charge_function_standard
productRatePlanChargeNumber:
type: string
description: PRPC number
example: PRPC-00000279
triggerEvent:
type: string
description: Event that triggers the charge to start billing.
example: contract_effective
endDateCondition:
type: string
description: Rule for when the charge ends, for example, subscription_end.
example: subscription_end
upToPeriodsType:
type: string
description: Unit applied when charge ends after a fixed duration.
example: billing_periods
upToPeriods:
type: number
description: Number of periods defining fixed charge duration.
example: 0
listPriceBase:
type: string
description: List price basis, for example, Per_Billing_Period.
example: Per_Billing_Period
specificListPriceBase:
type: number
description: |
Optional override for list price base when billing uses a specific period configuration.
example: 0
billCycle:
type: object
description: How and when this charge bills within each billing period.
properties:
type:
type: string
description: Bill-cycle mode (inherit defaults or set specific day rules).
example: specific_day_of_month
dayOfMonth:
type: integer
description: Specific bill day when type = specific_day_of_month.
example: 5
period:
type: string
description: Billing period length, for example, bill_cycle_period_month.
example: bill_cycle_period_month
periodAlignment:
type: string
description: How the billing period start aligns, for example, align_to_charge.
example: align_to_charge
timing:
type: string
description: Whether the charge bills before or after the service period.
example: in_advance
accounting:
$ref: '#/components/schemas/AccountingResponse'
pricing:
type: object
description: Default (charge-level) price configuration by model/currency.
properties:
flatAmounts:
type: object
additionalProperties:
type: number
description: Flat amounts by currency for flat-fee pricing.
example:
USD: 100
unitAmounts:
type: object
additionalProperties:
type: number
description: Per-unit amounts by currency for per-unit/usage pricing.
tiers:
type: array
items:
type: object
description: Tier definitions for tiered/volume pricing.
discountAmounts:
type: object
additionalProperties:
type: number
description: Fixed discount amounts by currency.
discountPercentages:
type: object
additionalProperties:
type: number
description: Percentage discount values by currency.
minAmounts:
type: object
additionalProperties:
type: number
description: Minimum charge amounts by currency.
maxAmounts:
type: object
additionalProperties:
type: number
description: Maximum charge amounts by currency.
percentages:
type: object
additionalProperties:
type: number
description: Percentage price values by currency (model-dependent).
priceChangeOption:
type: string
description: How price changes are applied across renewals/amendments.
example: no_change
prorationOption:
type: string
description: How proration is handled relative to tenant defaults.
example: default_from_tenant_setting
taxable:
type: boolean
description: Whether the charge is taxable.
example: false
discountOptions:
type: object
description: How discount charges apply and interact with other discounts.
properties:
stackedDiscount:
type: boolean
description: Whether this discount stacks with other discounts.
example: false
applyToBillingPeriodPartially:
type: boolean
description: Whether the discount can partially align to a billing period.
example: false
reflectDiscountInNetAmount:
type: boolean
description: Whether discounts reduce the net amount on invoices.
example: false
rollover:
type: boolean
description: Whether unused discount can roll over to future periods.
example: false
attributes:
type: array
description: Attribute metadata for this charge.
items:
type: object
createdById:
type: string
description: User ID that created the charge record.
example: 53c162482f054f3ca08e1ec82dccfec9
createdTime:
type: string
format: date-time
description: Timestamp when the charge record was created.
example: '2025-10-13T07:46:02.375-07:00'
updatedById:
type: string
description: User ID that last updated the charge record.
example: 53c162482f054f3ca08e1ec82dccfec9
updatedTime:
type: string
format: date-time
description: Timestamp when the charge record was last updated.
example: '2025-10-13T07:46:02.375-07:00'
labels:
type: object
additionalProperties: true
description: Free-form labels/tags attached to the charge.
mergedRateCards:
type: array
items:
type: object
description: Effective rate-card rows after merges (if any).
negotiatedRateCards:
type: array
items:
type: object
description: Customer- or deal-specific rate-card rows.
ocmJsonByCurrency:
type: object
additionalProperties: true
description: Offer/OCM metadata keyed by currency (internal use).
productChargeDefinitions:
type: array
items:
type: object
description: Underlying charge definitions referenced for pricing.
rateCards:
type: array
items:
type: object
description: Dynamic Pricing rate-card rows configured on the charge.
pricingSummary:
type: array
items:
type: object
description: Structured price summary breakdown (if returned).
pricingWaterfalls:
type: object
additionalProperties: true
description: Detailed pricing/waterfall breakdown (if returned).
overageOptions:
type: object
description: Overage settings for usage charges.
properties:
includedUnits:
type: number
description: Included units before overage starts.
example: 0
unusedUnitsCreditRates:
type: object
additionalProperties:
type: number
description: Credit rates for unused units (by currency).
prepaid:
type: boolean
description: Indicates whether the charge is prepaid.
example: false
prepayment:
type: object
description: Prepayment handling and rollover behavior.
properties:
rollover:
type: boolean
description: Whether unused prepayment rolls over.
example: false
rolloverApply:
type: string
description: Order in which rollover is applied.
example: apply_last
rolloverPeriodLength:
type: integer
description: Length of each rollover period.
example: 0
rolloverPeriods:
type: integer
description: Number of rollover periods allowed.
example: 0
isChargeLevelMinCommit:
type: boolean
description: Whether a minimum commit is enforced at the charge level.
example: false
isCommitted:
type: boolean
description: Indicates if the charge definition is committed/finalized.
example: false
useTenantDefaultForPriceChange:
type: boolean
description: Whether tenant defaults govern price change behavior.
example: true
revenue:
type: object
description: Revenue policy settings for this charge.
properties:
excludeItemBillingFromRevenueAccounting:
type: boolean
description: If true, item billing is excluded from revenue accounting.
example: false
excludeItemBookingFromRevenueAccounting:
type: boolean
description: If true, item booking is excluded from revenue accounting.
example: false
legacyReporting:
type: boolean
description: Indicator for legacy revenue reporting behaviors.
example: false
revenueRecognitionRuleName:
type: string
description: Name of the revenue recognition rule applied.
example: Recognize upon invoicing
additionalProperties: true
additionalProperties: true
UpdatePlanRequest:
type: object
description: Request body for updating a Product Rate Plan (PRP).
properties:
id:
type: string
description: Unique identifier of the Product Rate Plan to update.
example: 5758b1d5a589840e0e6855e1c2ce014d
name:
type: string
description: Rate plan name.
example: Bronze Plan
description:
type: string
description: Rate plan description.
example: Basic version of our software service
grade:
type: integer
description: Plan grade or display rank used for ordering in catalogs or UIs.
example: 1
startDate:
type: string
format: date
description: Rate plan effective start date (UTC, YYYY-MM-DD).
example: '2025-09-10'
endDate:
type: string
format: date
description: Rate plan effective end date (UTC, YYYY-MM-DD).
example: '2043-08-16'
required:
- id
UpdatePlanResponse:
type: object
description: Product Rate Plan record returned after a successful update.
properties:
id:
type: string
description: Unique identifier of the Product Rate Plan (PRP).
example: 38660706ef2f48cfb5222f7dde491895
name:
type: string
description: Rate plan name.
example: Bronze Plan
description:
type: string
description: Rate plan description.
example: Basic version of our software service
productId:
type: string
description: Owning product ID.
example: 8a90aac8948deebf01949098b7790326
productRatePlanNumber:
type: string
description: Rate plan number.
example: PRP-00000172
startDate:
type: string
format: date
description: Rate plan effective start date (UTC, YYYY-MM-DD).
example: '2025-09-10'
endDate:
type: string
format: date
description: Rate plan effective end date (UTC, YYYY-MM-DD).
example: '2027-01-01'
state:
type: string
description: Current rate plan state.
example: active
status:
type: string
description: Rate plan status.
example: ACTIVE
activeCurrencies:
type: array
description: Currencies with active pricing.
items:
type: string
example:
- USD
displayName:
type: string
description: Product rate plan display name.
example: ''
attributes:
type: array
description: Attribute definitions associated with the plan.
items:
type: object
additionalProperties: true
contextFilters:
type: array
description: Context filters at the plan level.
items:
type: object
additionalProperties: true
entitlements:
type: array
description: Entitlements linked to the plan.
items:
type: object
additionalProperties: true
externalIdSourceSystem:
type: string
description: External ID source system.
example: ''
externalRateplanId:
type: array
description: External plan identifiers.
items:
type: string
netsuite:
type: object
description: Netsuite integration attributes.
additionalProperties: true
organizationLabels:
type: array
description: Organization labels.
items:
type: string
customFields:
type: object
description: Custom fields at the plan level.
additionalProperties: true
productRatePlanCharges:
type: array
description: Charges (PRPCs) that belong to this product rate plan.
items:
type: object
properties:
id:
type: string
description: Unique identifier of the Product Rate Plan Charge (PRPC).
example: 99e226fec45943f4b80ed7bcf6d595d7
name:
type: string
description: Charge name.
example: disc_currency
chargeType:
type: string
description: Charge type.
example: recurring
chargeModel:
type: string
description: Charge model.
example: discount_percentage
listPriceBase:
type: string
description: Indicates how list price is interpreted.
example: Per_Billing_Period
triggerEvent:
type: string
description: Event that triggers the charge.
example: contract_effective
billCycle:
type: object
description: Billing cycle configuration.
additionalProperties: true
example:
period: bill_cycle_period_quarter
periodAlignment: align_to_term_start
type: term_start_day
pricing:
type: object
description: Pricing configuration for the charge.
additionalProperties: true
example:
discountPercentages:
USD: 10
tiers: []
prepayment:
type: object
description: Prepayment options for the charge (when applicable).
additionalProperties: true
taxMode:
type: string
description: Tax mode for this charge, for example, non_taxable or taxable.
example: non_taxable
taxable:
type: boolean
description: Indicates whether the charge is taxable.
example: false
createdById:
type: string
description: ID of the user who created the charge.
createdTime:
type: string
format: date-time
description: Timestamp when the charge was created.
updatedById:
type: string
description: ID of the user who last updated the charge.
updatedTime:
type: string
format: date-time
description: Timestamp when the charge was last updated.
accounting:
type: object
additionalProperties: true
description: Accounting configuration for the charge (for example, account mappings and posting preferences).
attributes:
type: array
items:
type: object
additionalProperties: true
description: Attribute definitions bound to this charge (used for dynamic pricing or evaluation).
customFields:
type: object
additionalProperties: true
description: Custom fields on the charge.
deliverySchedule:
type: object
additionalProperties: true
description: Delivery schedule settings, for example, frequency and applicable days.
discountOptions:
type: object
additionalProperties: true
description: Discount configuration for this charge, including scope, stacking, and net-amount reflection.
drawdown:
type: object
additionalProperties: true
description: Drawdown configuration for consuming balances or entitlements.
endDateCondition:
type: string
description: Defines when the charge ends, for example, subscription_end or after a term.
extendedPrice:
type: object
additionalProperties: true
description: Calculated extended price details, if applicable.
isChargeLevelMinCommit:
type: boolean
description: Indicates whether a minimum commitment is enforced at the charge level.
isCommitted:
type: boolean
description: Indicates whether this charge is part of a committed contract.
labels:
type: object
additionalProperties: true
description: Key-value metadata labels associated with the charge.
mergedRateCards:
type: array
items:
type: object
additionalProperties: true
description: Effective rate card entries after merging default and negotiated cards.
negotiatedRateCards:
type: array
items:
type: object
additionalProperties: true
description: Customer- or segment-specific negotiated rate card entries.
ocmJsonByCurrency:
type: object
additionalProperties: true
description: Per-currency pricing/configuration metadata in JSON format.
organizationLabels:
type: array
items:
type: string
description: Organization labels attached to the charge.
overageOptions:
type: object
additionalProperties: true
description: Overage configuration, for example, included units and unused-unit credit rates.
prepaid:
type: boolean
description: Indicates whether the charge is prepaid.
priceChangeOption:
type: string
description: How price changes are handled on updates, for example, no_change.
pricingSummary:
type: array
items:
type: string
description: Human-readable pricing summary lines.
pricingWaterfalls:
type: object
additionalProperties: true
description: Pricing source breakdown, for example, base price vs. segment price.
productChargeDefinitions:
type: array
items:
type: object
additionalProperties: true
description: Charge definition objects that specify pricing and behavioral rules.
productRatePlanChargeNumber:
type: string
description: Charge number (PRPC number) for this charge.
productRatePlanId:
type: string
description: Owning Product Rate Plan ID.
prorationOption:
type: string
description: Proration behavior for this charge.
rateCards:
type: array
items:
type: object
additionalProperties: true
description: Associated rate card definitions used for dynamic or segmented pricing.
revenue:
type: object
additionalProperties: true
description: Revenue recognition configuration, for example, rules and codes.
taxCode:
type: string
description: Tax code applied to the charge for taxation purposes.
createTime:
type: string
format: date-time
description: Plan creation time.
example: '2025-02-24T01:20:44.000+00:00'
updateTime:
type: string
format: date-time
description: Plan update time.
example: '2025-10-23T05:16:28.334+00:00'
createdBy:
type: string
description: ID of the user who created the plan.
example: 8a90a2fd8030ea2e018032b11d3a3f06
updatedBy:
type: string
description: ID of the user who updated the plan.
example: 53c162482f054f3ca08e1ec82dccfec9
ListPlansRequest:
type: object
description: Request body for retrieving Product Rate Plans from the Product Catalog.
properties:
filters:
type: array
description: |
Filter conditions for querying product rate plans.
Each filter defines a field, operator, and value.
items:
type: object
required:
- field
- operator
- value
properties:
field:
type: string
description: Field name to filter by, such as `prp_id`, `product_id`, or `name`.
example: prp_id
operator:
type: string
description: |
Comparison operator for the filter condition. Supported values:
- `EQ` (equals)
- `NE` (not equals)
- `IN` (in a list of values)
- `LIKE` (partial match)
- `GT` (greater than)
- `GTE` (greater than or equal)
- `LT` (less than)
- `LTE` (less than or equal)
- `SW` (starts with)
- `EW` (ends with)
enum:
- EQ
- NE
- IN
- LIKE
- GT
- GTE
- LT
- LTE
- SW
- EW
example: EQ
value:
type: string
description: Value to match for the specified field.
example: 38660706ef2f48cfb5222f7dde491895
expand:
type: object
description: Expand related entities in the response.
properties:
product_rate_plan_charges:
type: boolean
description: Whether to include associated Product Rate Plan Charges (PRPCs).
example: true
required:
- filters
ListPlansResponse:
type: object
description: Response body containing a list of Product Rate Plans.
properties:
values:
type: array
description: List of Product Rate Plans returned by the query.
items:
type: object
properties:
id:
type: string
description: Unique identifier of the Product Rate Plan.
example: 38660706ef2f48cfb5222f7dde491895
name:
type: string
description: Product Rate Plan name.
example: Bronze Plan
description:
type: string
description: Product Rate Plan description.
example: Basic version of our software service
productId:
type: string
description: Identifier of the product this plan belongs to.
example: 8a90aac8948deebf01949098b7790326
startDate:
type: string
format: date
description: Effective start date of the plan (UTC, YYYY-MM-DD).
example: '2025-09-10'
endDate:
type: string
format: date
description: Effective end date of the plan (UTC, YYYY-MM-DD).
example: '2027-01-01'
state:
type: string
description: Current plan state.
example: active
status:
type: string
description: Status of the plan.
example: ACTIVE
activeCurrencies:
type: array
items:
type: string
description: Currencies supported by this plan.
example:
- USD
accounting:
$ref: '#/components/schemas/AccountingResponse'
productRatePlanNumber:
type: string
description: Product Rate Plan number.
example: PRP-00000172
productRatePlanCharges:
type: array
description: List of Product Rate Plan Charges (PRPCs) belonging to the plan.
items:
type: object
properties:
id:
type: string
description: Unique identifier of the Product Rate Plan Charge.
example: fe9b0e764dca4178a11c0e471e5dc0d8
name:
type: string
description: Charge name.
example: prepay_currency
chargeType:
type: string
description: Charge type (recurring, one_time, or usage).
example: recurring
chargeModel:
type: string
description: Charge model (flat_fee, per_unit, tiered, etc.).
example: flat_fee
listPriceBase:
type: string
description: Indicates how list price is interpreted.
example: Per_Billing_Period
specificListPriceBase:
type: number
description: |
Optional override for list price base when billing uses a specific period configuration.
example: 0
triggerEvent:
type: string
description: Event that triggers the charge.
example: contract_effective
unitOfMeasure:
type: string
description: Unit of measure used for pricing (for example, Each).
example: Each
defaultQuantity:
type: number
description: Default quantity applied for the charge.
example: 1
endDateCondition:
type: string
description: Condition that determines when the charge ends.
example: subscription_end
upToPeriodsType:
type: string
description: Unit applied when charge ends after a fixed duration.
example: billing_periods
upToPeriods:
type: number
description: Number of periods defining fixed charge duration.
example: 0
billCycle:
type: object
description: Billing cycle configuration.
additionalProperties: true
example:
period: bill_cycle_period_quarter
periodAlignment: align_to_term_start
timing: in_advance
type: term_start_day
pricing:
type: object
description: Pricing configuration for the charge.
additionalProperties: true
example:
flatAmounts:
USD: 30
tiers: []
pricingSummary:
type: array
items:
type: string
description: Human-readable pricing summary lines.
example:
- USD30
taxMode:
type: string
description: Tax mode for this charge.
example: non_taxable
taxable:
type: boolean
description: Indicates whether the charge is taxable.
example: false
createdById:
type: string
description: ID of the user who created the charge.
example: 8a90a2fd8030ea2e018032b11d3a3f06
createdTime:
type: string
format: date-time
description: Timestamp when the charge was created.
example: '2025-02-24T01:21:23.000+00:00'
updatedById:
type: string
description: ID of the user who last updated the charge.
example: 8a90a2fd8030ea2e018032b11d3a3f06
updatedTime:
type: string
format: date-time
description: Timestamp when the charge was last updated.
example: '2025-02-24T01:21:23.000+00:00'
GetProductByKeyResponse:
type: object
description: Response body returned when retrieving a product by product key.
properties:
allowFeatureChanges:
type: boolean
example: false
category:
type: string
description: Product category, for example `base` or `add_on`.
example: base
contextFilters:
type: array
items:
type: object
createdBy:
type: string
description: ID of the user who created the product.
example: 53c162482f054f3ca08e1ec82dccfec9
createdTime:
type: string
format: date-time
example: '2025-10-13T07:44:55.000-07:00'
customFields:
type: object
description: Custom field values keyed by API name.
additionalProperties: true
customObjects:
type: object
nullable: true
description: Custom object references related to this product.
example: null
dacTag:
type: object
description: Internal DAC tag associated with the product.
properties:
id:
type: string
description: DAC tag identifier.
example: 1234567890abcdef
name:
type: string
description: DAC tag name.
example: Example DAC Tag
endDate:
type: string
format: date
description: Product effective end date.
example: '2050-12-31'
features:
type: array
items:
type: object
id:
type: string
description: Unique identifier of the product.
example: 7228c9e6fd814e3a9e59bcdf0117e34f
legacyFeatures:
type: array
description: Legacy, customer-defined feature objects retained for compatibility.
items:
type: object
additionalProperties: true
name:
type: string
description: Product name.
example: New prod
netsuite:
type: object
nullable: true
description: NetSuite integration metadata if applicable.
example: null
organizationLabels:
type: array
items:
type: object
productNumber:
type: string
description: System-generated product number.
example: PC-00000103
productRatePlans:
type: array
description: List of rate plans under this product.
items:
type: object
properties:
id:
type: string
description: Unique identifier of the Product Rate Plan.
example: 38660706ef2f48cfb5222f7dde491895
createdBy:
type: string
description: ID of the user who created the rate plan.
example: 53c162482f054f3ca08e1ec82dccfec9
createTime:
type: string
format: date-time
description: Timestamp when the rate plan was created.
example: '2025-02-24T01:21:23.000+00:00'
updatedBy:
type: string
description: ID of the user who last updated the rate plan.
example: 53c162482f054f3ca08e1ec82dccfec9
updateTime:
type: string
format: date-time
description: Timestamp when the rate plan was last updated.
example: '2025-02-24T01:21:23.000+00:00'
name:
type: string
description: Product Rate Plan name.
example: Bronze Plan
displayName:
type: string
description: Product Rate Plan display name.
example: Bronze Plan
description:
type: string
description: Product Rate Plan description.
example: Basic version of our software service
productId:
type: string
description: Identifier of the product this plan belongs to.
example: 7228c9e6fd814e3a9e59bcdf0117e34f
startDate:
type: string
format: date
description: Effective start date of the plan (UTC, YYYY-MM-DD).
example: '2025-09-10'
endDate:
type: string
format: date
description: Effective end date of the plan (UTC, YYYY-MM-DD).
example: '2027-01-01'
state:
type: string
description: Current plan state.
example: active
status:
type: string
description: Status of the plan.
example: ACTIVE
activeCurrencies:
type: array
items:
type: string
description: Currencies supported by this plan.
example:
- USD
productRatePlanNumber:
type: string
description: Product Rate Plan number.
example: PRP-00000172
productRatePlanCharges:
type: array
description: List of Product Rate Plan Charges (PRPCs) belonging to the plan.
items:
type: object
properties:
id:
type: string
description: Unique identifier of the Product Rate Plan Charge.
example: fe9b0e764dca4178a11c0e471e5dc0d8
productRatePlanChargeNumber:
type: string
description: System-generated number of the Product Rate Plan Charge.
example: PRPC-00000279
name:
type: string
description: Charge name.
example: prepay_currency
description:
type: string
description: Charge description.
example: Prepaid recurring software fee
chargeType:
type: string
description: Charge type (recurring, one_time, or usage).
example: recurring
chargeModel:
type: string
description: Charge model (flat_fee, per_unit, tiered, etc.).
example: flat_fee
listPriceBase:
type: string
description: Indicates how list price is interpreted.
example: Per_Billing_Period
specificListPriceBase:
type: integer
description: Specifies the number of periods for list price when listPriceBase is period-based.
example: 1
triggerEvent:
type: string
description: Event that triggers the charge.
example: contract_effective
endDateCondition:
type: string
description: Condition that determines when the charge ends.
example: subscription_end
upToPeriodsType:
type: string
description: Type of period used with `upToPeriods` to control charge duration.
example: billing_periods
upToPeriods:
type: integer
description: Number of periods after which the charge ends, based on `upToPeriodsType`.
example: 1
billCycle:
type: object
description: Billing cycle configuration.
additionalProperties: true
example:
period: bill_cycle_period_quarter
periodAlignment: align_to_term_start
timing: in_advance
type: term_start_day
pricing:
type: object
description: Pricing configuration for the charge.
additionalProperties: true
example:
flatAmounts:
USD: 30
tiers: []
pricingSummary:
type: array
items:
type: string
description: Human-readable pricing summary lines.
example:
- USD30
taxMode:
type: string
description: Tax mode for this charge.
example: non_taxable
taxable:
type: boolean
description: Indicates whether the charge is taxable.
example: false
createdById:
type: string
description: ID of the user who created the charge.
example: 53c162482f054f3ca08e1ec82dccfec9
createdTime:
type: string
format: date-time
description: Timestamp when the charge was created.
example: '2025-02-24T01:21:23.000+00:00'
updatedById:
type: string
description: ID of the user who last updated the charge.
example: 53c162482f054f3ca08e1ec82dccfec9
updatedTime:
type: string
format: date-time
description: Timestamp when the charge was last updated.
example: '2025-02-24T01:21:23.000+00:00'
sku:
type: string
description: Stock keeping unit for the product.
example: SKU-00000133
startDate:
type: string
format: date
description: Product effective start date.
example: '2024-01-01'
state:
type: string
description: Current product state.
example: product_active
updatedBy:
type: string
description: ID of the user who last updated the product.
example: 53c162482f054f3ca08e1ec82dccfec9
updatedTime:
type: string
format: date-time
description: Timestamp of the last update.
example: '2025-10-13T07:44:55.000-07:00'
example:
allowFeatureChanges: false
category: base
contextFilters: []
createdBy: 53c162482f054f3ca08e1ec82dccfec9
createdTime: '2025-10-13T07:44:55.000-07:00'
customFields: {}
customObjects: null
dacTag:
id: 1234567890abcdef
name: Example DAC Tag
endDate: '2050-12-31'
features: []
id: 7228c9e6fd814e3a9e59bcdf0117e34f
legacyFeatures: []
name: New prod
netsuite: null
organizationLabels: []
productNumber: PC-00000103
productRatePlans:
- id: 38660706ef2f48cfb5222f7dde491895
createdBy: 53c162482f054f3ca08e1ec82dccfec9
createTime: '2025-02-24T01:21:23.000+00:00'
updatedBy: 53c162482f054f3ca08e1ec82dccfec9
updateTime: '2025-02-24T01:21:23.000+00:00'
name: Bronze Plan
displayName: Bronze Plan
description: Basic version of our software service
productId: 7228c9e6fd814e3a9e59bcdf0117e34f
startDate: '2025-09-10'
endDate: '2027-01-01'
state: active
status: ACTIVE
activeCurrencies:
- USD
productRatePlanNumber: PRP-00000172
productRatePlanCharges:
- id: fe9b0e764dca4178a11c0e471e5dc0d8
productRatePlanChargeNumber: PRPC-00000279
name: prepay_currency
description: Prepaid recurring software fee
chargeType: recurring
chargeModel: flat_fee
listPriceBase: Per_Billing_Period
specificListPriceBase: 1
triggerEvent: contract_effective
endDateCondition: subscription_end
upToPeriodsType: billing_periods
upToPeriods: 1
billCycle:
period: bill_cycle_period_quarter
periodAlignment: align_to_term_start
timing: in_advance
type: term_start_day
pricing:
flatAmounts:
USD: 30
tiers: []
pricingSummary:
- USD30
taxMode: non_taxable
taxable: false
createdById: 53c162482f054f3ca08e1ec82dccfec9
createdTime: '2025-02-24T01:21:23.000+00:00'
updatedById: 53c162482f054f3ca08e1ec82dccfec9
updatedTime: '2025-02-24T01:21:23.000+00:00'
sku: SKU-00000133
startDate: '2024-01-01'
state: product_active
updatedBy: 53c162482f054f3ca08e1ec82dccfec9
updatedTime: '2025-10-13T07:44:55.000-07:00'
CreateProductListLegacyRequest:
type: object
description: Request body for querying legacy products in the Product Catalog.
properties:
filters:
type: array
description: |
Filter conditions for querying legacy products.
Each filter defines a field, an operator, and a value to match against.
Common filter fields include `id`, `name`, `product_number`, or `category`.
items:
type: object
required:
- field
- operator
- value
properties:
field:
type: string
description: |
Field name to filter by.
example: id
enum:
- id
- name
- product_number
- category
operator:
type: string
description: |
Comparison operator for the filter condition.
Supported values:
- `EQ` (equals)
- `NE` (not equals)
- `LT` (less than)
- `GT` (greater than)
- `SW` (starts with)
- `EW` (ends with)
- `IN` (in list of values)
- `LIKE` (partial match)
example: EQ
enum:
- EQ
- NE
- LT
- GT
- SW
- IN
- EW
- LIKE
value:
type: string
description: |
Value to match for the specified field.
The data type depends on the field being filtered.
example: 8a90850b963680cb01963ad92a7a46e0
expand:
type: object
description: |
Defines whether to include related entities such as Product Rate Plans (PRPs) and
Product Rate Plan Charges (PRPCs) in the response. Each key corresponds to an entity type that can be expanded.
properties:
product_rate_plans:
type: boolean
description: When true, includes Product Rate Plans (PRPs) under each product.
example: true
product_rate_plan_charges:
type: boolean
description: When true, includes Product Rate Plan Charges (PRPCs) for each rate plan.
example: true
example:
filters:
- field: id
operator: EQ
value: 8a90850b963680cb01963ad92a7a46e0
expand:
product_rate_plans: true
product_rate_plan_charges: true
CreateProductListLegacyResponse:
type: object
description: Response body returned after querying legacy products.
properties:
values:
type: array
description: List of legacy products matching the query.
items:
type: object
properties:
id:
type: string
description: Unique identifier of the product.
example: 1a951a549f464e93bea1bfe7b8ffce1f
name:
type: string
description: Product name.
example: ABP demo product
description:
type: string
description: Product description.
example: ''
category:
type: string
description: Product category label.
example: Add On Services
productNumber:
type: string
description: Product number in the catalog.
example: PC-00011567
sku:
type: string
description: Product SKU.
example: SKU-00011727
effectiveStartDate:
type: string
format: date
description: Date when the product becomes effective in the catalog.
example: '2025-05-01'
effectiveEndDate:
type: string
format: date
description: Date when the product is no longer effective in the catalog.
example: '2025-05-31'
state:
type: string
description: Current product state.
example: active
allowFeatureChanges:
type: boolean
description: Whether features on this product can be changed.
example: false
contextFilters:
type: array
description: Context filters applied to the product.
items:
type: object
additionalProperties: true
features:
type: array
description: Product features.
items:
type: object
additionalProperties: true
legacyFeatures:
type: array
description: Legacy features associated with this product.
items:
type: object
additionalProperties: true
customFields:
type: object
description: Custom fields on the product.
additionalProperties: true
example:
DecimalNumber__c: 1.12
test5bool__c: true
customObjects:
type: object
nullable: true
description: Custom objects linked to this product.
additionalProperties: true
netsuite:
type: object
description: Netsuite integration attributes.
additionalProperties: true
organizationLabels:
type: array
description: Organization labels for the product.
items:
type: string
createdBy:
type: string
description: ID of the user who created the product.
example: 34aa321aa7cd46d19bebcf9c090af7a0
createdTime:
type: string
format: date-time
description: Timestamp when the product was created.
example: '2025-05-01T19:32:51.000+00:00'
updatedBy:
type: string
description: ID of the user who last updated the product.
example: 34aa321aa7cd46d19bebcf9c090af7a0
updatedTime:
type: string
format: date-time
description: Timestamp when the product was last updated.
example: '2025-05-12T08:19:44.000+00:00'
productRatePlans:
type: array
description: Product rate plans (PRPs) of the product.
items:
type: object
properties:
id:
type: string
description: Unique identifier of the Product Rate Plan.
example: c3a52dd029704b7e89274c9e7e8fd99c
name:
type: string
description: Rate plan name.
example: Demo Rate Plan
description:
type: string
description: Rate plan description.
example: ''
displayName:
type: string
description: Rate plan display name.
example: ''
state:
type: string
description: Current rate plan state.
example: active
effectiveStartDate:
type: string
format: date
description: Effective start date of the rate plan.
example: '2025-05-01'
effectiveEndDate:
type: string
format: date
description: Effective end date of the rate plan.
example: '2025-05-31'
activeCurrencies:
type: array
description: Currencies with active pricing.
items:
type: string
example:
- USD
productId:
type: string
description: Owning product ID.
example: 1a951a549f464e93bea1bfe7b8ffce1f
productRatePlanNumber:
type: string
description: Rate plan number.
example: PRP-00012518
attributes:
type: array
description: Attribute definitions associated with the plan.
items:
type: object
additionalProperties: true
contextFilters:
type: array
description: Context filters at the plan level.
items:
type: object
additionalProperties: true
customFields:
type: object
description: Custom fields at the plan level.
additionalProperties: true
entitlements:
type: array
description: Entitlements linked to the plan.
items:
type: object
additionalProperties: true
externalIdSourceSystem:
type: string
description: External ID source system.
example: ''
externalManagedPlanIds:
type: array
items:
type: string
description: External plan identifiers.
netsuite:
type: object
additionalProperties: true
description: Netsuite integration attributes.
organizationLabels:
type: array
items:
type: string
description: Organization labels.
createTime:
type: string
format: date-time
description: Plan creation time.
example: '2025-05-01T19:33:11.000+00:00'
createdBy:
type: string
description: ID of the user who created the plan.
updateTime:
type: string
format: date-time
description: Plan update time.
updatedBy:
type: string
description: ID of the user who updated the plan.
productRatePlanCharges:
type: array
description: Charges (PRPCs) that belong to this product rate plan.
items:
type: object
properties:
id:
type: string
description: Unique identifier of the Product Rate Plan Charge.
example: ebcd93dc77b34d20912dbfae5881acff
name:
type: string
description: Charge name.
example: Charge with state 2
model:
type: string
description: Charge model.
example: PerUnit
uom:
type: string
description: Unit of measure.
example: Each
billingDay:
type: string
description: Billing day behavior.
billingPeriod:
type: string
description: Billing period (e.g., Month).
example: Month
billingPeriodAlignment:
type: string
description: Alignment for billing period.
example: AlignToCharge
billingTiming:
type: string
description: Billing timing (IN_ADVANCE or IN_ARREARS).
example: IN_ADVANCE
listPriceBase:
type: string
description: How list price is interpreted.
example: Per_Billing_Period
defaultQuantity:
type: number
description: Default quantity for the charge.
example: 10
includedUnits:
type: number
description: Included units for usage or dimensional pricing.
example: 0
isDimensionalPrice:
type: boolean
description: Indicates if the charge uses dimensional pricing.
example: true
triggerEvent:
type: string
description: Event that triggers the charge.
example: ContractEffective
productRatePlanId:
type: string
description: Owning PRP ID.
example: c3a52dd029704b7e89274c9e7e8fd99c
productRatePlanChargeNumber:
type: string
description: Charge number.
example: PRPC-00017066
attributes:
type: array
description: Dynamic pricing attributes bound to the charge.
items:
type: object
properties:
name:
type: string
description: Attribute name
example: State
type:
type: string
description: Attribute type
example: String
mapping:
type: object
description: Source mapping for attribute values.
properties:
object:
type: string
description: Source object
example: account
field:
type: string
description: Source field
example: state__c
pricing:
type: array
description: Currency pricing entries.
items:
type: object
properties:
currency:
type: string
description: ISO currency code
example: USD
price:
type: number
format: double
description: Price for the currency
example: 101
tiers:
type: array
items:
type: object
description: Tier definitions (if applicable).
pricingSummary:
type: array
description: Human-readable pricing summary.
items:
type: string
example:
- USD101/Each
pricingWaterfalls:
type: object
description: Price sources such as base and segment prices.
additionalProperties: true
revenue:
type: object
description: Revenue recognition settings.
additionalProperties: true
netsuite:
type: object
description: Netsuite integration settings.
additionalProperties: true
customFields:
type: object
description: Custom fields on the charge.
additionalProperties: true
accounting:
type: object
additionalProperties: true
description: Accounting configuration.
applyToBillingPeriodPartially:
type: boolean
description: Indicates whether the charge is applied to partial billing periods.
creditOption:
type: string
description: Specifies how credits are handled for this charge, for example, credit_option.
deliverySchedule:
type: object
additionalProperties: true
description: Defines the delivery frequency and applicable days for the charge.
discountRollover:
type: boolean
description: Indicates whether unused discounts roll over to the next billing period.
endDateCondition:
type: string
description: Defines when the charge ends, such as at the subscription end or after a fixed term.
extendedPrice:
type: object
additionalProperties: true
description: Contains calculated extended pricing details for the charge, if applicable.
isCommitted:
type: boolean
description: Indicates whether this charge is part of a committed contract.
isPrepaid:
type: boolean
description: Specifies whether the charge is prepaid.
isRollover:
type: boolean
description: Indicates whether unused units or balances roll over to subsequent periods.
isStackedDiscount:
type: boolean
description: Indicates whether this charge supports multiple stacked discounts.
labels:
type: object
additionalProperties: true
description: Stores additional key-value metadata labels associated with the charge.
ocmJsonByCurrency:
type: object
additionalProperties: true
description: Contains pricing or configuration metadata per currency in JSON format.
priceChangeOption:
type: string
description: Defines how price changes are handled when the product or rate plan changes.
productChargeDefinitions:
type: array
description: List of charge-level definition objects that specify pricing and behavior for the charge.
items:
type: object
additionalProperties: true
productDiscountApplyDetails:
type: array
description: Details of how discounts are applied to this charge.
items:
type: object
additionalProperties: true
rateCards:
type: array
description: Associated rate card definitions used for dynamic or segmented pricing.
items:
type: object
additionalProperties: true
reflectDiscountInNetAmount:
type: boolean
description: Indicates whether discounts are reflected directly in the net amount of the charge.
rolloverApply:
type: string
description: Defines how rolled-over balances or discounts are applied.
rolloverPeriodLength:
type: number
description: Length of each rollover period, in the unit specified by the product configuration.
rolloverPeriods:
type: number
description: Total number of rollover periods allowed for this charge.
taxCode:
type: string
description: Tax code applied to the charge for taxation purposes.
taxMode:
type: string
description: Tax mode for this charge, for example, NonTaxable or Taxable.
taxable:
type: boolean
description: Indicates whether the charge is taxable.
type:
type: string
description: The charge type, for example, Recurring, OneTime, or Usage.
updatedById:
type: string
description: ID of the user who last updated the charge.
updatedTime:
type: string
format: date-time
description: Timestamp when the charge was last updated.
createdById:
type: string
description: ID of the user who created the charge.
createdTime:
type: string
format: date-time
description: Timestamp when the charge was created.
UpdateTierRequest:
type: object
description: Request body to update a Product Rate Plan Charge Tier.
properties:
id:
type: string
description: |
**Product Rate Plan Charge Tier ID** (`productRatePlanChargeTierId`).
This is the unique identifier of the tier row under a Product Rate Plan Charge.
This identifier is **not surfaced by the new Commerce APIs** and is typically retrieved via **Zuora Data Query (DQ)** or by using the legacy v1 Object API equivalence:
`/v1/object/product-rate-plan-charge-tier/{id}` CRUD: Update a product rate plan charge tier
example: 8fe232784e7946f9aa79cfc8aad30bd9
price:
type: number
format: double
description: Tier price to apply for the specified currency/quantity range.
example: 450
required:
- id
- price
UpdateTierResponse:
type: object
description: Product Rate Plan Charge Tier record returned after a successful update.
properties:
id:
type: string
description: Product Rate Plan Charge Tier ID.
example: 8fe232784e7946f9aa79cfc8aad30bd9
currency:
type: string
description: ISO currency code for this tier.
example: USD
price:
type: number
format: double
description: Price configured for this tier.
example: 450
startingUnit:
type: number
description: The inclusive starting unit for this tier’s range.
example: 0
endingUnit:
type: number
description: The inclusive ending unit for this tier’s range. `0` can represent open-ended depending on tenant configuration.
example: 0
tier:
type: string
description: Display order or label of the tier within the charge.
example: '1'
isOveragePrice:
type: boolean
description: Indicates whether this tier represents an overage price row.
example: false
priceFormat:
type: string
description: Price format applied to this tier (for example, `price_format_flat_fee`).
example: price_format_flat_fee
createdById:
type: string
description: ID of the user who created the tier.
example: 190758cda21c41138233263a951580b3
createdTime:
type: string
format: date-time
description: Timestamp when the tier was created.
example: '2025-10-15T19:07:25.000+00:00'
updatedById:
type: string
description: ID of the user who last updated the tier.
example: 190758cda21c41138233263a951580b3
updatedTime:
type: string
format: date-time
description: Timestamp when the tier was last updated.
example: '2025-10-15T20:47:58.000+00:00'
required:
- id
- currency
- price
- startingUnit
- endingUnit
PurchaseOptionRequest:
type: object
properties:
filters:
type: array
description: |
Defines the filtering criteria for querying purchase options or product rate plans.
Each filter includes a target field, an operator, and a value.
items:
type: object
required:
- field
- operator
- value
properties:
field:
type: string
description: |
Name of the field to filter by.
Supported fields include:
- `prp_id`: Product Rate Plan ID.
- `product_id`: Product ID.
example: prp_id
operator:
type: string
description: |
Comparison operator. Supported values:
- `EQ` (equals)
- `NE` (not equals)
- `LT` (less than)
- `GT` (greater than)
- `SW` (starts with)
- `EW` (ends with)
- `IN` (in list)
- `LIKE` (partial match)
enum:
- EQ
- NE
- LT
- GT
- SW
- IN
- EW
- LIKE
example: EQ
value:
type: object
description: |
Specifies the value to compare against.
Only one of the following value types should be provided.
properties:
string_value:
type: string
description: String value for string-based comparisons.
example: 8a90f5088799c8ed01879cb4b47a3b1a
number_value:
type: number
format: double
description: Numeric value for numeric comparisons.
boolean_value:
type: boolean
description: Boolean value for logical comparisons.
expand:
type: object
description: |
Optional flags to include related entities in the query results.
properties:
product_rate_plan_charges:
type: boolean
description: |
When `true`, expands the response to include Product Rate Plan Charges (PRPCs)
associated with the queried Product Rate Plans. Expanded PRPCs include full
charge configuration, including pricing, billing settings, and end date
configuration fields such as `endDateCondition`, `upToPeriodsType`, and `upToPeriods`.
example: true
product_rate_plan_charge_key:
type: string
description: |
Optional identifier for a specific Product Rate Plan Charge (PRPC) to query.
Can be either a PRPC ID or a PRPC number/key.
example: ad95b694d2b8442b84dc8ad26561c7d7
attributes:
type: array
description: |
Optional attributes used for evaluating Dynamic Pricing.
Required when the queried PRPC is configured to depend on contextual attributes.
items:
type: object
required:
- name
properties:
name:
type: string
description: Name of the pricing attribute (e.g., `Region`, `Age`, `EffectiveDate`).
example: Region
string_value:
type: string
description: String-based attribute value.
number_value:
type: number
format: double
description: Numeric attribute value.
boolean_value:
type: boolean
description: Boolean attribute value.
date_value:
type: string
format: date
description: Date value in `YYYY-MM-DD` format.
datetime_value:
type: string
format: date-time
description: Datetime value in ISO 8601 format.
PurchaseOptionResponse:
type: object
description: |
Response object containing Product Rate Plan (PRP) and Product Rate Plan Charge (PRPC) details
that match the request filters. Each returned PRP includes all associated charge configurations,
pricing details, and relevant metadata.
properties:
error:
type: object
nullable: true
description: Error information, if the request fails. Returns `null` on success.
productRatePlans:
type: array
description: |
List of Product Rate Plans (PRPs) that match the filter criteria.
Each PRP includes associated product, pricing, and charge configuration details.
items:
type: object
properties:
id:
type: string
description: Unique identifier of the Product Rate Plan (PRP).
example: 8a90f5088799c8ed01879cb4b47a3b1a
name:
type: string
description: Display name of the Product Rate Plan.
example: New Rate Plan
description:
type: string
description: Description of the Product Rate Plan.
startDate:
type: string
format: date
description: Effective start date of the Product Rate Plan.
endDate:
type: string
format: date
description: Effective end date of the Product Rate Plan.
state:
type: string
description: Current state of the Product Rate Plan (for example, `active`).
example: active
productRatePlanNumber:
type: string
description: Unique reference number of the Product Rate Plan.
example: PRP-00000001
productId:
type: string
description: ID of the Product associated with this rate plan.
example: 8a90f5088799c8ed01879cb481d83b18
product:
type: object
description: Metadata and configuration details for the associated Product.
properties:
id:
type: string
description: Unique Product ID.
name:
type: string
description: Product name.
productNumber:
type: string
description: Unique product reference number.
category:
type: string
description: Product category, such as `base` or `addon`.
sku:
type: string
description: Stock-keeping unit (SKU) identifier for the Product.
state:
type: string
description: Current state of the Product (for example, `product_active`).
customFields:
type: object
additionalProperties: true
description: Custom field values defined for the Product.
productRatePlanCharges:
type: array
description: |
List of Product Rate Plan Charges (PRPCs) defined under this rate plan.
Each charge defines pricing, billing, taxation, and accounting details.
items:
type: object
properties:
id:
type: string
description: Unique identifier of the Product Rate Plan Charge (PRPC).
example: 8a90876c8799b81801879cb516f8400b
name:
type: string
description: Display name of the charge.
example: New Component
chargeType:
type: string
description: Type of charge (for example, `recurring`, `usage`, `one_time`).
chargeModel:
type: string
description: Pricing model applied to the charge (for example, `flat_fee`, `tiered`).
pricing:
type: object
description: |
Pricing configuration for the charge by currency.
Includes flat, unit, or tier-based amounts depending on the model.
properties:
flatAmounts:
type: object
additionalProperties:
type: number
description: Flat amount per billing period by currency.
example:
USD: 100
minAmounts:
type: object
additionalProperties:
type: number
description: Minimum charge thresholds by currency.
maxAmounts:
type: object
additionalProperties:
type: number
description: Maximum charge thresholds by currency.
unitAmounts:
type: object
additionalProperties:
type: number
description: Per-unit charge amounts by currency.
tiers:
type: array
items:
type: object
description: Tier-level pricing definitions for tiered or volume models.
billCycle:
type: object
description: Billing configuration for this charge.
properties:
period:
type: string
description: Billing period, such as `month` or `year`.
periodAlignment:
type: string
description: How the billing period aligns (for example, `align_to_charge`).
timing:
type: string
description: Whether the charge bills `in_advance` or `in_arrears`.
taxMode:
type: string
description: Whether tax is included (`tax_inclusive`) or excluded (`tax_exclusive`).
taxable:
type: boolean
description: Indicates if the charge is taxable.
revenue:
type: object
description: Revenue recognition configuration for this charge.
properties:
revenueRecognitionRuleName:
type: string
description: Name of the revenue recognition rule (for example, “Recognize upon invoicing”).
accounting:
$ref: '#/components/schemas/AccountingResponse'
customFields:
type: object
additionalProperties: true
description: Tenant-specific custom fields for the PRPC.
pricingSummary:
type: array
description: Human-readable price summary for quick display.
items:
type: string
example: USD100
triggerEvent:
type: string
description: Event that triggers the charge (for example, `contract_effective`).
endDateCondition:
type: string
description: |
Condition that determines when the charge ends, for example `subscription_end`,
`fixed_period`, or `specific_end_date`.
upToPeriodsType:
type: string
description: |
Unit of time used when `endDateCondition` is duration-based (for example, `billing_periods`).
upToPeriods:
type: integer
description: |
Duration value used together with `upToPeriodsType` when `endDateCondition` is `fixed_period`.
listPriceBase:
type: string
description: Indicates how list price is interpreted.
example: Per_Billing_Period
specificListPriceBase:
type: number
description: |
Optional override for list price base when billing uses a specific period configuration.
example: 0
updatedTime:
type: string
format: date-time
description: Timestamp when the charge was last updated.
createdTime:
type: string
format: date-time
description: Timestamp when the charge was created.
example:
error: null
productRatePlans:
- id: 8a90f5088799c8ed01879cb4b47a3b1a
name: New Rate Plan
state: active
productId: 8a90f5088799c8ed01879cb481d83b18
productRatePlanCharges:
- id: 8a90876c8799b81801879cb516f8400b
name: New Component
chargeType: recurring
chargeModel: flat_fee
pricing:
flatAmounts:
USD: 100
pricingSummary:
- USD100
taxMode: tax_exclusive
taxable: true
triggerEvent: contract_effective
endDateCondition: subscription_end
upToPeriodsType: billing_periods
upToPeriods: 0
createdTime: '2023-04-19T20:28:46.000+00:00'
updatedTime: '2023-04-19T20:28:46.000+00:00'
POSTAccountType:
allOf:
- properties:
accountNumber:
description: |
A unique account number, up to 50 characters that do not begin with the default account number prefix. If no account number is specified, one is generated.
type: string
additionalEmailAddresses:
description: |
A list of additional email addresses to receive email notifications. Use commas to separate email addresses.
items:
type: string
type: array
applicationOrder:
description: |
The priority order to apply credit memos and/or unapplied payments to an invoice. Possible item values are: `CreditMemo`, `UnappliedPayment`.
**Note:**
- This field is valid only if the `applyCredit` field is set to `true`.
- If no value is specified for this field, the default priority order is used, ["CreditMemo", "UnappliedPayment"], to apply credit memos first and then apply unapplied payments.
- If only one item is specified, only the items of the spedified type are applied to invoices. For example, if the value is `["CreditMemo"]`, only credit memos are used to apply to invoices.
items:
type: string
type: array
applyCredit:
description: |
Whether to automatically apply credit memos or unapplied payments, or both to an invoice.
If the value is `true`, the credit memo or unapplied payment, or both will be automatically applied to the invoice. If no value is specified or the value is `false`, no action is taken.
**Note:** This field is only available if you have [Invoice Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement) 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: boolean
applyCreditBalance:
description: |
Applies a credit balance to an invoice.
If the value is `true`, the credit balance is applied to the invoice. If the value is `false`, no action is taken.
Prerequisite: `invoice` must be `true`.
To view the credit balance adjustment, retrieve the details of the invoice using the Get Invoices method.
**Note:**
- If you are using the field `invoiceCollect` rather than the field `invoice`, the `invoiceCollect` value must be `true`.
- This field is deprecated if you have the Invoice Settlement feature enabled.
type: boolean
autoPay:
description: |
Whether future payments are to be automatically billed when they are due.
- If this field is set to `true`, you must specify either the `creditCard` field or the `hpmCreditCardPaymentMethodId` field, but not both.
- If this field is set to `false`, you can specify neither the `creditCard` field nor the `hpmCreditCardPaymentMethodId` field.
type: boolean
batch:
description: |
The alias name given to a batch. A string of 50 characters or
less.
**Note**: By default, you have 50 configurable account batches. To increase the limit to 200 batches, you must have the Performance Booster Elite package.
type: string
billCycleDay:
description: |
The account's bill cycle day (BCD), when bill runs generate invoices for the account. Specify any day of the month (1-31, where 31 = end-of-month), or 0 for auto-set.
Required if no subscription will be created.
Optional if a subscription is created and defaults to the day-of-the-month of the subscription's `contractEffectiveDate`.
format: int64
type: integer
billToContact:
$ref: '#/components/schemas/POSTAccountTypeBillToContact'
collect:
default: true
description: |
Collects an automatic payment for a subscription. The collection generated in this operation is only for this subscription, not for the entire customer account.
If the value is `true`, the automatic payment is collected. If the value is `false`, no action is taken.
Prerequisite: The `invoice` or `runBilling` field must be `true`.
**Note**: This field is available only if you are on the latest Zuora API version, or you set the `Zuora-Version` request header to `196.0` or [a later available version](https://developer.zuora.com/v1-api-reference/api-versions/#minor-version).
type: boolean
communicationProfileId:
description: |
The ID of the communication profile that this account is linked to.
You can provide either or both of the `communicationProfileId` and `profileNumber` fields.
If both are provided, the request will fail if they do not refer to the same communication profile.
If none is provided, the default communication profile will be used for this account.
type: string
creditCard:
$ref: '#/components/schemas/POSTAccountTypeCreditCard'
creditMemoReasonCode:
description: A code identifying the reason for the credit memo transaction that is generated by the request. The value must be an existing reason code. If you do not pass the field or pass the field with empty value, Zuora uses the default reason code.
type: string
creditMemoTemplateId:
description: |
**Note:** This field is only available if you have [Invoice Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement) 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.
The unique ID of the credit memo template, configured in **Billing Settings** > **Manage Billing Document Configuration** through the Zuora UI. For example, 2c92c08a6246fdf101626b1b3fe0144b.
type: string
crmId:
description: |
CRM account ID for the account, up to 100 characters.
type: string
currency:
description: |
A currency as defined in Billing Settings in the Zuora UI.
For payment method authorization, if the `paymentMethod` > `currencyCode` field is specified, `currencyCode` is used. Otherwise, this `currency` field is used for payment method authorization. If no currency is specified for the account, the default currency of the account is then used.
type: string
customerServiceRepName:
description: |
Name of the account's customer service representative, if applicable.
maxLength: 50
type: string
debitMemoTemplateId:
description: |
**Note:** This field is only available if you have [Invoice Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement) 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.
The unique ID of the debit memo template, configured in **Billing Settings** > **Manage Billing Document Configuration** through the Zuora UI. For example, 2c92c08d62470a8501626b19d24f19e2.
type: string
documentDate:
description: |
The date of the billing document, in `yyyy-mm-dd` format. It represents the invoice date for invoices, credit memo date for credit memos, and debit memo date for debit memos.
- If this field is specified, the specified date is used as the billing document date.
- If this field is not specified, the date specified in the `targetDate` is used as the billing document date.
format: date
type: string
einvoiceProfile:
$ref: '#/components/schemas/PostAccountEInvoiceProfile'
gatewayRoutingEligible:
default: false
description: |
Indicates whether to include the applicable billing accounts to gateway routing for controlled adoption.
type: boolean
hpmCreditCardPaymentMethodId:
description: |
The ID of the payment method associated with this account. You can use this field to set the default payment method for the account. The payment method ID specified in this field will be set as the default payment method for this account. You can pass the ID of any valid payment method, including a system-generated payment method ID, into this field.
If the `autoPay` field is set to `true`, you must provide the credit card payment method ID for either this field or the `creditCard` field, but not both.
For the Credit Card Reference Transaction payment method, you can specify the payment method ID in this field or use the `paymentMethod` field to create a CC Reference Transaction payment method for an account.
type: string
invoiceDeliveryPrefsEmail:
default: false
description: |
Whether the customer wants to receive invoices through email.
type: boolean
invoiceDeliveryPrefsPrint:
default: false
description: |
Whether the customer wants to receive printed invoices, such as through postal mail.
type: boolean
invoiceTemplateId:
description: |
Invoice template ID or template number, configured in Billing Settings in the Zuora UI.
type: string
name:
description: |
Account name, up to 255 characters.
type: string
notes:
description: A string of up to 65,535 characters.
type: string
organizationLabel:
description: |
Name of the organization that the account belongs to.
This field is only required when you have already turned on Multi-Org feature.
type: string
parentId:
description: Identifier of the parent customer account for this Account object. The length is 32 characters. Use this field if you have Customer Hierarchy enabled.
type: string
partnerAccount:
default: false
description: |
Whether the customer account is a partner, distributor, or reseller.
You can set this field to `true` if you have business with distributors or resellers, or operating in B2B model to manage numerous subscriptions through concurrent API requests. After this field is set to `true`, the calculation of account metrics is performed asynchronously during operations such as subscription creation, order changes, invoice generation, and payments.
**Note**: This field is available only if you have the Reseller Account feature enabled.
type: boolean
paymentGateway:
description: |
The name of the payment gateway instance. If null or left unassigned, the Account will use the Default Gateway.
type: string
paymentMethod:
$ref: '#/components/schemas/POSTPaymentMethodRequest'
paymentTerm:
description: |
Payment terms for this account. Possible values are: `Due Upon Receipt`, `Net 30`, `Net 60`, `Net 90`.
**Note**: If you want to specify a payment term when creating a new account, you must set a value in this field. If you do not set a value in this field, Zuora will use the default value set in **Billing Settings** > **Payment Terms** from Zuora UI.
type: string
profileNumber:
description: |
The number of the communication profile that this account is linked to.
You can provide either or both of the `communicationProfileId` and `profileNumber` fields.
If both are provided, the request will fail if they do not refer to the same communication profile.
If none is provided, the default communication profile will be used for this account.
type: string
purchaseOrderNumber:
description: The purchase order number provided by your customer for services, products, or both purchased.
type: string
runBilling:
default: true
description: |
Creates an invoice for a subscription. If you have the Invoice Settlement feature enabled, a credit memo might also be created based on the [invoice and credit memo generation rule](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement/B_Credit_and_Debit_Memos/Rules_for_generating_invoices_and_credit_memos).
The billing documents generated
in this operation is only for this subscription, not for the entire
customer account.
Possible values:
- `true`: An invoice is created. If you have the Invoice Settlement feature enabled, a credit memo might also be created.
- `false`: No invoice is created.
**Note**: This field is available only if you are on the latest Zuora API version, or you set the `Zuora-Version` request header to `196.0` or [a later available version](https://developer.zuora.com/v1-api-reference/api-versions/#minor-version).
type: boolean
salesRep:
description: The name of the sales representative associated with this account, if applicable. Maximum of 50 characters.
type: string
sequenceSetId:
description: |
The ID or number of the billing document sequence set to assign to the customer account.
The billing documents to generate for this account will adopt the prefix and starting document number configured in the sequence set.
If a customer account has no assigned billing document sequence set, billing documents generated for this account adopt the prefix and starting document number from the default sequence set.
type: string
nullable: true
shipToContact:
$ref: '#/components/schemas/CreateAccountShipToContact'
shipToSameAsBillTo:
description: |
Whether the ship-to contact and bill-to contact are the same entity.
The created account has the same bill-to contact and ship-to contact entity only when all the following conditions are met in the request body:
- This field is set to `true`.
- A bill-to contact is specified.
- No ship-to contact is specified.
type: boolean
soldToContact:
$ref: '#/components/schemas/POSTAccountTypeSoldToContact'
soldToSameAsBillTo:
description: |
Whether the sold-to contact and bill-to contact are the same entity.
The created account has the same bill-to contact and sold-to contact entity only when all the following conditions are met in the request body:
- This field is set to `true`.
- A bill-to contact is specified.
- No sold-to contact is specified.
type: boolean
subscription:
$ref: '#/components/schemas/POSTAccountTypeSubscription'
summaryStatementTemplateId:
description: |
The summary statement template ID or number. When a user attempts to generate a summary statement from the "Account Summary Statement" screen, the system utilizes this template to produce the PDF.
type: string
nullable: true
tagging:
description: ''
type: string
targetDate:
description: |
Date through which to calculate charges if an invoice or a credit memo is generated, as yyyy-mm-dd. Default is current date.
**Note**: This field is available only if you are on the latest Zuora API version, or you set the `Zuora-Version` request header to `211.0` or [a later available version](https://developer.zuora.com/v1-api-reference/api-versions/#minor-version).
**Note:** The credit memo is only available only if you have the Invoice Settlement feature enabled.
format: date
type: string
taxInfo:
description: |
Container for tax exempt information, used to establish the tax exempt status of a customer account.
properties:
VATId:
description: |
EU Value Added Tax ID.
**Note:** This feature is in Limited Availability. If you wish to have access to the feature, submit a request at [Zuora Global Support](https://support.zuora.com).
type: string
companyCode:
description: |
Unique code that identifies a company account in Avalara. Use this field to calculate taxes based on origin and sold-to addresses in Avalara.
**Note:** This feature is in Limited Availability. If you wish to have access to the feature, submit a request at [Zuora Global Support](https://support.zuora.com).
type: string
exemptCertificateId:
description: |
ID of the customer tax exemption certificate. Requires Zuora Tax.
type: string
exemptCertificateType:
description: |
Type of tax exemption certificate that the customer holds. Requires Zuora Tax.
type: string
exemptDescription:
description: |
Description of the tax exemption certificate that the customer holds. Requires Zuora Tax.
type: string
exemptEffectiveDate:
description: |
Date when the customer tax exemption starts. Requires Zuora Tax.
Format: `yyyy-mm-dd`. Defaults to the current date.
format: date
type: string
exemptEntityUseCode:
description: |
A unique entity use code to apply exemptions in Avalara AvaTax.
This account-level field is required only when you choose Avalara as your tax engine. See [Exempt Transactions](https://developer.avalara.com/avatax/handling-tax-exempt-customers/)for more details.
maxLength: 64
type: string
exemptExpirationDate:
description: |
Date when the customer tax exemption expires. Requires Zuora Tax.
Format: `yyyy-mm-dd`. Defaults to the current date.
format: date
type: string
exemptIssuingJurisdiction:
description: |
Jurisdiction in which the customer tax exemption certificate was issued.
type: string
exemptStatus:
description: |
Status of the account tax exemption. Requires Zuora Tax.
Required if you use Zuora Tax. This field is unavailable if Zuora Tax is not used.
Values: `Yes`, `No`(default), `pendingVerification`. Note that the value will be set to `No` if no input.
type: string
type: object
required:
- name
- currency
- billToContact
type: object
- $ref: '#/components/schemas/AccountObjectNSFields'
- $ref: '#/components/schemas/AccountObjectCustomFields'
example:
name: Amy Lawrence
billToContact:
firstName: Amy
lastName: Lawrence
country: United States
state: CA
autoPay: false
currency: USD
billCycleDay: 1
POSTAccountResponseType:
properties:
accountId:
description: |
Auto-generated account ID.
type: string
accountNumber:
description: |
Account number.
type: string
billToContactId:
description: |
The ID of the bill-to contact.
type: string
contractedMrr:
description: |
Contracted monthly recurring revenue of the subscription.
format: decimal
type: string
creditMemoId:
description: |
The credit memo ID, if a credit memo is generated during the subscription process.
**Note:** This field is only available if you have [Invoice Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement) 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
invoiceId:
description: |
ID of the invoice generated at account creation, if applicable.
type: string
paidAmount:
description: |
Amount collected on the invoice generated at account creation, if applicable.
format: decimal
type: string
paymentId:
description: |
ID of the payment collected on the invoice generated at account creation, if applicable.
type: string
paymentMethodId:
description: |
ID of the payment method that was set up at account creation, which automatically becomes the default payment method for this account.
type: string
shipToContactId:
description: |
The ID of the ship-to contact.
type: string
soldToContactId:
description: |
The ID of the sold-to contact.
type: string
subscriptionId:
description: |
ID of the subscription that was set up at account creation, if applicable.
type: string
subscriptionNumber:
description: |
Number of the subscription that was set up at account creation, if applicable.
type: string
success:
description: |
Returns `true` if the request was processed successfully.
type: boolean
totalContractedValue:
description: |
Total contracted value of the subscription.
format: decimal
type: string
type: object
POSTAccountTypeBillToContact:
allOf:
- properties:
address1:
description: |
First address line, 255 characters or less.
type: string
address2:
description: |
Second address line, 255 characters or less.
type: string
city:
description: |
City
type: string
maxLength: 100
country:
description: |
Country; must be a valid country name or abbreviation. If using Zuora Tax, you must specify a country in the sold-to contact to calculate tax. A bill-to contact may be used if no sold-to contact is provided.
type: string
county:
description: |
May optionally be used by Zuora Tax to calculate county tax.
type: string
maxLength: 100
fax:
description: |
Fax phone number, 40 characters or less.
type: string
firstName:
description: |
First name, 100 characters or less.
type: string
homePhone:
description: |
Home phone number, 40 characters or less.
type: string
lastName:
description: |
Last name, 100 characters or less.
type: string
mobilePhone:
description: |
Mobile phone number, 40 characters or less.
type: string
nickname:
description: |
Nickname for this contact
type: string
otherPhone:
description: |
Other phone number, 40 characters or less.
type: string
otherPhoneType:
description: |
Possible values are: `Work`, `Mobile`, `Home`, `Other`.
type: string
personalEmail:
description: |
Personal email address.
type: string
format: email
maxLength: 80
state:
description: |
State must be a valid subregion (state or province) name or code. For more information, see View subregions of a specific country or region. If using Zuora Tax, be aware that Zuora tax requires a state (in the US) or province (in Canada) in this field for the sold-to contact to calculate tax, and that a bill-to contact may be used if no sold-to contact is provided.
type: string
maxLength: 100
taxRegion:
description: |
If using Zuora Tax, a region string as optionally defined in your tax rules. Not required.
type: string
maxLength: 100
workEmail:
description: |
Work email address, 80 characters or less.
type: string
workPhone:
description: |
Work phone number, 40 characters or less.
type: string
zipCode:
description: |
Zip code, 20 characters or less.
type: string
required:
- firstName
- lastName
type: object
- $ref: '#/components/schemas/ContactObjectCustomFields'
description: |
Container for bill-to contact information for this account. If you do not provide a sold-to contact, the bill-to contact is copied to sold-to contact. Once the sold-to contact is created, changes to billToContact will not affect soldToContact and vice versa.
title: Contact
POSTAccountTypeCreditCard:
allOf:
- properties:
cardHolderInfo:
description: |
Container for cardholder information.
properties:
addressLine1:
description: |
First address line, 255 characters or less.
type: string
addressLine2:
description: |
Second address line, 255 characters or less.
type: string
cardHolderName:
description: |
The card holder's full name as it appears on the card, e.g., "John J Smith", 50 characters or less.
type: string
city:
description: |
City, 40 characters or less.
It is recommended to provide the city and country information when creating a payment method. The information will be used to process payments. If the information is not provided during payment method creation, the city and country data will be missing during payment processing.
type: string
country:
description: |
Country; must be a valid country name or abbreviation.
It is recommended to provide the city and country information when creating a payment method. The information will be used to process payments. If the information is not provided during payment method creation, the city and country data will be missing during payment processing.
type: string
email:
description: |
Card holder's email address, 80 characters or less.
type: string
phone:
description: |
Phone number, 40 characters or less.
type: string
state:
description: |
State; must be a valid subregion (state or province) name or code. For more information, see View subregions of a specific country or region.
type: string
zipCode:
description: |
Zip code, 20 characters or less.
type: string
required:
- addressLine1
- cardHolderName
- city
- country
- state
- zipCode
cardNumber:
description: |
Card number, up to 16 characters. Once created, this field can't be updated or queried, and is only available in masked format (e.g., XXXX-XXXX-XXXX-1234).
type: string
cardType:
description: |
The type of the credit card.
Possible values include `Visa`, `MasterCard`, `AmericanExpress`, `Discover`, `JCB`, and `Diners`. For more information about credit card types supported by different payment gateways, see [Supported Payment Gateways](https://knowledgecenter.zuora.com/CB_Billing/M_Payment_Gateways/Supported_Payment_Gateways).
type: string
expirationMonth:
description: |
Two-digit expiration month (01-12).
type: string
expirationYear:
description: |
Four-digit expiration year.
type: string
securityCode:
description: |
The CVV or CVV2 security code of the card. To ensure PCI compliance, this value is not stored and cannot be queried.
type: string
required:
- cardHolderInfo
- cardNumber
- cardType
- expirationMonth
- expirationYear
type: object
- $ref: '#/components/schemas/PaymentMethodObjectCustomFields'
description: |
**Note:** This field has been deprecated, and is currently available only for backward compatibility. Use the `paymentMethod` field instead to create a payment method associated with this account.
Container for information on a credit card to associate with this account.
If the `autoPay` field is set to `true`, you must provide one of the `paymentMethod`, `creditCard`, or `hpmCreditCardPaymentMethodId` field, but not multiple.
title: creditCard
PostAccountEInvoiceProfile:
allOf:
- properties:
businessCategory:
description: |
The high-level category of the business.
type: string
enum:
- B2B
- B2C
- B2G
businessName:
description: |
The full official name that the Buyer is registered with the relevant legal authority.
maxLength: 255
type: string
businessNumber:
description: |
The unique identifier number of the legal entity or person that you do business with.
For example, you must use a GSTIN for India.
type: string
businessNumberSchemeId:
description: |
The identification scheme identifier that an official registrar issues to identify the Buyer as a legal entity or person.
type: string
enabled:
description: |
Whether to enable the e-invoicing profile for the customer account.
If the following conditions are met, all billing documents for one account can be submitted to an e-invoicing service provider to be generated in electronic format:
- The account must be configured to generate e-invoice files for billing documents.
- The billing document must be in Posted status.
- A business region must be created for the billing country contact, and be linked to an e-invoicing service provider.
type: boolean
endpointId:
description: |
The Buyer's electronic address, to which the application-level response to the billing document might be delivered.
type: string
endpointSchemeId:
description: |
The identification scheme identifier of the Buyer’s electronic address.
type: string
taxRegisterNumber:
description: |
The Buyer's VAT identifier (also known as the Buyer's VAT identification number) or the local identification (defined by the Buyer’s address) of the Buyer for tax purposes, or a reference that enables the Buyer to state the registered tax status.
type: string
type: object
- $ref: '#/components/schemas/EinvoiceObjectCustomFields'
description: |
Container for e-invoicing profile information for this account.
**Note**: This field is available only if you have the E-Invoicing feature in **Early Adopter** phase enabled.
title: einvoiceProfile
POSTPaymentMethodRequest:
type: object
discriminator:
propertyName: type
mapping:
CreditCard: '#/components/schemas/CreatePaymentMethodCreditCard'
CreditCardReferenceTransaction: '#/components/schemas/CreatePaymentMethodCCReferenceTransaction'
ACH: '#/components/schemas/CreatePaymentMethodACH'
SEPA: '#/components/schemas/CreatePaymentMethodSEPA'
Betalingsservice: '#/components/schemas/CreatePaymentMethodBetalingsservice'
Autogiro: '#/components/schemas/CreatePaymentMethodAutogiro'
Bacs: '#/components/schemas/CreatePaymentMethodBacs'
Becs: '#/components/schemas/CreatePaymentMethodBecs'
Becsnz: '#/components/schemas/CreatePaymentMethodBecsnz'
PAD: '#/components/schemas/CreatePaymentMethodPAD'
PayPalCP: '#/components/schemas/CreatePMPayPalCP'
PayPalEC: '#/components/schemas/CreatePMPayPalEC'
PayPalNativeEC: '#/components/schemas/CreatePMPayPalNativeEC'
PayPalAdaptive: '#/components/schemas/CreatePaymentMethodPayPalAdaptive'
AdyenApplePay: '#/components/schemas/CreatePaymentMethodApplePayAdyen'
AdyenGooglePay: '#/components/schemas/CreatePaymentMethodGooglePayAdyen'
GooglePay: '#/components/schemas/CreatePaymentMethodGooglePayChase'
AmazonPay: '#/components/schemas/CreatePaymentMethodAmazonPay'
oneOf:
- $ref: '#/components/schemas/CreatePaymentMethodCreditCard'
- $ref: '#/components/schemas/CreatePaymentMethodCCReferenceTransaction'
- $ref: '#/components/schemas/CreatePaymentMethodACH'
- $ref: '#/components/schemas/CreatePaymentMethodSEPA'
- $ref: '#/components/schemas/CreatePaymentMethodBetalingsservice'
- $ref: '#/components/schemas/CreatePaymentMethodAutogiro'
- $ref: '#/components/schemas/CreatePaymentMethodBacs'
- $ref: '#/components/schemas/CreatePaymentMethodBecs'
- $ref: '#/components/schemas/CreatePaymentMethodBecsnz'
- $ref: '#/components/schemas/CreatePaymentMethodPAD'
- $ref: '#/components/schemas/CreatePMPayPalNativeEC'
- $ref: '#/components/schemas/CreatePMPayPalCP'
- $ref: '#/components/schemas/CreatePMPayPalEC'
- $ref: '#/components/schemas/CreatePaymentMethodPayPalAdaptive'
- $ref: '#/components/schemas/CreatePaymentMethodApplePayAdyen'
- $ref: '#/components/schemas/CreatePaymentMethodGooglePayChase'
- $ref: '#/components/schemas/CreatePaymentMethodAmazonPay'
required:
- type
description: Payment method information associated with an account.
CreateAccountShipToContact:
allOf:
- properties:
address1:
description: |
First address line, 255 characters or less.
type: string
address2:
description: |
Second address line, 255 characters or less.
type: string
city:
description: |
City
type: string
maxLength: 100
country:
description: |
Country; must be a valid country name or abbreviation.
type: string
county:
description: |
May optionally be used by Zuora Tax to calculate county tax.
type: string
maxLength: 100
fax:
description: |
Fax phone number, 40 characters or less.
type: string
firstName:
description: |
First name, 100 characters or less.
type: string
homePhone:
description: |
Home phone number, 40 characters or less.
type: string
lastName:
description: |
Last name, 100 characters or less.
type: string
mobilePhone:
description: |
Mobile phone number, 40 characters or less.
type: string
nickname:
description: |
Nickname for this contact
type: string
otherPhone:
description: |
Other phone number, 40 characters or less.
type: string
otherPhoneType:
description: |
Possible values are: `Work`, `Mobile`, `Home`, `Other`.
type: string
personalEmail:
description: |
Personal email address.
type: string
format: email
maxLength: 80
state:
description: |
State must be a valid subregion (state or province) name or code. For more information, see View subregions of a specific country or region.
type: string
maxLength: 100
taxRegion:
description: |
100 characters or less.
If using Zuora Tax, a region string as optionally defined in your tax rules. Not required.
type: string
maxLength: 100
workEmail:
description: |
Work email address, 80 characters or less.
type: string
workPhone:
description: |
Work phone number, 40 characters or less.
type: string
zipCode:
description: |
Zip code, 20 characters or less.
type: string
required:
- firstName
- lastName
type: object
- $ref: '#/components/schemas/ContactObjectCustomFields'
description: |
Container for optional ship-to contact; uses the same field structure as the `billToContact` field. If this field is not specified and the `shipToSameAsBillTo` field is `false`, the ship-to contact of the account is empty.
title: ShipToContact
POSTAccountTypeSoldToContact:
allOf:
- properties:
address1:
description: |
First address line, 255 characters or less.
type: string
address2:
description: |
Second address line, 255 characters or less.
type: string
city:
description: |
City
type: string
maxLength: 100
country:
description: |
Country; must be a valid country name or abbreviation. If using Zuora Tax, you must specify a country in the sold-to contact to calculate tax. A bill-to contact may be used if no sold-to contact is provided.
type: string
county:
description: |
May optionally be used by Zuora Tax to calculate county tax.
type: string
maxLength: 100
fax:
description: |
Fax phone number, 40 characters or less.
type: string
firstName:
description: |
First name, 100 characters or less.
type: string
homePhone:
description: |
Home phone number, 40 characters or less.
type: string
lastName:
description: |
Last name, 100 characters or less.
type: string
mobilePhone:
description: |
Mobile phone number, 40 characters or less.
type: string
nickname:
description: |
Nickname for this contact
type: string
otherPhone:
description: |
Other phone number, 40 characters or less.
type: string
otherPhoneType:
description: |
Possible values are: `Work`, `Mobile`, `Home`, `Other`.
type: string
personalEmail:
description: |
Personal email address.
type: string
format: email
maxLength: 80
state:
description: |
State; must be a valid subregion (state or province) name or code. For more information, see View subregions of a specific country or region. If using Zuora Tax, be aware that Zuora Tax requires a state (in the US) or province (in Canada) in this field for the sold-to contact to calculate tax, and that a bill-to contact may be used if no sold-to contact is provided.
type: string
maxLength: 100
taxRegion:
description: |
If using Zuora Tax, a region string as optionally defined in your tax rules. Not required.
type: string
maxLength: 100
workEmail:
description: |
Work email address, 80 characters or less.
type: string
workPhone:
description: |
Work phone number, 40 characters or less.
type: string
zipCode:
description: |
Zip code, 20 characters or less.
type: string
required:
- firstName
- lastName
type: object
- $ref: '#/components/schemas/ContactObjectCustomFields'
description: |
Container for optional sold-to contact; uses the same field structure as the bill-to contact (above). If a sold-to contact is not specified, one is created from the bill-to contact. Once created, these are two separate data entities, and future changes to one do not affect the other.
title: soldToContact
POSTAccountTypeSubscription:
allOf:
- properties:
autoRenew:
description: |
If `true`, auto-renew is enabled. Default is `false`.
type: boolean
contractEffectiveDate:
description: |
Effective contract date for this subscription, as `yyyy-mm-dd`.
format: date
type: string
customerAcceptanceDate:
description: |
The date on which the services or products within a subscription have been accepted by the customer, as `yyyy-mm-dd`.
Default value is dependent on the value of other fields. See Notes section for more details.
format: date
type: string
initialTerm:
description: |
Duration of the initial subscription term in whole months. Default is 0.
format: int64
type: integer
invoiceOwnerAccountKey:
description: |
Invoice owner account number or ID.
**Note:** This feature is in Limited Availability. If you wish to have access to the feature, submit a request at [Zuora Global Support](https://support.zuora.com).
type: string
invoiceSeparately:
description: |
Separates a single subscription from other subscriptions and invoices the charge independently.
If the value is `true`, the subscription is billed separately from other subscriptions. If the value is `false`, the subscription is included with other subscriptions in the account invoice.
The default value is `false`.
Prerequisite: The default subscription setting `Enable Subscriptions to be Invoiced Separately` must be set to `Yes`.
type: boolean
notes:
description: ''
type: string
renewalTerm:
description: |
Duration of the renewal term in whole months. Default is 0.
format: int64
type: integer
serviceActivationDate:
description: |
The date on which the services or products within a subscription have been activated and access has been provided to the customer, as `yyyy-mm-dd`.
Default value is dependent on the value of other fields. See Notes section for more details.
format: date
type: string
subscribeToRatePlans:
description: |
Container for one or more rate plans for this subscription.
items:
$ref: '#/components/schemas/POSTSrpCreateType'
type: array
subscriptionNumber:
description: |
Subscription Number. The value can be up to 1000 characters.
If you do not specify a subscription number when creating a subscription for the new account, Zuora will generate a subscription number automatically.
If the account is created successfully, the subscription number is returned in the `subscriptionNumber` response field.
type: string
termStartDate:
description: |
The date on which the subscription term begins, as `yyyy-mm-dd`. If this is a renewal subscription, this date is different from the subscription start date.
format: date
type: string
termType:
description: |
Possible values are: `TERMED`, `EVERGREEN`.
type: string
required:
- contractEffectiveDate
- termType
type: object
- $ref: '#/components/schemas/SubscriptionObjectQTFields'
- $ref: '#/components/schemas/SubscriptionObjectNSFields'
- $ref: '#/components/schemas/SubscriptionObjectCustomFields'
description: |
Container for subscription information, used if creating a subscription for the new account at the time of account creation.
title: subscription
AccountObjectNSFields:
description: |
Container for Account fields provided by the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
properties:
Class__NS:
description: |
Value of the Class field for the corresponding customer account in NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
maxLength: 255
type: string
CustomerType__NS:
description: |
Value of the Customer Type field for the corresponding customer account in NetSuite. The Customer Type field is used when the customer account is created in NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
enum:
- Company
- Individual
type: string
Department__NS:
description: |
Value of the Department field for the corresponding customer account in NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
maxLength: 255
type: string
IntegrationId__NS:
description: |
ID of the corresponding object in NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
maxLength: 255
type: string
IntegrationStatus__NS:
description: |
Status of the account's synchronization with NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
maxLength: 255
type: string
Location__NS:
description: |
Value of the Location field for the corresponding customer account in NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
maxLength: 255
type: string
Subsidiary__NS:
description: |
Value of the Subsidiary field for the corresponding customer account in NetSuite. The Subsidiary field is required if you use NetSuite OneWorld. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
maxLength: 255
type: string
SyncDate__NS:
description: |
Date when the account was sychronized with NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
maxLength: 255
type: string
SynctoNetSuite__NS:
description: |
Specifies whether the account should be synchronized with NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
enum:
- 'Yes'
- 'No'
type: string
title: accountFieldsNetSuite
type: object
AccountObjectCustomFields:
additionalProperties:
description: |
Custom fields of the Account object. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
description: |
Container for custom fields of an Account object.
title: accountFieldsCustom
type: object
POSTSrpCreateType:
allOf:
- properties:
chargeOverrides:
description: |
This optional container is used to override the quantity of one or more product rate plan charges for this subscription.
items:
$ref: '#/components/schemas/POSTScCreateType'
type: array
externalCatalogPlanId:
description: |
An external ID of the product rate plan to be added. You can use this field to specify a product rate plan that is imported from an external system. The value of the `externalCatalogPlanId` field must match one of the values that are predefined in the `externallyManagedPlanIds` field on a product rate plan.
**Note:** If both `externalCatalogPlanId` and `productRatePlanId` are provided. They must point to the same product rate plan. Otherwise, the request would fail.
type: string
externalIdSourceSystem:
description: |
The ID of the external source system. You can use this field and `externalCatalogPlanId` to specify a product rate plan that is imported from an external system.
**Note:** If both `externalCatalogPlanId`, `externalIdSourceSystem` and `productRatePlanId` are provided. They must point to the same product rate plan. Otherwise, the request would fail.
type: string
externallyManagedPlanId:
description: |
Indicates the unique identifier for the rate plan purchased on a third-party store. This field is used to represent a subscription rate plan created through third-party stores.
type: string
productRatePlanId:
description: |
ID of a product rate plan for this subscription.
type: string
productRatePlanNumber:
description: |
Number of a product rate plan for this subscription.
type: string
type: object
- $ref: '#/components/schemas/RatePlanObjectCustomFields'
title: subscribeToRatePlans
SubscriptionObjectQTFields:
description: |
Container for Subscription fields provided by Zuora Quotes.
properties:
CpqBundleJsonId__QT:
description: |
The Bundle product structures from Zuora Quotes if you utilize Bundling in Salesforce. Do not change the value in this field.
maxLength: 32
type: string
OpportunityCloseDate__QT:
description: |
The closing date of the Opportunity. This field is used in Zuora data sources to report on Subscription metrics. If the subscription originated from Zuora Quotes, the value is populated with the value from Zuora Quotes.
format: date
type: string
OpportunityName__QT:
description: |
The unique identifier of the Opportunity. This field is used in Zuora data sources to report on Subscription metrics. If the subscription originated from Zuora Quotes, the value is populated with the value from Zuora Quotes.
maxLength: 100
type: string
QuoteBusinessType__QT:
description: |
The specific identifier for the type of business transaction the Quote represents such as New, Upsell, Downsell, Renewal or Churn. This field is used in Zuora data sources to report on Subscription metrics. If the subscription originated from Zuora Quotes, the value is populated with the value from Zuora Quotes.
maxLength: 32
type: string
QuoteNumber__QT:
description: |
The unique identifier of the Quote. This field is used in Zuora data sources to report on Subscription metrics. If the subscription originated from Zuora Quotes, the value is populated with the value from Zuora Quotes.
maxLength: 32
type: string
QuoteType__QT:
description: |
The Quote type that represents the subscription lifecycle stage such as New, Amendment, Renew or Cancel. This field is used in Zuora data sources to report on Subscription metrics. If the subscription originated from Zuora Quotes, the value is populated with the value from Zuora Quotes.
maxLength: 32
type: string
title: subscriptionFieldsQT
type: object
SubscriptionObjectNSFields:
description: |
Container for Subscription fields provided by the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
properties:
IntegrationId__NS:
description: |
ID of the corresponding object in NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
maxLength: 255
type: string
IntegrationStatus__NS:
description: |
Status of the subscription's synchronization with NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
maxLength: 255
type: string
Project__NS:
description: |
The NetSuite project that the subscription was created from. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
maxLength: 255
type: string
SalesOrder__NS:
description: |
The NetSuite sales order than the subscription was created from. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
maxLength: 255
type: string
SyncDate__NS:
description: |
Date when the subscription was synchronized with NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
maxLength: 255
type: string
title: subscriptionFieldsNS
type: object
SubscriptionObjectCustomFields:
additionalProperties:
description: |
Custom fields of the Subscription object. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
description: |
Container for custom fields of a Subscription object.
title: subscriptionFieldsCustom
type: object
POSTScCreateType:
allOf:
- properties:
amendedByOrderOn:
description: |
The date when the rate plan charge is amended through an order or amendment. This field is to standardize the booking date information to increase audit ability and traceability of data between Zuora Billing and Zuora Revenue. It is mapped as the booking date for a sale order line in Zuora Revenue.
type: string
applyDiscountTo:
description: |
Specifies the type of charges that you want a specific discount to apply to.
Values:
* `ONETIME`
* `RECURRING`
* `USAGE`
* `ONETIMERECURRING`
* `ONETIMEUSAGE`
* `RECURRINGUSAGE`
* `ONETIMERECURRINGUSAGE`
type: string
billCycleDay:
description: |
Sets the bill cycle day (BCD) for the charge. The BCD determines which day of the month the customer is billed.
Values: `1`-`31`
type: string
billCycleType:
description: |
Specifies how to determine the billing day for the charge. When this field is set to `SpecificDayofMonth`, set the `BillCycleDay` field. When this field is set to `SpecificDayofWeek`, set the `weeklyBillCycleDay` field.
Values:
* `DefaultFromCustomer`
* `SpecificDayofMonth`
* `SubscriptionStartDay`
* `ChargeTriggerDay`
* `SpecificDayofWeek`
type: string
billingPeriod:
description: |
Billing period for the charge. The start day of the billing period is also called the bill cycle day (BCD).
Values:
* `Month`
* `Quarter`
* `Semi_Annual`
* `Annual`
* `Eighteen_Months`
* `Two_Years`
* `Three_Years`
* `Five_Years`
* `Specific_Months`
* `Subscription_Term`
* `Week`
* `Specific_Weeks`
type: string
billingPeriodAlignment:
description: |
Aligns charges within the same subscription if multiple charges begin on different dates.
Values:
* `AlignToCharge`
* `AlignToSubscriptionStart`
* `AlignToTermStart`
type: string
billingTiming:
description: |
Billing timing for the charge for recurring charge types. Not avaliable for one time, usage, and discount charges.
Values:
* `IN_ADVANCE` (default)
* `IN_ARREARS`
type: string
chargeModelConfiguration:
$ref: '#/components/schemas/ChargeModelConfigurationType'
description:
description: |
Description of the charge.
type: string
discountAmount:
description: |
Specifies the amount of fixed-amount discount.
type: number
discountLevel:
description: |
Specifies if the discount applies to the product rate plan only, the entire subscription, or to any activity in the account.
Values:
* `rateplan`
* `subscription`
* `account`
type: string
discountPercentage:
description: |
Percentage of discount for a percentage discount.
type: number
endDateCondition:
description: |
Defines when the charge ends after the charge trigger date. If the subscription ends before the charge end date, the charge ends when the subscription ends. But if the subscription end date is subsequently changed through a Renewal, or Terms and Conditions amendment, the charge will end on the charge end date.
Values:
* `Subscription_End`
* `Fixed_Period`
* `Specific_End_Date`
* `One_Time`
type: string
excludeItemBillingFromRevenueAccounting:
default: false
description: |
The flag to exclude rate plan charge related invoice items, invoice item adjustments, credit memo items, and debit memo items from revenue accounting.
**Note**: This field is only available if you have the Order to Revenue or Billing - Revenue Integration feature enabled.
type: boolean
excludeItemBookingFromRevenueAccounting:
default: false
description: |
The flag to exclude rate plan charges from revenue accounting.
**Note**: This field is only available if you have the Order to Revenue or Billing - Revenue Integration feature enabled.
type: boolean
includedUnits:
description: |
Specifies the number of units in the base set of units for this charge. Must be >=`0`.
type: number
isAllocationEligible:
description: |
This field is used to identify if the charge segment is allocation
eligible in revenue recognition.
**Note**: The field is only available if you have the Order to Revenue feature enabled. To enable this field, submit a request at Zuora Global Support.
type: boolean
isUnbilled:
description: |
This field is used to dictate how to perform the accounting during
revenue recognition.
**Note**: The field is only available if you have the Order to Revenue feature enabled. To enable this field, submit a request at Zuora Global Support.
type: boolean
listPriceBase:
description: |
The list price base for the product rate plan charge.
Values:
* `Per_Billing_Period`
* `Per_Month`
* `Per_Week`
* `Per_Year`
* `Per_Specific_Months`
type: string
number:
description: |
Unique number that identifies the charge. Max 50 characters. System-generated if not provided.
type: string
numberOfPeriods:
description: |
Specifies the number of periods to use when calculating charges in an overage smoothing charge model.
format: int64
type: integer
originalOrderDate:
description: |
The date when the rate plan charge is created through an order or amendment. This field is not updatable.
This field is to standardize the booking date information to increase audit ability and traceability of data between Zuora Billing and Zuora Revenue. It is mapped as the booking date for a sale order line in Zuora Revenue.
format: date
type: string
overagePrice:
description: |
Price for units over the allowed amount.
type: number
overageUnusedUnitsCreditOption:
description: |
Determines whether to credit the customer with unused units of usage.
Values:
* `NoCredit`
* `CreditBySpecificRate`
type: string
price:
description: |
Price for units in the subscription rate plan.
type: number
priceChangeOption:
description: |
Applies an automatic price change when a termed subscription is renewed. The Billing Admin setting **Enable Automatic Price Change When Subscriptions are Renewed?** must be set to Yes to use this field.
Values:
* `NoChange` (default)
* `SpecificPercentageValue`
* `UseLatestProductCatalogPricing`
type: string
priceIncreasePercentage:
description: |
Specifies the percentage to increase or decrease the price of a termed subscription's renewal. Required if you set the `PriceChangeOption` field to `SpecificPercentageValue`.
Value must be a decimal between `-100` and `100`.
type: number
productRatePlanChargeId:
description: |
ID of a product rate-plan charge for this subscription.
type: string
productRatePlanChargeNumber:
description: |
Number of a product rate-plan charge for this subscription.
type: string
quantity:
description: |
Number of units. Must be a decimal >=`0`.
When using `chargeOverrides` for creating subscriptions with recurring charge types, the `quantity` field must be populated when the charge model is "Tiered Pricing" or "Volume Pricing". It is not required for "Flat Fee Pricing" charge model.
type: number
ratingGroup:
description: |
Specifies a rating group based on which usage records are rated.
Possible values:
- `ByBillingPeriod` (default): The rating is based on all the usages in a billing period.
- `ByUsageStartDate`: The rating is based on all the usages on the same usage start date.
- `ByUsageRecord`: The rating is based on each usage record.
- `ByUsageUpload`: The rating is based on all the usages in a uploaded usage file (`.xls` or `.csv`).
- `ByGroupId`: The rating is based on all the usages in a custom group.
**Note:**
- The `ByBillingPeriod` value can be applied for all charge models.
- The `ByUsageStartDate`, `ByUsageRecord`, and `ByUsageUpload` values can only be applied for per unit, volume pricing, and tiered pricing charge models.
- The `ByGroupId` value is only available if you have the Active Rating feature enabled.
- Use this field only for Usage charges. One-Time Charges and Recurring Charges return `NULL`.
type: string
specificBillingPeriod:
description: |
Specifies the number of month or week for the charges billing period. Required if you set the value of the `billingPeriod` field to `Specific_Months` or `Specific_Weeks`.
format: int64
type: integer
specificEndDate:
description: |
Defines when the charge ends after the charge trigger date.
**Note**:
* This field is only applicable when the `endDateCondition` field is set to `Specific_End_Date`.
* If the subscription ends before the specific end date, the charge ends when the subscription ends. But if the subscription end date is subsequently changed through a Renewal, or Terms and Conditions amendment, the charge will end on the specific end date.
format: date
type: string
specificListPriceBase:
description: |
The number of months for the list price base of the charge. This field is required if you set the value of the `listPriceBase` field to `Per_Specific_Months`.
**Note**:
- This field is available only if you have the Annual List Price feature enabled.
- The value of this field is `null` if you do not set the value of the `listPriceBase` field to `Per_Specific_Months`.
format: int32
maximum: 200
minimum: 1
type: integer
tiers:
description: |
Container for Volume, Tiered, or Tiered with Overage charge models. Supports the following charge types:
* One-time
* Recurring
* Usage-based
items:
$ref: '#/components/schemas/POSTTierType'
type: array
triggerDate:
description: |
Specifies when to start billing the customer for the charge. Required if the `triggerEvent` field is set to `USD`.
format: date
type: string
triggerEvent:
description: |
Specifies when to start billing the customer for the charge.
Values:
* `UCE`
* `USA`
* `UCA`
* `USD`
type: string
unusedUnitsCreditRates:
description: |
Specifies the rate to credit a customer for unused units of usage. This field applies only for overage charge models when the `OverageUnusedUnitsCreditOption` field is set to `CreditBySpecificRate`.
type: number
upToPeriods:
description: |
Specifies the length of the period during which the charge is active. If this period ends before the subscription ends, the charge ends when this period ends.
**Note:** You must use this field together with the `upToPeriodsType` field to specify the time period.
* This field is applicable only when the `endDateCondition` field is set to `Fixed_Period`.
* If the subscription end date is subsequently changed through a Renewal, or Terms and Conditions amendment, the charge end date will change accordingly up to the original period end.
format: int64
type: integer
upToPeriodsType:
description: |
The period type used to define when the charge ends.
Values:
* `Billing_Periods`
* `Days`
* `Weeks`
* `Months`
* `Years`
You must use this field together with the `upToPeriods` field to specify the time period.
This field is applicable only when the `endDateCondition` field is set to `Fixed_Period`.
type: string
weeklyBillCycleDay:
description: |
Specifies which day of the week is the bill cycle day (BCD) for the charge.
Values:
* `Sunday`
* `Monday`
* `Tuesday`
* `Wednesday`
* `Thursday`
* `Friday`
* `Saturday`
type: string
required:
- productRatePlanChargeId
type: object
- $ref: '#/components/schemas/RatePlanChargeObjectCustomFields'
title: chargeOverrides
RatePlanObjectCustomFields:
additionalProperties:
description: |
Custom fields of the Rate Plan object. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
description: |
Container for custom fields of a Rate Plan object.
title: RatePlanCustomFields
type: object
ChargeModelConfigurationType:
description: |
Container for charge model configuration data.
**Note**: This field is only available if you have the High Water Mark, Pre-Rated Pricing, or Multi-Attribute Pricing charge models enabled. These charge models are available for customers with Enterprise and Nine editions by default. If you are a Growth customer, see [Zuora Editions](https://docs.zuora.com/en/entitlements/current-entitlements/zuora-editions) for pricing information.
properties:
customFieldPerUnitRate:
description: |
The custom field that carries the per-unit rate for each usage record. For example, `perUnitAmount__c`.
This field is only available for the usage-based charges that use the Pre-Rated Per Unit Pricing charge model. The charge model is available for customers with Enterprise and Nine editions by default. If you are a Growth customer, see [Zuora Editions](https://docs.zuora.com/en/entitlements/current-entitlements/zuora-editions) for pricing information.
type: string
customFieldTotalAmount:
description: |
The custom field that carries the total amount to charge for a usage record. For example, `totalAmount__c`.
This field is only available for the usage-based charges that use the Pre-Rated Pricing charge model. The charge model is available for customers with Enterprise and Nine editions by default. If you are a Growth customer, see [Zuora Editions](https://docs.zuora.com/en/entitlements/current-entitlements/zuora-editions) for pricing information.
type: string
formula:
description: |
The pricing formula to calculate actual rating amount for each usage record.
This field is only available for the usage-based charges that use the Multi-Attribute Pricing charge model. The charge model is available for customers with Enterprise and Nine editions by default. If you are a Growth customer, see [Zuora Editions](https://docs.zuora.com/en/entitlements/current-entitlements/zuora-editions) for pricing information.
type: string
title: chargeModelConfiguration
type: object
POSTTierType:
properties:
endingUnit:
description: |
End number of a range of units for the tier.
type: number
price:
description: |
Price of the tier if the charge is a flat fee, or the price of each unit in the tier if the charge model is tiered pricing.
type: number
priceFormat:
description: |
Indicates if pricing is a flat fee or is per unit.
Values:
* `FlatFee`
* `PerUnit`
type: string
startingUnit:
description: |
Starting number of a range of units for the tier.
type: number
tier:
description: |
Unique number that identifies the tier that the price applies to.
format: int64
type: integer
required:
- tier
- price
title: tiers
type: object
RatePlanChargeObjectCustomFields:
additionalProperties:
description: |
Custom fields of the Rate Plan Charge object. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
description: |
Container for custom fields of a Rate Plan Charge object.
title: ratePlanChargeFieldsCustom
type: object
ContactObjectCustomFields:
additionalProperties:
description: |
Custom fields of the Contact object. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
description: |
Container for custom fields of a Contact object.
title: contactFieldsCustom
type: object
CreatePaymentMethodCreditCard:
allOf:
- type: object
properties:
type:
type: string
cardHolderInfo:
$ref: '#/components/schemas/CreatePaymentMethodCardholderInfo'
cardMaskNumber:
description: |
The masked card number.
Currently, this field is only supported on certain integrations. See this article for more information.
type: string
cardNumber:
description: |
Credit card number.
type: string
cardType:
description: |
The type of the credit card.
Possible values include `Visa`, `MasterCard`, `AmericanExpress`, `Discover`, `JCB`, and `Diners`. For more information about credit card types supported by different payment gateways, see Supported Payment Gateways.
type: string
checkDuplicated:
description: |
Indicates whether the duplication check is performed when you create a new credit card payment method. The default value is `false`.
With this field set to `true`, Zuora will check all active payment methods associated with the same billing account to ensure that no duplicate credit card payment methods are created. An error is returned if a duplicate payment method is found.
The following fields are used for the duplication check:
- `cardHolderName`
- `expirationMonth`
- `expirationYear`
- `creditCardMaskNumber`. It is the masked credit card number generated by Zuora. For example, `************1234`.
**This field is being deprecated.** To achieve the same purpose, use the `processingOptions` > `checkDuplicated` field of the payment method object.
type: boolean
expirationMonth:
description: |
One or two digit expiration month (1-12) of the credit card.
type: integer
expirationYear:
description: |
Four-digit expiration year of the credit card.
type: integer
identityNumber:
description: |
The identity number of the cardholder. This field is required for Credit Card payment methods in certain countries such as Brazil.
type: string
mitConsentAgreementRef:
description: |
Specifies your reference for the stored credential consent agreement that you have established with the customer. Only applicable if you set the `mitProfileAction` field.
maxLength: 128
type: string
mitConsentAgreementSrc:
description: |
Required if you set the `mitProfileAction` field. Specifies how the consent agreement has been established with the customer. The allowed value is `External`. If you do not specify the `mitProfileAction` field, Zuora will automatically create a stored credential profile for the payment method, with the default value `External` set to this field.
enum:
- External
type: string
mitNetworkTransactionId:
description: |
Specifies the ID of a network transaction. Only applicable if you set the `mitProfileAction` field to `Persist`.
maxLength: 128
type: string
mitProfileAction:
description: |
Specifies how Zuora creates and activates the stored credential profile.
- `Activate` - Use this value if you are creating the stored credential profile after receiving the customer's consent.
Zuora will create the stored credential profile then send a cardholder-initiated transaction (CIT) to the payment gateway to validate the stored credential profile. If the CIT succeeds, the status of the stored credential profile will be `Active`. If the CIT does not succeed, Zuora will not create a stored credential profile.
If the payment gateway does not support the stored credential transaction framework, the status of the stored credential profile will be `Agreed`.
- `Persist` - Use this value if the stored credential profile represents a stored credential profile in an external system. The status of the payment method's stored credential profile will be `Active`.
If you do not specify this field, Zuora will automatically create a stored credential profile for the payment method, with the default value `Activate` set to this field.
enum:
- Activate
- Persist
type: string
mitProfileAgreedOn:
description: |
The date on which the profile is agreed. The date format is `yyyy-mm-dd`.
format: date
type: string
mitProfileType:
description: |
Required if you set the `mitProfileAction` field. Indicates the type of the stored credential profile to process recurring or unsecheduled transactions. If you do not specify the `mitProfileAction` field, Zuora will automatically create a stored credential profile for the payment method, with the default value `Recurring` set to this field.
enum:
- Recurring
- Unscheduled
type: string
screeningAmount:
description: |
For Chase Paymentech Orbital Gateway integrations, if the Safetech Fraud service is enabled, use this field to pass in the amount used for fraud screening for Credit Card validation transactions.
Two-decimal amount is supported.
If the `screeningAmount` field is not specified, the authorization amount is used for fraud screening.
format: decimal
type: number
securityCode:
description: |
CVV or CVV2 security code of the credit card.
To ensure PCI compliance, this value is not stored and cannot be queried.
type: string
tokens:
description: |
To create tokenized payment methods, pass in the existing token information through the fields in this container.
Currently, this field is only supported on certain integrations. See this article for more information.
properties:
gatewayType:
description: |
The type of the payment gateway to generate the tokens. This field is
case-sensitive.
type: string
secondTokenId:
description: |
Pass in the second token of the payment method.
type: string
thirdTokenId:
description: |
Pass in the third token of the payment method.
type: string
tokenId:
description: |
Pass in the first token of the payment method.
type: string
required:
- gatewayType
- tokenId
type: object
tokenize:
default: false
description: |
Specify `true` to tokenize the payment method with the card information.
Currently, this field is only supported on certain integrations.
See this article for more information.
type: boolean
mandateInfo:
description: |
The container of the mandate information for the payment method.
properties:
mandateId:
description: |
The mandate ID.
maxLength: 36
type: string
mandateReason:
description: |
The reason of the mandate from the gateway side.
maxLength: 64
type: string
mandateStatus:
description: |
The status of the mandate from the gateway side.
maxLength: 64
type: string
type: object
processingOptions:
description: |
The container for payment method processing options.
type: object
properties:
checkDuplicated:
description: |
Indicates whether to perform a duplication check when you create a payment method.
The default value is `false`.
With this field set to `true`, Zuora will check the active and closed payment methods associated with the same billing account to ensure that no duplicate payment methods are created.
For more information, see Duplication check on payment methods.
type: boolean
- $ref: '#/components/schemas/PaymentMethodCommonFields'
- $ref: '#/components/schemas/PaymentMethodObjectCustomFields'
required:
- type
- cardHolderInfo
- cardNumber
- cardType
- expirationMonth
- expirationYear
example:
accountKey: 8ad09be48db5aba7018db604776d4854
type: CreditCard
cardType: Visa
cardNumber: '4111111111111111'
expirationMonth: 12
expirationYear: 2028
cardHolderInfo:
cardHolderName: Amy Lawrence
CreatePaymentMethodCCReferenceTransaction:
allOf:
- type: object
properties:
type:
type: string
creditCardMaskNumber:
description: |
The masked credit card number, such as `*********1112`.
This field is specific for the CC Reference Transaction payment method. It is an optional field that you can use to distinguish different CC Reference Transaction payment methods.
Though there are no special restrictions on the input string, it is highly recommended to specify a card number that is masked.
maxLength: 19
type: string
secondTokenId:
description: |
A gateway unique identifier that replaces sensitive payment method data.
`secondTokenId` is conditionally required only when `tokenId` is being used to represent a gateway customer profile. `secondTokenId` is used in the CC Reference Transaction payment method.
type: string
tokenId:
description: |
A gateway unique identifier that replaces sensitive payment method data or represents a gateway's unique customer profile.
When `tokenId` is used to represent a customer profile, `secondTokenId` is conditionally required for representing the underlying tokenized payment method.
The values for the `tokenId` and `secondTokenId` fields differ for gateways. For more information, see the Knowledge Center article specific to each gateway that supports the CC Reference Transaction payment method.
type: string
mandateInfo:
description: |
The container of the mandate information for the payment method.
properties:
mandateId:
description: |
The mandate ID.
maxLength: 36
type: string
mandateReason:
description: |
The reason of the mandate from the gateway side.
maxLength: 64
type: string
mandateStatus:
description: |
The status of the mandate from the gateway side.
maxLength: 64
type: string
- $ref: '#/components/schemas/PaymentMethodCommonFields'
- $ref: '#/components/schemas/PaymentMethodObjectCustomFields'
type: object
required:
- type
- tokenId
example:
accountKey: 8a90d6128d45df2b018d4b90681c05x0
tokenId: A9xCTM0A3D7g0OOiYnwxJMjkZ6Nn8yMDusVbnhvH
secondTokenId: B4D339HPV3KHQQ65
creditCardMaskNumber: '************1111'
type: CreditCardReferenceTransaction
CreatePaymentMethodACH:
allOf:
- properties:
type:
type: string
addressLine1:
description: |
First address line, 255 characters or less.
type: string
addressLine2:
description: |
Second address line, 255 characters or less.
type: string
bankABACode:
description: |
The nine-digit routing number or ABA number used by banks. This field is
only required if the `type` field is set to `ACH`.
type: string
bankAccountMaskNumber:
description: |
The masked account number such as ****1234.
Currently, this field is only supported on certain integrations.
See this article for more information.
type: string
bankAccountName:
description: |
The name of the account holder, which can be either a person or a company.
For ACH payment methods on the BlueSnap integration, see [Overview of
BlueSnap gateway
integration](https://knowledgecenter.zuora.com/Zuora_Billing/Billing_and_Payments/M_Payment_Gateways/Supported_Payment_Gateways/BlueSnap_Gateway/Overview_of_BlueSnap_gateway_integration#Payer_Name_Extraction)
for more information about how Zuora splits the string in this field into
two parts and passes them to BlueSnap's `firstName` and `lastName` fields.
maxLength: 70
type: string
bankAccountNumber:
description: |
The bank account number associated with the ACH payment.
For the creation of tokenized ACH payment methods, this field is optional. Currently, ACH tokenization is supported on selected payment gateway integrations.
See this article for more information.
maxLength: 30
type: string
bankAccountType:
description: |
The type of bank account associated with the ACH payment.
When creating an ACH payment method on Adyen, this field is required by
Zuora but it is not required by Adyen. To create the ACH payment method
successfully, specify a real value for this field if you can. If it is not
possible to get the real value for it, specify any of the allowed values
as a dummy value, `Checking` preferably.
enum:
- BusinessChecking
- Checking
- Saving
type: string
bankName:
description: |
The name of the bank where the ACH payment account is held.
When creating an ACH payment method on Adyen, this field is required by
Zuora but it is not required by Adyen. To create the ACH payment method
successfully, specify a real value for this field if you can. If it is not
possible to get the real value for it, specify a dummy value.
maxLength: 70
type: string
city:
description: |
City, 40 characters or less.
It is recommended to provide the city and country information when
creating a payment method. The information will be used to process
payments. If the information is not provided during payment method
creation, the city and country data will be missing during payment
processing.
type: string
country:
description: |
Country, must be a valid country name or abbreviation.
See View countries or regions
for the list of supported country names and abbreviations.
It is recommended to provide the city and country information when
creating a payment method. The information will be used to process
payments. If the information is not provided during payment method
creation, the city and country data will be missing during payment
processing.
type: string
phone:
description: |
Phone number, 40 characters or less.
type: string
state:
description: |
State, must be a valid subregion (state or province) name or code. For more information, see View subregions of a specific country or region.
type: string
zipCode:
description: |
Zip code, 20 characters or less.
type: string
mandateInfo:
description: |
The container of the mandate information for the payment method.
properties:
mandateId:
description: |
The mandate ID.
maxLength: 36
type: string
mandateReason:
description: |
The reason of the mandate from the gateway side.
maxLength: 64
type: string
mandateStatus:
description: |
The status of the mandate from the gateway side.
maxLength: 64
type: string
type: object
processingOptions:
description: |
The container for payment method processing options.
properties:
checkDuplicated:
description: |
Indicates whether to perform a duplication check when you create a payment method.
The default value is `false`.
With this field set to `true`, Zuora will check the active and closed payment methods associated with the same billing account to ensure that no duplicate payment methods are created.
For more information, see Duplication check on payment methods.
type: boolean
type: object
tokens:
description: |
To create tokenized payment methods, pass in the existing token information through the fields in this container.
Currently, this field is only supported on certain integrations.
See this article for more information.
properties:
gatewayType:
description: |
The type of the payment gateway to generate the tokens. This field is
case-sensitive.
type: string
secondTokenId:
description: |
Pass in the second token of the payment method.
type: string
thirdTokenId:
description: |
Pass in the third token of the payment method.
type: string
tokenId:
description: |
Pass in the first token of the payment method.
type: string
type: object
required:
- gatewayType
- tokenId
tokenize:
default: false
description: |
Specify `true` to tokenize the payment method with the account information.
Currently, this field is only supported on certain integrations.
See this article for more information.
type: boolean
type: object
title: AchPaymentMethod
- $ref: '#/components/schemas/PaymentMethodCommonFields'
- $ref: '#/components/schemas/PaymentMethodObjectCustomFields'
required:
- type
- bankABACode
- bankAccountName
- bankAccountNumber
- bankAccountType
- bankName
example:
accountKey: 8a90d6128d45df2b018d4b90681c05x0
bankABACode: '999999999'
bankAccountName: TestName
bankAccountNumber: '999999999'
bankAccountType: Checking
bankName: TestBank
addressLine1: Test Address line1
addressLine2: Test Address line2
phone: '1234567890'
city: testCity
country: USA
state: Alaska
zipCode: '123456'
processingOptions:
checkDuplicated: true
type: ACH
CreatePaymentMethodSEPA:
allOf:
- properties:
type:
type: string
IBAN:
description: |
The International Bank Account Number.
This field is required if the `type` field is set to `SEPA`.
However, for the creation of tokenized SEPA payment methods, this field is optional.
Currently, SEPA tokenization is supported on selected payment gateway integrations.
See this article for more information.
type: string
accountHolderInfo:
description: |
The container for the account holder information. The nested `accountHolderName` field is required.
However, for the creation of tokenized SEPA payment methods, this field is optional.
Currently, SEPA tokenization is supported on selected payment gateway integrations.
See this article for more information.
properties:
accountHolderName:
description: |
The full name of the bank account holder.
maxLength: 60
type: string
addressLine1:
description: |
The first line of the address for the account holder.
This field is required for SEPA Direct Debit payment methods on Stripe v2 for [certain countries](https://stripe.com/docs/payments/sepa-debit/set-up-payment?platform=web#web-submit-payment-method).
type: string
addressLine2:
description: |
The second line of the address for the account holder.
type: string
city:
description: |
The city where the account holder stays.
It is recommended to provide the city and country information when creating a payment method. The information will be used to process payments. If the information is not provided during payment method creation, the city and country data will be missing during payment processing.
type: string
country:
description: |
The country where the account holder stays.
This field is required for SEPA payment methods on Stripe v2 for [certain countries](https://stripe.com/docs/payments/sepa-debit/set-up-payment?platform=web#web-submit-payment-method).
type: string
email:
description: |
The email address of the account holder.
type: string
firstName:
description: |
The first name of the account holder.
type: string
lastName:
description: |
The last name of the account holder.
type: string
phone:
description: |
The phone number of the account holder.
type: string
state:
description: |
The state where the account holder stays.
type: string
zipCode:
description: |
The zip code for the address of the account holder.
type: string
type: object
required:
- accountHolderName
accountMaskNumber:
description: |
The masked account number such as ****1234.
When creating tokenized SEPA payment methods, this `accountMaskNumber` field is required if the `tokens` field is provided.
Currently, SEPA tokenization is supported on selected payment gateway integrations.
See this article for more information.
type: string
businessIdentificationCode:
description: |
The BIC code used for SEPA.
type: string
mandateInfo:
description: |
The container of the mandate information for the payment method.
properties:
mandateId:
description: |
The mandate ID.
maxLength: 36
type: string
mandateReason:
description: |
The reason of the mandate from the gateway side.
maxLength: 64
type: string
mandateStatus:
description: |
The status of the mandate from the gateway side.
maxLength: 64
type: string
type: object
tokenize:
default: false
description: |
When creating a SEPA payment method on Adyen Integration v2.0, use this
field to specify whether to tokenize the payment method with IBAN. If
`tokenize` is `true`, `IBAN` is required. If the `tokens` field is provided, this `tokenize` field is not required. For more information about how to create tokenized SEPA payment methods on
Adyen, see Tokenize SEPA payment methods on Adyen Integration
v2.0.
type: boolean
tokens:
description: |
To create tokenized payment methods, pass in the existing token information through the fields in this container.
Currently, SEPA tokenization is supported on selected payment gateway integrations.
See this article for more information.
properties:
gatewayType:
description: |
The type of the payment gateway to generate the tokens. This field is
case-sensitive.
enum:
- Adyen
- Stripe
type: string
secondTokenId:
description: |
Pass in the second token of the payment method.
type: string
thirdTokenId:
description: |
Pass in the third token of the payment method.
type: string
tokenId:
description: |
Pass in the first token of the payment method.
type: string
type: object
required:
- gatewayType
- tokenId
processingOptions:
description: |
The container for payment method processing options.
properties:
checkDuplicated:
description: |
Indicates whether to perform a duplication check when you create a payment method.
The default value is `false`.
With this field set to `true`, Zuora will check the active and closed payment methods associated with the same billing account to ensure that no duplicate payment methods are created.
For more information, see Duplication check on payment methods.
type: boolean
type: object
type: object
- $ref: '#/components/schemas/PaymentMethodCommonFields'
- $ref: '#/components/schemas/PaymentMethodObjectCustomFields'
required:
- type
- IBAN
- accountHolderInfo
example:
accountKey: 8a90d6128d45df2b018d4b90681c05x0
IBAN: FR1420041010050500013M02606
accountHolderInfo:
accountHolderName: TestName
processingOptions:
checkDuplicated: true
type: SEPA
CreatePaymentMethodBetalingsservice:
allOf:
- properties:
type:
type: string
accountHolderInfo:
description: |
The container for the account holder information. The nested `accountHolderName` field is required.
properties:
accountHolderName:
description: |
Required.
The full name of the bank account holder.
maxLength: 60
type: string
addressLine1:
description: |
The first line of the address for the account holder.
type: string
addressLine2:
description: |
The second line of the address for the account holder.
type: string
city:
description: |
The city where the account holder stays.
It is recommended to provide the city and country information when creating a payment method. The information will be used to process payments. If the information is not provided during payment method creation, the city and country data will be missing during payment processing.
type: string
country:
description: |
The country where the account holder stays.
type: string
email:
description: |
The email address of the account holder.
type: string
firstName:
description: |
The first name of the account holder.
type: string
lastName:
description: |
The last name of the account holder.
type: string
phone:
description: |
The phone number of the account holder.
type: string
state:
description: |
The state where the account holder stays.
type: string
zipCode:
description: |
The zip code for the address of the account holder.
type: string
type: object
accountNumber:
description: |
The number of the customer's bank account.
type: string
accountMaskNumber:
description: |
The masked account number such as ****1234.
type: string
bankCode:
description: |
The sort code or number that identifies the bank. This is also known as the sort code.
type: string
identityNumber:
description: |
The identity number used for Bank Transfer.
type: string
mandateInfo:
description: |
The container of the mandate information for the payment method.
properties:
mandateId:
description: |
The mandate ID.
maxLength: 36
type: string
mandateReason:
description: |
The reason of the mandate from the gateway side.
maxLength: 64
type: string
mandateStatus:
description: |
The status of the mandate from the gateway side.
maxLength: 64
type: string
type: object
processingOptions:
description: |
The container for payment method processing options.
properties:
checkDuplicated:
description: |
Indicates whether to perform a duplication check when you create a payment method.
The default value is `false`.
With this field set to `true`, Zuora will check the active and closed payment methods associated with the same billing account to ensure that no duplicate payment methods are created.
For more information, see Duplication check on payment methods.
type: boolean
type: object
type: object
- $ref: '#/components/schemas/PaymentMethodCommonFields'
- $ref: '#/components/schemas/PaymentMethodObjectCustomFields'
required:
- type
- accountNumber
- identityNumber
- bankCode
- accountHolderInfo
example:
accountKey: 8a90d6128d45df2b018d4b90681c05x0
accountNumber: '3179681'
identityNumber: '0101701234'
bankCode: '345'
accountHolderInfo:
accountHolderName: TestName
processingOptions:
checkDuplicated: true
type: Betalingsservice
CreatePaymentMethodAutogiro:
allOf:
- properties:
type:
type: string
accountHolderInfo:
description: |
The container for the account holder information. The nested `accountHolderName` field is required.
properties:
accountHolderName:
description: |
Required.
The full name of the bank account holder.
maxLength: 60
type: string
addressLine1:
description: |
The first line of the address for the account holder.
type: string
addressLine2:
description: |
The second line of the address for the account holder.
type: string
city:
description: |
The city where the account holder stays.
It is recommended to provide the city and country information when creating a payment method. The information will be used to process payments. If the information is not provided during payment method creation, the city and country data will be missing during payment processing.
type: string
country:
description: |
The country where the account holder stays.
type: string
email:
description: |
The email address of the account holder.
type: string
firstName:
description: |
The first name of the account holder.
type: string
lastName:
description: |
The last name of the account holder.
type: string
phone:
description: |
The phone number of the account holder.
type: string
state:
description: |
The state where the account holder stays.
type: string
zipCode:
description: |
The zip code for the address of the account holder.
type: string
type: object
accountNumber:
description: |
The number of the customer's bank account.
type: string
accountMaskNumber:
description: |
The masked account number such as ****1234.
type: string
branchCode:
description: |
The branch code of the bank used for direct debit.
type: string
identityNumber:
description: |
The identity number used for Bank Transfer.
type: string
mandateInfo:
description: |
The container of the mandate information for the payment method.
properties:
mandateId:
description: |
The mandate ID.
maxLength: 36
type: string
mandateReason:
description: |
The reason of the mandate from the gateway side.
maxLength: 64
type: string
mandateStatus:
description: |
The status of the mandate from the gateway side.
maxLength: 64
type: string
type: object
processingOptions:
description: |
The container for payment method processing options.
properties:
checkDuplicated:
description: |
Indicates whether to perform a duplication check when you create a payment method.
The default value is `false`.
With this field set to `true`, Zuora will check the active and closed payment methods associated with the same billing account to ensure that no duplicate payment methods are created.
For more information, see Duplication check on payment methods.
type: boolean
type: object
type: object
title: AutogiroPaymentMethod
- $ref: '#/components/schemas/PaymentMethodCommonFields'
- $ref: '#/components/schemas/PaymentMethodObjectCustomFields'
required:
- type
- accountNumber
- identityNumber
- branchCode
- accountHolderInfo
example:
accountKey: 8a90d6128d45df2b018d4b90681c05x0
accountNumber: '0000003'
identityNumber: '198112289874'
branchCode: '5491'
accountHolderInfo:
accountHolderName: TestName
processingOptions:
checkDuplicated: true
type: Autogiro
CreatePaymentMethodBacs:
allOf:
- properties:
type:
type: string
accountHolderInfo:
description: |
The container for the account holder information. The nested `accountHolderName` field is required.
properties:
accountHolderName:
description: |
Required.
The full name of the bank account holder.
maxLength: 60
type: string
addressLine1:
description: |
The first line of the address for the account holder.
type: string
addressLine2:
description: |
The second line of the address for the account holder.
type: string
city:
description: |
The city where the account holder stays.
It is recommended to provide the city and country information when creating a payment method. The information will be used to process payments. If the information is not provided during payment method creation, the city and country data will be missing during payment processing.
type: string
country:
description: |
The country where the account holder stays.
type: string
email:
description: |
The email address of the account holder.
type: string
firstName:
description: |
The first name of the account holder.
type: string
lastName:
description: |
The last name of the account holder.
type: string
phone:
description: |
The phone number of the account holder.
type: string
state:
description: |
The state where the account holder stays.
type: string
zipCode:
description: |
The zip code for the address of the account holder.
type: string
type: object
accountNumber:
description: |
The number of the customer's bank account.
type: string
accountMaskNumber:
description: |
The masked account number such as ****1234.
When creating BACS payment methods on Stripe, if the `tokens` field is provided, this `accountMaskNumber` field is required. For more information, see Overview of Stripe payment gateway integration.
type: string
bankCode:
description: |
The sort code or number that identifies the bank. This is also known as the sort code.
type: string
mandateInfo:
description: |
The container of the mandate information for the payment method.
properties:
mandateId:
description: |
The mandate ID.
maxLength: 36
type: string
mandateReason:
description: |
The reason of the mandate from the gateway side.
maxLength: 64
type: string
mandateStatus:
description: |
The status of the mandate from the gateway side.
maxLength: 64
type: string
type: object
tokenize:
default: false
description: |
When creating a BACS payment method on Adyen v2.0, set this field to `true` to support processing BACS recurring payments. For more information about other requirements for processing BACS recurring payments, see Overview of Adyen Integration v2.0.
type: boolean
tokens:
description: |
To create tokenized BACS payment methods on Stripe v2, pass in the existing token information through the fields in this container.
For more information, see Overview of Stripe payment gateway integration.
properties:
gatewayType:
description: |
Required.
The type of the payment gateway to generate the tokens. This field is case-sensitive.
enum:
- Stripe
type: string
secondTokenId:
description: |
Pass in the second token of the payment method. For more information, see Overview of Stripe payment gateway integration.
type: string
thirdTokenId:
description: |
Pass in the third token of the payment method.
type: string
tokenId:
description: |
Required.
Pass in the first token of the payment method. For more information, see Overview of Stripe payment gateway integration.
type: string
type: object
processingOptions:
description: |
The container for payment method processing options.
properties:
checkDuplicated:
description: |
Indicates whether to perform a duplication check when you create a payment method.
The default value is `false`.
With this field set to `true`, Zuora will check the active and closed payment methods associated with the same billing account to ensure that no duplicate payment methods are created.
For more information, see Duplication check on payment methods.
type: boolean
type: object
type: object
title: BacsPaymentMethod
- $ref: '#/components/schemas/PaymentMethodCommonFields'
- $ref: '#/components/schemas/PaymentMethodObjectCustomFields'
required:
- type
- accountNumber
- bankCode
- accountHolderInfo
example:
accountKey: 8a90d6128d45df2b018d4b90681c05x0
accountNumber: '55779911'
bankCode: '200000'
accountHolderInfo:
accountHolderName: TestName
processingOptions:
checkDuplicated: true
type: Bacs
CreatePaymentMethodBecs:
allOf:
- properties:
type:
type: string
accountHolderInfo:
description: |
The container for the account holder information. The nested `accountHolderName` field is required.
properties:
accountHolderName:
description: |
Required.
The full name of the bank account holder.
maxLength: 60
type: string
addressLine1:
description: |
The first line of the address for the account holder.
type: string
addressLine2:
description: |
The second line of the address for the account holder.
type: string
city:
description: |
The city where the account holder stays.
It is recommended to provide the city and country information when creating a payment method. The information will be used to process payments. If the information is not provided during payment method creation, the city and country data will be missing during payment processing.
type: string
country:
description: |
The country where the account holder stays.
type: string
email:
description: |
The email address of the account holder.
type: string
firstName:
description: |
The first name of the account holder.
type: string
lastName:
description: |
The last name of the account holder.
type: string
phone:
description: |
The phone number of the account holder.
type: string
state:
description: |
The state where the account holder stays.
type: string
zipCode:
description: |
The zip code for the address of the account holder.
type: string
type: object
accountNumber:
description: |
The number of the customer's bank account.
type: string
accountMaskNumber:
description: |
The masked account number such as ****1234.
type: string
branchCode:
description: |
The branch code of the bank used for direct debit.
type: string
mandateInfo:
description: |
The container of the mandate information for the payment method.
properties:
mandateId:
description: |
The mandate ID.
maxLength: 36
type: string
mandateReason:
description: |
The reason of the mandate from the gateway side.
maxLength: 64
type: string
mandateStatus:
description: |
The status of the mandate from the gateway side.
maxLength: 64
type: string
type: object
processingOptions:
description: |
The container for payment method processing options.
properties:
checkDuplicated:
description: |
Indicates whether to perform a duplication check when you create a payment method.
The default value is `false`.
With this field set to `true`, Zuora will check the active and closed payment methods associated with the same billing account to ensure that no duplicate payment methods are created.
For more information, see Duplication check on payment methods.
type: boolean
type: object
type: object
- $ref: '#/components/schemas/PaymentMethodCommonFields'
- $ref: '#/components/schemas/PaymentMethodObjectCustomFields'
required:
- type
- accountNumber
- branchCode
example:
accountKey: 8a90d6128d45df2b018d4b90681c05x0
accountNumber: '012345678'
branchCode: 082-082
accountHolderInfo:
accountHolderName: TestName
processingOptions:
checkDuplicated: true
type: Becs
CreatePaymentMethodBecsnz:
allOf:
- properties:
type:
type: string
accountHolderInfo:
description: |
The container for the account holder information. The nested `accountHolderName` field is required.
properties:
accountHolderName:
description: |
Required.
The full name of the bank account holder.
maxLength: 60
type: string
addressLine1:
description: |
The first line of the address for the account holder.
type: string
addressLine2:
description: |
The second line of the address for the account holder.
type: string
city:
description: |
The city where the account holder stays.
It is recommended to provide the city and country information when creating a payment method. The information will be used to process payments. If the information is not provided during payment method creation, the city and country data will be missing during payment processing.
type: string
country:
description: |
The country where the account holder stays.
type: string
email:
description: |
The email address of the account holder.
type: string
firstName:
description: |
The first name of the account holder.
type: string
lastName:
description: |
The last name of the account holder.
type: string
phone:
description: |
The phone number of the account holder.
type: string
state:
description: |
The state where the account holder stays.
type: string
zipCode:
description: |
The zip code for the address of the account holder.
type: string
type: object
accountNumber:
description: |
The number of the customer's bank account.
type: string
accountMaskNumber:
description: |
The masked account number such as ****1234.
type: string
branchCode:
description: |
The branch code of the bank used for direct debit.
type: string
bankCode:
description: |
The sort code or number that identifies the bank. This is also known as the sort code.
type: string
mandateInfo:
description: |
The container of the mandate information for the payment method.
properties:
mandateId:
description: |
The mandate ID.
maxLength: 36
type: string
mandateReason:
description: |
The reason of the mandate from the gateway side.
maxLength: 64
type: string
mandateStatus:
description: |
The status of the mandate from the gateway side.
maxLength: 64
type: string
type: object
processingOptions:
description: |
The container for payment method processing options.
properties:
checkDuplicated:
description: |
Indicates whether to perform a duplication check when you create a payment method.
The default value is `false`.
With this field set to `true`, Zuora will check the active and closed payment methods associated with the same billing account to ensure that no duplicate payment methods are created.
For more information, see Duplication check on payment methods.
type: boolean
type: object
type: object
- $ref: '#/components/schemas/PaymentMethodCommonFields'
- $ref: '#/components/schemas/PaymentMethodObjectCustomFields'
required:
- type
- accountNumber
- bankCode
- branchCode
- accountHolderInfo
example:
accountKey: 8a90d6128d45df2b018d4b90681c05x0
accountNumber: 0003869-00
accountHolderInfo:
accountHolderName: TestName
branchCode: '3113'
bankCode: '12'
processingOptions:
checkDuplicated: true
type: Becsnz
CreatePaymentMethodPAD:
allOf:
- properties:
type:
type: string
accountHolderInfo:
description: |
The container for the account holder information. The nested `accountHolderName` field is required.
properties:
accountHolderName:
description: |
Required.
The full name of the bank account holder.
maxLength: 60
type: string
addressLine1:
description: |
The first line of the address for the account holder.
type: string
addressLine2:
description: |
The second line of the address for the account holder.
type: string
city:
description: |
The city where the account holder stays.
It is recommended to provide the city and country information when creating a payment method. The information will be used to process payments. If the information is not provided during payment method creation, the city and country data will be missing during payment processing.
type: string
country:
description: |
The country where the account holder stays.
type: string
email:
description: |
The email address of the account holder.
type: string
firstName:
description: |
The first name of the account holder.
type: string
lastName:
description: |
The last name of the account holder.
type: string
phone:
description: |
The phone number of the account holder.
type: string
state:
description: |
The state where the account holder stays.
type: string
zipCode:
description: |
The zip code for the address of the account holder.
type: string
type: object
accountNumber:
description: |
The number of the customer's bank account.
type: string
accountMaskNumber:
description: |
The masked account number such as ****1234.
type: string
branchCode:
description: |
The branch code of the bank used for direct debit.
type: string
bankCode:
description: |
The sort code or number that identifies the bank. This is also known as the sort code.
type: string
mandateInfo:
description: |
The container of the mandate information for the payment method.
properties:
mandateId:
description: |
The mandate ID.
maxLength: 36
type: string
mandateReason:
description: |
The reason of the mandate from the gateway side.
maxLength: 64
type: string
mandateStatus:
description: |
The status of the mandate from the gateway side.
maxLength: 64
type: string
type: object
processingOptions:
description: |
The container for payment method processing options.
properties:
checkDuplicated:
description: |
Indicates whether to perform a duplication check when you create a payment method.
The default value is `false`.
With this field set to `true`, Zuora will check the active and closed payment methods associated with the same billing account to ensure that no duplicate payment methods are created.
For more information, see Duplication check on payment methods.
type: boolean
type: object
type: object
- $ref: '#/components/schemas/PaymentMethodCommonFields'
- $ref: '#/components/schemas/PaymentMethodObjectCustomFields'
required:
- type
- accountNumber
- bankCode
- branchCode
- accountHolderInfo
example:
accountKey: 8a90d6128d45df2b018d4b90681c05x0
accountNumber: '0000000'
accountHolderInfo:
accountHolderName: TestName
branchCode: '00006'
bankCode: '0003'
processingOptions:
checkDuplicated: true
type: PAD
CreatePMPayPalCP:
allOf:
- properties:
type:
type: string
BAID:
description: |
ID of a PayPal billing agreement.
type: string
example: I-1TJ3GAGG82Y9
email:
description: |
Email address associated with the payment method.
type: string
tokens:
description: |
To create tokenized payment methods, pass in the existing token information through the fields in this container.
Currently, this field is only supported on certain integrations. See this article for more information.
properties:
gatewayType:
description: |
The type of the payment gateway to generate the tokens. This field is
case-sensitive.
type: string
secondTokenId:
description: |
Pass in the second token of the payment method.
type: string
thirdTokenId:
description: |
Pass in the third token of the payment method.
type: string
tokenId:
description: |
Pass in the first token of the payment method.
type: string
required:
- gatewayType
- tokenId
type: object
tokenize:
default: false
description: |
Specify `true` to tokenize the payment method.
Currently, this field is only supported on certain integrations.
See this article for more information.
type: boolean
type: object
- $ref: '#/components/schemas/PaymentMethodCommonFields'
- $ref: '#/components/schemas/PaymentMethodObjectCustomFields'
required:
- type
- BAID
- email
example:
BAID: I-1TJ3GAGG82Y9
accountKey: 8a90d6128d45df2b018d4b90681c05x0
email: customer@example.com
type: PayPalCP
CreatePMPayPalEC:
allOf:
- properties:
type:
type: string
BAID:
description: |
ID of a PayPal billing agreement.
type: string
example: I-1TJ3GAGG82Y9
email:
description: |
Email address associated with the payment method.
type: string
type: object
- $ref: '#/components/schemas/PaymentMethodCommonFields'
- $ref: '#/components/schemas/PaymentMethodObjectCustomFields'
required:
- type
- BAID
- email
example:
BAID: I-1TJ3GAGG82Y9
accountKey: 8a90d6128d45df2b018d4b90681c05x0
email: customer@example.com
type: PayPalEC
CreatePMPayPalNativeEC:
allOf:
- properties:
type:
type: string
BAID:
description: |
ID of a PayPal billing agreement.
example: I-1TJ3GAGG82Y9
type: string
email:
description: |
Email address associated with the payment method.
type: string
type: object
- $ref: '#/components/schemas/PaymentMethodCommonFields'
- $ref: '#/components/schemas/PaymentMethodObjectCustomFields'
required:
- type
- BAID
example:
BAID: I-1TJ3GAGG82Y9
accountKey: 8a90d6128d45df2b018d4b90681c05x0
email: customer@example.com
type: PayPalNativeEC
CreatePaymentMethodPayPalAdaptive:
allOf:
- properties:
type:
type: string
preapprovalKey:
description: |
The PayPal preapproval key.
type: string
email:
description: |
Email address associated with the payment method.
type: string
format: email
type: object
- $ref: '#/components/schemas/PaymentMethodCommonFields'
- $ref: '#/components/schemas/PaymentMethodObjectCustomFields'
required:
- type
- preapprovalKey
- email
example:
preapprovalKey: PA-3X000000LS390262X
accountKey: 8a90d6128d45df2b018d4b90681c05x0
email: customer@example.com
type: PayPalAdaptive
CreatePaymentMethodApplePayAdyen:
allOf:
- properties:
type:
type: string
applePaymentData:
description: |
This field is specific for setting up Apple Pay for Adyen to include payload with Apple Pay token or Apple payment data. This information should be stringified. For more information, see [Set up Adyen Apple Pay](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/L_Payment_Methods/Payment_Method_Types/Apple_Pay_on_Web/Set_up_Adyen_Apple_Pay).
type: string
email:
type: string
format: email
description: |
Email address associated with the payment method. This field is specific for setting up Apple Pay on Adyen v2.0. This field will be passed to Adyen as `shopperEmail`.
type: object
- $ref: '#/components/schemas/PaymentMethodCommonFields'
required:
- type
- applePaymentData
example:
accountKey: 2c92c0f97911f46a0179147510484b90
type: AdyenApplePay
email: testemail@test.com
applePaymentData: '{"data":"hM8GTBX0UVhoKmJ/DkneZfwLlH/utWfEueshybbTpuzlf5i1IwO1kvW32SlFW7TmyvU98gf2Pp1FeyFCh7F2atmstxQdonkeJgpIUV7eWW1wUNaOeND28J8YQsEkDhC3sMgOJoju7FHcXNwveq5fk94StFZozRSi08oAjTnTJko5F32aY/JNWr19GiwWBHZe2jkokryt0TEWKO5hm5oTxeLs1LBOoC2ezaR+p2jQb4ISN2aCgCNiX8605w5eYWk7UCTK3Axf/EuJT4vHe75OKghEmcQLxvFzTtEw33ly6Nj2RJX3+I5TbYLXOfiAO0XnsWdhguDrKogtI44HMFqlNCdt79G71tXwCwbXz0VJywEh1d57tbU5Y5f6pw8TrjjeAMt9sa2pHuHmMGDf","signature":"MIAGCSqGSIb3DQEHAqCAMIACAQExDzANBglghkgBZQMEAgEFADCABgkqhkiG9w0BBwEAAKCAMIID5DCCA4ugAwIBAgIIWdihvKr0480wCgYIKoZIzj0EAwIwejEuMCwGA1UEAwwlQXBwbGUgQXBwbGljYXRpb24gSW50ZWdyYXRpb24gQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMB4XDTIxMDQyMDE5MzcwMFoXDTI2MDQxOTE5MzY1OVowYjEoMCYGA1UEAwwfZWNjLXNtcC1icm9rZXItc2lnbl9VQzQtU0FOREJPWDEUMBIGA1UECwwLaU9TIFN5c3RlbXMxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEgjD9q8Oc914gLFDZm0US5jfiqQHdbLPgsc1LUmeY+M9OvegaJajCHkwz3c6OKpbC9q+hkwNFxOh6RCbOlRsSlaOCAhEwggINMAwGA1UdEwEB/wQCMAAwHwYDVR0jBBgwFoAUI/JJxE+T5O8n5sT2KGw/orv9LkswRQYIKwYBBQUHAQEEOTA3MDUGCCsGAQUFBzABhilodHRwOi8vb2NzcC5hcHBsZS5jb20vb2NzcDA0LWFwcGxlYWljYTMwMjCCAR0GA1UdIASCARQwggEQMIIBDAYJKoZIhvdjZAUBMIH+MIHDBggrBgEFBQcCAjCBtgyBs1JlbGlhbmNlIG9uIHRoaXMgY2VydGlmaWNhdGUgYnkgYW55IHBhcnR5IGFzc3VtZXMgYWNjZXB0YW5jZSBvZiB0aGUgdGhlbiBhcHBsaWNhYmxlIHN0YW5kYXJkIHRlcm1zIGFuZCBjb25kaXRpb25zIG9mIHVzZSwgY2VydGlmaWNhdGUgcG9saWN5IGFuZCBjZXJ0aWZpY2F0aW9uIHByYWN0aWNlIHN0YXRlbWVudHMuMDYGCCsGAQUFBwIBFipodHRwOi8vd3d3LmFwcGxlLmNvbS9jZXJ0aWZpY2F0ZWF1dGhvcml0eS8wNAYDVR0fBC0wKzApoCegJYYjaHR0cDovL2NybC5hcHBsZS5jb20vYXBwbGVhaWNhMy5jcmwwHQYDVR0OBBYEFAIkMAua7u1GMZekplopnkJxghxFMA4GA1UdDwEB/wQEAwIHgDAPBgkqhkiG92NkBh0EAgUAMAoGCCqGSM49BAMCA0cAMEQCIHShsyTbQklDDdMnTFB0xICNmh9IDjqFxcE2JWYyX7yjAiBpNpBTq/ULWlL59gBNxYqtbFCn1ghoN5DgpzrQHkrZgTCCAu4wggJ1oAMCAQICCEltL786mNqXMAoGCCqGSM49BAMCMGcxGzAZBgNVBAMMEkFwcGxlIFJvb3QgQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMB4XDTE0MDUwNjIzNDYzMFoXDTI5MDUwNjIzNDYzMFowejEuMCwGA1UEAwwlQXBwbGUgQXBwbGljYXRpb24gSW50ZWdyYXRpb24gQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE8BcRhBnXZIXVGl4lgQd26ICi7957rk3gjfxLk+EzVtVmWzWuItCXdg0iTnu6CP12F86Iy3a7ZnC+yOgphP9URaOB9zCB9DBGBggrBgEFBQcBAQQ6MDgwNgYIKwYBBQUHMAGGKmh0dHA6Ly9vY3NwLmFwcGxlLmNvbS9vY3NwMDQtYXBwbGVyb290Y2FnMzAdBgNVHQ4EFgQUI/JJxE+T5O8n5sT2KGw/orv9LkswDwYDVR0TAQH/BAUwAwEB/zAfBgNVHSMEGDAWgBS7sN6hWDOImqSKmd6+veuv2sskqzA3BgNVHR8EMDAuMCygKqAohiZodHRwOi8vY3JsLmFwcGxlLmNvbS9hcHBsZXJvb3RjYWczLmNybDAOBgNVHQ8BAf8EBAMCAQYwEAYKKoZIhvdjZAYCDgQCBQAwCgYIKoZIzj0EAwIDZwAwZAIwOs9yg1EWmbGG+zXDVspiv/QX7dkPdU2ijr7xnIFeQreJ+Jj3m1mfmNVBDY+d6cL+AjAyLdVEIbCjBXdsXfM4O5Bn/Rd8LCFtlk/GcmmCEm9U+Hp9G5nLmwmJIWEGmQ8Jkh0AADGCAYswggGHAgEBMIGGMHoxLjAsBgNVBAMMJUFwcGxlIEFwcGxpY2F0aW9uIEludGVncmF0aW9uIENBIC0gRzMxJjAkBgNVBAsMHUFwcGxlIENlcnRpZmljYXRpb24gQXV0aG9yaXR5MRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUwIIWdihvKr0480wDQYJYIZIAWUDBAIBBQCggZUwGAYJKoZIhvcNAQkDMQsGCSqGSIb3DQEHATAcBgkqhkiG9w0BCQUxDxcNMjEwNjAzMTgzNzExWjAqBgkqhkiG9w0BCTQxHTAbMA0GCWCGSAFlAwQCAQUAoQoGCCqGSM49BAMCMC8GCSqGSIb3DQEJBDEiBCCiDFBojwOJgYgEzWaGdLTMez4XiDpYJd34PswTPVdt+DAKBggqhkjOPQQDAgRGMEQCIHAWYyr/s28rtd/khGapLi1jCg3iXwgUfL2l4XadiKq3AiBHuronD982WBP3x0Tzc51rXwMEVpL+GDPme9Ydn2MF2gAAAAAAAA==", "header": { "publicKeyHash":"vJeh5XAkv8SGX2JHswEbnCUPn01YHcQ6imAp+gP300w=", "ephemeralPublicKey":"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEVx9kP/eFM6MrP5sXKuzHT7f9Uhsc0Rox0FKvRpHIiqQ05EXYPsgBJZCEjOYlkviC2jDSvV6tEC8Kfq/z/GhrFA==", "transactionId":"7fd9ede5ea8c1d7a8985346c241a8933190a1acb408448c52ac27f7862f674ff" }, "version":"EC_v1" }'
CreatePaymentMethodGooglePayAdyen:
allOf:
- properties:
type:
type: string
googlePaymentToken:
description: |
This field is specific for setting up Google Pay for Adyen gateway integrations to specify the stringified Google Pay token. For more information, see [Set up Adyen Google Pay](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/L_Payment_Methods/Payment_Method_Types/Set_up_Adyen_Google_Pay).
type: string
email:
description: |
Email address associated with the payment method. This field is specific for setting up Google Pay on Adyen v2.0. This field will be passed to Adyen as `shopperEmail`.
type: string
type: object
- $ref: '#/components/schemas/PaymentMethodCommonFields'
required:
- type
- googlePaymentToken
example:
accountKey: 2c92c0f97911f46a0179147510484b90
type: AdyenGooglePay
email: testemail@test.com
googlePaymentToken: '{"signature":"MEUCICeJTEEW+a9ak93yk8pYg4xGlPJbrBNjD8b6vahxD5TRAiEAyMiNhzosJDl2N46Dojzc53bwbT/O0t+VToLCqr01qs4\u003d","protocolVersion":"ECv1","signedMessage":"{\"encryptedMessage\":\"aXpc95j3gEFJfaHF8PEpybNuV/k/IDKMa/FkbNnj2p/uaH8ll99hAUwWkH5EnHr2NwNgLuj3j9IhDomWI9gJ4n2fQlsQ9FsNuqsJjct/QuNvlzooLhu76HlzE3mScXcTUqPI1fgC8s/CVNz06aCUd7/oNMzyCw6VploO9abxp3zcpRvAO39bScaO3fri2Kl0WGozyiS0egXcUzMOpPxDw03SjmpgU/X5FjmxayOBUNxM9r/yOQyvY9mTUHOK855XVl3Xf9dpj6GDnDMp4bvCW8zpXWr76Snwtvv41dIaLxNWsBP0lS5PpJ5K1/rSRZg/dauIKQbWGmTTL24vz4Om7hVu25L7XrSM6F2PRUE4rqMblVDvXAlVsD+149r2fjXsB4DXmvGmwaDcuFeTDuI3ov7GDetgW3Fdl+n7RtBOK/luJYs76a9nPbVLhN/aKU5Hpd0ZrIO8ZUOoUYr6WuecD24tTzwic3k921eLJez8IJnG1k05kiqPpHEqMeLyP/WovjH/U7Vu3iDrH4yAxMEuh0MMi0tTgjXlVEezVnsU\",\"ephemeralPublicKey\":\"BGNnBpAd6WypQEYJmDH/DhUZ9mX2b/wJK6as8g6hZmDCDpHSWFC1BZ42UBrX/hrF/UarrT24CMcWLZp6fYl6PNw\\u003d\",\"tag\":\"j9fPmiEL/zj8R+0JRrTC1NgV9VVCYQ9zYaB7uZrEz9U\\u003d\"}"}'
CreatePaymentMethodGooglePayChase:
allOf:
- properties:
type:
type: string
googlePaymentToken:
description: |
This field is specific for setting up Google Pay on Chase gateway integrations to specify the stringified Google Pay token. For more information, see [Set up Google Pay on Chase](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/L_Payment_Methods/Payment_Method_Types/Set_up_Google_Pay_on_Chase).
type: string
type: object
- $ref: '#/components/schemas/PaymentMethodCommonFields'
required:
- type
- googlePaymentToken
example:
accountKey: 2c92c0f97911f46a0179147510484b90
type: GooglePay
googlePaymentToken: '{"signature":"MEUCICeJTEEW+a9ak93yk8pYg4xGlPJbrBNjD8b6vahxD5TRAiEAyMiNhzosJDl2N46Dojzc53bwbT/O0t+VToLCqr01qs4\u003d","protocolVersion":"ECv1","signedMessage":"{\"encryptedMessage\":\"aXpc95j3gEFJfaHF8PEpybNuV/k/IDKMa/FkbNnj2p/uaH8ll99hAUwWkH5EnHr2NwNgLuj3j9IhDomWI9gJ4n2fQlsQ9FsNuqsJjct/QuNvlzooLhu76HlzE3mScXcTUqPI1fgC8s/CVNz06aCUd7/oNMzyCw6VploO9abxp3zcpRvAO39bScaO3fri2Kl0WGozyiS0egXcUzMOpPxDw03SjmpgU/X5FjmxayOBUNxM9r/yOQyvY9mTUHOK855XVl3Xf9dpj6GDnDMp4bvCW8zpXWr76Snwtvv41dIaLxNWsBP0lS5PpJ5K1/rSRZg/dauIKQbWGmTTL24vz4Om7hVu25L7XrSM6F2PRUE4rqMblVDvXAlVsD+149r2fjXsB4DXmvGmwaDcuFeTDuI3ov7GDetgW3Fdl+n7RtBOK/luJYs76a9nPbVLhN/aKU5Hpd0ZrIO8ZUOoUYr6WuecD24tTzwic3k921eLJez8IJnG1k05kiqPpHEqMeLyP/WovjH/U7Vu3iDrH4yAxMEuh0MMi0tTgjXlVEezVnsU\",\"ephemeralPublicKey\":\"BGNnBpAd6WypQEYJmDH/DhUZ9mX2b/wJK6as8g6hZmDCDpHSWFC1BZ42UBrX/hrF/UarrT24CMcWLZp6fYl6PNw\\u003d\",\"tag\":\"j9fPmiEL/zj8R+0JRrTC1NgV9VVCYQ9zYaB7uZrEz9U\\u003d\"}"}'
CreatePaymentMethodAmazonPay:
allOf:
- properties:
type:
type: string
amazonPayToken:
description: |
This field is specific for setting up Amazon Pay gateway integrations to specify the stringified Amazon Pay token.
type: string
type: object
- $ref: '#/components/schemas/PaymentMethodCommonFields'
required:
- type
- amazonPayToken
example:
amazonPayToken: C03-0739300-4671639
amazonPayRegion: JP
accountKey: 2c92c0f97911f46a0179147510484b90
PaymentMethodCommonFields:
properties:
accountKey:
description: |
The customer account ID such as `2x92c0f859b0480f0159d3a4a6ee5bb6` or the customer account number such as `A02855638`.
To create an orphan payment method that is not associated with any customer account, you can skip this field. As soon as the account information is available, associate the payment method with an account through the [Update a payment method](https://developer.zuora.com/v1-api-reference/api/operation/PUT_PaymentMethod/) operation.
type: string
authGateway:
description: |
Internal ID of the payment gateway that Zuora will use to authorize the payments that are made with the payment method.
If you do not set this field, Zuora will use one of the following payment gateways instead:
* The default payment gateway of the customer account that owns the payment method, if the `accountKey` field is set.
* The default payment gateway of your Zuora tenant, if the `accountKey` field is not set.
If Payment Gateway Routing is enabled:
- If this field is not specified, gateway routing rules will be invoked.
- If this field is specified, the specified gateway will be used to process the payment.
If Payment Gateway Routing is disabled:
- If this field is not specified, the default payment gateway will be used to process the payment. The default gateway of the customer account takes precedence over the default gateway of the tenant.
- If this field is specified, the specified gateway will be used to process the payment.
type: string
currencyCode:
description: |
The currency used for payment method authorization.
type: string
example: USD
gatewayOptions:
description: |
The field used to pass gateway-specific parameters and parameter values. The fields supported by gateways vary. For more information, see the Overview topic of each gateway integration in [Zuora Knowledge Center](https://knowledgecenter.zuora.com/Zuora_Billing/Billing_and_Payments/M_Payment_Gateways/Supported_Payment_Gateways).
Zuora sends all the information that you specified to the gateway. If you specify any unsupported gateway option parameters, they will be ignored without error prompts.
properties:
key:
description: |
The name of a gateway-specific parameter.
type: string
value:
description: |
The value of the gateway-specific parameter.
type: string
type: object
example:
shopperInteraction: POS
shopperEmail: testemail@test.com
ipAddress:
description: |
The IPv4 or IPv6 information of the user when the payment method is created or updated. Some gateways use this field for fraud prevention. If this field is passed to Zuora, Zuora directly passes it to gateways.
If the IP address length is beyond 45 characters, a validation error occurs.
For validating SEPA payment methods on Stripe v2, this field is required.
type: string
makeDefault:
default: false
description: |
Specifies whether the payment method will be the default payment method of the customer account that owns the payment method. Only applicable if the `accountKey` field is set.
When you set this field to `true`, make sure the payment method is supported by the default payment gateway.
type: boolean
skipValidation:
default: false
description: |
Specify whether to skip the validation of the information through the payment gateway. For example, when migrating your payment methods, you can set this field to `true` to skip the validation.
type: boolean
type:
description: |
Type of the payment method. The following types of the payment methods are supported:
* `CreditCard`
* `CreditCardReferenceTransaction`
* `ACH`
* `SEPA`
* `Betalingsservice`
* `Autogiro`
* `Bacs`
* `Becs`
* `Becsnz`
* `PAD`
* `PayPalCP`
* `PayPalEC`
* `PayPalNativeEC`
* `PayPalAdaptive`
* `AdyenApplePay`
* `AdyenGooglePay`
* `GooglePay`
* `AmazonPay`
To view the schema and example applicable to a specific payment method type, select the corresponding option from the following list.
type: string
enum:
- CreditCard
- CreditCardReferenceTransaction
- ACH
- SEPA
- Betalingsservice
- Autogiro
- Bacs
- Becs
- Becsnz
- PAD
- PayPalCP
- PayPalEC
- PayPalNativeEC
- PayPalAdaptive
- AdyenApplePay
- AdyenGooglePay
- GooglePay
- AmazonPay
type: object
PaymentMethodObjectCustomFields:
additionalProperties:
description: |
Custom fields of the payment method. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
description: |
Container for custom fields of a payment method object.
title: paymentMethodFieldsCustom
type: object
CreatePaymentMethodCardholderInfo:
description: "Container for cardholder information. The nested\_`cardHolderName`\_field is required.\n"
properties:
addressLine1:
description: |
First address line, 255 characters or less.
type: string
addressLine2:
description: |
Second address line, 255 characters or less.
type: string
cardHolderName:
description: The card holder's full name as it appears on the card, e.g., "John J Smith", 50 characters or less. The value must consist only of US-ASCII characters and must not include special characters.
type: string
city:
description: |
City, 40 characters or less.
It is recommended to provide the city and country information when creating a payment method. The information will be used to process payments. If the information is not provided during payment method creation, the city and country data will be missing during payment processing.
type: string
country:
description: |
Country, must be a valid country name or abbreviation.
It is recommended to provide the city and country information when creating a payment method. The information will be used to process payments. If the information is not provided during payment method creation, the city and country data will be missing during payment processing.
type: string
email:
description: |
Card holder's email address, 80 characters or less.
type: string
phone:
description: |
Phone number, 40 characters or less.
type: string
state:
description: |
State; must be a valid subregion (state or province) name or code. For more information, see View subregions of a specific country or region.
type: string
zipCode:
description: |
Zip code, 20 characters or less.
type: string
required:
- cardHolderName
title: cardHolderInfo
type: object
example:
cardHolderName: Amy Lawrence
addressLine1: 101 Redwood Shores Parkway
city: Redwood City
state: CA
zipCode: 94065
country: USA
phone: (888) 976-9056
EinvoiceObjectCustomFields:
additionalProperties:
description: |
Custom fields of the eInvoiceProfile object. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Manage custom fields for more information.
description: |
Container for custom fields of an EinvoiceProfile object.
title: eInvoiceProfileCustomFields
type: object
DeleteAccountResponseType:
properties:
id:
description: |
The ID of the deleted account.
type: string
jobId:
description: |
The ID of the job that handles the account deletion operation.
You can specify the value of this field as the value of the `jobId` path parameter in the [Retrieve an operation job](https://developer.zuora.com/api-references/api/operation/GET_OperationJob/) API operation to query job information.
type: string
jobStatus:
description: |
The status of the account deletion operation.
enum:
- Pending
type: string
reasons:
items:
properties:
code:
description: |
The error code of the response.
type: string
message:
description: |
The detail information of the error response.
type: string
type: object
type: array
success:
description: |
Whether the call succeeded.
type: boolean
type: object
GETAccountType:
properties:
basicInfo:
$ref: '#/components/schemas/GETAccountTypeBasicInfo'
billToContact:
$ref: '#/components/schemas/GETAccountTypeBillToContact'
billingAndPayment:
description: Container for billing and payment information for the account.
properties:
additionalEmailAddresses:
description: |
A list of additional email addresses to receive email notifications.
items:
type: string
type: array
autoPay:
description: |+
Whether future payments are automatically collected when they are due during a payment run.
type: boolean
billCycleDay:
description: |
Billing cycle day (BCD), the day of the month when a bill run generates invoices for the account.
format: int64
type: integer
bcdSettingOption:
description: |
Bill cycle day setting option. Indicates whether the account’s bill cycle day is managed manually or automatically.
- `ManualSet`: The bill cycle day is explicitly set to a specific day of the month (1–31).
- `AutoSet`: The bill cycle day is automatically determined by Zuora. The bill cycle day is assigned when the first subscription is created for the account.
This field is system-derived and read-only. Its value is automatically determined based on the `billCycleDay` field.
type: string
enum:
- ManualSet
- AutoSet
currency:
description: |
A currency defined in the web-based UI administrative settings.
type: string
defaultPaymentMethodId:
description: |
ID of the default payment method for the account.
type: string
invoiceDeliveryPrefsEmail:
description: |
Whether the customer wants to receive invoices through email.
type: boolean
invoiceDeliveryPrefsPrint:
description: |
Whether the customer wants to receive printed invoices, such as through postal mail.
type: boolean
paymentMethodCascadingConsent:
description: |
`true` indicates the consent from your customer to use the Cascading Payment Method feature was collected.
`false` indicates the consent was not collected and the Cascading Payment Method feature is not enabled.
type: boolean
paymentGateway:
description: |
The name of the payment gateway instance. If null or left unassigned, the Account will use the Default Gateway.
type: string
paymentTerm:
description: |
A payment-terms indicator defined in the web-based UI administrative settings, e.g., "Net 30".
type: string
type: object
einvoiceProfile:
$ref: '#/components/schemas/GetAccountEInvoiceProfile'
gatewayRoutingEligible:
description: |
Returns `true` if the applicable billing accounts were was processed successfully for gateway routing .
type: boolean
metrics:
description: |
Container for account metrics of the account's default currency.
If you have the Multiple Currencies feature enabled, the `metricsData` field provides account metrics of different currencies.
properties:
balance:
description: |
The customer's total invoice balance minus credit balance.
format: decimal
type: string
contractedMrr:
description: |
Future expected MRR that accounts for future upgrades, downgrades, upsells and cancellations.
format: decimal
type: string
creditBalance:
description: |
Current credit balance.
format: decimal
type: string
reservedPaymentAmount:
description: |
The Reserved Payment Amount of the customer account. See [Prepaid Cash with Drawdown](https://knowledgecenter.zuora.com/Zuora_Billing/Billing_and_Invoicing/JA_Advanced_Consumption_Billing/Prepaid_Cash_with_Drawdown) for more information.
format: float
type: number
totalDebitMemoBalance:
description: |
**Note:** This field is only available if you have [Invoice Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement) 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.
Total balance of all posted debit memos.
format: decimal
type: string
totalInvoiceBalance:
description: |
Total balance of all posted invoices.
format: decimal
type: string
unappliedCreditMemoAmount:
description: |
**Note:** This field is only available if you have [Invoice Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement) 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.
Total unapplied amount of all posted credit memos.
format: decimal
type: string
unappliedPaymentAmount:
description: |
**Note:** This field is only available if you have [Invoice Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement) 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.
Total unapplied amount of all posted payments.
format: decimal
type: string
type: object
metricsData:
description: |
Container for account metrics of different currencies.
**Note**: This field is available only if you have the Multiple Currencies feature enabled.
items:
$ref: '#/components/schemas/GETAccountCurrencyMetricsType'
type: array
shipToContact:
$ref: '#/components/schemas/GetAccountTypeShipToContact'
soldToContact:
$ref: '#/components/schemas/GETAccountTypeSoldToContact'
success:
description: |
Returns `true` if the request was processed successfully.
type: boolean
taxInfo:
description: |
Container for tax exempt information, used to establish the tax exempt status of a customer account.
properties:
VATId:
description: |
EU Value Added Tax ID.
type: string
companyCode:
description: |
Unique code that identifies a company account in Avalara.
type: string
exemptCertificateId:
description: |
ID of the customer tax exemption certificate.
type: string
exemptCertificateType:
description: |
Type of tax exemption certificate that the customer holds.
type: string
exemptDescription:
description: |
Description of the tax exemption certificate that the customer holds.
type: string
exemptEffectiveDate:
description: |
Date when the customer tax exemption starts.
format: date
type: string
exemptEntityUseCode:
description: |
A unique entity use code to apply exemptions in Avalara AvaTax.
This account-level field is required only when you choose Avalara as your tax engine. See [Exempt Transactions](https://developer.avalara.com/avatax/handling-tax-exempt-customers/)for more details.
maxLength: 64
type: string
exemptExpirationDate:
description: |
Date when the customer tax exemption expires.
format: date
type: string
exemptIssuingJurisdiction:
description: |
Jurisdiction in which the customer tax exemption certificate was issued.
type: string
exemptStatus:
description: |
Status of the account tax exemption.
type: string
type: object
type: object
GETAccountTypeBasicInfo:
allOf:
- properties:
accountNumber:
description: |
Account number.
type: string
batch:
description: |
The alias name given to a batch. A string of 50 characters or less.
type: string
communicationProfileId:
description: The ID of the communication profile that this account is linked to.
type: string
creditMemoTemplateId:
description: |
**Note:** This field is only available if you have [Invoice Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement) 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.
The unique ID of the credit memo template, configured in **Billing Settings** > **Manage Billing Document Configuration** through the Zuora UI. For example, 2c92c08a6246fdf101626b1b3fe0144b.
type: string
crmId:
description: |
CRM account ID for the account, up to 100 characters.
type: string
customerServiceRepName:
description: |
Name of the account's customer service representative, if applicable.
maxLength: 50
type: string
debitMemoTemplateId:
description: |
**Note:** This field is only available if you have [Invoice Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement) 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.
The unique ID of the debit memo template, configured in **Billing Settings** > **Manage Billing Document Configuration** through the Zuora UI. For example, 2c92c08d62470a8501626b19d24f19e2.
type: string
id:
description: |
Account ID.
type: string
invoiceTemplateId:
description: |
Invoice template ID, configured in Billing Settings in the Zuora UI.
type: string
nullable: true
lastMetricsUpdate:
description: |
The date and time when account metrics are last updated, if the account is a partner account.
**Note**:
- This field is available only if you have the Reseller Account feature enabled.
- If you have the Reseller Account feature enabled, and set the `partnerAccount` field to `false` for an account, the value of the `lastMetricsUpdate` field is automatically set to `null` in the response.
- If you ever set the `partnerAccount` field to `true` for an account, the value of `lastMetricsUpdate` field is the time when the account metrics are last updated.
format: date-time
type: string
name:
description: |
Account name.
type: string
notes:
description: |
Notes associated with the account, up to 65,535 characters.
type: string
organizationLabel:
description: |
The organization that this object belongs to.
Note: This field is available only when the Multi-Org feature is enabled.
type: string
parentId:
description: Identifier of the parent customer account for this Account object. The length is 32 characters. Use this field if you have Customer Hierarchy enabled.
type: string
partnerAccount:
description: |
Whether the customer account is a partner, distributor, or reseller.
**Note**: This field is available only if you have the Reseller Account feature enabled.
type: boolean
profileNumber:
description: The number of the communication profile that this account is linked to.
type: string
purchaseOrderNumber:
description: The purchase order number provided by your customer for services, products, or both purchased.
type: string
salesRep:
description: The name of the sales representative associated with this account, if applicable. Maximum of 50 characters.
type: string
sequenceSetId:
description: |
The ID of the billing document sequence set that is assigned to the customer account.
type: string
nullable: true
summaryStatementTemplateId:
description: The summary statement template ID. When a user attempts to generate a summary statement from the "Account Summary Statement" screen, the system utilizes this template to produce the PDF.
type: string
nullable: true
status:
description: |
Account status; possible values are: `Active`, `Draft`, `Canceled`.
type: string
tags:
description: ''
type: string
type: object
- $ref: '#/components/schemas/AccountObjectNSFields'
- $ref: '#/components/schemas/AccountObjectCustomFields'
description: |
Container for basic information about the account.
**Notes**:
- In the "Retrieve an order" operation, if the `getAccountDetails` query parameter is set to `true`, the subscription owner account details `subscriptionOwnerAccountDetails` and invoice owner account details `existingAccountDetails` will be in the response.
- In the "Retrieve a subscription by key" operation, the returned result differs based on the following query parameters:
- If the `getSubscriptionOwnerDetails` query parameter is set to `true`, the subscription owner account details `accountOwnerDetails` will be in the response.
- If the `getInvoiceOwnerDetails` query parameter is set to `true`, the invoice owner account details `invoiceOwnerAccountDetails` will be in the response.
- If both query parameters are set to `true`, the subscription owner account details `accountOwnerDetails` and invoice owner account details `invoiceOwnerAccountDetails` will be in the response.
title: basicInfo
GETAccountTypeBillToContact:
allOf:
- properties:
address1:
description: |
First address line, 255 characters or less.
type: string
address2:
description: |
Second address line, 255 characters or less.
type: string
asBillTo:
description: |
Indicates whether the contact can be specified as a bill-to contact.
This field is available only if you have turned on the Ship To Contact feature. You can turn on the feature through the self-service interface for Feature Management.
type: boolean
asShipTo:
description: |
Indicates whether the contact can be specified as a ship-to contact.
This field is available only if you have turned on the Ship To Contact feature. You can turn on the feature through the self-service interface for Feature Management.
type: boolean
asSoldTo:
description: |
Indicates whether the contact can be specified as a sold-to contact.
This field is available only if you have turned on the Ship To Contact feature. You can turn on the feature through the self-service interface for Feature Management.
type: boolean
city:
description: |
City
type: string
maxLength: 100
country:
description: |
Full country name. This field does not contain the ISO-standard abbreviation of the country name.
type: string
nullable: true
county:
description: 'Zuora Tax uses this information to calculate county taxation. '
type: string
maxLength: 100
nullable: true
fax:
description: |
Fax phone number, 40 characters or less.
type: string
firstName:
description: |
First name, 100 characters or less.
type: string
homePhone:
description: |
Home phone number, 40 characters or less.
type: string
id:
description: ID of the person to bill for the account, 32 characters or less.
type: string
lastName:
description: |
Last name, 100 characters or less.
type: string
mobilePhone:
description: |
Mobile phone number, 40 characters or less.
type: string
nickname:
description: |
Nickname for this contact.
type: string
otherPhone:
description: |
Other phone number, 40 characters or less.
type: string
nullable: true
otherPhoneType:
description: |
Possible values are: `Work`, `Mobile`, `Home`, `Other`.
type: string
nullable: true
personalEmail:
description: |
Personal email address.
type: string
maxLength: 80
state:
description: |
Full state name. This field does not contain the ISO-standard abbreviation of the state name.
type: string
maxLength: 100
taxRegion:
description: |
A region string, defined in your Zuora tax rules.
type: string
maxLength: 100
nullable: true
workEmail:
description: |
Work email address, 80 characters or less.
type: string
workPhone:
description: |
Work phone number, 40 characters or less.
type: string
zipCode:
description: |
Zip code, 20 characters or less.
type: string
type: object
- $ref: '#/components/schemas/ContactObjectCustomFields'
description: |
Container for bill-to contact information.
title: Contact
GetAccountEInvoiceProfile:
description: |
Container for e-invoicing profile information for this account.
**Note**: This field is available only if you have the E-Invoicing feature in **Early Adopter** phase enabled.
allOf:
- properties:
businessCategory:
description: |
The high-level category of the business.
type: string
enum:
- B2B
- B2C
- B2G
businessName:
description: |
The full official name that the Buyer is registered with the relevant legal authority.
maxLength: 255
type: string
businessNumber:
description: |
The unique identifier number of the legal entity or person that you do business with.
For example, you must use a GSTIN for India.
type: string
businessNumberSchemeId:
description: |
The identification scheme identifier that an official registrar issues to identify the Buyer as a legal entity or person.
type: string
enabled:
description: |
Whether the e-invoicing profile for the customer account is enabled.
If the following conditions are met, all billing documents for one account can be submitted to an e-invoicing service provider to be generated in electronic format:
- The account must be configured to generate e-invoice files for billing documents.
- The billing document must be in Posted status.
- A business region must be created for the billing country contact, and be linked to an e-invoicing service provider.
type: boolean
endpointId:
description: |
The Buyer's electronic address, to which the application-level response to the billing document might be delivered.
type: string
endpointSchemeId:
description: |
The identification scheme identifier of the Buyer’s electronic address.
type: string
taxRegisterNumber:
description: |
The Buyer's VAT identifier (also known as the Buyer's VAT identification number) or the local identification (defined by the Buyer’s address) of the Buyer for tax purposes, or a reference that enables the Buyer to state the registered tax status.
type: string
title: einvoiceProfile
type: object
- $ref: '#/components/schemas/EinvoiceObjectCustomFields'
GETAccountCurrencyMetricsType:
allOf:
- properties:
balance:
description: |
The total balance in this currency.
type: string
contractedMrr:
description: |
The future expected Monthly Recurring Revenue (MRR) in this currency, accounting for future upgrades, downgrades, upsells, and cancellations.
format: decimal
type: string
currency:
description: |
The currency that metrics are aggregated based on.
type: string
reservedPaymentAmount:
description: |
The reserved payment amount of the customer account in this currency. For more information, see Prepaid Cash with Drawdown.
format: decimal
type: string
totalDebitMemoBalance:
description: |
The total balance of all posted debit memos in this currency.
**Note:** This field is only available if you have Invoice Settlement 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 for more information.
format: decimal
type: string
totalInvoiceBalance:
description: |
The total balance of all posted invoices in this currency.
format: decimal
type: string
unappliedCreditMemoAmount:
description: |
The total unapplied amount of all posted credit memos in this currency.
format: decimal
type: string
unappliedPaymentAmount:
description: |
The total unapplied amount of all posted payments in this currency.
**Note:** This field is only available if you have [Invoice Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement) 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.
format: decimal
type: string
type: object
title: metricsData
GetAccountTypeShipToContact:
allOf:
- properties:
address1:
description: |
First address line, 255 characters or less.
type: string
address2:
description: |
Second address line, 255 characters or less.
type: string
asBillTo:
description: |
Indicates whether the contact can be specified as a bill-to contact.
This field is available only if you have turned on the Ship To Contact feature. You can turn on the feature through the self-service interface for Feature Management.
type: boolean
asShipTo:
description: |
Indicates whether the contact can be specified as a ship-to contact.
This field is available only if you have turned on the Ship To Contact feature. You can turn on the feature through the self-service interface for Feature Management.
type: boolean
asSoldTo:
description: |
Indicates whether the contact can be specified as a sold-to contact.
This field is available only if you have turned on the Ship To Contact feature. You can turn on the feature through the self-service interface for Feature Management.
type: boolean
city:
description: |
City, 40 characters or less.
type: string
country:
description: |
Full country name. This field does not contain the ISO-standard abbreviation of the country name.
type: string
nullable: true
county:
description: 'County; 32 characters or less. Zuora tax uses this information to calculate county taxation. '
type: string
fax:
description: |
Fax phone number, 40 characters or less.
type: string
firstName:
description: |
First name, 100 characters or less.
type: string
homePhone:
description: |
Home phone number, 40 characters or less.
type: string
id:
description: ID of the person who bought the subscription associated with the account, 32 characters or less.
type: string
lastName:
description: |
Last name, 100 characters or less.
type: string
mobilePhone:
description: |
Mobile phone number, 40 characters or less.
type: string
nickname:
description: |
Nickname for this contact.
type: string
otherPhone:
description: |
Other phone number, 40 characters or less.
type: string
otherPhoneType:
description: |
Possible values are: `Work`, `Mobile`, `Home`, `Other`.
type: string
personalEmail:
description: |
Personal email address.
type: string
maxLength: 80
state:
description: |
Full state name. This field does not contain the ISO-standard abbreviation of the state name.
type: string
taxRegion:
description: |
A region string, defined in your Zuora tax rules.
type: string
workEmail:
description: |
Work email address, 80 characters or less.
type: string
workPhone:
description: |
Work phone number, 40 characters or less.
type: string
zipCode:
description: |
Zip code, 20 characters or less.
type: string
type: object
- $ref: '#/components/schemas/ContactObjectCustomFields'
description: |
Container for ship-to contact information. Uses the same field structure as billToContact.
title: Contact
GETAccountTypeSoldToContact:
allOf:
- properties:
address1:
description: |
First address line, 255 characters or less.
type: string
address2:
description: |
Second address line, 255 characters or less.
type: string
asBillTo:
description: |
Indicates whether the contact can be specified as a bill-to contact.
This field is available only if you have turned on the Ship To Contact feature. You can turn on the feature through the self-service interface for Feature Management.
type: boolean
asShipTo:
description: |
Indicates whether the contact can be specified as a ship-to contact.
This field is available only if you have turned on the Ship To Contact feature. You can turn on the feature through the self-service interface for Feature Management.
type: boolean
asSoldTo:
description: |
Indicates whether the contact can be specified as a sold-to contact.
This field is available only if you have turned on the Ship To Contact feature. You can turn on the feature through the self-service interface for Feature Management.
type: boolean
city:
description: |
City, 40 characters or less.
type: string
country:
description: |
Full country name. This field does not contain the ISO-standard abbreviation of the country name.
type: string
nullable: true
county:
description: 'County; 32 characters or less. Zuora tax uses this information to calculate county taxation. '
type: string
fax:
description: |
Fax phone number, 40 characters or less.
type: string
firstName:
description: |
First name, 100 characters or less.
type: string
homePhone:
description: |
Home phone number, 40 characters or less.
type: string
id:
description: ID of the person who bought the subscription associated with the account, 32 characters or less.
type: string
lastName:
description: |
Last name, 100 characters or less.
type: string
mobilePhone:
description: |
Mobile phone number, 40 characters or less.
type: string
nickname:
description: |
Nickname for this contact.
type: string
otherPhone:
description: |
Other phone number, 40 characters or less.
type: string
otherPhoneType:
description: |
Possible values are: `Work`, `Mobile`, `Home`, `Other`.
type: string
personalEmail:
description: |
Personal email address.
type: string
maxLength: 80
state:
description: |
Full state name. This field does not contain the ISO-standard abbreviation of the state name.
type: string
taxRegion:
description: |
A region string, defined in your Zuora tax rules.
type: string
workEmail:
description: |
Work email address, 80 characters or less.
type: string
workPhone:
description: |
Work phone number, 40 characters or less.
type: string
zipCode:
description: |
Zip code, 20 characters or less.
type: string
type: object
- $ref: '#/components/schemas/ContactObjectCustomFields'
description: |
Container for sold-to contact information. Uses the same field structure as billToContact.
title: Contact
PUTAccountType:
allOf:
- properties:
additionalEmailAddresses:
description: |
A list of additional email addresses to receive email notifications. Use commas to separate email addresses.
items:
type: string
type: array
autoPay:
description: |
Whether future payments are to be automatically billed when they are due.
type: boolean
batch:
description: |
The alias name given to a batch. A string of 50 characters or
less.
**Note**: By default, you have 50 configurable account batches. To increase the limit to 200 batches, you must have the Performance Booster Elite package.
type: string
billCycleDay:
description: |
Sets the bill cycle day (BCD) for the charge. The BCD determines
which day of the month the customer is billed. Values: Any activated system-defined bill cycle day （`1`-`31`）
maxLength: 2
type: integer
billToContact:
$ref: '#/components/schemas/PUTAccountTypeBillToContact'
billToContactId:
description: |
The ID of a contact that will be the bill-to contact of the current account.
type: string
communicationProfileId:
description: |
The ID of the communication profile that this account is linked to.
You can provide either or both of the `communicationProfileId` and `profileNumber` fields.
If both are provided, the request will fail if they do not refer to the same communication profile.
type: string
creditMemoTemplateId:
description: |
**Note:** This field is only available if you have [Invoice Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement) 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.
The unique ID of the credit memo template, configured in **Billing Settings** > **Manage Billing Document Configuration** through the Zuora UI. For example, 2c92c08a6246fdf101626b1b3fe0144b.
type: string
crmId:
description: |
CRM account ID for the account, up to 100 characters.
type: string
customerServiceRepName:
description: |
Name of the account’s customer service representative, if applicable.
maxLength: 50
type: string
debitMemoTemplateId:
description: |
**Note:** This field is only available if you have [Invoice Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement) 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.
The unique ID of the debit memo template, configured in **Billing Settings** > **Manage Billing Document Configuration** through the Zuora UI. For example, 2c92c08d62470a8501626b19d24f19e2.
type: string
defaultPaymentMethodId:
description: |
ID of the default payment method for the account.
Values: a valid ID for an existing payment method.
maxLength: 64
type: string
einvoiceProfile:
$ref: '#/components/schemas/PUTAccountEinvoiceProfile'
gatewayRoutingEligible:
default: false
description: |
Indicates whether to include the applicable billing accounts to gateway routing for controlled adoption.
type: boolean
invoiceDeliveryPrefsEmail:
description: |
Whether the customer wants to receive invoices through email.
The default value is `false`.
type: boolean
invoiceDeliveryPrefsPrint:
description: |
Whether the customer wants to receive printed invoices, such as through postal mail.
The default value is `false`.
type: boolean
invoiceTemplateId:
description: |
Invoice template ID, configured in Billing Settings in the Zuora UI.
type: string
name:
description: |
Account name, up to 255 characters.
type: string
notes:
description: |
A string of up to 65,535 characters.
type: string
parentId:
description: Identifier of the parent customer account for this Account object. The length is 32 characters. Use this field if you have Customer Hierarchy enabled.
type: string
partnerAccount:
default: false
description: |
Whether the customer account is a partner, distributor, or reseller.
You can set this field to `true` if you have business with distributors or resellers, or operating in B2B model to manage numerous subscriptions through concurrent API requests. After this field is set to `true`, the calculation of account metrics is performed asynchronously during operations such as subscription creation, order changes, invoice generation, and payments.
**Note**: This field is available only if you have the Reseller Account feature enabled.
type: boolean
paymentGateway:
description: |
The name of the payment gateway instance. If null or left unassigned, the Account will use the Default Gateway.
type: string
paymentTerm:
description: Payment terms for this account. Possible values are `Due Upon Receipt`, `Net 30`, `Net 60`, `Net 90`.
type: string
profileNumber:
description: |
The number of the communication profile that this account is linked to.
You can provide either or both of the `communicationProfileId` and `profileNumber` fields.
If both are provided, the request will fail if they do not refer to the same communication profile.
type: string
purchaseOrderNumber:
description: The purchase order number provided by your customer for services, products, or both purchased.
type: string
salesRep:
description: The name of the sales representative associated with this account, if applicable. Maximum of 50 characters.
type: string
sequenceSetId:
description: |
The ID of the billing document sequence set to assign to the customer account.
The billing documents to generate for this account will adopt the prefix and starting document number configured in the sequence set.
If a customer account has no assigned billing document sequence set, billing documents generated for this account adopt the prefix and starting document number from the default sequence set.
type: string
nullable: true
shipToContact:
$ref: '#/components/schemas/UpdateAccountShipToContact'
shipToContactId:
description: |
The ID of a contact that will be the ship-to contact of the current account.
type: string
soldToContact:
$ref: '#/components/schemas/PUTAccountTypeSoldToContact'
soldToContactId:
description: |
The ID of a contact that will be the sold-to contact of the current account.
type: string
tagging:
description: ''
type: string
summaryStatementTemplateId:
description: |
The summary statement template ID or number. When a user attempts to generate a summary statement from the "Account Summary Statement" screen, the system utilizes this template to produce the PDF.
type: string
nullable: true
taxInfo:
description: |
Container for tax exempt information, used to establish the tax exempt status of a customer account.
properties:
VATId:
description: |
EU Value Added Tax ID.
**Note:** This feature is in Limited Availability. If you wish to have access to the feature, submit a request at [Zuora Global Support](https://support.zuora.com).
type: string
companyCode:
description: |
Unique code that identifies a company account in Avalara. Use this field to calculate taxes based on origin and sold-to addresses in Avalara.
**Note:** This feature is in Limited Availability. If you wish to have access to the feature, submit a request at [Zuora Global Support](https://support.zuora.com).
type: string
exemptCertificateId:
description: |
ID of the customer tax exemption certificate. Requires Zuora Tax.
type: string
exemptCertificateType:
description: |
Type of tax exemption certificate that the customer holds. Requires Zuora Tax.
type: string
exemptDescription:
description: |
Description of the tax exemption certificate that the customer holds. Requires Zuora Tax.
type: string
exemptEffectiveDate:
description: |
Date when the customer tax exemption starts. Requires Zuora Tax.
Format: `yyyy-mm-dd`. Defaults to the current date.
format: date
type: string
exemptEntityUseCode:
description: |
A unique entity use code to apply exemptions in Avalara AvaTax.
This account-level field is required only when you choose Avalara as your tax engine. See [Exempt Transactions](https://developer.avalara.com/avatax/handling-tax-exempt-customers/)for more details.
maxLength: 64
type: string
exemptExpirationDate:
description: |
Date when the customer tax exemption expires. Requires Zuora Tax.
Format: `yyyy-mm-dd`. Defaults to the current date.
format: date
type: string
exemptIssuingJurisdiction:
description: |
Jurisdiction in which the customer tax exemption certificate was issued.
type: string
exemptStatus:
description: |
Status of the account tax exemption. Requires Zuora Tax.
Required if you use Zuora Tax. This field is unavailable if Zuora Tax is not used.
Values: `Yes`, `No`(default), `pendingVerification`. Note that the value will be set to `No` if no input.
type: string
type: object
type: object
- $ref: '#/components/schemas/AccountObjectNSFields'
- $ref: '#/components/schemas/AccountObjectCustomFields'
example:
billCycleDay: 1
PUTAccountTypeBillToContact:
allOf:
- properties:
address1:
description: |
First address line, 255 characters or less.
type: string
address2:
description: |
Second address line, 255 characters or less.
type: string
city:
description: |
City
type: string
maxLength: 100
country:
description: |
Country; must be a valid country name or abbreviation. If using Zuora Tax, you must specify a country in the sold-to contact to calculate tax. A bill-to contact may be used if no sold-to contact is provided.
type: string
county:
description: |
May optionally be used by Zuora Tax to calculate county tax.
type: string
maxLength: 100
fax:
description: |
Fax phone number, 40 characters or less.
type: string
firstName:
description: |
First name, 100 characters or less.
type: string
homePhone:
description: |
Home phone number, 40 characters or less.
type: string
lastName:
description: |
Last name, 100 characters or less.
type: string
mobilePhone:
description: |
Mobile phone number, 40 characters or less.
type: string
nickname:
description: |
Nickname for this contact
type: string
otherPhone:
description: |
Other phone number, 40 characters or less.
type: string
otherPhoneType:
description: |
Possible values are: `Work`, `Mobile`, `Home`, `Other`.
type: string
personalEmail:
description: |
Personal email address.
type: string
format: email
maxLength: 80
state:
description: |
State; must be a valid subregion (state or province) name or code. For more information, see View subregions of a specific country or region. If using Zuora Tax, be aware that Zuora Tax requires a state (in the US) or province (in Canada) in this field for the sold-to contact to calculate tax, and that a bill-to contact may be used if no sold-to contact is provided.
type: string
maxLength: 100
taxRegion:
description: |
If using Zuora Tax, a region string as optionally defined in your tax rules. Not required.
type: string
maxLength: 100
workEmail:
description: |
Work email address, 80 characters or less.
type: string
workPhone:
description: |
Work phone number, 40 characters or less.
type: string
zipCode:
description: |
Zip code, 20 characters or less.
type: string
type: object
- $ref: '#/components/schemas/ContactObjectCustomFields'
description: |
Container for bill-to contact information for this account.
title: Contact
PUTAccountEinvoiceProfile:
allOf:
- properties:
businessCategory:
description: |
The high-level category of the business.
type: string
enum:
- B2B
- B2C
- B2G
businessName:
description: 'Legal Business Name. The full formal name by which the Buyer is registered with the relevant legal authority. '
maxLength: 255
type: string
businessNumber:
description: 'Buyer legal registration identifier. An identifier issued by an official registrar that identifies the Buyer as a legal entity or person. GSTIN of buyer for India. '
type: string
businessNumberSchemeId:
description: 'Business Number Schema Id. The identification scheme identifier of the Buyer legal registration identifier. '
type: string
enabled:
description: 'Enable e-invoice for the account. All invoices generated from this account can be submitted to generate e-invoices when invoices meet the conditions: A business region must be created for the billing country contact, and it must be linked to a service provider. The account must be enabled to generate e-invoices. The invoice must be in the "Posted" status. '
type: boolean
endpointId:
description: |
Buyer electronic address.Identifies the Buyer's electronic address to which the invoice is delivered.
type: string
endpointSchemeId:
description: 'Buyer electronic address identification scheme identifier. '
type: string
taxRegisterNumber:
description: |
Buyer VAT identifier. The Buyer's VAT identifier (also known as Buyer VAT identification number).
type: string
type: object
- $ref: '#/components/schemas/EinvoiceObjectCustomFields'
description: |
Container for profile information for this account.
**Note**: This field is available only if you have the E-Invoicing feature in **Early Adopter** phase enabled.
title: einvoiceProfile
UpdateAccountShipToContact:
allOf:
- properties:
address1:
description: |
First address line, 255 characters or less.
type: string
address2:
description: |
Second address line, 255 characters or less.
type: string
city:
description: |
City
type: string
maxLength: 100
country:
description: |
Country; must be a valid country name or abbreviation.
type: string
county:
description: |
May optionally be used by Zuora Tax to calculate county tax.
type: string
maxLength: 100
fax:
description: |
Fax phone number, 40 characters or less.
type: string
firstName:
description: |
First name, 100 characters or less.
type: string
homePhone:
description: |
Home phone number, 40 characters or less.
type: string
lastName:
description: |
Last name, 100 characters or less.
type: string
mobilePhone:
description: |
Mobile phone number, 40 characters or less.
type: string
nickname:
description: |
Nickname for this contact
type: string
otherPhone:
description: |
Other phone number, 40 characters or less.
type: string
otherPhoneType:
description: |
Possible values are: `Work`, `Mobile`, `Home`, `Other`.
type: string
personalEmail:
description: |
Personal email address.
type: string
format: email
maxLength: 80
state:
description: |
State; must be a valid subregion (state or province) name or code. For more information, see View subregions of a specific country or region.
type: string
maxLength: 100
taxRegion:
description: |
If using Zuora Tax, a region string as optionally defined in your tax rules. Not required.
type: string
maxLength: 100
workEmail:
description: |
Work email address, 80 characters or less.
type: string
workPhone:
description: |
Work phone number, 40 characters or less.
type: string
zipCode:
description: |
Zip code, 20 characters or less.
type: string
type: object
- $ref: '#/components/schemas/ContactObjectCustomFields'
description: |
Container for optional ship-to contact.
title: Contact
PUTAccountTypeSoldToContact:
allOf:
- properties:
address1:
description: |
First address line, 255 characters or less.
type: string
address2:
description: |
Second address line, 255 characters or less.
type: string
city:
description: |
City, 100 characters or less.
type: string
country:
description: |
Country; must be a valid country name or abbreviation. If using Zuora Tax, you must specify a country in the sold-to contact to calculate tax. A bill-to contact may be used if no sold-to contact is provided.
type: string
county:
description: |
County; 100 characters or less. May optionally be used by Zuora Tax to calculate county tax.
type: string
fax:
description: |
Fax phone number, 40 characters or less.
type: string
firstName:
description: |
First name, 100 characters or less.
type: string
homePhone:
description: |
Home phone number, 40 characters or less.
type: string
lastName:
description: |
Last name, 100 characters or less.
type: string
mobilePhone:
description: |
Mobile phone number, 40 characters or less.
type: string
nickname:
description: |
Nickname for this contact
type: string
otherPhone:
description: |
Other phone number, 40 characters or less.
type: string
otherPhoneType:
description: |
Possible values are: `Work`, `Mobile`, `Home`, `Other`.
type: string
personalEmail:
description: |
Personal email address.
type: string
format: email
maxLength: 80
state:
description: |
100 characters or less.
State; must be a valid subregion (state or province) name or code. For more information, see View subregions of a specific country or region. If using Zuora Tax, be aware that Zuora Tax requires a state (in the US) or province (in Canada) in this field for the sold-to contact to calculate tax, and that a bill-to contact may be used if no sold-to contact is provided.
type: string
taxRegion:
description: |
100 characters or less.
If using Zuora Tax, a region string as optionally defined in your tax rules. Not required.
type: string
workEmail:
description: |
Work email address, 80 characters or less.
type: string
workPhone:
description: |
Work phone number, 40 characters or less.
type: string
zipCode:
description: |
Zip code, 20 characters or less.
type: string
type: object
- $ref: '#/components/schemas/ContactObjectCustomFields'
description: |
Container for optional sold-to contact.
title: Contact
GETAccountPaymentMethodType:
allOf:
- properties:
defaultPaymentMethodId:
description: |
ID of the default payment method for the account.
type: string
paymentGateway:
description: |
The name of the payment gateway instance. If null or left unassigned, the Account will use the Default Gateway.
type: string
returnedPaymentMethodType:
description: |
Container for a specific type of payment method on the customer account. For example, `creditcard`, `debitcard`, `creditcardreferencetransaction`, `ach`, etc. Each `returnedPaymentMethodType` array contains one or more payment methods of that payment method type.
**Note:** The response could return more than one payment method type arrays. See **Response samples** as an example.
items:
$ref: '#/components/schemas/GETPaymentMethodResponseForAccount'
title: Payment Method Type
type: array
success:
description: |
Returns `true` if the request was processed successfully.
type: boolean
type: object
- $ref: '#/components/schemas/CustomAccountPaymentMethod'
GETPaymentMethodResponseForAccount:
allOf:
- properties:
accountHolderInfo:
$ref: '#/components/schemas/GETAccountPMAccountHolderInfo'
accountVerificationService:
description: |
Displays the name of the service provider. For example, Plaid.
type: string
accountVerificationStatus:
description: |
Displays the status of the account.
**Note:**
- `Active` - Access token is active.
- `Expired` - Access token has expired and must be linked again.
- `Expiring` - Access token will expire in few days(7 days for Plaid) and must be linked again
- `Inactive` - The end customer has revoked the account pemission. The end customer can login again and select the same method for the access token to be linked again.
enum:
- Active
- Expired
- Expiring
- Inactive
type: string
bankIdentificationNumber:
description: |
The first six or eight digits of the payment method's number, such as the credit card number or account number. Banks use this number to identify a payment method.
type: string
createdBy:
description: ID of the user who created this payment method.
type: string
createdOn:
description: |
The date and time when the payment method was created, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
creditCardMaskNumber:
description: |
The masked credit card number, such as:
```
*********1112
```
**Note:** This field is only returned for Credit Card Reference Transaction payment type.
type: string
creditCardType:
description: |
The type of the credit card or debit card.
Possible values include `Visa`, `MasterCard`, `AmericanExpress`, `Discover`, `JCB`, and `Diners`. For more information about credit card types supported by different payment gateways, see [Supported Payment Gateways](https://knowledgecenter.zuora.com/CB_Billing/M_Payment_Gateways/Supported_Payment_Gateways).
**Note:** This field is only returned for the Credit Card and Debit Card payment types.
type: string
deviceSessionId:
description: |
The session ID of the user when the `PaymentMethod` was created or updated.
type: string
existingMandate:
description: |
Indicates whether the mandate is an existing mandate.
enum:
- 'Yes'
- 'No'
type: string
id:
description: |
The payment method ID.
type: string
ipAddress:
description: |
The IP address of the user when the payment method was created or updated.
type: string
isDefault:
description: |
Indicates whether this payment method is the default payment method for the account.
type: boolean
lastFailedSaleTransactionDate:
description: |
The date of the last failed attempt to collect payment with this payment method.
format: date-time
type: string
lastTransaction:
description: Indicates the occurrence and status of the last transaction.
type: string
lastTransactionTime:
description: The time when the last transaction of this payment method happened.
format: date-time
type: string
mandateInfo:
$ref: '#/components/schemas/POSTAccountPMMandateInfo'
maxConsecutivePaymentFailures:
description: |
The number of allowable consecutive failures Zuora attempts with the payment method before stopping.
type: integer
numConsecutiveFailures:
description: |
The number of consecutive failed payments for this payment method. It is reset to `0` upon successful payment.
format: int32
type: integer
paymentRetryWindow:
description: |
The retry interval setting, which prevents making a payment attempt if the last failed attempt was within the last specified number of hours.
type: integer
secondTokenId:
description: |
A gateway unique identifier that replaces sensitive payment method data.
**Note:** This field is only returned for the Credit Card Reference Transaction payment type.
type: string
status:
description: |
The status of the payment method.
enum:
- Active
- Closed
- Scrubbed
type: string
tokenId:
description: |
A gateway unique identifier that replaces sensitive payment method data or represents a gateway's unique customer profile.
**Note:** This field is only returned for the Credit Card Reference Transaction payment type.
type: string
totalNumberOfErrorPayments:
description: |
The number of error payments that used this payment method.
format: int32
type: integer
totalNumberOfProcessedPayments:
description: |
The number of successful payments that used this payment method.
format: int32
type: integer
type:
description: |
The type of the payment method.
type: string
enum:
- CreditCard
- CreditCardReferenceTransaction
- ACH
- SEPA
- Betalingsservice
- Autogiro
- Bacs
- Becs
- Becsnz
- PAD
- PayPalCP
- PayPalEC
- PayPalNativeEC
- PayPalAdaptive
- AdyenApplePay
- AdyenGooglePay
- GooglePay
updatedBy:
description: ID of the user who made the last update to this payment method.
type: string
updatedOn:
description: |
The last date and time when the payment method was updated, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
useDefaultRetryRule:
description: |
Indicates whether this payment method uses the default retry rules configured in the Zuora Payments settings.
type: boolean
type: object
- $ref: '#/components/schemas/PaymentMethodObjectCustomFieldsForAccount'
- $ref: '#/components/schemas/GETPaymentMethodResponseBankTransferForAccount'
- $ref: '#/components/schemas/GETPaymentMethodResponseACHForAccount'
- $ref: '#/components/schemas/GETPaymentMethodResponseCreditCardForAccount'
- $ref: '#/components/schemas/GETPaymentMethodResponsePayPalForAccount'
- $ref: '#/components/schemas/GETPaymentMethodResponseGooglePayForAccount'
- $ref: '#/components/schemas/GETPaymentMethodResponseApplePayForAccount'
CustomAccountPaymentMethod:
additionalProperties:
description: |
Container for custom payment methods created through the [Open Payment Method](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/MB_Set_up_custom_payment_gateways_and_payment_methods) service.
**Note:** The response could return more than one custom payment methods.
title: Custom Payment Method
type: object
description: |
Container for custom payment methods created through the [Open Payment Method](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/MB_Set_up_custom_payment_gateways_and_payment_methods) service.
**Note:** The response could return more than one custom payment methods.
title: CustomPaymentMethod
type: object
GETAccountPMAccountHolderInfo:
description: |
The account holder information.
properties:
accountHolderName:
description: |
The full name of the account holder.
maxLength: 60
type: string
addressLine1:
description: |
The first line of the address for the account holder.
type: string
addressLine2:
description: |
The second line of the address for the account holder.
type: string
city:
description: |
The city where the account holder stays.
type: string
country:
description: |
The country where the account holder stays.
When creating a payment method through a translated UI or Payment Page, a country name in a translated language might be selected. Regardless of the country texts selected when creating the payment method, only the supported country name returns in this field. For a complete list of supported country names, see View countries or regions. Internationalization is not supported for the API field value.
type: string
nullable: true
email:
description: |
The email address of the account holder.
type: string
phone:
description: |
The phone number of the account holder.
type: string
state:
description: |
The state where the account holder stays.
type: string
zipCode:
description: |
The zip code for the address of the account holder.
type: string
title: accountHolderInfo
type: object
POSTAccountPMMandateInfo:
description: |
The mandate information for the Credit Card, Apple Pay, Google Pay, Credit Card Reference Transaction, ACH, or Bank Transfer payment method.
The following mandate fields are common to all supported payment methods:
* `mandateId`
* `mandateReason`
* `mandateStatus`
The following mandate fields are specific to the ACH and Bank Transfer payment methods:
* `mandateReceivedStatus`
* `existingMandateStatus`
* `mandateCreationDate`
* `mandateUpdateDate`
The following mandate fields are specific to the Credit Card, Apple Pay, and Google Pay payment methods:
* `mitTransactionId`
* `mitProfileAgreedOn`
* `mitConsentAgreementRef`
* `mitConsentAgreementSrc`
* `mitProfileType`
* `mitProfileAction`
properties:
existingMandateStatus:
description: |
Indicates whether the mandate is an existing mandate.
enum:
- 'Yes'
- 'No'
type: string
mandateCreationDate:
description: |
The date on which the mandate was created.
format: date
type: string
mandateId:
description: |
The mandate ID.
type: string
mandateReason:
description: |
The reason of the mandate from the gateway side.
type: string
mandateReceivedStatus:
description: |
Indicates whether the mandate is received from the gateway
enum:
- 'Yes'
- 'No'
type: string
mandateStatus:
description: |
The status of the mandate from the gateway side.
type: string
mandateUpdateDate:
description: |
The date on which the mandate was updated.
format: date
type: string
mitConsentAgreementRef:
description: |
Reference for the consent agreement that you have established with the customer.
type: string
mitConsentAgreementSrc:
description: |
Required if you set the `mitProfileAction` field. Specify how the consent agreement has been established with the customer. The allowed value is `External`. If you do not specify the `mitProfileAction` field, Zuora will automatically create a stored credential profile for the payment method, with the default value `External` set to this field.
enum:
- External
type: string
mitProfileAction:
description: |
Specifies how Zuora creates and activates the stored credential profile. Only applicable if you set the `status` field to `Active`.
* `Activate` (default) - Use this value if you are creating the stored credential profile after receiving the customer's consent.
Zuora will create the stored credential profile then send a cardholder-initiated transaction (CIT) to the payment gateway to validate the stored credential profile. If the CIT succeeds, the status of the stored credential profile will be `Active`. If the CIT does not succeed, Zuora will not create a stored credential profile.
If the payment gateway does not support the stored credential transaction framework, the status of the stored credential profile will be `Agreed`.
* `Persist` - Use this value if the stored credential profile represents a stored credential profile in an external system. The status of the payment method's stored credential profile will be `Active`.
If you do not specify this field, Zuora will automatically create a stored credential profile for the payment method, with the default value `Activate` set to this field.
enum:
- Activate
- Persist
type: string
mitProfileAgreedOn:
description: |
The date on which the stored credential profile is agreed. The date format is `yyyy-mm-dd`.
format: date
type: string
mitProfileType:
description: |
Indicates the type of the stored credential profile. If you do not specify the `mitProfileAction` field, Zuora will automatically create a stored credential profile for the payment method, with the default value `Recurring` set to this field.
type: string
mitTransactionId:
description: |
Specifies the ID of the transaction. Only applicable if you set the `mitProfileAction` field to `Persist`.
maxLength: 128
type: string
title: mandateInfo
type: object
PaymentMethodObjectCustomFieldsForAccount:
additionalProperties:
description: |
Custom fields of the payment method. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
description: |
Container for custom fields of a payment method object.
title: paymentMethodFieldsCustom
type: object
GETPaymentMethodResponseBankTransferForAccount:
properties:
IBAN:
description: |
The International Bank Account Number used to create the SEPA payment method. The value is masked.
type: string
accountNumber:
description: |
The number of the customer's bank account and it is masked.
type: string
bankCode:
description: |
The sort code or number that identifies the bank. This is also known as the sort code.
type: string
bankTransferType:
description: |
The type of the Bank Transfer payment method. For example, `SEPA`.
type: string
branchCode:
description: |
The branch code of the bank used for Direct Debit.
type: string
businessIdentificationCode:
description: |
The BIC code used for SEPA. The value is masked.
type: string
identityNumber:
description: |
The identity number of the account holder or the cardholder.
type: string
type: object
GETPaymentMethodResponseACHForAccount:
properties:
bankABACode:
description: |
The nine-digit routing number or ABA number used by banks. This field is only required if the `type` field is set to `ACH`.
type: string
bankAccountName:
description: |
The name of the account holder, which can be either a person or a company. This field is only required if the `type` field is set to `ACH`.
type: string
type: object
GETPaymentMethodResponseCreditCardForAccount:
properties:
cardNumber:
description: |
The masked credit card number.
When `cardNumber` is `null`, the following fields will not be returned:
- `expirationMonth`
- `expirationYear`
- `accountHolderInfo`
type: string
expirationMonth:
description: |
One or two digits expiration month (1-12).
type: integer
expirationYear:
description: |
Four-digit expiration year.
type: integer
securityCode:
description: |
The CVV or CVV2 security code for the credit card or debit card.
Only required if changing expirationMonth, expirationYear, or cardHolderName.
To ensure PCI compliance, this value isn''t stored and can''t be queried.
type: string
type: object
GETPaymentMethodResponsePayPalForAccount:
properties:
BAID:
description: |
ID of a PayPal billing agreement. For example, I-1TJ3GAGG82Y9.
type: string
email:
description: |
Email address associated with the PayPal payment method.
type: string
preapprovalKey:
description: |
The PayPal preapproval key.
type: string
type: object
GETPaymentMethodResponseGooglePayForAccount:
properties:
googleBIN:
description: |
This field is only available for Google Pay payment methods.
type: string
googleCardNumber:
description: |
This field is only available for Google Pay payment methods.
type: string
googleCardType:
description: |
This field is only available for Google Pay payment methods.
For Google Pay payment methods on Adyen, the first 100 characters of [paymentMethodVariant](https://docs.adyen.com/development-resources/paymentmethodvariant) returned from Adyen are stored in this field.
type: string
googleExpiryDate:
description: |
This field is only available for Google Pay payment methods.
type: string
googleGatewayToken:
description: |
This field is only available for Google Pay payment methods.
type: string
type: object
GETPaymentMethodResponseApplePayForAccount:
properties:
appleBIN:
description: |
This field is only available for Apple Pay payment methods.
type: string
appleCardNumber:
description: |
This field is only available for Apple Pay payment methods.
type: string
appleCardType:
description: |
This field is only available for Apple Pay payment methods.
For Apple Pay payment methods on Adyen, the first 100 characters of [paymentMethodVariant](https://docs.adyen.com/development-resources/paymentmethodvariant) returned from Adyen are stored in this field.
type: string
appleExpiryDate:
description: |
This field is only available for Apple Pay payment methods.
type: string
appleGatewayToken:
description: |
This field is only available for Apple Pay payment methods.
type: string
type: object
GetCascadingPaymentMethodsConfigurationResponse:
properties:
consent:
type: boolean
description: |
`true` indicates the consent from your customer to use the Cascading Payment Method feature was collected. `false` indicates the consent was not collected and the Cascading Payment Method feature is not enabled.
priorities:
type: array
description: |
Container for the priority configuration of payment methods.
items:
type: object
properties:
paymentMethodId:
type: string
description: |
The ID of a payment method.
nullable: true
order:
type: integer
minimum: 1
description: |
The order of the payment method in the priority list. For example, `1` indicates the payment method is the first one in the priority list, and `2` indicates it is the second.
The first payment method in the priority list is the default payment method of the customer account.
title: priority
success:
type: boolean
description: |
Indicates whether the call succeeded.
type: object
PutCascadingPaymentMethodsConfigurationRequest:
properties:
consent:
type: boolean
description: |
`true` indicates that you have collected consent from your customer to use the Cascading Payment Method feature. `false` indicates the consent was not collected and the Cascading Payment Method feature is not enabled.
The `priorities` field can be specified only if `consent` is `true`.
priorities:
type: array
description: |
Container for the priority configuration of payment methods. You can add up to three payment methods to this container. For more information, see Cascade payment methods.
`priorities` is required if `consent` is `true`.
items:
type: object
properties:
paymentMethodId:
type: string
description: |
The ID of a payment method.
order:
type: integer
minimum: 1
description: |
The order of the payment method in the priority list. For example, `1` indicates the payment method is the first one in the priority list, and `2` indicates it is the second.
The first payment method in the priority list will be the default payment method of the customer account.
required:
- paymentMethodId
- order
title: priority
type: object
example:
consent: true
priorities:
- paymentMethodId: 2c92c0f95be68649015bf14e001f2760
order: 1
- paymentMethodId: 2c92c0f95be68649015bf14e001f2761
order: 2
- paymentMethodId: 2c92c0f95be68649015bf14e001f2762
order: 3
GETAccountSummaryType:
properties:
basicInfo:
$ref: '#/components/schemas/GETAccountSummaryTypeBasicInfo'
billToContact:
$ref: '#/components/schemas/GETAccountSummaryTypeBillToContact'
invoices:
description: |
Container for invoices. Only returns the last 6 invoices.
items:
$ref: '#/components/schemas/GETAccountSummaryInvoiceType'
type: array
payments:
description: |
Container for payments. Only returns the last 6 payments.
items:
$ref: '#/components/schemas/GETAccountSummaryPaymentType'
type: array
shipToContact:
$ref: '#/components/schemas/GetAccountSummaryTypeShipToContact'
soldToContact:
$ref: '#/components/schemas/GETAccountSummaryTypeSoldToContact'
subscriptions:
description: |
Container for subscriptions.
items:
$ref: '#/components/schemas/GETAccountSummarySubscriptionType'
type: array
success:
description: |
Returns `true` if the request was processed successfully.
type: boolean
taxInfo:
description: |
Container for tax exempt information, used to establish the tax exempt status of a customer account.
properties:
VATId:
description: |
EU Value Added Tax ID.
type: string
companyCode:
description: |
Unique code that identifies a company account in Avalara.
type: string
exemptCertificateId:
description: |
ID of the customer tax exemption certificate.
type: string
exemptCertificateType:
description: |
Type of tax exemption certificate that the customer holds.
type: string
exemptDescription:
description: |
Description of the tax exemption certificate that the customer holds.
type: string
exemptEffectiveDate:
description: |
Date when the customer tax exemption starts.
format: date
type: string
exemptEntityUseCode:
description: |
A unique entity use code to apply exemptions in Avalara AvaTax.
This account-level field is required only when you choose Avalara as your tax engine. See [Exempt Transactions](https://developer.avalara.com/avatax/handling-tax-exempt-customers/)for more details.
maxLength: 64
type: string
exemptExpirationDate:
description: |
Date when the customer tax exemption expires.
format: date
type: string
exemptIssuingJurisdiction:
description: |
Jurisdiction in which the customer tax exemption certificate was issued.
type: string
exemptStatus:
description: |
Status of the account tax exemption.
type: string
type: object
usage:
description: |
Container for usage data. Only returns the last 6 months of usage.
**Note:** If the Active Rating feature is enabled, no usage data is returned in the response body field.
items:
$ref: '#/components/schemas/GETAccountSummaryUsageType'
type: array
type: object
GETAccountSummaryTypeBasicInfo:
allOf:
- properties:
accountNumber:
description: |
Account number.
type: string
additionalEmailAddresses:
description: |
A list of additional email addresses to receive email notifications.
items:
type: string
type: array
autoPay:
description: |
Whether future payments are automatically collected when they are due during a payment run.
type: boolean
balance:
description: |
Current outstanding balance.
format: decimal
type: string
batch:
description: |
The alias name given to a batch. A string of 50 characters or less.
type: string
billCycleDay:
description: |
Billing cycle day (BCD), the day of the month when a bill run generates invoices for the account.
type: string
bcdSettingOption:
description: |
Bill cycle day setting option. Indicates whether the account’s bill cycle day is managed manually or automatically.
- `ManualSet`: The bill cycle day is explicitly set to a specific day of the month (1–31).
- `AutoSet`: The bill cycle day is automatically determined by Zuora. The bill cycle day is assigned when the first subscription is created for the account.
This field is system-derived and read-only. Its value is automatically determined based on the `billCycleDay` field.
type: string
enum:
- ManualSet
- AutoSet
currency:
description: |
A currency as defined in Billing Settings in the Zuora UI.
type: string
defaultPaymentMethod:
description: |
Information of the default payment method for the account.
properties:
creditCardExpirationMonth:
description: |
Two-digit numeric card expiration month as `mm`.
type: string
creditCardExpirationYear:
description: |
Four-digit card expiration year as `yyyy`.
type: string
creditCardNumber:
description: |
Credit card number, 16 characters or less, displayed in masked format (e.g., ************1234).
type: string
creditCardType:
description: |
The type of the credit card.
Possible values include `Visa`, `MasterCard`, `AmericanExpress`, `Discover`, `JCB`, and `Diners`. For more information about credit card types supported by different payment gateways, see [Supported Payment Methods](https://knowledgecenter.zuora.com/Zuora_Central/Billing_and_Payments/L_Payment_Methods/Supported_Payment_Methods).
type: string
id:
description: |
ID of the default payment method associated with this account.
type: string
paymentMethodType:
description: |
Type of the payment method. For non-Credit-Card payment methods, only the `id` and `paymentMethodType` fields are returned.
type: string
enum:
- CreditCard
- CreditCardReferenceTransaction
- ACH
- BankTransfer
- PayPal
- AdyenApplePay
- AdyenGooglePay
- GooglePay
type: object
id:
description: |
Account ID.
type: string
invoiceDeliveryPrefsEmail:
description: |
Whether the customer wants to receive invoices through email.
type: boolean
invoiceDeliveryPrefsPrint:
description: |
Whether the customer wants to receive printed invoices, such as through postal mail.
type: boolean
lastInvoiceDate:
description: |
Date of the most recent invoice for the account; null if no invoice has ever been generated.
format: date
type: string
lastMetricsUpdate:
description: |
The date and time when account metrics are last updated, if the account is a partner account.
**Note**:
- This field is available only if you have the Reseller Account feature enabled.
- If you have the Reseller Account feature enabled, and set the `partnerAccount` field to `false` for an account, the value of the `lastMetricsUpdate` field is automatically set to `null` in the response.
- If you ever set the `partnerAccount` field to `true` for an account, the value of `lastMetricsUpdate` field is the time when the account metrics are last updated.
format: date-time
type: string
lastPaymentAmount:
description: |
Amount of the most recent payment collected for the account; null if no payment has ever been collected.
format: decimal
type: string
lastPaymentDate:
description: |
Date of the most recent payment collected for the account. Null if no payment has ever been collected.
format: date
type: string
name:
description: |
Account name.
type: string
organizationLabel:
description: |
The organization that this object belongs to.
Note: This field is available only when the Multi-Org feature is enabled.
type: string
partnerAccount:
description: |
Whether the customer account is a partner, distributor, or reseller.
**Note**: This field is available only if you have the Reseller Account feature enabled.
type: boolean
paymentMethodCascadingConsent:
description: |
`true` indicates the consent from your customer to use the Cascading Payment Method feature was collected.
`false` indicates the consent was not collected and the Cascading Payment Method feature is not enabled.
type: boolean
purchaseOrderNumber:
description: The purchase order number provided by your customer for services, products, or both purchased.
type: string
status:
description: |
Account status; possible values are: `Active`, `Draft`, `Canceled`.
type: string
tags:
description: ''
type: string
type: object
- $ref: '#/components/schemas/AccountObjectNSFields'
- $ref: '#/components/schemas/AccountObjectCustomFields'
description: |
Container for basic information about the account.
title: basicInfo
GETAccountSummaryTypeBillToContact:
allOf:
- properties:
address1:
description: |
First address line, 255 characters or less.
type: string
address2:
description: |
Second address line, 255 characters or less.
type: string
asBillTo:
description: |
Indicates whether the contact can be specified as a bill-to contact.
This field is available only if you have turned on the Ship To Contact feature. You can turn on the feature through the self-service interface for Feature Management.
type: boolean
asShipTo:
description: |
Indicates whether the contact can be specified as a ship-to contact.
This field is available only if you have turned on the Ship To Contact feature. You can turn on the feature through the self-service interface for Feature Management.
type: boolean
asSoldTo:
description: |
Indicates whether the contact can be specified as a sold-to contact.
This field is available only if you have turned on the Ship To Contact feature. You can turn on the feature through the self-service interface for Feature Management.
type: boolean
city:
description: |
City, 40 characters or less.
type: string
country:
description: |
Full country name. This field does not contain the ISO-standard abbreviation of the country name.
type: string
nullable: true
county:
description: 'County; 32 characters or less. Zuora Tax uses this information to calculate county taxation. '
type: string
nullable: true
fax:
description: |
Fax phone number, 40 characters or less.
type: string
firstName:
description: |
First name, 100 characters or less.
type: string
id:
description: |
Contact ID.
type: string
lastName:
description: |
Last name, 100 characters or less.
type: string
state:
description: |
Full state name. This field does not contain the ISO-standard abbreviation of the state name.
type: string
taxRegion:
description: |
A region string, defined in your Zuora tax rules.
type: string
workEmail:
description: |
Work email address, 80 characters or less.
type: string
workPhone:
description: |
Work phone number, 40 characters or less.
type: string
zipCode:
description: |
Zip code, 20 characters or less.
type: string
type: object
- $ref: '#/components/schemas/ContactObjectCustomFields'
description: |
Container for bill-to contact information.
**Notes**:
- If the bill-to contact is specified on the subscription, its value is populated in this field. For more information about how to specify the bill-to contact on the subscription, see Overview of Flexible Billing Attributes.
- If the bill-to contact is not specified on the subscription, the bill-to contact on the invoice owner account will be populated in this field.
title: Contact
GETAccountSummaryInvoiceType:
properties:
amount:
description: |
Invoice amount before adjustments, discounts, and similar items.
type: number
balance:
description: |
Balance due on the invoice.
format: decimal
type: string
dueDate:
description: |
Due date as `yyyy-mm-dd`.
format: date
type: string
id:
description: |
Invoice ID.
type: string
invoiceDate:
description: |
Invoice date as `yyyy-mm-dd`.
format: date
type: string
invoiceNumber:
description: |
Invoice number.
type: string
status:
description: |
Invoice status - not the payment status of the invoice, just the status of the invoice itself. Possible values are: `Posted`, `Draft`, `Canceled`, `Error`.
type: string
title: invoices
type: object
GETAccountSummaryPaymentType:
properties:
effectiveDate:
description: |
Effective date as `yyyy-mm-dd`.
format: date
type: string
id:
description: |
Payment ID.
type: string
paidInvoices:
description: |
Container for paid invoices for this subscription.
items:
$ref: '#/components/schemas/GETAccountSummaryPaymentInvoiceType'
type: array
paymentNumber:
description: |
Payment number.
type: string
paymentType:
description: |
Payment type; possible values are: `External`, `Electronic`.
type: string
status:
description: |
Payment status. Possible values are: `Draft`, `Processing`, `Processed`, `Error`, `Voided`, `Canceled`, `Posted`.
type: string
title: payments
type: object
GetAccountSummaryTypeShipToContact:
allOf:
- properties:
address1:
description: |
First address line, 255 characters or less.
type: string
address2:
description: |
Second address line, 255 characters or less.
type: string
asBillTo:
description: |
Indicates whether the contact can be specified as a bill-to contact.
This field is available only if you have turned on the Ship To Contact feature. You can turn on the feature through the self-service interface for Feature Management.
type: boolean
asShipTo:
description: |
Indicates whether the contact can be specified as a ship-to contact.
This field is available only if you have turned on the Ship To Contact feature. You can turn on the feature through the self-service interface for Feature Management.
type: boolean
asSoldTo:
description: |
Indicates whether the contact can be specified as a sold-to contact.
This field is available only if you have turned on the Ship To Contact feature. You can turn on the feature through the self-service interface for Feature Management.
type: boolean
city:
description: |
City, 40 characters or less.
type: string
country:
description: |
Full country name. This field does not contain the ISO-standard abbreviation of the country name.
type: string
nullable: true
county:
description: 'County; 32 characters or less. Zuora Tax uses this information to calculate county taxation. '
type: string
nullable: true
fax:
description: |
Fax phone number, 40 characters or less.
type: string
firstName:
description: |
First name, 100 characters or less.
type: string
id:
description: |
Contact ID.
type: string
lastName:
description: |
Last name, 100 characters or less.
type: string
state:
description: |
Full state name. This field does not contain the ISO-standard abbreviation of the state name.
type: string
taxRegion:
description: |
A region string, defined in your Zuora tax rules.
type: string
workEmail:
description: |
Work email address, 80 characters or less.
type: string
workPhone:
description: |
Work phone number, 40 characters or less.
type: string
zipCode:
description: |
Zip code, 20 characters or less.
type: string
type: object
- $ref: '#/components/schemas/ContactObjectCustomFields'
description: |
Container for ship-to contact information.
**Notes**:
- If the ship-to contact is specified on the subscription, its value is populated in this field. For more information about how to specify the ship-to contact on the subscription, see Overview of Flexible Billing Attributes.
- If the ship-to contact is not specified on the subscription, the ship-to contact on the subscription owner account will be populated in this field.
title: Contact
GETAccountSummaryTypeSoldToContact:
allOf:
- properties:
address1:
description: |
First address line, 255 characters or less.
type: string
address2:
description: |
Second address line, 255 characters or less.
type: string
asBillTo:
description: |
Indicates whether the contact can be specified as a bill-to contact.
This field is available only if you have turned on the Ship To Contact feature. You can turn on the feature through the self-service interface for Feature Management.
type: boolean
asShipTo:
description: |
Indicates whether the contact can be specified as a ship-to contact.
This field is available only if you have turned on the Ship To Contact feature. You can turn on the feature through the self-service interface for Feature Management.
type: boolean
asSoldTo:
description: |
Indicates whether the contact can be specified as a sold-to contact.
This field is available only if you have turned on the Ship To Contact feature. You can turn on the feature through the self-service interface for Feature Management.
type: boolean
city:
description: |
City, 40 characters or less.
type: string
country:
description: |
Full country name. This field does not contain the ISO-standard abbreviation of the country name.
type: string
nullable: true
county:
description: 'County; 32 characters or less. Zuora Tax uses this information to calculate county taxation. '
type: string
nullable: true
fax:
description: |
Fax phone number, 40 characters or less.
type: string
firstName:
description: |
First name, 100 characters or less.
type: string
id:
description: |
Contact ID.
type: string
lastName:
description: |
Last name, 100 characters or less.
type: string
state:
description: |
Full state name. This field does not contain the ISO-standard abbreviation of the state name.
type: string
taxRegion:
description: |
A region string, defined in your Zuora tax rules.
type: string
workEmail:
description: |
Work email address, 80 characters or less.
type: string
workPhone:
description: |
Work phone number, 40 characters or less.
type: string
zipCode:
description: |
Zip code, 20 characters or less.
type: string
type: object
- $ref: '#/components/schemas/ContactObjectCustomFields'
description: |
Container for sold-to contact information.
**Notes**:
- If the sold-to contact is specified on the subscription, its value is populated in this field. For more information about how to specify the sold-to contact on the subscription, see Overview of Flexible Billing Attributes.
- If the sold-to contact is not specified on the subscription, the sold-to contact on the subscription owner account will be populated in this field.
title: Contact
GETAccountSummarySubscriptionType:
allOf:
- properties:
autoRenew:
description: |
If `true`, auto-renew is enabled. If `false`, auto-renew is disabled.
type: boolean
id:
description: |
Subscription ID.
type: string
initialTerm:
description: |
Duration of the initial subscription term in whole months.
type: string
ratePlans:
description: |
Container for rate plans for this subscription.
items:
$ref: '#/components/schemas/GETAccountSummarySubscriptionRatePlanType'
type: array
renewalTerm:
description: |
Duration of the renewal term in whole months.
type: string
status:
description: |
Subscription status; possible values are: `Draft`, `PendingActivation`, `PendingAcceptance`, `Active`, `Cancelled`, `Expired`.
type: string
subscriptionNumber:
description: |
Subscription Number.
type: string
subscriptionStartDate:
description: |
Subscription start date.
format: date
type: string
termEndDate:
description: |
End date of the subscription term. If the subscription is evergreen, this is either null or equal to the cancellation date, as appropriate.
format: date
type: string
termStartDate:
description: |
Start date of the subscription term. If this is a renewal subscription, this date is different than the subscription start date.
format: date
type: string
termType:
description: |
Possible values are: `TERMED`, `EVERGREEN`.
type: string
type: object
- $ref: '#/components/schemas/SubscriptionObjectQTFields'
- $ref: '#/components/schemas/SubscriptionObjectNSFields'
- $ref: '#/components/schemas/SubscriptionObjectCustomFields'
title: subscriptions
GETAccountSummaryUsageType:
properties:
quantity:
description: |
Number of units used.
format: decimal
type: string
startDate:
description: |
The start date of a usage period as `yyyy-mm`. Zuora uses this field value to determine the usage date.
format: date
type: string
unitOfMeasure:
description: |
Unit by which consumption is measured, as configured in the Billing Settings section of the web-based UI.
type: string
title: usage
type: object
GETAccountSummarySubscriptionRatePlanType:
properties:
productId:
description: |
Product ID.
type: string
productName:
description: |
Product name.
type: string
productRatePlanId:
description: |
Product Rate Plan ID.
type: string
productSku:
description: ''
type: string
ratePlanName:
description: |
Rate plan name.
type: string
title: ratePlans
type: object
GETAccountSummaryPaymentInvoiceType:
properties:
appliedPaymentAmount:
description: |
Amount of payment applied to the invoice.
format: decimal
type: string
invoiceId:
description: |
Invoice ID.
type: string
invoiceNumber:
description: |
Invoice number.
type: string
title: paidInvoices
type: object
POSTContactType:
allOf:
- properties:
accountId:
description: |
The ID of the account associated with the contact.
**Note**: When creating a contact, you must specify `accountNumber`, `accountId`, or both in the request body. If both fields are specified, they must correspond to the same account.
type: string
accountNumber:
description: |
The number of the customer account associated with the contact.
**Note**: When creating a contact, you must specify `accountNumber`, `accountId`, or both in the request body. If both fields are specified, they must correspond to the same account.
type: string
address1:
description: |
The first line of the contact's address, which is often a street address or business name.
maxLength: 255
type: string
address2:
description: |
The second line of the contact's address.
maxLength: 255
type: string
asBillTo:
description: |
Indicates whether the contact can be specified as a bill-to contact.
This field is available only if you have turned on the Ship To Contact feature. You can turn on the feature through the self-service interface for Feature Management.
type: boolean
asShipTo:
description: |
Indicates whether the contact can be specified as a ship-to contact.
This field is available only if you have turned on the Ship To Contact feature. You can turn on the feature through the self-service interface for Feature Management.
type: boolean
asSoldTo:
description: |
Indicates whether the contact can be specified as a sold-to contact.
This field is available only if you have turned on the Ship To Contact feature. You can turn on the feature through the self-service interface for Feature Management.
type: boolean
city:
description: |
The city of the contact's address.
maxLength: 100
type: string
contactDescription:
description: |
A description for the contact.
maxLength: 100
type: string
country:
description: |
The country of the contact's address. Either a full name or an ISO code is supported.
maxLength: 64
type: string
county:
description: |
The county. May optionally be used by Zuora Tax to calculate county tax.
maxLength: 100
type: string
fax:
description: |
The contact's fax number.
maxLength: 40
type: string
firstName:
description: |
The contact's first name.
maxLength: 100
type: string
homePhone:
description: |
The contact's home phone number.
maxLength: 40
type: string
lastName:
description: |
The contact's last name.
maxLength: 100
type: string
mobilePhone:
description: |
The mobile phone number of the contact.
maxLength: 100
type: string
nickname:
description: |
A nickname for the contact.
maxLength: 100
type: string
otherPhone:
description: |
An additional phone number for the contact.
maxLength: 40
type: string
otherPhoneType:
description: |
The type of the additional phone number.
enum:
- Work
- Mobile
- Home
- Other
type: string
personalEmail:
description: |
The contact's personal email address.
maxLength: 80
type: string
format: email
state:
description: |
The state or province of the contact's address. Either a full name or an abbreviation code is supported.
maxLength: 100
type: string
taxRegion:
description: |
If using Zuora Tax, a region string as optionally defined in your tax rules. Not required.
maxLength: 100
type: string
workEmail:
description: |
The contact's business email address.
maxLength: 80
type: string
workPhone:
description: |
The contact's business phone number.
maxLength: 40
type: string
zipCode:
description: |
The zip code for the contact's address.
maxLength: 20
type: string
required:
- firstName
- lastName
type: object
- $ref: '#/components/schemas/ContactObjectCustomFields'
example:
accountId: 6e767220676e6e61206776652075207570
accountNumber: A00000001
address1: 314, Bongora
address2: near Tech City
city: GHY
contactDescription: This is a description for the contact
country: India
fax: '6174'
firstName: Kuhi
homePhone: '1234123'
lastName: Das
mobilePhone: '123213'
nickname: Dorimi
otherPhone: '2314213'
otherPhoneType: Work
personalEmail: kuhiroll@example.com
state: Assam
zipCode: '123456'
ContactResponse:
allOf:
- properties:
accountId:
description: |
The ID of the account associated with the contact.
type: string
accountNumber:
description: |
The number of the customer account associated with the contact.
type: string
address1:
description: |
The first line of the contact's address, which is often a street address or business name.
maxLength: 255
type: string
address2:
description: |
The second line of the contact's address.
maxLength: 255
type: string
asBillTo:
description: |
Indicates whether the contact can be specified as a bill-to contact.
This field is available only if you have turned on the Ship To Contact feature. You can turn on the feature through the self-service interface for Feature Management.
type: boolean
asShipTo:
description: |
Indicates whether the contact can be specified as a ship-to contact.
This field is available only if you have turned on the Ship To Contact feature. You can turn on the feature through the self-service interface for Feature Management.
type: boolean
asSoldTo:
description: |
Indicates whether the contact can be specified as a sold-to contact.
This field is available only if you have turned on the Ship To Contact feature. You can turn on the feature through the self-service interface for Feature Management.
type: boolean
city:
description: |
The city of the contact's address.
maxLength: 40
type: string
contactDescription:
description: |
A description for the contact.
maxLength: 100
type: string
country:
description: |
The full country name of the contact's address.
maxLength: 64
type: string
county:
description: |
The county. May optionally be used by Zuora Tax to calculate county tax.
maxLength: 32
type: string
fax:
description: |
The contact's fax number.
maxLength: 40
type: string
firstName:
description: |
The contact's first name.
maxLength: 100
type: string
homePhone:
description: |
The contact's home phone number.
maxLength: 40
type: string
lastName:
description: |
The contact's last name.
maxLength: 100
type: string
mobilePhone:
description: |
The mobile phone number of the contact.
maxLength: 100
type: string
nickname:
description: |
A nickname for the contact.
maxLength: 100
type: string
otherPhone:
description: |
An additional phone number for the contact.
maxLength: 40
type: string
otherPhoneType:
description: |
The type of the additional phone number.
enum:
- Work
- Mobile
- Home
- Other
type: string
personalEmail:
description: |
The contact's personal email address.
maxLength: 80
type: string
state:
description: |
The full state or province name of the contact's address.
maxLength: 40
type: string
success:
description: |
Returns `true` if the request was processed successfully.
type: boolean
taxRegion:
description: |
If using Zuora Tax, a region string as optionally defined in your tax rules. Not required.
maxLength: 32
type: string
workEmail:
description: |
The contact's business email address.
maxLength: 80
type: string
workPhone:
description: |
The contact's business phone number.
maxLength: 40
type: string
zipCode:
description: |
The zip code for the contact's address.
maxLength: 20
type: string
type: object
- $ref: '#/components/schemas/ContactObjectCustomFields'
PUTContactType:
allOf:
- properties:
address1:
description: |
The first line of the contact's address, which is often a street address or business name.
maxLength: 255
type: string
address2:
description: |
The second line of the contact's address.
maxLength: 255
type: string
asBillTo:
description: |
Indicates whether the contact can be specified as a bill-to contact.
This field is available only if you have turned on the Ship To Contact feature. You can turn on the feature through the self-service interface for Feature Management.
type: boolean
asShipTo:
description: |
Indicates whether the contact can be specified as a ship-to contact.
This field is available only if you have turned on the Ship To Contact feature. You can turn on the feature through the self-service interface for Feature Management.
type: boolean
asSoldTo:
description: |
Indicates whether the contact can be specified as a sold-to contact.
This field is available only if you have turned on the Ship To Contact feature. You can turn on the feature through the self-service interface for Feature Management.
type: boolean
city:
description: |
The city of the contact's address.
maxLength: 100
type: string
contactDescription:
description: |
A description for the contact.
maxLength: 100
type: string
country:
description: |
The country of the contact's address. Either a full name or an ISO code is supported.
maxLength: 64
type: string
county:
description: |
The county. May optionally be used by Zuora Tax to calculate county tax.
maxLength: 100
type: string
fax:
description: |
The contact's fax number.
maxLength: 40
type: string
firstName:
description: |
The contact's first name.
maxLength: 100
type: string
homePhone:
description: |
The contact's home phone number.
maxLength: 40
type: string
lastName:
description: |
The contact's last name.
maxLength: 100
type: string
mobilePhone:
description: |
The mobile phone number of the contact.
maxLength: 100
type: string
nickname:
description: |
A nickname for the contact.
maxLength: 100
type: string
otherPhone:
description: |
An additional phone number for the contact.
maxLength: 40
type: string
otherPhoneType:
description: |
The type of the additional phone number.
enum:
- Work
- Mobile
- Home
- Other
type: string
personalEmail:
description: |
The contact's personal email address.
maxLength: 80
type: string
state:
description: |
The state or province of the contact's address. Either a full name or an abbreviation code is supported.
maxLength: 100
type: string
taxRegion:
description: |
If using Zuora Tax, a region string as optionally defined in your tax rules. Not required.
maxLength: 100
type: string
workEmail:
description: |
The contact's business email address.
maxLength: 80
type: string
workPhone:
description: |
The contact's business phone number.
maxLength: 40
type: string
zipCode:
description: |
The zip code for the contact's address.
maxLength: 20
type: string
type: object
- $ref: '#/components/schemas/ContactObjectCustomFields'
example:
address1: new Address
city: Mumbai
contactDescription: This is the new Description
mobilePhone: 123213
zipCode: 123134
PUTTransferContact:
type: object
properties:
destinationAccountKey:
description: |
The ID or number of the destination account.
type: string
example:
destinationAccountKey: A00000135
GETContactSnapshotResponse:
allOf:
- properties:
address1:
description: |
The first line for the address of the contact, which is often a street address or business name.
type: string
address2:
description: |
The second line for the address of the contact, which is mostly the locality.
type: string
asBillTo:
description: |
Indicates whether the contact can be specified as a bill-to contact.
This field is available only if you have turned on the Ship To Contact feature. You can turn on the feature through the self-service interface for Feature Management.
type: boolean
asShipTo:
description: |
Indicates whether the contact can be specified as a ship-to contact.
This field is available only if you have turned on the Ship To Contact feature. You can turn on the feature through the self-service interface for Feature Management.
type: boolean
asSoldTo:
description: |
Indicates whether the contact can be specified as a sold-to contact.
This field is available only if you have turned on the Ship To Contact feature. You can turn on the feature through the self-service interface for Feature Management.
type: boolean
city:
description: |
The city for the address of the contact.
type: string
contactId:
description: |
The Zuora ID of the contact who the snapshot belongs to.
type: string
country:
description: |
The country for the address of the contact.
type: string
nullable: true
county:
description: |
The county for the address of the contact. The field value might optionally be used by Zuora Tax to calculate county tax.
type: string
description:
description: |
A description of the contact.
type: string
fax:
description: |
The fax number of the contact.
format: number
type: string
firstName:
description: |
The first name of the contact.
type: string
homePhone:
description: |
The home phone number of the contact.
format: number
type: string
id:
description: |
The unique ID of the contact snapshot.
type: string
lastName:
description: |
The last name of the contact.
type: string
mobilePhone:
description: |
The mobile phone number of the contact.
format: number
type: string
nickname:
description: |
A nickname for the contact.
type: string
otherPhone:
description: |
An additional phone number for the contact.
type: string
otherPhoneType:
description: |
The type of the additional phone number.
enum:
- Work
- Mobile
- Home
- Other
type: string
personalEmail:
description: |
The personal email address of the contact.
type: string
maxLength: 80
postalCode:
description: |
The postal code for the address of the contact.
format: number
type: string
state:
description: |
The state or province for the address of the contact.
type: string
taxRegion:
description: |
If using Zuora Tax rules.
type: string
workEmail:
description: |
The business email address of the contact.
type: string
workPhone:
description: |
The business email address of the contact.
format: number
type: string
type: object
- $ref: '#/components/schemas/ContactSnapshotObjectCustomFields'
ContactSnapshotObjectCustomFields:
additionalProperties:
description: |
Custom fields of the Contact Snapshot object. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. For more information, see Manage custom fields.
description: |
Container for custom fields of a Contact Snapshot object.
title: contactSnapshotFieldsCustom
type: object
SignUpRequest:
example:
accountData:
autoPay: false
billCycleDay: 15
billToContact:
country: US
firstName: foo
lastName: bar
state: California
currency: USD
customFields:
CustomerUserId__c: User_269145114619000
name: User
paymentMethod:
makeDefault: true
secondTokenId: '010'
tokenId: User_269145114619000
type: CreditCardReferenceTransaction
accountIdentifierField: CustomerUserId__c
options:
billingTargetDate: '2021-07-01'
collectPayment: true
maxSubscriptionsPerAccount: 0
runBilling: true
subscriptionData:
invoiceSeparately: false
ratePlans:
- productRatePlanId: 4028818284f5f8130184f5fe1a73101f
startDate: '2021-04-15'
terms:
autoRenew: false
initialTerm:
period: 6
periodType: Month
startDate: '2021-04-15'
termType: TERMED
renewalSetting: RENEW_WITH_SPECIFIC_TERM
renewalTerms:
- period: 6
periodType: Month
properties:
accountData:
$ref: '#/components/schemas/AccountData'
accountIdentifierField:
description: Specify the name of the field that holds external account id
type: string
customFields:
$ref: '#/components/schemas/CustomFields'
options:
$ref: '#/components/schemas/Options'
paymentData:
$ref: '#/components/schemas/PaymentData'
subscriptionData:
$ref: '#/components/schemas/SubscriptionData'
type: object
SignUpResponse:
properties:
accountId:
description: The account id for the order.
type: string
accountNumber:
description: The account number for the order.
type: string
creditMemoId:
description: An array of the credit memo id generated in this order request. The credit memo is only available if you have the Invoice Settlement feature enabled.
type: string
creditMemoNumber:
description: An array of the credit memo numbers generated in this order request. The credit memo is only available if you have the Invoice Settlement feature enabled.
type: string
invoiceId:
description: The invoice id generated in this order request
type: string
invoiceNumber:
description: The invoice number generated in this order request
type: string
orderNumber:
description: The order number of the order created.
type: string
paidAmount:
description: The total amount collected in this order request.
type: string
paymentId:
description: The payment id that is collected in this order request.
type: string
paymentNumber:
description: The payment number that is collected in this order request.
type: string
processId:
description: |
The Id of the process that handles the operation.
type: string
reasons:
items:
$ref: '#/components/schemas/SignUpResponse_reasons'
type: array
status:
description: Status of the order. `Pending` is only applicable for an order that contains a `CreateSubscription` order action.
enum:
- Completed
- Pending
type: string
subscriptionId:
description: The subscription id of the order.
type: string
subscriptionNumber:
description: The subscription number of the order.
type: string
success:
description: |
Indicates whether the call succeeded.
type: boolean
type: object
SignUpResponse_reasons:
properties:
code:
description: |
The error code of response.
type: string
message:
description: |
The detail information of the error response
type: string
type: object
AccountData:
description: |
The information of the account that you are to create through the "Sign up" operation.
properties:
accountNumber:
maxLength: 70
type: string
autoPay:
description: Specifies whether future payments are to be automatically billed when they are due. Possible values are `true`, `false`.
type: boolean
batch:
description: |
**Note**: By default, you have 50 configurable account batches. To increase the limit to 200 batches, you must have the Performance Booster Elite package.
type: string
billCycleDay:
description: Day of the month that the account prefers billing periods to begin on. If set to 0, the bill cycle day will be set as "AutoSet".
maximum: 31
minimum: 0
type: integer
billToContact:
$ref: '#/components/schemas/ContactInfo'
communicationProfileId:
type: string
creditMemoTemplateId:
description: |
**Note:** This field is only available if you have [Invoice Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement) 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.
The unique ID of the credit memo template, configured in **Billing Settings** > **Manage Billing Document Configuration** through the Zuora UI. For example, 2c92c08a6246fdf101626b1b3fe0144b.
type: string
crmId:
maxLength: 100
type: string
currency:
description: |
3 uppercase character currency code.
**Note**: Specify this field only for a new account to be created; do not specify this field to update an existing account.
For payment method authorization, if the `paymentMethod` > `currencyCode` field is specified, `currencyCode` is used. Otherwise, this `currency` field is used for payment method authorization. If no currency is specified for the account, the default currency of the account is then used.
type: string
customFields:
$ref: '#/components/schemas/CustomFields'
debitMemoTemplateId:
description: |
**Note:** This field is only available if you have [Invoice Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement) 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.
The unique ID of the debit memo template, configured in **Billing Settings** > **Manage Billing Document Configuration** through the Zuora UI. For example, 2c92c08d62470a8501626b19d24f19e2.
type: string
invoiceTemplateId:
type: string
name:
maxLength: 255
type: string
notes:
maxLength: 65535
type: string
organizationLabel:
type: string
description: |
The organization that this object belongs to.
Note: This field is available only when the Multi-Org feature is enabled.
paymentMethod:
$ref: '#/components/schemas/SignUpPaymentMethod'
paymentTerm:
type: string
purchaseOrderNumber:
description: |
The number of the purchase order associated with this account. Purchase order information generally comes from customers.
maxLength: 100
type: string
sequenceSetId:
description: |
The ID of the billing document sequence set to assign to the customer account.
The billing documents to generate for this account will adopt the prefix and starting document number configured in the sequence set.
type: string
nullable: true
shipToContact:
$ref: '#/components/schemas/ContactInfo'
soldToContact:
$ref: '#/components/schemas/ContactInfo'
taxInfo:
$ref: '#/components/schemas/SignUpTaxInfo'
required:
- billCycleDay
- billToContact
- currency
- name
type: object
CustomFields:
additionalProperties:
description: |
The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
The Sign up API is based on Orders. The root element uses the custom field defintion on an "Order" object, `accountData` uses the custom field defintion on an "Account" object, and `subscriptionData` uses the custom field defintion on an "Order Action" object (not on an "Subscription" object).
description: |
Container for custom fields.
title: CustomFields
type: object
Options:
description: Invoice or Payment.
properties:
billingTargetDate:
description: Date through which to calculate charges if an invoice is generated. See [What is a Target Date?](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/G_Bill_Runs/Creating_Bill_Runs#What_is_a_Target_Date.3F).
format: date
type: string
collectPayment:
description: Indicates if the current request needs to collect payments. This value can not be 'true' when 'runBilling' flag is 'false'.
type: boolean
maxSubscriptionsPerAccount:
type: number
runBilling:
description: Indicates if the current request needs to generate an invoice. The invoice will be generated against all subscriptions included in this order.
type: boolean
type: object
PaymentData:
properties:
authTransactionId:
description: |
The authorization transaction ID from the payment gateway.
type: string
authorizedAmount:
description: |
The amount that is authorized before this API call. Only used for the Delay Capture function.
format: double
type: number
authorizedCurrency:
description: The authorization of currency code that occurs before this API call. We will verify whether it is same as the account's currency.
type: string
type: object
SubscriptionData:
properties:
customFields:
$ref: '#/components/schemas/CustomFields'
invoiceSeparately:
description: |
Specifies whether the subscription appears on a separate invoice when Zuora generates invoices.
type: boolean
notes:
description: |
Notes about the subscription. These notes are only visible to Zuora users.
maxLength: 500
type: string
ratePlans:
$ref: '#/components/schemas/RatePlans'
startDate:
format: date
type: string
subscriptionNumber:
description: |
Subscription number of the subscription to create, for example, A-S00000001.
If you do not set this field, Zuora will generate a subscription number.
maxLength: 100
type: string
terms:
$ref: '#/components/schemas/TermInfo'
type: object
RatePlans:
items:
$ref: '#/components/schemas/RatePlan'
type: array
TermInfo:
description: |
Container for the terms and renewal settings of the subscription.
properties:
autoRenew:
description: |
Specifies whether the subscription automatically renews at the end of the each term. Only applicable if the type of the first term is `TERMED`.
type: boolean
initialTerm:
$ref: '#/components/schemas/TermInfo_initialTerm'
renewalSetting:
description: |
Specifies the type of the terms that follow the first term if the subscription is renewed. Only applicable if the type of the first term is `TERMED`.
* `RENEW_WITH_SPECIFIC_TERM` - Each renewal term has a predefined duration. The first entry in `renewalTerms` specifies the duration of the second term of the subscription, the second entry in `renewalTerms` specifies the duration of the third term of the subscription, and so on. The last entry in `renewalTerms` specifies the ultimate duration of each renewal term.
* `RENEW_TO_EVERGREEN` - The second term of the subscription does not have a predefined duration.
enum:
- RENEW_WITH_SPECIFIC_TERM
- RENEW_TO_EVERGREEN
type: string
renewalTerms:
$ref: '#/components/schemas/TermInfo_renewalTerms'
required:
- initialTerm
type: object
TermInfo_initialTerm:
description: |
Information about the first term of the subscription.
properties:
period:
description: |
Duration of the first term in months, years, days, or weeks, depending on the value of the `periodType` field. Only applicable if the value of the `termType` field is `TERMED`.
type: integer
periodType:
description: |
Unit of time that the first term is measured in. Only applicable if the value of the `termType` field is `TERMED`.
enum:
- Month
- Year
- Day
- Week
type: string
startDate:
description: |
Start date of the first term, in YYYY-MM-DD format.
format: date
type: string
termType:
description: |
Type of the first term. If the value of this field is `TERMED`, the first term has a predefined duration based on the value of the `period` field. If the value of this field is `EVERGREEN`, the first term does not have a predefined duration.
enum:
- TERMED
- EVERGREEN
type: string
required:
- termType
type: object
TermInfo_renewalTerms:
properties:
period:
description: |
Duration of the renewal term in months, years, days, or weeks, depending on the value of the `periodType` field.
type: integer
periodType:
description: |
Unit of time that the renewal term is measured in.
enum:
- Month
- Year
- Day
- Week
type: string
type: object
RatePlan:
properties:
customFields:
$ref: '#/components/schemas/CustomFields'
productRatePlanId:
description: |
Internal identifier of the product rate plan that the rate plan is based on.
type: string
type: object
ContactInfo:
allOf:
- description: |
Contact details associated with an account.
properties:
address1:
description: |
First line of the contact's address. This is often a street address or a business name.
maxLength: 255
type: string
address2:
description: |
Second line of the contact's address.
maxLength: 255
type: string
city:
description: |
City of the contact's address.
maxLength: 100
type: string
contactDescription:
description: |
A description for the contact.
maxLength: 100
type: string
country:
description: |
Country; must be a valid country name or abbreviation. If using [Zuora Tax](https://knowledgecenter.zuora.com/Zuora_Billing/Taxes/A_Zuora_Tax), you must specify a country in the bill-to contact to calculate tax.
maxLength: 64
type: string
county:
description: |
County of the contact's address.
maxLength: 100
type: string
customFields:
$ref: '#/components/schemas/CustomFields'
fax:
description: |
Fax number of the contact.
maxLength: 40
type: string
firstName:
description: |
First name of the contact.
maxLength: 100
type: string
homePhone:
description: |
Home phone number of the contact.
maxLength: 40
type: string
lastName:
description: ''
maxLength: 100
type: string
mobilePhone:
description: |
Mobile phone number of the contact.
maxLength: 40
type: string
nickname:
description: |
Nickname of the contact.
maxLength: 100
type: string
otherPhone:
description: |
Additional phone number of the contact. Use the `otherPhoneType` field to specify the type of phone number.
maxLength: 40
type: string
otherPhoneType:
description: |
Specifies the type of phone number in the `otherPhone` field.
enum:
- Work
- Mobile
- Home
- Other
type: string
personalEmail:
description: |
Personal email address of the contact.
format: email
maxLength: 80
type: string
postalCode:
description: |
ZIP code or other postal code of the contact's address.
maxLength: 20
type: string
state:
description: |
State or province of the contact's address.
maxLength: 100
type: string
taxRegion:
description: |
Region defined in your taxation rules. Only applicable if you use Zuora Tax.
maxLength: 100
type: string
workEmail:
description: |
Business email address of the contact.
format: email
maxLength: 80
type: string
workPhone:
description: |
Business phone number of the contact.
maxLength: 40
type: string
required:
- firstName
- lastName
type: object
- {}
SignUpPaymentMethod:
allOf:
- properties:
type:
description: |
Type of payment method. The following types of the payment method are supported:
enum:
- PayPalEC
- PayPalNativeEC
- PayPalAdaptive
- CreditCard
- CreditCardReferenceTransaction
type: string
required:
- type
type: object
- $ref: '#/components/schemas/SignUpCreatePaymentMethodCreditCardReferenceTransaction'
- $ref: '#/components/schemas/SignUpCreatePMPayPalECPayPalNativeEC'
- $ref: '#/components/schemas/SignUpCreatePaymentMethodPayPalAdaptive'
- $ref: '#/components/schemas/SignUpCreatePaymentMethodCreditCard'
- $ref: '#/components/schemas/SignUpCreatePaymentMethodCommon'
- $ref: '#/components/schemas/SignUpPaymentMethodObjectCustomFields'
SignUpTaxInfo:
description: |
Information about the tax exempt status of a customer account.
properties:
VATId:
description: |
EU Value Added Tax ID.
**Note:** This feature is in Limited Availability. If you wish to have access to the feature, submit a request at [Zuora Global Support](https://support.zuora.com).
maxLength: 25
type: string
companyCode:
description: |
Unique code that identifies a company account in Avalara. Use this field to calculate taxes based on origin and sold-to addresses in Avalara.
**Note:** This feature is in Limited Availability. If you wish to have access to the feature, submit a request at [Zuora Global Support](https://support.zuora.com).
maxLength: 50
type: string
exemptCertificateId:
description: |
ID of the customer tax exemption certificate. Applicable if you use Zuora Tax or Connect tax engines.
maxLength: 32
type: string
exemptCertificateType:
description: |
Type of tax exemption certificate that the customer holds. Applicable if you use Zuora Tax or Connect tax engines.
maxLength: 32
type: string
exemptDescription:
description: |
Description of the tax exemption certificate that the customer holds. Applicable if you use Zuora Tax or Connect tax engines.
maxLength: 500
type: string
exemptEffectiveDate:
description: |
Date when the customer tax exemption starts, in YYYY-MM-DD format. Applicable if you use Zuora Tax or Connect tax engines.
format: date
type: string
exemptExpirationDate:
description: |
Date when the customer tax exemption expires, in YYYY-MM-DD format. Applicable if you use Zuora Tax or Connect tax engines.
format: date
type: string
exemptIssuingJurisdiction:
description: |
Jurisdiction in which the customer tax exemption certificate was issued.
maxLength: 32
type: string
exemptStatus:
default: 'No'
description: |
Status of the account tax exemption. Applicable if you use Zuora Tax or Connect tax engines. Required if you use Zuora Tax.
enum:
- 'No'
- 'Yes'
- PendingVerification
type: string
title: taxInfo
type: object
SignUpCreatePaymentMethodCreditCardReferenceTransaction:
properties:
secondTokenId:
description: |
The second token id of CreditCardReferenceTransaction.
type: string
tokenId:
description: |
The token id of payment method, required field of CreditCardReferenceTransaction type.
type: string
type: object
SignUpCreatePMPayPalECPayPalNativeEC:
properties:
BAID:
description: |
ID of a PayPal billing agreement, for example, I-1TJ3GAGG82Y9.
type: string
email:
description: |
Email address associated with the payment method. This field is only supported for PayPal payment methods and is required if you want to create any of the following PayPal payment methods:
- PayPal Express Checkout payment method
- PayPal Adaptive payment method
- PayPal Commerce Platform payment method
type: string
type: object
SignUpCreatePaymentMethodPayPalAdaptive:
properties:
preapprovalKey:
description: |
The PayPal preapproval key.
type: string
type: object
SignUpCreatePaymentMethodCreditCard:
properties:
cardHolderInfo:
$ref: '#/components/schemas/SignUpCreatePaymentMethodCardholderInfo'
cardNumber:
description: |
Credit card number.
type: string
cardType:
description: |
The type of the credit card.
Possible values include `Visa`, `MasterCard`, `AmericanExpress`, `Discover`, `JCB`, and `Diners`. For more information about credit card types supported by different payment gateways, see [Supported Payment Gateways](https://knowledgecenter.zuora.com/CB_Billing/M_Payment_Gateways/Supported_Payment_Gateways).
type: string
checkDuplicated:
type: boolean
expirationMonth:
description: |
One or two digit expiration month (1-12) of the credit card.
type: string
expirationYear:
description: |
Four-digit expiration year of the credit card.
type: string
mitConsentAgreementRef:
description: |
Specifies your reference for the stored credential consent agreement that you have established with the customer. Only applicable if you set the `mitProfileAction` field.
maxLength: 128
type: string
mitConsentAgreementSrc:
description: |
Required if you set the `mitProfileAction` field. Specifies how the consent agreement has been established with the customer. The allowed value is `External`. If you do not specify the `mitProfileAction` field, Zuora will automatically create a stored credential profile for the payment method, with the default value `External` set to this field.
enum:
- External
type: string
mitNetworkTransactionId:
description: |
Specifies the ID of a network transaction. Only applicable if you set the `mitProfileAction` field to `Persist`.
maxLength: 128
type: string
mitProfileAction:
description: |
Specifies how Zuora creates and activates the stored credential profile. If you do not specify this field, Zuora will automatically create a stored credential profile for the payment method, with the default value `Activate` set to this field.
enum:
- Activate
- Persist
type: string
mitProfileAgreedOn:
description: |
The date on which the profile is agreed. The date format is `yyyy-mm-dd`.
format: date
type: string
mitProfileType:
description: |
Required if you set the `mitProfileAction` field. If you do not specify the `mitProfileAction` field, Zuora will automatically create a stored credential profile for the payment method, with the default value `Recurring` set to this field.
enum:
- Recurring
type: string
securityCode:
description: |
CVV or CVV2 security code of the credit card.
To ensure PCI compliance, this value is not stored and cannot be queried.
type: string
type: object
SignUpCreatePaymentMethodCommon:
properties:
accountKey:
description: |
Internal ID of the customer account that will own the payment method.
type: string
authGateway:
description: |
Internal ID of the payment gateway that Zuora will use to authorize the payments that are made with the payment method.
If you do not set this field, Zuora will use one of the following payment gateways instead:
* The default payment gateway of the customer account that owns the payment method, if the `accountKey` field is set.
* The default payment gateway of your Zuora tenant, if the `accountKey` field is not set.
type: string
ipAddress:
description: |
The IPv4 or IPv6 information of the user when the payment method is created or updated. Some gateways use this field for fraud prevention. If this field is passed to Zuora, Zuora directly passes it to gateways.
If the IP address length is beyond 45 characters, a validation error occurs.
type: string
makeDefault:
default: false
description: |
Specifies whether the payment method will be the default payment method of the customer account that owns the payment method. Only applicable if the `accountKey` field is set.
type: boolean
type: object
SignUpPaymentMethodObjectCustomFields:
additionalProperties:
description: |
Custom fields of the payment method. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
description: |
Container for custom fields of a payment method object.
title: paymentMethodFieldsCustom
type: object
SignUpCreatePaymentMethodCardholderInfo:
description: |
Container for cardholder information. If provided, Zuora will
only use this information for this card. Otherwise, Zuora will use
the account''s existing bill-to contact information for this card.
properties:
addressLine1:
description: |
First address line, 255 characters or less.
type: string
addressLine2:
description: |
Second address line, 255 characters or less.
type: string
cardHolderName:
description: |
The card holder's full name as it appears on the card, e.g., "John J Smith", 50 characters or less.
type: string
city:
description: |
City, 40 characters or less.
type: string
country:
description: |
Country, must be a valid country name or abbreviation.
type: string
email:
description: |
Card holder's email address, 80 characters or less.
type: string
phone:
description: |
Phone number, 40 characters or less.
type: string
state:
description: |
State; must be a valid subregion (state or province) name or code. For more information, see View subregions of a specific country or region.
type: string
zipCode:
description: |
Zip code, 20 characters or less.
type: string
required:
- cardHolderName
title: cardHolderInfo
type: object
POSTOrderPreviewRequestType:
example:
existingAccountNumber: A00000097
orderDate: '2024-07-01'
previewOptions:
previewTypes:
- BillingDocs
previewThruType: SpecificDate
specificPreviewThruDate: '2024-07-31'
subscriptions:
- orderActions:
- type: CreateSubscription
createSubscription:
terms:
initialTerm:
period: 12
periodType: Month
termType: TERMED
renewalSetting: RENEW_WITH_SPECIFIC_TERM
renewalTerms:
period: 12
periodType: Month
subscribeToRatePlans:
- productRatePlanId: 8ad081dd9096ef9501909b40bb4e74a4
triggerDates:
- name: ContractEffective
triggerDate: '2024-07-01'
- name: ServiceActivation
triggerDate: '2024-07-01'
- name: CustomerAcceptance
triggerDate: '2024-07-01'
properties:
category:
default: NewSales
description: |
Category of the order to indicate a product sale or return. Default value is `NewSales`.
enum:
- NewSales
- Return
type: string
customFields:
$ref: '#/components/schemas/OrderObjectCustomFields'
description:
description: A description of the order.
maxLength: 500
type: string
existingAccountId:
description: |
The account ID under which this order will be created. This field sets the default invoice owner account and subscription owner account for any new subscriptions in the order. To override these defaults for individual subscriptions, use the `subscriptionOwnerAccountNumber` and `invoiceOwnerAccountNumber` nested fields in the `subscriptions` field.
**Note:** You can specify either the `existingAccountNumber` or `existingAccountId` field, but not both.
type: string
existingAccountNumber:
description: |
The account number under which this order will be created. This field sets the default invoice owner account and subscription owner account for any new subscriptions in the order. To override these defaults for individual subscriptions, use the `subscriptionOwnerAccountNumber` and `invoiceOwnerAccountNumber` nested fields in the `subscriptions` field.
maxLength: 70
type: string
orderDate:
description: The date when the order is signed. All of the order actions under this order will use this order date as the contract effective date.
format: date
type: string
orderLineItems:
description: |
[Order Line Items](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Order_Line_Items/AA_Overview_of_Order_Line_Items) are non subscription based items created by an Order, representing transactional charges such as one-time fees, physical goods, or professional service charges that are not sold as subscription services.
With the Order Line Items feature enabled, you can now launch non-subscription and unified monetization business models in Zuora, in addition to subscription business models.
If you do not have the **Create Order Line Items Without Product Catalog** billing permission, you can only create order line items from existing products by specifying the product rate plan charge ID in the `productRatePlanChargeId` field. For more information about billing permissions, see Billing Roles.
**Note:** The [Order Line Items](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Order_Line_Items/AA_Overview_of_Order_Line_Items) feature is now generally available to all Zuora customers. You need to enable the [Orders](https://knowledgecenter.zuora.com/BC_Subscription_Management/Orders/AA_Overview_of_Orders#Orders) feature to access the [Order Line Items](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Order_Line_Items/AA_Overview_of_Order_Line_Items) feature. As of Zuora Billing Release 313 (November 2021), new customers who onboard on [Orders](https://docs.zuora.com/en/zuora-billing/manage-accounts-subscriptions-and-non-subscriptions/manage-subscription-transactions/orders/orders-introduction/overview-of-orders) will have the [Order Line Items](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Order_Line_Items) feature enabled by default.
items:
$ref: '#/components/schemas/CreateOrderOrderLineItem'
type: array
orderNumber:
description: |
The order number of this order.
**Note:** The characters `#`, `?`, and `/` are not allowed in this field. Additionally, to ensure compatibility with the UI when viewing orders, use only the following special characters: `_`,`-`, `.`, `~`, `*`, `(`, `)`, and `'`.
maxLength: 100
type: string
previewAccountInfo:
$ref: '#/components/schemas/PreviewAccountInfo'
previewOptions:
$ref: '#/components/schemas/PreviewOptions'
reasonCode:
description: |
Values of reason code configured in **Billing Settings** > **Configure Reason Codes** through Zuora UI. Indicates the reason when a return order line item occurs.
maxLength: 255
type: string
subscriptions:
description: 'Each item includes a set of order actions, which will be applied to the same base subscription. When you create an order that involves multiple subscriptions, these subscriptions can have different invoice owner accounts or subscription owner accounts. '
items:
properties:
customFields:
$ref: '#/components/schemas/SubscriptionObjectCustomFields'
notes:
description: |
Notes about the subscription. These notes are only visible to Zuora users. Notes set in this field will override the value of the `notes` field within the createSubscription order action.
type: string
maxLength: 1000
orderActions:
description: The actions to be applied to the subscription. Order actions will be stored with the sequence when it was provided in the request.
items:
$ref: '#/components/schemas/PreviewOrderOrderAction'
type: array
quote:
$ref: '#/components/schemas/QuoteObjectFields'
ramp:
$ref: '#/components/schemas/RampRequest'
subscriptionNumber:
description: |
Leave this field empty to represent new subscription creation, or specify a subscription number to update an existing subscription.
type: string
type: object
type: array
required:
- orderDate
- previewOptions
type: object
PostOrderPreviewResponseType:
allOf:
- $ref: '#/components/schemas/CommonResponse'
- properties:
previewResult:
$ref: '#/components/schemas/PreviewOrderResult'
type: object
PreviewOrderResult:
description: The result of each type of preview. Returned only when the current request is preview call.
properties:
chargeMetrics:
items:
properties:
charges:
items:
$ref: '#/components/schemas/ChargePreviewMetrics'
type: array
subscriptionNumber:
description: The number of the subscription that has been affected by this order. When creating a subscription, this value will not show if the subscription number was not specified in the request.
type: string
type: object
type: array
creditMemos:
description: This field is only available if you have the Invoice Settlement feature enabled.
items:
properties:
amount:
type: number
amountWithoutTax:
type: number
creditMemoItems:
items:
$ref: '#/components/schemas/InvoiceItemPreviewResult'
type: array
targetDate:
format: date
type: string
taxAmount:
type: number
type: object
type: array
invoices:
items:
properties:
amount:
type: number
description: |
The total amount of the invoice.
amountWithoutTax:
type: number
description: |
The amount of the invoice without tax.
invoiceItems:
description: |
The invoice items on the invoice.
items:
$ref: '#/components/schemas/InvoiceItemPreviewResult'
type: array
targetDate:
format: date
type: string
description: |
The target date to bill the invoice.
taxAmount:
type: number
description: |
The total tax amount of the invoice.
invoiceItemSummary:
type: array
description: |
The aggregated summary data for all future invoices to be billed within the preview period.
This field is returned only if you set the `summarizeInvoiceItem` query parameter to `true`.
items:
$ref: '#/components/schemas/InvoiceItemSummary'
type: object
type: array
orderDeltaMetrics:
description: |
**Note:** As of Zuora Billing Release 306, Zuora has upgraded the methodologies for calculating metrics in [Orders](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders). The new methodologies are reflected in the following Order Delta Metrics objects.
* [Order Delta Mrr](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Order_Delta_Metrics/Order_Delta_Mrr)
* [Order Delta Tcv](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Order_Delta_Metrics/Order_Delta_Tcv)
* [Order Delta Tcb](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Order_Delta_Metrics/Order_Delta_Tcb)
It is recommended that all customers use the new [Order Delta Metrics](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Order_Delta_Metrics/AA_Overview_of_Order_Delta_Metrics). If you are an existing [Order Metrics](https://docs.zuora.com/en/zuora-billing/manage-accounts-subscriptions-and-non-subscriptions/manage-subscription-transactions/orders/orders-introduction/overview-of-orders/Key_Metrics_for_Orders) customer and want to migrate to Order Delta Metrics, submit a request at [Zuora Global Support](https://support.zuora.com/).
properties:
orderDeltaMrr:
items:
$ref: '#/components/schemas/OrderDeltaMrr'
type: array
orderDeltaTcb:
items:
$ref: '#/components/schemas/OrderDeltaTcb'
type: array
orderDeltaTcv:
items:
$ref: '#/components/schemas/OrderDeltaTcv'
type: array
type: object
orderMetrics:
description: |
**Note:** As of Zuora Billing Release 306, Zuora has upgraded the methodologies for calculating metrics in [Orders](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders). The new methodologies are reflected in the following Order Delta Metrics objects.
* [Order Delta Mrr](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Order_Delta_Metrics/Order_Delta_Mrr)
* [Order Delta Tcv](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Order_Delta_Metrics/Order_Delta_Tcv)
* [Order Delta Tcb](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Order_Delta_Metrics/Order_Delta_Tcb)
It is recommended that all customers use the new [Order Delta Metrics](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Order_Delta_Metrics/AA_Overview_of_Order_Delta_Metrics). If you are an existing [Order Metrics](https://docs.zuora.com/en/zuora-billing/manage-accounts-subscriptions-and-non-subscriptions/manage-subscription-transactions/orders/orders-introduction/overview-of-orders/Key_Metrics_for_Orders) customer and want to migrate to Order Delta Metrics, submit a request at [Zuora Global Support](https://support.zuora.com/).
Whereas new customers, and existing customers not currently on [Order Metrics](https://docs.zuora.com/en/zuora-billing/manage-accounts-subscriptions-and-non-subscriptions/manage-subscription-transactions/orders/orders-introduction/overview-of-orders/Key_Metrics_for_Orders), will no longer have access to Order Metrics, existing customers currently using Order Metrics will continue to be supported.
items:
properties:
orderActions:
items:
properties:
orderItems:
description: |
The `orderItems` nested field is only available to existing Orders customers who already have access to the field.
**Note:** The following objects and fields of the Order Metrics are end of support. Any new customers who onboard on [Orders](https://docs.zuora.com/en/zuora-billing/manage-accounts-subscriptions-and-non-subscriptions/manage-subscription-transactions/orders/orders-introduction/overview-of-orders) or [Orders Harmonization](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Orders_Harmonization/Orders_Harmonization) will not get these metrics.
* The Order ELP and Order Item objects
* The "Generated Reason" and "Order Item ID" fields in the Order MRR, Order TCB, Order TCV, and Order Quantity objects
Zuora no longer provides product support, and bug fixes or security issues are no longer addressed.
items:
$ref: '#/components/schemas/OrderItem'
type: array
orderMetrics:
description: |
The container for order metrics.
**Note:** The following objects and fields of the Order Metrics are end of support. Any new customers who onboard on [Orders](https://docs.zuora.com/en/zuora-billing/manage-accounts-subscriptions-and-non-subscriptions/manage-subscription-transactions/orders/orders-introduction/overview-of-orders) or [Orders Harmonization](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Orders_Harmonization/Orders_Harmonization) will not get these metrics.
* The Order ELP and Order Item objects
* The "Generated Reason" and "Order Item ID" fields in the Order MRR, Order TCB, Order TCV, and Order Quantity objects
Zuora no longer provides product support, and bug fixes or security issues are no longer addressed.
items:
$ref: '#/components/schemas/orderMetric'
type: array
sequence:
type: string
type:
type: string
type: object
type: array
subscriptionNumber:
type: string
type: object
type: array
rampMetrics:
description: |
**Note**: This field is only available if you have the Ramps feature enabled. The [Orders](https://docs.zuora.com/en/zuora-billing/manage-accounts-subscriptions-and-non-subscriptions/manage-subscription-transactions/orders/orders-introduction/overview-of-orders) feature must be enabled before you can access the [Ramps](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Ramps_and_Ramp_Metrics/A_Overview_of_Ramps_and_Ramp_Metrics) feature. The Ramps feature is available for customers with Enterprise and Nine editions by default. If you are a Growth customer, see [Zuora Editions](https://docs.zuora.com/en/entitlements/current-entitlements/zuora-editions) for pricing information coming October 2020.
The ramp metrics.
items:
$ref: '#/components/schemas/OrderRampMetrics'
type: array
type: object
ChargePreviewMetrics:
properties:
chargeNumber:
type: string
cmrr:
properties:
discount:
description: Total discountCmrr of all discount charges which are applied to one specific recurring charge. This value is calculated from the rating results for the latest subscription version in the order. Only selects the applied discount charge when its endDateCondition is "Subscription_End".
type: number
discountDelta:
description: Delta discountCmrr value between the order base and the latest subscription version.
type: number
regular:
type: number
regularDelta:
type: number
type: object
originRatePlanId:
type: string
productRatePlanChargeId:
type: string
productRatePlanId:
type: string
subscriptionRatePlanNumber:
type: string
description: |
Number of a subscription rate plan for this subscription.
tax:
properties:
discount:
description: Total tax amount of all discount charges which are applied to one specific recurring charge. This value is calculated from the rating results for the latest subscription version in the order.
type: number
discountDelta:
description: Delta discount TAX value between the base and the latest subscription version in the order for the specific recurring charge.
type: number
regular:
type: number
regularDelta:
description: Delta tax value between the base and the latest subscription version in the order.
type: number
type: object
tcb:
properties:
discount:
description: Total contract billing amount of all discount charges which are applied to one specific recurring charge. This value is calculated from the rating results for the latest subscription version in the order.
type: number
discountDelta:
description: Delta discount TCB value between the base and the latest subscription version for specific recurring charge in the order.
type: number
regular:
type: number
regularDelta:
description: Delta TCB value between the base and the latest subscription version in the order.
type: number
type: object
tcv:
properties:
discount:
description: Always equals to discountTcb.
type: number
discountDelta:
description: Always equals to delta discountTcb.
type: number
regular:
type: number
regularDelta:
type: number
type: object
type: object
InvoiceItemPreviewResult:
properties:
additionalInfo:
properties:
numberOfDeliveries:
description: |
The number of deliveries dedicated to the Delivery Pricing charges.
**Note**: This field is available only if you have the Delivery Pricing feature enabled.
type: number
quantity:
type: number
unitOfMeasure:
type: string
type: object
amountWithoutTax:
type: number
appliedToChargeNumber:
description: Available when the chargeNumber of the charge that discount applies to was specified in the request or when the order is amending an existing subscription.
type: string
chargeDescription:
type: string
chargeName:
type: string
chargeNumber:
description: Available when the `chargeNumber` field was specified in the request or when the order is amending an existing subscription.
type: string
nullable: true
orderLineItemNumber:
description: A sequential number auto-assigned for each of order line items in a order, used as an index, for example, "1".
type: string
nullable: true
processingType:
enum:
- Charge
- Discount
- Tax
type: string
productName:
type: string
productRatePlanChargeId:
type: string
description: |
The product rate plan charge ID in this `productRatePlanChargeId` field belongs to a product rate plan specified through the `subscribeToRatePlans` > `productRatePlanId` field.
Therefore, this `productRatePlanChargeId` field has a value only when the `subscribeToRatePlans` > `productRatePlanId` field is specified during the subscription creation.
This `productRatePlanChargeId` field does not indicate a product rate plan charge associated with an order line item.
serviceEndDate:
format: date
type: string
serviceStartDate:
format: date
type: string
subscriptionNumber:
type: string
nullable: true
description: |
The number of the subscription.
taxAmount:
type: number
taxationItems:
description: |
List of taxation items.
**Note**: This field is available only if you are on the latest Zuora API minor version, or you set the `Zuora-Version` request header to `309.0` or [a later available version](https://developer.zuora.com/v1-api-reference/api-versions/#minor-version).
items:
properties:
exemptAmount:
description: |
The calculated tax amount excluded due to the exemption.
type: number
id:
description: |
The ID of the taxation item.
type: string
jurisdiction:
description: |
The jurisdiction that applies the tax or VAT. This value is typically a state, province, county, or city.
type: string
locationCode:
description: |
The identifier for the location based on the value of the taxCode field.
type: string
name:
description: |
The name of the taxation item.
type: string
taxAmount:
description: |
The amount of the tax applied to the invoice.
type: number
taxCode:
description: |
The tax code identifies which tax rules and tax rates to apply to a specific invoice.
type: string
taxCodeDescription:
description: |
The description of the tax code.
type: string
taxDate:
description: |
The date when the tax is applied to the invoice.
type: string
taxRate:
description: |
The tax rate applied to the invoice.
type: number
taxRateDescription:
description: |
The description of the tax rate.
type: string
taxRateType:
description: |
Enum:"Percentage" "FlatFee". The type of the tax rate applied to the invoice.
enum:
- Percentage
- FlatFee
type: string
type: object
type: array
unitPrice:
description: |
The per-unit price of the invoice item.
type: number
type: object
InvoiceItemSummary:
type: object
properties:
previewInvoiceSequence:
type: number
description: |
The sequence number of the invoice to be billed.
subTotal:
type: number
format: double
description: |
The aggregated subtotal amount of the invoice.
discountAmount:
type: number
format: double
description: |
The aggregated discount amount of the invoice.
taxAmount:
type: number
format: double
description: |
The aggregated tax amount of the invoice.
total:
type: number
format: double
description: |
The aggregated total amount of the invoice.
servicePeriodStartDate:
type: string
format: date
description: |
The start date of the period being billed.
servicePeriodEndDate:
type: string
format: date
description: |
The end date of the period being billed.
OrderDeltaMrr:
allOf:
- $ref: '#/components/schemas/OrderDeltaMetric'
description: |
Order Delta Mrr. This is a metric that reflects the change to the TCV on rate plan charge object as the result of the order.
type: object
OrderDeltaTcb:
allOf:
- $ref: '#/components/schemas/OrderDeltaMetric'
- properties:
orderLineItemId:
description: |
The sytem generated Id for the Order Line Item. This field can be null if the metric is generated for a Rate Plan Charge.
format: UUID
type: string
type: object
description: |
Order Delta Tcb. This is a metric that reflects the change to the estimated billing on Rate Plan Charge object, or the estimated billing for an Order Line Item as the result of the order
type: object
OrderDeltaTcv:
allOf:
- $ref: '#/components/schemas/OrderDeltaMetric'
- properties:
orderLineItemId:
description: |
The sytem generated Id for the Order Line Item. This field can be null if the metric is generated for subscriptions.
format: UUID
type: string
type: object
description: |
Order Delta Tcv. This is a metric that reflects the change to the TCV on Rate Plan Charge object, or the Total Contracted Value for an Order Line Item as the result of the order
type: object
OrderItem:
description: "Represents an order item. An order item is a sales item within an order in the context of the recurring subscription business model. It can be a unit of products or a service, but defined by both quantity and term (the start and end dates).\_\n\nFor the one time and the recurring charge types, if an order action causes a quantity metric creation (when the delta quantity equals to or is greater than zero), an order item is created.\n\nThe following order actions will create an order item for the one time and recurring charges. The other order actions will refer to an existing order item. Also, the Owner Transfer order action always creates an order item whose quantity field is zero.\n\n * Create Subscription\n * Terms and Conditions - Extend Term\n * Renewal\n * Update Product - Increase Quantity\n * Add product\n * Owner Transfer\n\nFor the usage charge type, if the order action causes a usage increase, an order item is created, and the quantity field of the order item is always zero.\n\nThe following order actions will create an order item for for the usage charges.\n\n * Create Subscription\n * Terms and Conditions - Extend Term\n * Renewal\n * Add product\n * Owner Transfer\n"
properties:
endDate:
description: The order item's effective end date, aligned with the end date of an increased quantity order metrics.
format: date
type: string
id:
description: The ID of the order item.
type: string
orderActionId:
description: Specify the order action that creates this order item.
type: string
quantity:
description: The order item quantity. For the usage charge type, the value of this field is always zero. Also, the Owner Transfer order action always creates an order item whose Quantity field is zero.
type: number
scId:
description: The ID of the charge segment that gets newly generated when the order item is created.
type: string
startDate:
description: The order item's effective start date, aligned with the start date of an increased quantity order metrics.
format: date
type: string
type: object
orderMetric:
description: The set of order metrics for an order action.
properties:
chargeNumber:
type: string
elp:
description: |
The extended list price which is calculated by the original product catalog list price multiplied by the delta quantity.
The `elp` nested field is only available to existing Orders customers who already have access to the field.
**Note:** The following objects and fields of the Order Metrics are end of support. Any new customers who onboard on [Orders](https://docs.zuora.com/en/zuora-billing/manage-accounts-subscriptions-and-non-subscriptions/manage-subscription-transactions/orders/orders-introduction/overview-of-orders) or [Orders Harmonization](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Orders_Harmonization/Orders_Harmonization) will not get these metrics.
* The Order ELP and Order Item objects
* The "Generated Reason" and "Order Item ID" fields in the Order MRR, Order TCB, Order TCV, and Order Quantity objects
Zuora no longer provides product support, and bug fixes or security issues are no longer addressed.
items:
$ref: '#/components/schemas/TimeSlicedElpNetMetrics'
type: array
mrr:
items:
$ref: '#/components/schemas/TimeSlicedNetMetrics'
type: array
originRatePlanId:
type: string
productRatePlanChargeId:
type: string
productRatePlanId:
type: string
subscriptionRatePlanNumber:
type: string
description: |
Number of a subscription rate plan for this subscription.
quantity:
items:
$ref: '#/components/schemas/TimeSlicedMetrics'
type: array
tcb:
description: Total contracted billing which is the forecast value for the total invoice amount.
items:
$ref: '#/components/schemas/TimeSlicedTcbNetMetrics'
type: array
tcv:
description: Total contracted value.
items:
$ref: '#/components/schemas/TimeSlicedNetMetrics'
type: array
type: object
OrderRampMetrics:
properties:
description:
description: The short description of the ramp.
type: string
discountTcb:
description: The discount amount for the TCB.
type: number
discountTcv:
description: The discount amount for the TCV.
type: number
grossTcb:
description: The gross TCB value before discount charges are applied.
type: number
grossTcv:
description: The gross TCV value before discount charges are applied.
type: number
intervals:
description: The ramp metrics for each ramp intervals in its timeline.
items:
$ref: '#/components/schemas/OrderRampIntervalMetrics'
type: array
name:
description: The name of the ramp.
type: string
netTcb:
description: The net TCB value after discount charges are applied.
type: number
netTcv:
description: The net TCV value after discount charges are applied.
type: number
number:
description: The number of the ramp. It is automaticcally generated by the billing system.
type: string
title: RampMetrics
type: object
OrderRampIntervalMetrics:
properties:
description:
description: The short description of the interval.
type: string
discountTcb:
description: The discount amount for the TCB.
type: number
discountTcv:
description: The discount amount for the TCV.
type: number
endDate:
description: The end date of the interval.
format: date
type: string
grossTcb:
description: The gross TCB value before discount charges are applied.
type: number
grossTcv:
description: The gross TCV value before discount charges are applied.
type: number
intervalDeltaMetrics:
description: Container for the delta metrics for each rate plan charge in each ramp interval. The delta is the difference of the subscription metrics between before and after the order.
items:
$ref: '#/components/schemas/RampIntervalChargeDeltaMetrics'
type: array
intervalMetrics:
description: Container for the detailed metrics for each rate plan charge in each ramp interval.
items:
$ref: '#/components/schemas/RampIntervalChargeMetrics'
type: array
name:
description: The name of the interval.
type: string
netTcb:
description: The net TCB value after discount charges are applied.
type: number
netTcv:
description: The net TCV value after discount charges are applied.
type: number
startDate:
description: The start date of the interval.
format: date
type: string
title: RampIntervalMetrics
type: object
RampIntervalChargeDeltaMetrics:
properties:
chargeNumber:
description: The number of the rate plan charge.
type: string
deltaDiscountTcb:
description: The discount delta amount for the TCB.
type: number
deltaDiscountTcv:
description: The discount delta amount for the TCV.
type: number
deltaGrossTcb:
description: The TCB delta value before discount charges are applied.
type: number
deltaGrossTcv:
description: The TCV delta value before discount charges are applied.
type: number
deltaMrr:
description: The MRR changing history of the current rate plan charge in the current ramp interval.
items:
properties:
discount:
description: The discount delta amount for the MRR.
type: number
endDate:
description: The end date.
format: date
type: string
gross:
description: The MRR delta amount before discounts charges are applied.
type: number
net:
description: The MRR delta amount after discounts charges are applied.
type: number
startDate:
description: The start date.
format: date
type: string
type: object
type: array
deltaNetTcb:
description: The TCB delta value after discount charges are applied.
type: number
deltaNetTcv:
description: The TCV delta value after discount charges are applied.
type: number
deltaQuantity:
description: The charge quantity changing history of the current rate plan charge in the current ramp interval.
items:
properties:
amount:
description: The delta amount of the charge quantity.
type: number
endDate:
description: The end date.
format: date
type: string
startDate:
description: The start date.
format: date
type: string
type: object
type: array
productRatePlanChargeId:
description: The ID of the corresponding product rate plan charge.
type: string
subscriptionNumber:
description: The number of the subscription that the current rate plan charge belongs to.
type: string
title: intervalDeltaMetrics
type: object
RampIntervalChargeMetrics:
properties:
chargeNumber:
description: The number of the charge.
type: string
discountTcb:
description: The discount amount for the TCB.
type: number
discountTcv:
description: The discount amount for the TCV.
type: number
endDate:
description: The end date of the rate plan charge in the current ramp interval.
format: date
type: string
grossTcb:
description: The gross TCB value before discount charges are applied.
type: number
grossTcv:
description: The gross TCV value before discount charges are applied.
type: number
mrr:
description: The MRR changing history of the current rate plan charge in the current ramp interval.
items:
properties:
discount:
description: The discount amount for the MRR.
type: number
endDate:
description: The end date.
format: date
type: string
gross:
description: The gross MRR amount before discounts charges are applied.
type: number
net:
description: The net MRR amount after discounts charges are applied.
type: number
startDate:
description: The start date.
format: date
type: string
type: object
type: array
netTcb:
description: The net TCB value after discount charges are applied.
type: number
netTcv:
description: The net TCV value after discount charges are applied.
type: number
productRatePlanChargeId:
description: The ID of the corresponding product rate plan charge.
type: string
quantity:
description: The quantity of the rate plan charge.
type: number
ratePlanChargeId:
description: The ID of the rate plan charge.
type: string
startDate:
description: The start date of the rate plan charge in the current ramp interval.
format: date
type: string
subscriptionNumber:
description: The number of the subscription that the current rate plan charge belongs to.
type: string
title: intervalMetrics
type: object
TimeSlicedElpNetMetrics:
properties:
amount:
description: The extended list price which is calculated by the original product catalog list price multiplied by the delta quantity.
type: number
endDate:
description: The latest date that the metric applies.
format: date
type: string
generatedReason:
description: |
Specify the reason why the metrics are generated by the certain order action.
enum:
- IncreaseQuantity
- DecreaseQuantity
- ChangePrice
- Extension
- Contraction
type: string
invoiceOwner:
description: The acount number of the billing account that is billed for the subscription.
type: string
orderItemId:
description: The ID of the order item referenced by the order metrics.
type: string
startDate:
description: The earliest date that the metric applies.
format: date
type: string
subscriptionOwner:
description: The acount number of the billing account that owns the subscription.
type: string
tax:
description: The tax amount in the metric when the tax permission is enabled.
type: number
termNumber:
format: long
type: number
type:
description: The type for ELP is always "Regular".
enum:
- Regular
- Discount
type: string
type: object
TimeSlicedNetMetrics:
properties:
amount:
type: number
discountChargeNumber:
type: string
endDate:
format: date
type: string
generatedReason:
description: |
Specify the reason why the metrics are generated by the certain order action.
This field is only available to existing Orders customers who already have access to the field.
**Note:** The following objects and fields of the Order Metrics are end of support. Any new customers who onboard on [Orders](https://docs.zuora.com/en/zuora-billing/manage-accounts-subscriptions-and-non-subscriptions/manage-subscription-transactions/orders/orders-introduction/overview-of-orders) or [Orders Harmonization](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Orders_Harmonization/Orders_Harmonization) will not get these metrics.
* The Order ELP and Order Item objects
* The "Generated Reason" and "Order Item ID" fields in the Order MRR, Order TCB, Order TCV, and Order Quantity objects
Zuora no longer provides product support, and bug fixes or security issues are no longer addressed.
enum:
- IncreaseQuantity
- DecreaseQuantity
- ChangePrice
- Extension
- Contraction
type: string
invoiceOwner:
description: The acount number of the billing account that is billed for the subscription.
type: string
orderItemId:
description: |
The ID of the order item referenced by the order metrics.
This field is only available to existing Orders customers who already have access to the field.
**Note:** The following objects and fields of the Order Metrics are end of support. Any new customers who onboard on [Orders](https://docs.zuora.com/en/zuora-billing/manage-accounts-subscriptions-and-non-subscriptions/manage-subscription-transactions/orders/orders-introduction/overview-of-orders) or [Orders Harmonization](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Orders_Harmonization/Orders_Harmonization) will not get these metrics.
* The Order ELP and Order Item objects
* The "Generated Reason" and "Order Item ID" fields in the Order MRR, Order TCB, Order TCV, and Order Quantity objects
Zuora no longer provides product support, and bug fixes or security issues are no longer addressed.
type: string
startDate:
format: date
type: string
subscriptionOwner:
description: The acount number of the billing account that owns the subscription.
type: string
termNumber:
format: long
type: number
type:
description: Indicates whether this metrics is for a regular charge or a discount charge.
enum:
- Regular
- Discount
type: string
type: object
TimeSlicedMetrics:
properties:
amount:
type: number
endDate:
format: date
type: string
generatedReason:
description: |
Specify the reason why the metrics are generated by the certain order action.
This field is only available to existing Orders customers who already have access to the field.
**Note:** The following objects and fields of the Order Metrics are end of support. Any new customers who onboard on [Orders](https://docs.zuora.com/en/zuora-billing/manage-accounts-subscriptions-and-non-subscriptions/manage-subscription-transactions/orders/orders-introduction/overview-of-orders) or [Orders Harmonization](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Orders_Harmonization/Orders_Harmonization) will not get these metrics.
* The Order ELP and Order Item objects
* The "Generated Reason" and "Order Item ID" fields in the Order MRR, Order TCB, Order TCV, and Order Quantity objects
Zuora no longer provides product support, and bug fixes or security issues are no longer addressed.
enum:
- IncreaseQuantity
- DecreaseQuantity
- ChangePrice
- Extension
- Contraction
type: string
invoiceOwner:
description: The acount number of the billing account that is billed for the subscription.
type: string
orderItemId:
description: |
The ID of the order item referenced by the order metrics.
This field is only available to existing Orders customers who already have access to the field.
**Note:** The following objects and fields of the Order Metrics are end of support. Any new customers who onboard on [Orders](https://docs.zuora.com/en/zuora-billing/manage-accounts-subscriptions-and-non-subscriptions/manage-subscription-transactions/orders/orders-introduction/overview-of-orders) or [Orders Harmonization](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Orders_Harmonization/Orders_Harmonization) will not get these metrics.
* The Order ELP and Order Item objects
* The "Generated Reason" and "Order Item ID" fields in the Order MRR, Order TCB, Order TCV, and Order Quantity objects
Zuora no longer provides product support, and bug fixes or security issues are no longer addressed.
type: string
startDate:
format: date
type: string
subscriptionOwner:
description: The acount number of the billing account that owns the subscription.
type: string
termNumber:
format: long
type: number
type: object
TimeSlicedTcbNetMetrics:
properties:
amount:
type: number
discountChargeNumber:
type: string
endDate:
format: date
type: string
generatedReason:
description: |
Specify the reason why the metrics are generated by the certain order action.
This field is only available to existing Orders customers who already have access to the field.
**Note:** The following objects and fields of the Order Metrics are end of support. Any new customers who onboard on [Orders](https://docs.zuora.com/en/zuora-billing/manage-accounts-subscriptions-and-non-subscriptions/manage-subscription-transactions/orders/orders-introduction/overview-of-orders) or [Orders Harmonization](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Orders_Harmonization/Orders_Harmonization) will not get these metrics.
* The Order ELP and Order Item objects
* The "Generated Reason" and "Order Item ID" fields in the Order MRR, Order TCB, Order TCV, and Order Quantity objects
Zuora no longer provides product support, and bug fixes or security issues are no longer addressed.
enum:
- IncreaseQuantity
- DecreaseQuantity
- ChangePrice
- Extension
- Contraction
type: string
invoiceOwner:
description: The acount number of the billing account that is billed for the subscription.
type: string
orderItemId:
description: |
The ID of the order item referenced by the order metrics.
This field is only available to existing Orders customers who already have access to the field.
**Note:** The following objects and fields of the Order Metrics are end of support. Any new customers who onboard on [Orders](https://docs.zuora.com/en/zuora-billing/manage-accounts-subscriptions-and-non-subscriptions/manage-subscription-transactions/orders/orders-introduction/overview-of-orders) or [Orders Harmonization](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Orders_Harmonization/Orders_Harmonization) will not get these metrics.
* The Order ELP and Order Item objects
* The "Generated Reason" and "Order Item ID" fields in the Order MRR, Order TCB, Order TCV, and Order Quantity objects
Zuora no longer provides product support, and bug fixes or security issues are no longer addressed.
type: string
startDate:
format: date
type: string
subscriptionOwner:
description: The acount number of the billing account that owns the subscription.
type: string
tax:
type: number
termNumber:
format: long
type: number
type:
description: Indicates whether this metrics is for a regular charge or a discount charge.
enum:
- Regular
- Discount
type: string
type: object
OrderDeltaMetric:
properties:
chargeNumber:
description: |
The charge number for the associated Rate Plan Charge. This field can be null if the metric is generated for an Order Line Item.
type: string
currency:
description: |
ISO 3-letter currency code (uppercase). For example, USD.
type: string
endDate:
description: |
The end date for the order delta metric.
format: date
type: string
grossAmount:
description: |
The gross amount for the metric. The is the amount excluding applied discount.
type: number
netAmount:
description: |
The net amount for the metric. The is the amount with discounts applied
type: number
orderActionId:
description: |
The Id for the related Order Action. This field can be null if the metric is generated for an Order Line Item.
type: string
orderActionSequence:
description: |
The sequence for the related Order Action. This field can be null if the metric is generated for an Order Line Item.
type: string
orderActionType:
description: |
The type for the related Order Action. This field can be null if the metric is generated for an Order Line Item.
type: string
orderLineItemNumber:
description: |
A sequential number auto-assigned for each of order line items in a order, used as an index, for example, "1".
type: string
productRatePlanChargeId:
description: |
The Id for the associated Product Rate Plan Charge. This field can be null if the Order Line Item is not associated with a Product Rate Plan Charge.
type: string
ratePlanChargeId:
description: |
The id for the associated Rate Plan Charge. This field can be null if the metric is generated for an Order Line Item.
type: string
startDate:
description: |
The start date for the order delta metric.
format: date
type: string
subscriptionNumber:
description: |
The number of the subscription. This field can be null if the metric is generated for an Order Line Item.
type: string
type: object
OrderObjectCustomFields:
additionalProperties:
description: |
Custom fields of the Order object. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
description: |
Container for custom fields of an Order object.
title: OrderCustomFields
type: object
CreateOrderOrderLineItem:
allOf:
- $ref: '#/components/schemas/OrderLineItemCommonPostOrder'
PreviewAccountInfo:
description: |
Information about the account that will own the order.
properties:
billCycleDay:
description: Day of the month that the account prefers billing periods to begin on. If set to 0, the bill cycle day will be set as "AutoSet".
maximum: 31
minimum: 0
type: integer
currency:
description: |
ISO 3-letter currency code (uppercase). For example, USD.
maxLength: 3
type: string
customFields:
$ref: '#/components/schemas/AccountObjectCustomFields'
shipToContact:
$ref: '#/components/schemas/PreviewContactInfo'
soldToContact:
$ref: '#/components/schemas/PreviewContactInfo'
taxInfo:
$ref: '#/components/schemas/TaxInfo'
required:
- currency
- billCycleDay
title: previewAccountInfo
type: object
PreviewOptions:
properties:
previewNumberOfPeriods:
description: |
The number of periods to preview when the value of the `previewThroughType` field is set to `NumberOfPeriods`.
minLength: 1
type: integer
previewThruType:
description: |
The options on how the preview through date is calculated. Available for preview only.
- If you set this field to `SpecificDate`, you must specify a specific date in the `specificPreviewThruDate` field. If you also set `billTargetDate` in the `orderLineItems` field, order line items whose `billTargetDate` is no later than `specificPreviewThruDate` are returned.
- If you set this field to `NumberOfPeriods`, you must use the `previewNumberOfPeriods` field to specify how many periods you want to preview. In case the order only contains an order line item but not contains a subscription, if you also set `billTargetDate` in the `orderLineItems` field, order line items whose `billTargetDate` is no later than today are returned.
- The `TermEnd` option is invalid when any subscription included in this order is evergreen. In case the order only contains an order line item but not contains a subscription, if you set this field to `TermEnd` and set `billTargetDate` in the `orderLineItems` field, order line items whose `billTargetDate` is no later than today are returned.
enum:
- SpecificDate
- TermEnd
- NumberOfPeriods
type: string
previewTypes:
description: |
One or more types of the preview. It can include:
* ChargeMetrics: charge level metrics will be returned in the response, including: `cmrr`, `tcv`, `tcb`, and `tax`.
* BillingDocs: `invoices` and `creditMemos` will be returned in the response. Note `creditMemos` is only available if the Invoice Settlement feature is enabled.
* OrderDeltaMetrics: order delta metrics will be returned in the response, including: `orderDeltaMrr`, `orderDeltaTcb` and `orderDeltaTcv`.
* OrderMetrics: order metrics will be returned in the response, including: `quantity`, `mrr`, `tcb`, `tcv`, and `elp`. **Note:** As of Zuora Billing Release 306, Zuora has upgraded the methodologies for calculating metrics in [Orders](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders). The new methodologies are reflected in the OrderDeltaMetrics. It is recommended that all customers use the [Order Delta Metrics](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Order_Delta_Metrics/AA_Overview_of_Order_Delta_Metrics). If you are an existing [Order Metrics](https://docs.zuora.com/en/zuora-billing/manage-accounts-subscriptions-and-non-subscriptions/manage-subscription-transactions/orders/orders-introduction/overview-of-orders/Key_Metrics_for_Orders) customer and want to migrate to Order Delta Metrics, submit a request at [Zuora Global Support](https://support.zuora.com/). Whereas new customers, and existing customers not currently on [Order Metrics](https://docs.zuora.com/en/zuora-billing/manage-accounts-subscriptions-and-non-subscriptions/manage-subscription-transactions/orders/orders-introduction/overview-of-orders/Key_Metrics_for_Orders), will no longer have access to Order Metrics, existing customers currently using Order Metrics will continue to be supported.
* RampMetrics: ramp metrics will be returned in the response, including: `quantity`, `mrr`, `tcb`, `tcv` metrics for each charge and each ramp interval.
* RampDeltaMetrics: ramp metrics changes will be returned in the response, including: `deltaQuantity`, `deltaMrr`, `deltaTcb`, `deltaTcv` metrics for each charge and each ramp interval.
items:
enum:
- ChargeMetrics
- BillingDocs
- OrderDeltaMetrics
- OrderMetrics
- RampMetrics
- RampDeltaMetrics
type: string
type: array
skipTax:
type: boolean
description: If set to true, the system will bypass the tax calculation during order preview.
default: false
specificPreviewThruDate:
description: |
The end date of the order preview. You can preview the invoice charges through the preview through date. (Invoice preview only)
**Note:** This field is only applicable if the 'previewThruType' field is set to 'SpecificDate'.
format: date
type: string
chargeTypeToExclude:
description: |
The charge types to exclude from the forecast run.
items:
type: string
enum:
- OneTime
- Recurring
- Usage
type: array
type: object
PreviewOrderOrderAction:
properties:
addProduct:
$ref: '#/components/schemas/PreviewOrderRatePlanOverride'
cancelSubscription:
$ref: '#/components/schemas/CancelSubscription'
changePlan:
$ref: '#/components/schemas/PreviewOrderCreateChangePlan'
changeReason:
description: |
The change reason set for an order action when an order is created.
type: string
createSubscription:
$ref: '#/components/schemas/PreviewOrderCreateSubscription'
customFields:
$ref: '#/components/schemas/OrderActionObjectCustomFields'
ownerTransfer:
$ref: '#/components/schemas/OwnerTransfer'
removeProduct:
$ref: '#/components/schemas/RemoveProduct'
renewSubscription:
$ref: '#/components/schemas/RenewSubscription'
resume:
$ref: '#/components/schemas/CreateOrderResume'
suspend:
$ref: '#/components/schemas/CreateOrderSuspend'
termsAndConditions:
$ref: '#/components/schemas/CreateOrderTermsAndConditions'
triggerDates:
description: |
Container for the contract effective, service activation, and customer acceptance dates of the order action.
If the service activation date is set as a required field in Default Subscription Settings, skipping this field in a `CreateSubscription` order action of your JSON request will result in a `Pending` order and a `Pending Activation` subscription.
If the customer acceptance date is set as a required field in Default Subscription Settings, skipping this field in a `CreateSubscription` order action of your JSON request will result in a `Pending` order and a `Pending Acceptance` subscription. If the service activation date field is at the same time required and skipped (or set as null), it will be a `Pending Activation` subscription.
items:
$ref: '#/components/schemas/TriggerDate'
type: array
type:
description: |
Type of order action.
Unless the type of order action is `RenewSubscription`, you must use the corresponding field to provide information about the order action. For example, if the type of order action is `AddProduct`, you must set the `addProduct` field.
Zuora returns an error if you set a field that corresponds to a different type of order action. For example, if the type of order action is `AddProduct`, Zuora returns an error if you set the `updateProduct` field.
**Note**: The change plan type of order action is supported for the Order to Revenue feature. However, it is currently not supported for the Billing - Revenue Integration feature. When Billing - Revenue Integration is enabled, the change plan type of order action will no longer be applicable in Zuora Billing.
enum:
- CreateSubscription
- TermsAndConditions
- AddProduct
- UpdateProduct
- RemoveProduct
- RenewSubscription
- CancelSubscription
- OwnerTransfer
- Suspend
- Resume
- ChangePlan
type: string
updateProduct:
$ref: '#/components/schemas/PreviewOrderRatePlanUpdate'
required:
- type
type: object
QuoteObjectFields:
description: |
The fields populated for a quote when a quote is sent to Zuora Billing from Zuora Quote.
properties:
OpportunityCloseDate__QT:
description: |
The closing date of the Opportunity.
This field is used in Zuora Reporting Data Sources to report on Subscription metrics.
If the subscription was originated from Zuora Quotes, the value is populated with the value from Zuora Quotes.
type: string
OpportunityName__QT:
description: |
The unique identifier of the Opportunity.
This field is used in the Zuora Reporting Data Sources to report on Subscription metrics.
If the subscription was originated from Zuora Quotes, the value is populated with the value from Zuora Quotes.
**Character limit**: 100
type: string
QuoteBusinessType__QT:
description: |
The specific identifier for the type of business transaction the Quote represents such as New, Upsell, Downsell, Renewal or Churn.
This field is used in the Zuora Reporting Data Sources to report on Subscription metrics.
If the subscription was originated from Zuora Quotes, the value is populated with the value from Zuora Quotes.
**Character limit**: 32
type: string
QuoteNumber__QT:
description: |
The unique identifier of the Quote.
This field is used in the Zuora Reporting Data Sources to report on Subscription metrics.
If the subscription was originated from Zuora Quotes, the value is populated with the value from Zuora Quotes.
**Character limit**: 32
type: string
QuoteType__QT:
description: |
The Quote type that represents the subscription lifecycle stage such as New, Amendment, Renew or Cancel.
This field is used in the Zuora Reporting Data Sources to report on Subscription metrics.
If the subscription was originated from Zuora Quotes, the value is populated with the value from Zuora Quotes.
**Character limit**: 32
type: string
title: quote
type: object
RampRequest:
description: |
Container of the ramp definitions. It is used to create, update, or remove the ramp definition for the new subscription.
properties:
charges:
description: |
Container for the rate plan charges that are considered as part of the ramp deal.
* If this field is not specified, all the one-time and recurring regular charges of the new subscription are automatically considered as part of the ramp deal.
* If this field is specified, either 'chargeNumber' or 'uniqueToken' must be specified.
items:
$ref: '#/components/schemas/RampChargeRequest'
type: array
delete:
description: |
Whether to remove the ramp definition from the new subscription. If you want to remove the ramp definition, this field is the only required field for the `ramp` object.
type: boolean
description:
description: The short description of the ramp.
type: string
intervals:
description: |
Container for the intervals that the ramp is split into in its timeline.
It is required when you want to create or update the ramp definition. The ramp intervals cannot have any overlap or gap between each other.
items:
$ref: '#/components/schemas/RampIntervalRequest'
type: array
name:
description: The name of the ramp.
type: string
title: Ramp
type: object
RampChargeRequest:
properties:
chargeNumber:
description: The number of the rate plan charge.
type: string
uniqueToken:
description: |
Unique identifier for the charge. This identifier enables you to refer to the charge before the charge has an internal identifier in Zuora.
type: string
title: RampCharge
type: object
RampIntervalRequest:
description: |
Container for the intervals that the ramp is split into in its timeline. Zuora can report metrics for this specific period.
properties:
description:
description: The short description of the interval.
type: string
endDate:
description: The end date of the interval.
format: date
type: string
name:
description: The name of the interval.
type: string
startDate:
description: The start date of the interval.
format: date
type: string
required:
- startDate
- endDate
title: intervals
type: object
PreviewOrderRatePlanOverride:
description: |
Information about an order action of type `AddProduct`.
properties:
chargeOverrides:
description: |
List of charges associated with the rate plan.
items:
$ref: '#/components/schemas/PreviewOrderChargeOverride'
type: array
clearingExistingFeatures:
description: |
Specifies whether all features in the rate plan will be cleared.
type: boolean
customFields:
$ref: '#/components/schemas/OrdersRatePlanObjectCustomFields'
isAddingSubsetCharges:
description: |
Specifies whether to add a subset of charges to the subscription.
**Note:** To access this field for adding a subset of charges, submit a request at Zuora Global Support.
type: boolean
isFromExternalCatalog:
description: |
Indicates whether the rate plan is created from the Zuora product catalog or from an external product catalog.
**Note:** This field is available when the Standalone Orders feature is enabled.
type: boolean
productRatePlanId:
description: |
Internal identifier of the product rate plan that the rate plan is based on.
type: string
productRatePlanNumber:
description: |
Number of a product rate plan for this subscription.
type: string
ratePlanName:
description: |
Name of the standalone rate plan.
**Note:** This field is available when the Standalone Orders feature is enabled.
type: string
subscriptionProductFeatures:
description: |
List of features associated with the rate plan.
The system compares the `subscriptionProductFeatures` and `featureId` fields in the request with the counterpart fields in a rate plan. The comparison results are as follows:
* If there is no `subscriptionProductFeatures` field or the field is empty, features in the rate plan remain unchanged. But if the `clearingExistingFeatures` field is additionally set to true, all features in the rate plan are cleared.
* If the `subscriptionProductFeatures` field contains the `featureId` nested fields, as well as the optional `description` and `customFields` nested fields, the features indicated by the featureId nested fields in the request overwrite all features in the rate plan.
items:
$ref: '#/components/schemas/CreateOrderRatePlanFeatureOverride'
type: array
uniqueToken:
description: |
Unique identifier for the rate plan. This identifier enables you to refer to the rate plan before the rate plan has an internal identifier in Zuora.
For instance, suppose that you want to use a single order to add a product to a subscription and later update the same product. When you add the product, you can set a unique identifier for the rate plan. Then when you update the product, you can use the same unique identifier to specify which rate plan to modify.
maxLength: 50
type: string
subscriptionRatePlanNumber:
description: |
Number of a subscription rate plan for this subscription.
maxLength: 50
type: string
required:
- productRatePlanId
title: ratePlan
type: object
CancelSubscription:
description: |
Information about an order action of type `CancelSubscription`.
properties:
cancellationEffectiveDate:
format: date
type: string
cancellationPolicy:
enum:
- EndOfCurrentTerm
- EndOfLastInvoicePeriod
- SpecificDate
type: string
required:
- cancellationPolicy
title: cancelSubscription
type: object
PreviewOrderCreateChangePlan:
description: |
Information about an order action of type `ChangePlan`.
Use the change plan type of order action to replace the existing rate plans in a subscription with other rate plans.
**Note**: The change plan type of order action is supported for the Order to Revenue feature. However, it is currently not supported for the Billing - Revenue Integration feature. When Billing - Revenue Integration is enabled, the change plan type of order action will no longer be applicable in Zuora Billing.
If you want to create a pending order through the "change plan" order action, and if the charge's trigger condition is `Specific Date`, you must set a charge number in the `chargeNumber` field for the "change plan" order action. In this case, if you do not set it, Zuora will not generate the charge number for you.
See more information about pending orders in Pending orders and subscriptions.
properties:
effectivePolicy:
description: |
The default value for the `effectivePolicy` field is as follows:
* If the rate plan change (from old to new) is an upgrade, the effective policy is `EffectiveImmediately` by default.
* If the rate plan change (from old to new) is a downgrade, the effective policy is `EffectiveEndOfBillingPeriod` by default.
* Otherwise, the effective policy is `SpecificDate` by default.
**Notes**:
* When setting this field to `EffectiveEndOfBillingPeriod`, you cannot set the billing trigger dates for the subscription as the system will automatically set the trigger dates to the end of billing period, and you cannot set the following billing trigger date settings to `Yes`:
* Require Customer Acceptance of Orders?
* Require Service Activation of Orders?
* When setting this field to `SpecificDate`, you must also set the contract effective date in the `triggerDates` field as follows:
* Set the `name` field as `ContractEffective`
* Specify a date for the `triggerDate` field
enum:
- EffectiveImmediately
- EffectiveEndOfBillingPeriod
- SpecificDate
type: string
externalCatalogPlanId:
description: |
An external ID of the rate plan to be removed. You can use this field to specify an existing rate plan in your subscription. The value of the `externalCatalogPlanId` field must match one of the values that are predefined in the `externallyManagedPlanIds` field on a product rate plan. However, if there are multiple rate plans with the same `productRatePlanId` value existing in the subscription, you must use the `ratePlanId` field to remove the rate plan. The `externalCatalogPlanId` field cannot be used to distinguish multiple rate plans in this case.
**Note:** Please provide only one of `externalCatalogPlanId`, `ratePlanId` or `productRatePlanId`. If more than 1 field is provided then the request would fail.
type: string
newProductRatePlan:
$ref: '#/components/schemas/PreviewOrderChangePlanRatePlanOverride'
productRatePlanId:
description: |
ID of the product rate plan that the removed rate plan is based on.
type: string
productRatePlanNumber:
description: |
Number of a product rate plan for this subscription.
type: string
ratePlanId:
description: |
ID of the rate plan to remove. This can be the latest version or any history version of ID. Note that the removal of a rate plan through the Change Plan order action supports the function of removal before future-dated removals, as in a Remove Product order action.
type: string
resetBcd:
default: false
description: |
If resetBcd is true then reset the Account BCD to the effective date; if it is false keep the original BCD.
**Note**: If the rate plan change is an upgrade (the `subType` field is `Upgrade`), then the effective policy is `EffectiveImmediately` by default. In this case, if you do not specify the `resetBcd` field, the system sets this field to `true` while BCD is the effective date.
type: boolean
subType:
description: |
Use this field to choose the sub type for your change plan order action.
However, if you do not set this field, the field will be automatically generated by the system according to the following rules:
When the old and new rate plans are within the same Grading catalog group:
* If the grade of new plan is greater than that of the old plan, this is an "Upgrade".
* If the grade of new plan is less than that of the old plan, this is a "Downgrade".
* If the grade of new plan equals that of the old plan, this is a "Crossgrade".
When the old and new rate plans are not in the same Grading catalog group, or either has no group, this is "PlanChanged".
enum:
- Upgrade
- Downgrade
- Crossgrade
- PlanChanged
type: string
subscriptionRatePlanNumber:
description: |
Number of a rate plan for this subscription.
type: string
required:
- newProductRatePlan
title: createChangePlan
type: object
PreviewOrderCreateSubscription:
description: |
Information about an order action of type `CreateSubscription`.
properties:
billToContactId:
description: |
The ID of the bill-to contact associated with the subscription.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request or you select **Default Contact from Account** for this field during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
currency:
description: |
The code of currency that is used for this subscription. If the currency is not selected, the default currency from the account will be used.
All subscriptions in the same order must use the same currency. The currency for a subscription cannot be changed.
**Note**:
This field is available only if you have the Multiple Currencies feature enabled.
maxLength: 3
type: string
invoiceGroupNumber:
description: |
The number of the invoice group associated with the subscription.
After enabling the Invoice Grouping feature, you can specify invoice group numbers to bill subscriptions and order line items based on specific criteria. For the same account, Zuora generates separate invoices for subscriptions and order line items, each identified by unique invoice group numbers. For more information, see [Invoice Grouping](https://knowledgecenter.zuora.com/Billing/Subscriptions/Invoice_Grouping).
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
maxLength: 255
nullable: true
invoiceSeparately:
description: |
Specifies whether the subscription appears on a separate invoice when Zuora generates invoices.
type: boolean
invoiceTemplateId:
description: |
The ID of the invoice template associated with the subscription.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request or you select **Default Template from Account** for this field during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
newSubscriptionOwnerAccount:
description: |
Information about a new account that will own the subscription. Only available if you have enabled the Owner Transfer feature.
**Note:** The Owner Transfer feature is in **Limited Availability**. If you wish to have access to the feature, submit a request at [Zuora Global Support](http://support.zuora.com/).
If you do not set this field or the `subscriptionOwnerAccountNumber` field, the account that owns the order will also own the subscription. Zuora will return an error if you set this field and the `subscriptionOwnerAccountNumber` field.
properties:
accountNumber:
description: |
Account number. For example, A00000001.
maxLength: 70
type: string
additionalEmailAddresses:
description: |
List of additional email addresses to receive emailed invoices. Values should be a comma-separated list of email addresses.
maxLength: 1200
type: string
allowInvoiceEdit:
description: |
Indicates if associated invoices can be edited.
Values are:
* `true`
* `false` (default)
type: boolean
autoPay:
description: |
Specifies whether future payments are automatically billed when they are due.
type: boolean
batch:
description: |
Name of the billing batch that the account belongs to. For example, Batch1.
type: string
billCycleDay:
description: |
Day of the month that the account prefers billing periods to begin on. If set to 0, the bill cycle day will be set as "AutoSet".
maximum: 31
minimum: 0
type: integer
billToContact:
$ref: '#/components/schemas/BillToContactPostOrder'
communicationProfileId:
description: |
Internal identifier of the communication profile that Zuora uses when sending notifications to the account's contacts.
type: string
creditCard:
$ref: '#/components/schemas/creditCard'
creditMemoTemplateId:
description: |
**Note:** This field is only available if you have [Invoice Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement) 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.
The unique ID of the credit memo template, configured in **Billing Settings** > **Manage Billing Document Configuration** through the Zuora UI. For example, 2c92c08a6246fdf101626b1b3fe0144b.
type: string
crmId:
description: |
External identifier of the account in a CRM system.
maxLength: 100
type: string
currency:
description: |
ISO 3-letter currency code (uppercase). For example, USD.
type: string
customFields:
$ref: '#/components/schemas/AccountObjectCustomFields'
customerServiceRepName:
description: |
Name of the account's customer service representative, if applicable.
maxLength: 50
type: string
debitMemoTemplateId:
description: |
**Note:** This field is only available if you have [Invoice Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement) 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.
The unique ID of the debit memo template, configured in **Billing Settings** > **Manage Billing Document Configuration** through the Zuora UI. For example, 2c92c08d62470a8501626b19d24f19e2.
type: string
hpmCreditCardPaymentMethodId:
description: |
The ID of the payment method associated with this account. The payment method specified for this field will be set as the default payment method of the account.
If the `autoPay` field is set to `true`, you must provide the credit card payment method ID for either this field or the `creditCard` field,
but not both.
For a specified credit card payment method, it is recommended that [the support for stored credential transactions](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/L_Payment_Methods/Stored_credential_transactions) for this payment method is already enabled.
type: string
invoiceDeliveryPrefsEmail:
description: |
Specifies whether to turn on the invoice delivery method 'Email' for the new account.
Values are:
* `true` (default). Turn on the invoice delivery method 'Email' for the new account.
* `false`. Turn off the invoice delivery method 'Email' for the new account.
type: boolean
invoiceDeliveryPrefsPrint:
description: |
Specifies whether to turn on the invoice delivery method 'Print' for the new account.
Values are:
* `true`. Turn on the invoice delivery method 'Print' for the new account.
* `false` (default). Turn off the invoice delivery method 'Print' for the new account.
type: boolean
invoiceTemplateId:
description: |
Internal identifier of the invoice template that Zuora uses when generating invoices for the account.
type: string
name:
description: |
Account name.
maxLength: 255
type: string
notes:
description: |
Notes about the account. These notes are only visible to Zuora users.
maxLength: 65535
type: string
parentId:
description: Identifier of the parent customer account for this Account object. Use this field if you have Customer Hierarchy enabled.
type: string
paymentGateway:
description: |
The payment gateway that Zuora uses when processing electronic payments and refunds for the account. If you do not specify this field or if the value of this field is null, Zuora uses your default payment gateway.
maxLength: 40
type: string
paymentMethod:
$ref: '#/components/schemas/POSTPaymentMethodRequest'
paymentTerm:
description: |
Name of the payment term associated with the account. For example, "Net 30". The payment term determines the due dates of invoices.
type: string
purchaseOrderNumber:
description: |
The number of the purchase order associated with this account. Purchase order information generally comes from customers.
maxLength: 100
type: string
salesRep:
description: |
The name of the sales representative associated with this account, if applicable.
maxLength: 50
type: string
soldToContact:
$ref: '#/components/schemas/SoldToContactPostOrder'
taxInfo:
$ref: '#/components/schemas/TaxInfo'
required:
- name
- currency
- billCycleDay
- billToContact
type: object
notes:
description: |
Notes about the subscription. These notes are only visible to Zuora users.
maxLength: 500
type: string
paymentTerm:
description: |
The name of the payment term associated with the subscription. For example, `Net 30`. The payment term determines the due dates of invoices.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request or you select **Default Term from Account** for this field during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
sequenceSetId:
description: |
The ID of the sequence set associated with the subscription.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request or you select **Default Set from Account** for this field during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
nullable: true
shipToContactId:
description: |
The ID of the ship-to contact associated with the subscription. It must be a contact of the subscription owner.
**Note**:
To access this field, you must have the ShipToContactSupport permission. If you want to enable this permission, submit a request at Zuora Global Support.
type: string
soldToContactId:
description: |
The ID of the sold-to contact associated with the subscription.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request or you select **Default Contact from Account** for this field during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
subscribeToRatePlans:
description: |
List of rate plans associated with the subscription.
items:
$ref: '#/components/schemas/PreviewOrderRatePlanOverride'
type: array
subscriptionNumber:
description: |
Subscription number of the subscription. For example, A-S00000001.
If you do not set this field, Zuora will generate the subscription number.
maxLength: 100
type: string
subscriptionOwnerAccountNumber:
description: |
Account number of an existing account that will own the subscription. For example, A00000001.
If you do not set this field or the `newSubscriptionOwnerAccount` field, the account that owns the order will also own the subscription. Zuora will return an error if you set this field and the `newSubscriptionOwnerAccount` field.
maxLength: 70
type: string
invoiceOwnerAccountNumber:
description: |
Account number of an existing account that will own the invoice. For example, A00000001. If you do not set this field, the account that owns the order will also own this invoice.
maxLength: 70
type: string
terms:
description: |
Container for the terms and renewal settings of the subscription.
properties:
autoRenew:
description: |
Specifies whether the subscription automatically renews at the end of the each term. Only applicable if the type of the first term is `TERMED`.
type: boolean
initialTerm:
description: |
Information about the first term of the subscription.
properties:
period:
description: |
Duration of the first term in months, years, days, or weeks, depending on the value of the `periodType` field. Only applicable if the value of the `termType` field is `TERMED`.
type: integer
periodType:
description: |
Unit of time that the first term is measured in. Only applicable if the value of the `termType` field is `TERMED`.
enum:
- Month
- Year
- Day
- Week
type: string
startDate:
description: |
Start date of the first term, in YYYY-MM-DD format.
format: date
type: string
endDate:
description: |
End date of the first term, in YYYY-MM-DD format.
format: date
type: string
termType:
description: |
Type of the first term. If the value of this field is `TERMED`, the first term has a predefined duration based on the value of the `period` field. If the value of this field is `EVERGREEN`, the first term does not have a predefined duration.
enum:
- TERMED
- EVERGREEN
type: string
required:
- termType
type: object
renewalSetting:
description: |
Specifies the type of the terms that follow the first term if the subscription is renewed. Only applicable if the type of the first term is `TERMED`.
* `RENEW_WITH_SPECIFIC_TERM` - Each renewal term has a predefined duration. The first entry in `renewalTerms` specifies the duration of the second term of the subscription, the second entry in `renewalTerms` specifies the duration of the third term of the subscription, and so on. The last entry in `renewalTerms` specifies the ultimate duration of each renewal term.
* `RENEW_TO_EVERGREEN` - The second term of the subscription does not have a predefined duration.
enum:
- RENEW_WITH_SPECIFIC_TERM
- RENEW_TO_EVERGREEN
type: string
renewalTerms:
description: |
List of renewal terms of the subscription. Only applicable if the type of the first term is `TERMED` and the value of the `renewalSetting` field is `RENEW_WITH_SPECIFIC_TERM`.
items:
$ref: '#/components/schemas/RenewalTerm'
type: array
required:
- initialTerm
type: object
title: createSubscription
type: object
OrderActionObjectCustomFields:
additionalProperties:
description: |
Custom fields of the Order Action object. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
description: |
Container for custom fields of an Order Action object.
title: orderActionFieldsCustom
type: object
OwnerTransfer:
description: |
Information about an order action of type `OwnerTransfer`.
**Note:** The Owner Transfer feature is in **Limited Availability**. If you wish to have access to the feature, submit a request at [Zuora Global Support](http://support.zuora.com/).
properties:
billToContactId:
description: |
The contact id of the bill to contact that the subscription is being transferred to.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request or you select **Default Contact from Account** for this field during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
clearingExistingBillToContact:
default: false
description: |
Whether to clear the existing bill-to contact ID at the subscription level. This field is mutually exclusive with the `billToContactId` field.
**Note**: If you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
type: boolean
clearingExistingInvoiceGroupNumber:
default: false
description: |
Whether to clear the existing invoice group number at the subscription level. This field is mutually exclusive with the `invoiceGroupNumber` field.
**Note**: If you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
type: boolean
clearingExistingInvoiceTemplate:
default: false
description: |
Whether to clear the existing invoice template ID at the subscription level. This field is mutually exclusive with the `invoiceTemplateId` field.
**Note**: If you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
type: boolean
clearingExistingPaymentTerm:
default: false
description: |
Whether to clear the existing payment term at the subscription level. This field is mutually exclusive with the `paymentTerm` field.
**Note**: If you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
type: boolean
clearingExistingSequenceSet:
default: false
description: |
Whether to clear the existing sequence set ID at the subscription level. This field is mutually exclusive with the `sequenceSetId` field.
**Note**: If you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
type: boolean
clearingExistingShipToContact:
default: false
description: |
Whether to clear the existing ship-to contact ID at the subscription level. This field is mutually exclusive with the `shipToContactId` field.
**Note:**
To access this field, you must have the ShipToContactSupport permission. If you want to enable this permission, submit a request at Zuora Global Support.
type: boolean
clearingExistingSoldToContact:
default: false
description: |
Whether to clear the existing sold-to contact ID at the subscription level. This field is mutually exclusive with the `soldToContactId` field.
**Note**: If you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
type: boolean
destinationAccountNumber:
description: |
The account number of the account that the subscription is being transferred to.
type: string
destinationInvoiceAccountNumber:
description: |
The account number of the invoice owner account that the subscription is being transferred to.
type: string
invoiceGroupNumber:
description: |
The number of the invoice group associated with the subscription.
After enabling the Invoice Grouping feature, you can specify invoice group numbers to bill subscriptions and order line items based on specific criteria. For the same account, Zuora generates separate invoices for subscriptions and order line items, each identified by unique invoice group numbers. For more information, see [Invoice Grouping](https://knowledgecenter.zuora.com/Billing/Subscriptions/Invoice_Grouping).
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
maxLength: 255
nullable: true
invoiceTemplateId:
description: |
The ID of the invoice template associated with the subscription.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request or you select **Default Template from Account** for this field during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
paymentProfile:
description: |
Container for payment gateway and payment method details of a payment. If you do not set this field, the payment method and payment gateway values cannot be set in the subscription.
**Note:**
- If multiple order actions are specified, they will be applied in the same order they appear in the API payload.
- If one or more of these order actions include the `paymentProfile` element, the changes will be applied in sequence, and the result will be consistent with the last `paymentProfile` element.
properties:
paymentGatewayId:
description: |
The ID of the gateway instance that processes the payment.
This field remains unset, if you do not provide value.
type: string
paymentMethodId:
description: |
The ID of the payment method.
This field remains unset, if you do not provide value.
type: string
type: object
paymentTerm:
description: |
Name of the payment term associated with the account. For example, "Net 30". The payment term determines the due dates of invoices.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request or you select **Default Term from Account** for this field during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
sequenceSetId:
description: |
The ID of the sequence set associated with the subscription.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request or you select **Default Set from Account** for this field during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
nullable: true
shipToContactId:
description: |
The ID of the ship-to contact associated with the subscription.
**Note**:
To access this field, you must have the ShipToContactSupport permission. If you want to enable this permission, submit a request at Zuora Global Support.
type: string
soldToContactId:
description: |
The ID of the sold-to contact associated with the subscription.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request or you select **Default Contact from Account** for this field during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
title: ownerTransfer
type: object
RemoveProduct:
description: |
Information about an order action of type `RemoveProduct`.
properties:
externalCatalogPlanId:
description: |
An external ID of the rate plan to be removed. You can use this field to specify an existing rate plan in your subscription. The value of the `externalCatalogPlanId` field must match one of the values that are predefined in the `externallyManagedPlanIds` field on a product rate plan. However, if there are multiple rate plans with the same `productRatePlanId` value existing in the subscription, you must use the `ratePlanId` field to remove the rate plan. The `externalCatalogPlanId` field cannot be used to distinguish multiple rate plans in this case.
**Note:** If both `externalCatalogPlanId` and `ratePlanId` are provided. They must point to the same product rate plan. Otherwise, the request would fail.
type: string
productRatePlanNumber:
description: |
Number of a product rate plan for this subscription.
type: string
ratePlanId:
description: |
ID of the rate plan to remove. This can be the latest version or any history version of ID.
type: string
subscriptionRatePlanNumber:
description: |
Number of a rate plan for this subscription.
type: string
uniqueToken:
description: Unique identifier for the rate plan. This identifier enables you to refer to the rate plan before the rate plan has an internal identifier in Zuora.
type: string
customFields:
additionalProperties:
description: |
Custom fields of the Rate Plan object. The name of each custom field has
the form *customField*__c. Custom field names are case
sensitive. See [Manage Custom
Fields](https://knowledgecenter.zuora.com/BB_Introducing_Z_Business/Manage_Custom_Fields)
for more information.
type: object
description: |
Container for custom fields of a Rate Plan object.
title: RatePlanCustomFields
type: object
chargeUpdates:
items:
$ref: '#/components/schemas/OrderActionRatePlanChargeRemove'
type: array
title: removeProduct
type: object
RenewSubscription:
description: |
Information about an order action of type `RenewSubscription`.
properties:
billToContactId:
description: |
The ID of the bill-to contact associated with the subscription.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request or you select **Default Contact from Account** for this field during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
clearingExistingBillToContact:
default: false
description: |
Whether to clear the existing bill-to contact ID at the subscription level. This field is mutually exclusive with the `billToContactId` field.
**Note**: If you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
type: boolean
clearingExistingInvoiceGroupNumber:
default: false
description: |
Whether to clear the existing invoice group number at the subscription level. This field is mutually exclusive with the `invoiceGroupNumber` field.
**Note**: If you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
type: boolean
clearingExistingInvoiceTemplate:
default: false
description: |
Whether to clear the existing invoice template ID at the subscription level. This field is mutually exclusive with the `invoiceTemplateId` field.
**Note**: If you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
type: boolean
clearingExistingPaymentTerm:
default: false
description: |
Whether to clear the existing payment term at the subscription level. This field is mutually exclusive with the `paymentTerm` field.
**Note**: If you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
type: boolean
clearingExistingSequenceSet:
default: false
description: |
Whether to clear the existing sequence set ID at the subscription level. This field is mutually exclusive with the `sequenceSetId` field.
**Note**: If you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
type: boolean
clearingExistingShipToContact:
default: false
description: |
Whether to clear the existing ship-to contact ID at the subscription level. This field is mutually exclusive with the `shipToContactId` field.
**Note:**
To access this field, you must have the ShipToContactSupport permission. If you want to enable this permission, submit a request at Zuora Global Support.
type: boolean
clearingExistingSoldToContact:
default: false
description: |
Whether to clear the existing sold-to contact ID at the subscription level. This field is mutually exclusive with the `soldToContactId` field.
**Note**: If you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
type: boolean
invoiceGroupNumber:
description: |
The number of the invoice group associated with the subscription.
After enabling the Invoice Grouping feature, you can specify invoice group numbers to bill subscriptions and order line items based on specific criteria. For the same account, Zuora generates separate invoices for subscriptions and order line items, each identified by unique invoice group numbers. For more information, see [Invoice Grouping](https://knowledgecenter.zuora.com/Billing/Subscriptions/Invoice_Grouping).
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
maxLength: 255
nullable: true
invoiceTemplateId:
description: |
The ID of the invoice template associated with the subscription.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request or you select **Default Template from Account** for this field during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
nullable: true
paymentTerm:
description: |
The name of the payment term associated with the subscription. For example, `Net 30`. The payment term determines the due dates of invoices.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request or you select **Default Term from Account** for this field during subscription creation, the value of this field is automatically set to `null` in the response body..
type: string
sequenceSetId:
description: |
The ID of the sequence set associated with the subscription.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request or you select **Default Set from Account** for this field during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
nullable: true
shipToContactId:
description: |
The ID of the ship-to contact associated with the subscription.
**Note:**
To access this field, you must have the ShipToContactSupport permission. If you want to enable this permission, submit a request at Zuora Global Support.
type: string
soldToContactId:
description: |
The ID of the sold-to contact associated with the subscription.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request or you select **Default Contact from Account** for this field during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
title: RenewSubscription
type: object
CreateOrderResume:
description: |
Information about an order action of type `Resume`.
properties:
extendsTerm:
description: |
Specifies whether to extend the subscription term by the length of time the suspension is in effect.
type: boolean
resumePeriods:
description: |
This field is applicable only when the `resumePolicy` field is set to `FixedPeriodsFromToday` or `FixedPeriodsFromSuspendDate`. It must be used together with the `resumePeriodsType` field.
The total number of the periods used to specify when a subscription resumption takes effect. The subscription resumption will take place after the specified time frame (`suspendPeriods` multiplied by `suspendPeriodsType`) from today's date.
type: integer
resumePeriodsType:
description: |
This field is applicable only when the `resumePolicy` field is set to `FixedPeriodsFromToday` or `FixedPeriodsFromSuspendDate`. It must be used together with the `resumePeriods` field.
The period type used to specify when a subscription resumption takes effect. The subscription suspension will take place after the specified time frame (`suspendPeriods` multiplied by `suspendPeriodsType`) from today's date.
enum:
- Day
- Week
- Month
- Year
type: string
resumePolicy:
description: |
Resume methods. Specify a way to resume a subscription. See [Resume Date](https://knowledgecenter.zuora.com/BC_Subscription_Management/Subscriptions/Resume_a_Subscription#Resume_Date) for more information.
If `SuspendDate` is specfied, the resumption will take place on the same day as the suspension.
enum:
- Today
- FixedPeriodsFromSuspendDate
- FixedPeriodsFromToday
- SpecificDate
- SuspendDate
type: string
resumeSpecificDate:
description: |
This field is applicable only when the `resumePolicy` field is set to `SpecificDate`.
A specific date when the subscription resumption takes effect, in YYYY-MM-DD format. The value should not be earlier than the subscription suspension date.
format: date
type: string
required:
- resumePolicy
title: Resume
type: object
CreateOrderSuspend:
description: |
Information about an order action of type `Suspend`.
properties:
suspendPeriods:
description: |
This field is applicable only when the `suspendPolicy` field is set to `FixedPeriodsFromToday`. It must be used together with the `suspendPeriodsType` field.
The total number of the periods used to specify when a subscription suspension takes effect. The subscription suspension will take place after the specified time frame (`suspendPeriods` multiplied by `suspendPeriodsType`) from today's date.
type: integer
suspendPeriodsType:
description: |
This field is applicable only when the `suspendPolicy` field is set to `FixedPeriodsFromToday`. It must be used together with the `suspendPeriods` field.
The period type used to specify when a subscription suspension takes effect. The subscription suspension will take place after the specified time frame (`suspendPeriods` multiplied by `suspendPeriodsType`) from today's date.
enum:
- Day
- Week
- Month
- Year
type: string
suspendPolicy:
description: |
Suspend methods. Specify a way to suspend a subscription. See [Suspend Date](https://knowledgecenter.zuora.com/BC_Subscription_Management/Subscriptions/Suspend_a_Subscription#Suspend_Date) for more information.
enum:
- Today
- EndOfLastInvoicePeriod
- FixedPeriodsFromToday
- SpecificDate
type: string
suspendSpecificDate:
description: |
This field is applicable only when the `suspendPolicy` field is set to `SpecificDate`.
A specific date when the subscription suspension takes effect, in YYYY-MM-DD format. The value should not be earlier than the subscription's contract effective date or later [available versions](https://developer.zuora.com/api-references/api/overview/#section/API-Versions/Minor-Version) than the subscription's term end date.
format: date
type: string
required:
- suspendPolicy
title: Suspend
type: object
CreateOrderTermsAndConditions:
description: |
Information about an order action of type `TermsAndConditions`.
properties:
autoRenew:
type: boolean
billToContactId:
description: |
The ID of the bill-to contact associated with the subscription.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request or you select **Default Contact from Account** for this field during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
clearingExistingBillToContact:
default: false
description: |
Whether to clear the existing bill-to contact ID at the subscription level. This field is mutually exclusive with the `billToContactId` field.
**Note**: If you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
type: boolean
clearingExistingInvoiceGroupNumber:
default: false
description: |
Whether to clear the existing invoice group number at the subscription level. This field is mutually exclusive with the `invoiceGroupNumber` field.
**Note**: If you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
type: boolean
clearingExistingInvoiceTemplate:
default: false
description: |
Whether to clear the existing invoice template ID at the subscription level. This field is mutually exclusive with the `invoiceTemplateId` field.
**Note**: If you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
type: boolean
clearingExistingPaymentTerm:
default: false
description: |
Whether to clear the existing payment term at the subscription level. This field is mutually exclusive with the `paymentTerm` field.
**Note**: If you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
type: boolean
clearingExistingSequenceSet:
default: false
description: |
Whether to clear the existing sequence set ID at the subscription level. This field is mutually exclusive with the `sequenceSetId` field.
**Note**: If you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
type: boolean
clearingExistingShipToContact:
default: false
description: |
Whether to clear the existing ship-to contact ID at the subscription level. This field is mutually exclusive with the `shipToContactId` field.
**Note**:
To access this field, you must have the ShipToContactSupport permission. If you want to enable this permission, submit a request at Zuora Global Support.
type: boolean
clearingExistingSoldToContact:
default: false
description: |
Whether to clear the existing sold-to contact ID at the subscription level. This field is mutually exclusive with the `soldToContactId` field.
**Note**: If you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
type: boolean
communicationProfileId:
description: |
The ID of the communication profile associated with the subscription.
**Note**: This field is available in the request body only if you have the Flexible Billing Attributes
feature turned on. The value is `null` in the response body without this feature turned on.
type: string
clearingExistingCommunicationProfile:
default: false
description: |
Whether to clear the existing communication profile at the subscription
level. This field is mutually exclusive with the `communicationProfileId` field.
type: boolean
invoiceGroupNumber:
description: |
The number of the invoice group associated with the subscription.
After enabling the Invoice Grouping feature, you can specify invoice group numbers to bill subscriptions and order line items based on specific criteria. For the same account, Zuora generates separate invoices for subscriptions and order line items, each identified by unique invoice group numbers. For more information, see [Invoice Grouping](https://knowledgecenter.zuora.com/Billing/Subscriptions/Invoice_Grouping).
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
maxLength: 255
nullable: true
invoiceSeparately:
description: Specifies whether the subscription appears on a separate invoice while generating invoices.
type: boolean
invoiceTemplateId:
description: |
The ID of the invoice template associated with the subscription.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request or you select **Default Template from Account** for this field during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
lastTerm:
$ref: '#/components/schemas/LastTerm'
paymentProfile:
description: |
Container for payment gateway and payment method details of a payment. If you do not set this field, the payment method and payment gateway values cannot be set in the subscription.
**Note:**
- If multiple order actions are specified, they will be applied in the same order they appear in the API payload.
- If one or more of these order actions include the `paymentProfile` element, the changes will be applied in sequence, and the result will be consistent with the last `paymentProfile` element.
properties:
paymentGatewayId:
description: |
The ID of the gateway instance that processes the payment.
This field remains unset, if you do not provide value.
type: string
paymentMethodId:
description: |
The ID of the payment method.
This field remains unset, if you do not provide value.
type: string
type: object
paymentTerm:
description: |
The name of the payment term associated with the subscription. For example, `Net 30`. The payment term determines the due dates of invoices.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request or you select **Default Term from Account** for this field during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
renewalSetting:
enum:
- RENEW_WITH_SPECIFIC_TERM
- RENEW_TO_EVERGREEN
type: string
renewalTerms:
items:
$ref: '#/components/schemas/RenewalTerm'
type: array
scheduledCancelDate:
description: |
The date when the subscription is scheduled to be canceled. The subscription is not canceled until the date specified in this field.
format: date
type: string
scheduledSuspendDate:
description: |
The date when the subscription is scheduled to be suspended. The subscription is not suspended until the date specified in this field.
format: date
type: string
scheduledResumeDate:
description: |
The date when the subscription is scheduled to be resumed. The subscription is not resumed until the date specified in this field.
format: date
type: string
clearingScheduledCancelDate:
default: false
description: |
Whether to clear the value of the `scheduledCancelDate` field.
**Note**: Do not set this field and the `scheduledCancelDate` field simultaneously.
type: boolean
clearingScheduledSuspendDate:
default: false
description: |
Whether to clear the value of the `scheduledSuspendDate` field.
**Note**: Do not set this field and the `scheduledSuspendDate` field simultaneously.
type: boolean
clearingScheduledResumeDate:
default: false
description: |
Whether to clear the value of the `scheduledResumeDate` field.
**Note**: Do not set this field and the `scheduledResumeDate` field simultaneously.
type: boolean
sequenceSetId:
description: |
The ID of the sequence set associated with the subscription.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request or you select **Default Set from Account** for this field during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
shipToContactId:
description: |
The ID of the ship-to contact associated with the subscription.
**Note**:
To access this field, you must have the ShipToContactSupport permission. If you want to enable this permission, submit a request at Zuora Global Support.
type: string
soldToContactId:
description: |
The ID of the sold-to contact associated with the subscription.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request or you select **Default Contact from Account** for this field during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
title: termsAndConditions
type: object
TriggerDate:
properties:
name:
description: |
Name of the trigger date of the order action.
enum:
- ContractEffective
- ServiceActivation
- CustomerAcceptance
type: string
triggerDate:
description: |
Trigger date in YYYY-MM-DD format.
format: date
type: string
title: triggerDate
type: object
PreviewOrderRatePlanUpdate:
description: |
Information about an order action of type `UpdateProduct`.
properties:
chargeUpdates:
description: |
Array of the JSON objects containing the information for a charge update in the `updateProduct` type of order action.
When previewing an `updateProduct` order action, either the `chargeNumber` or `uniqueToken` field is required to specify the charge to update.
items:
$ref: '#/components/schemas/PreviewOrderChargeUpdate'
type: array
clearingExistingFeatures:
description: |
Specifies whether all features in the rate plan will be cleared.
type: boolean
customFields:
$ref: '#/components/schemas/OrdersRatePlanObjectCustomFields'
isAddingSubsetCharges:
description: |
Specifies whether to add a subset of charges to the subscription.
**Note:** To access this field for adding a subset of charges, submit a request at Zuora Global Support.
type: boolean
productRatePlanNumber:
description: |
Number of a product rate plan for this subscription.
type: string
ratePlanId:
description: |
The id of the rate plan to be updated. It can be the latest version or any history version id.
type: string
specificUpdateDate:
description: |
The specific date when the Update Product order action takes effect. This field allows you to update a charge before a future-dated Update Product order action on the subscription. The format of the date is yyyy-mm-dd.
**Note**: After you use this option, the charge's `TriggerEvent` field value will be changed to `SpecificDate`.
See [Update a Product on Subscription with Future-dated Updates](https://knowledgecenter.zuora.com/BC_Subscription_Management/Orders/AC_Orders_Tutorials/C_Update_a_Product_in_a_Subscription/Update_a_Product_on_Subscription_with_Future-dated_Updates) for more information about this feature.
format: date
type: string
subscriptionProductFeatures:
description: |
List of features associated with the rate plan.
The system compares the `subscriptionProductFeatures` and `featureId` fields in the request with the counterpart fields in a rate plan. The comparison results are as follows:
* If there is no `subscriptionProductFeatures` field or the field is empty, features in the rate plan remain unchanged. But if the `clearingExistingFeatures` field is additionally set to true, all features in the rate plan are cleared.
* If the `subscriptionProductFeatures` field contains the `featureId` nested fields, as well as the optional `description` and `customFields` nested fields, the features indicated by the featureId nested fields in the request overwrite all features in the rate plan.
items:
$ref: '#/components/schemas/CreateOrderRatePlanFeatureOverride'
type: array
subscriptionRatePlanNumber:
description: |
Number of a rate plan for this subscription.
type: string
uniqueToken:
description: |
A unique string to represent the rate plan in the order. The unique token is used to perform multiple actions against a newly added rate plan. For example, if you want to add and update a product in the same order, assign a unique token to the newly added rate plan and use that token in future order actions.
type: string
title: updateProduct
type: object
PreviewOrderChargeUpdate:
properties:
billing:
$ref: '#/components/schemas/BillingUpdate'
chargeNumber:
description: |
The number of the charge to be updated. The value of this field is inherited from the `subscriptions` > `orderActions` > `addProduct` > `chargeOverrides` > `chargeNumber` field.
type: string
customFields:
$ref: '#/components/schemas/RatePlanChargeObjectCustomFields'
description:
type: string
effectiveDate:
$ref: '#/components/schemas/PreviewOrderTriggerParams'
estimatedStartDate:
type: string
format: date
description: |
The estimated start date of the pending charge in an active subscription.
The value of this field must be a date within the subscription term. The system will then automatically calculate the estimated end date for the pending charge. The estimated start and end dates are used to manage the estimated charge duration and forecast the revenue for the pending charge.
**Note:** This field is available only when the Pending Subscription Processing feature is turned on.
negotiatedPriceTable:
description: |
Array of negotiated price table information. The rate card entries provided in the array will override the existing rate card entries in the standard price table to form a negotiated price table that will be
used during pricing evaluation.
**Note:** To enable the Negotiated Price Table feature, submit a request to Zuora Global Support.
items:
$ref: '#/components/schemas/NegotiatedItems'
type: array
prepaidQuantity:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
The number of units included in a [prepayment charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge). Must be a positive number (>0).
type: number
pricingAttributes:
description: |
Container for pricing attribute and value that provide additional context for dynamic pricing. The pricing attribute values included in the array will update the existing values. For the pricing attribute mapped to a Zuora object field, Zuora will retrieve the value automatically, you don’t need to pass its value explicitly. If you pass a value that doesn’t match the actual value of the Zuora object, an error will be returned.
Note that for any pricing attribute mapped to the field of Zuora object Usage, because its value is only determined when the usage record arrives, you can’t provide a value via Orders API payload and Zuora will not retrieve its value automatically.
**Note:** To enable Dynamic Pricing, submit a request to Zuora Global Support.
type: object
additionalProperties: true
pricing:
allOf:
- $ref: '#/components/schemas/PreviewOrderPricingUpdate'
description: |
Pricing information about the charge.
productRatePlanChargeId:
description: |
ID of a product rate plan charge for this subscription. When `isAddingSubsetCharges` is set to true, the product rate charge specified by `productRatePlanChargeId` is added to the existing rate plan specified by `ratePlanId`.
type: string
productRatePlanChargeNumber:
description: |
Number of a product rate plan charge for this subscription. When `isAddingSubsetCharges` is set to true, the product rate charge specified by `productRatePlanChargeNumber` is added to the existing rate plan specified by `ratePlanId`.
type: string
uniqueToken:
description: |
A unique string to represent the rate plan charge in the order. The unique token is used to perform multiple actions against a newly added rate plan charge. For example, if you want to add and update a product in the same order, assign a unique token to the newly added rate plan charge and use that token in future order actions.
type: string
type: object
OrdersRatePlanObjectCustomFields:
additionalProperties:
description: |
Custom fields of the Rate Plan object. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
description: |
Container for custom fields of the Rate Plan object. The custom fields of the Rate Plan object are used when rate plans are subscribed.
title: RatePlanCustomFields
type: object
CreateOrderRatePlanFeatureOverride:
description: |
Information about feature in rate plan.
properties:
customFields:
$ref: '#/components/schemas/RatePlanFeatureOverrideCustomFields'
description:
description: A description of the feature.
maxLength: 500
type: string
featureId:
description: |
Internal identifier of the feature in the product catalog.
type: string
required:
- featureId
title: ratePlanFeature
type: object
RatePlanFeatureOverrideCustomFields:
additionalProperties:
description: |
Custom fields of the feature. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See [Manage Custom Fields](https://knowledgecenter.zuora.com/BB_Introducing_Z_Business/Manage_Custom_Fields) for more information.
description: |
A container for custom fields of the feature.
title: ratePlanFeatureCustom
type: object
BillingUpdate:
properties:
billingPeriodAlignment:
description: |
**Note**: This field is not supported in one time charges.
enum:
- AlignToCharge
- AlignToSubscriptionStart
- AlignToTermStart
type: string
type: object
PreviewOrderTriggerParams:
description: |
Specifies when a charge becomes active.
properties:
specificTriggerDate:
description: |
Date in YYYY-MM-DD format. Only applicable if the value of the `triggerEvent` field is `SpecificDate`.
While this field is applicable, if this field is not set, your `CreateSubscription` order action creates a `Pending` order and a `Pending Acceptance` subscription. If at the same time the service activation date is required and not set, a `Pending Activation` subscription is created.
format: date
type: string
triggerEvent:
description: |
Condition for the charge to become active.
If the value of this field is `SpecificDate`, use the `specificTriggerDate` field to specify the date when the charge becomes active.
enum:
- ContractEffective
- ServiceActivation
- CustomerAcceptance
- SpecificDate
type: string
title: startDate
type: object
NegotiatedItems:
properties:
items:
description: |-
The rate card entry object.
**Note:** For more information, refer to the rate card definition in the product catalog.
additionalProperties: true
type: object
type: object
PreviewOrderPricingUpdate:
properties:
chargeModelData:
allOf:
- $ref: '#/components/schemas/ChargeModelDataOverride'
description: |
Container for charge model configuration data.
**Note**: This field is only available if you have the High Water Mark, Pre-Rated Pricing, or Multi-Attribute Pricing charge models enabled. The High Water Mark and Pre-Rated Pricing charge models are available for customers with Enterprise and Nine editions by default. If you are a Growth customer, see [Zuora Editions](https://docs.zuora.com/en/entitlements/current-entitlements/zuora-editions) for pricing information.
discount:
allOf:
- $ref: '#/components/schemas/DiscountPricingUpdate'
description: |
Pricing information about a discount charge.
recurringFlatFee:
allOf:
- $ref: '#/components/schemas/RecurringFlatFeePricingUpdate'
description: |
Pricing information about a recurring charge that uses the "flat fee" charge model. In this charge model, the charge has a fixed price.
recurringPerUnit:
allOf:
- $ref: '#/components/schemas/RecurringPerUnitPricingUpdate'
description: |
Pricing information about a recurring charge that uses the "per unit" charge model. In this charge model, the charge has a fixed price per unit purchased.
recurringTiered:
allOf:
- $ref: '#/components/schemas/RecurringTieredPricingUpdate'
description: |
Pricing information about a recurring charge that uses the "tiered pricing" charge model. In this charge model, the charge has cumulative pricing tiers that become effective as units are purchased.
recurringVolume:
allOf:
- $ref: '#/components/schemas/RecurringVolumePricingUpdate'
description: |
Pricing information about a recurring charge that uses the "volume pricing" charge model. In this charge model, the charge has a variable price per unit, depending on how many units are purchased.
type: object
ChargeModelDataOverride:
description: |
Container for charge model configuration data.
**Note**: This field is only available if you have the High Water Mark, Pre-Rated Pricing, or Multi-Attribute Pricing charge models enabled. The High Water Mark and Pre-Rated Pricing charge models are available for customers with Enterprise and Nine editions by default. If you are a Growth customer, see [Zuora Editions](https://docs.zuora.com/en/entitlements/current-entitlements/zuora-editions) for pricing information.
properties:
chargeModelConfiguration:
properties:
customFieldPerUnitRate:
description: |
The custom field that carries the per-unit rate for each usage record. For example, `perUnitAmount__c`.
This field is only available for the usage-based charges that use the Pre-Rated Per Unit Pricing charge model. The charge model is available for customers with Enterprise and Nine editions by default. If you are a Growth customer, see [Zuora Editions](https://docs.zuora.com/en/entitlements/current-entitlements/zuora-editions) for pricing information.
type: string
customFieldTotalAmount:
description: |
The custom field that carries the total amount to charge for a usage record. For example, `totalAmount__c`.
This field is only available for the usage-based charges that use the Pre-Rated Pricing charge model. The charge model is available for customers with Enterprise and Nine editions by default. If you are a Growth customer, see [Zuora Editions](https://docs.zuora.com/en/entitlements/current-entitlements/zuora-editions) for pricing information.
type: string
formula:
description: |
The pricing formula to calculate actual rating amount.
This field is only available for charges that use the Multi-Attribute Pricing charge model.
type: string
type: object
quantity:
description: |
Number of units purchased. This field is used if the Multi-Attribute Pricing formula uses the `quantity()` function.
This field is only available for one-time and recurring charges that use the Multi-Attribute Pricing charge model.
minimum: 0
type: number
tiers:
description: |
List of cumulative pricing tiers in the charge.
**Note**: When you override the tiers of a usage-based charge using High Water Mark Pricing charge model, you have to provide all of the tiers, including the ones you do not want to change. The new tiers will completely override the previous ones. The High Water Mark Pricing charge models are available for customers with Enterprise and Nine editions by default. If you are a Growth customer, see [Zuora Editions](https://docs.zuora.com/en/entitlements/current-entitlements/zuora-editions) for pricing information.
items:
$ref: '#/components/schemas/ChargeTier'
type: array
title: chargeModelData
type: object
DiscountPricingUpdate:
properties:
applyDiscountTo:
description: |
Specifies which type of charge the discount charge applies to.
enum:
- ONETIME
- RECURRING
- USAGE
- ONETIMERECURRING
- ONETIMEUSAGE
- RECURRINGUSAGE
- ONETIMERECURRINGUSAGE
type: string
discountLevel:
description: |
Application scope of the discount charge. For example, if the value of this field is `subscription` and the value of the `applyDiscountTo` field is `RECURRING`, the discount charge applies to all recurring charges in the same subscription as the discount charge.
enum:
- rateplan
- subscription
- account
type: string
discountPercentage:
description: |
The amount of the discount as a percentage. This field is only used for percentage discounts.
type: number
priceChangeOption:
description: |
Specifies how Zuora changes the price of the charge each time the subscription renews.
enum:
- NoChange
- UseLatestProductCatalogPricing
type: string
type: object
RecurringFlatFeePricingUpdate:
allOf:
- $ref: '#/components/schemas/PriceChangeParams'
- properties:
listPrice:
type: number
originalListPrice:
description: |
The original list price is the price of a product or service at which it is listed for sale by a manufacturer or retailer.
type: number
type: object
RecurringPerUnitPricingUpdate:
allOf:
- $ref: '#/components/schemas/PriceChangeParams'
- properties:
listPrice:
type: number
originalListPrice:
description: |
The original list price is the price of a product or service at which it is listed for sale by a manufacturer or retailer.
type: number
quantity:
minimum: 0
type: number
type: object
RecurringTieredPricingUpdate:
allOf:
- $ref: '#/components/schemas/PriceChangeParams'
- properties:
quantity:
minimum: 0
type: number
tiers:
items:
$ref: '#/components/schemas/ChargeTier'
type: array
type: object
RecurringVolumePricingUpdate:
allOf:
- $ref: '#/components/schemas/PriceChangeParams'
- properties:
quantity:
minimum: 0
type: number
tiers:
items:
$ref: '#/components/schemas/ChargeTier'
type: array
type: object
PriceChangeParams:
properties:
priceChangeOption:
description: |
Specifies how Zuora changes the price of the charge each time the subscription renews.
If the value of this field is `SpecificPercentageValue`, use the `priceIncreasePercentage` field to specify how much the price of the charge should change.
enum:
- NoChange
- SpecificPercentageValue
- UseLatestProductCatalogPricing
type: string
priceIncreasePercentage:
description: |
Specifies the percentage by which the price of the charge should change each time the subscription renews. Only applicable if the value of the `priceChangeOption` field is `SpecificPercentageValue`.
minimum: -100
type: number
type: object
ChargeTier:
properties:
endingUnit:
description: |
Limit on the number of units for which the tier is effective.
type: number
originalListPrice:
description: |
The original list price is the price of a product or service at which it is listed for sale by a manufacturer or retailer.
type: number
price:
description: |
Price or per-unit price of the tier, depending on the value of the `priceFormat` field.
type: number
priceFormat:
description: |
Specifies whether the tier has a fixed price or a per-unit price.
enum:
- FlatFee
- PerUnit
type: string
startingUnit:
description: |
Number of units at which the tier becomes effective.
type: number
tier:
description: |
Index of the tier in the charge.
minimum: 1
type: integer
required:
- tier
- startingUnit
- price
- priceFormat
title: chargeTier
type: object
LastTerm:
description: The length of the period for the current subscription term.
properties:
period:
description: Specify only when the termType is 'TERMED'.
minimum: 0
type: integer
periodType:
description: Specify only when the termType is 'TERMED'.
enum:
- Month
- Year
- Day
- Week
type: string
startDate:
description: |
The start date of the current term. You can change the term start date of a renewed subscription through a T&Cs order action. However, when changing it to an earlier date, this date must not be earlier than the term start date of the current term before this T&Cs.
format: date
type: string
endDate:
description: |
The end date of the current term, in YYYY-MM-DD format.
format: date
type: string
termType:
enum:
- TERMED
- EVERGREEN
type: string
required:
- termType
type: object
RenewalTerm:
properties:
period:
description: |
Duration of the renewal term in months, years, days, or weeks, depending on the value of the `periodType` field.
type: integer
periodType:
description: |
Unit of time that the renewal term is measured in.
enum:
- Month
- Year
- Day
- Week
type: string
type: object
OrderActionRatePlanChargeRemove:
description: |
The JSON object containing the information for a charge update(custom fields only) in the
'RemoveProduct' type order action.
A custom field of rate plan charge can be updated from a subscription through one
order action.
- If you update customFields of a charge while removing a rate plan, specify the following fields:
- `chargeNumber`
- `productRatePlanChargeId`
- `productRatePlanNumber`
- `uniqueToken`
- `customFields`
example:
chargeNumber: chargeNumber
productRatePlanChargeId: productRatePlanChargeId
productRatePlanNumber: productRatePlanNumber
uniqueToken: uniqueToken
customFields:
key: '{}'
properties:
chargeNumber:
description: |
Read only. Identifies the charge to be updated.
type: string
productRatePlanChargeId:
description: |
Identifier of the rate plan that was updated.
type: string
productRatePlanNumber:
description: |
Number of a product rate plan for this subscription.
type: string
uniqueToken:
description: |
A unique string to represent the rate plan charge in the order. The unique token is used to perform multiple actions against a newly added rate plan. For example, if you want to add and update a product in the same order, you would assign a unique token to the product rate plan when added and use that token in future order actions.
type: string
customFields:
additionalProperties:
description: |
Custom fields of the Rate Plan Charge object. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See [Manage Custom Fields](https://knowledgecenter.zuora.com/BB_Introducing_Z_Business/Manage_Custom_Fields) for more information.
type: object
description: |
Container for custom fields of a Rate Plan Charge object.
title: ratePlanChargeFieldsCustom
type: object
type: object
BillToContactPostOrder:
allOf:
- description: |
Contact details associated with an account.
properties:
address1:
description: |
First line of the contact's address. This is often a street address or a business name.
maxLength: 255
type: string
address2:
description: |
Second line of the contact's address.
maxLength: 255
type: string
city:
description: |
City of the contact's address.
maxLength: 100
type: string
contactDescription:
description: |
A description for the contact.
maxLength: 100
type: string
country:
description: |
Country; must be a valid country name or abbreviation. If using Zuora Tax, you must specify a country in the bill-to contact to calculate tax.
maxLength: 64
type: string
county:
description: |
County of the contact's address.
maxLength: 100
type: string
fax:
description: |
Fax number of the contact.
maxLength: 40
type: string
firstName:
description: |
First name of the contact.
maxLength: 100
type: string
homePhone:
description: |
Home phone number of the contact.
maxLength: 40
type: string
lastName:
description: |
Last name of the contact.
maxLength: 100
type: string
mobilePhone:
description: |
Mobile phone number of the contact.
maxLength: 40
type: string
nickname:
description: |
Nickname of the contact.
maxLength: 100
type: string
otherPhone:
description: |
Additional phone number of the contact. Use the `otherPhoneType` field to specify the type of phone number.
maxLength: 40
type: string
otherPhoneType:
description: |
Specifies the type of phone number in the `otherPhone` field.
enum:
- Work
- Mobile
- Home
- Other
type: string
personalEmail:
description: |
Personal email address of the contact.
format: email
maxLength: 80
type: string
postalCode:
description: |
ZIP code or other postal code of the contact's address.
maxLength: 20
type: string
state:
description: |
State or province of the contact's address.
maxLength: 100
type: string
taxRegion:
description: |
Region defined in your taxation rules. Only applicable if you use Zuora Tax.
maxLength: 100
type: string
nullable: true
workEmail:
description: |
Business email address of the contact.
format: email
maxLength: 80
type: string
workPhone:
description: |
Business phone number of the contact.
maxLength: 40
type: string
required:
- firstName
- lastName
type: object
- $ref: '#/components/schemas/ContactObjectCustomFields'
creditCard:
description: |
Default payment method associated with an account. Only credit card payment methods are supported.
properties:
cardHolderInfo:
$ref: '#/components/schemas/AccountCreditCardHolder'
cardNumber:
description: |
Card number. Once set, you cannot update or query the value of this field. The value of this field is only available in masked format. For example, XXXX-XXXX-XXXX-1234 (hyphens must not be used when you set the credit card number).
type: string
cardType:
description: |
Type of card.
enum:
- Visa
- MasterCard
- AmericanExpress
- Discover
- JCB
- Diners
- CUP
- Maestro
- Electron
- AppleVisa
- AppleMasterCard
- AppleAmericanExpress
- AppleDiscover
- AppleJCB
- Elo
- Hipercard
- Naranja
- Nativa
- TarjetaShopping
- Cencosud
- Argencard
- Cabal
type: string
expirationMonth:
description: |
Expiration date of the card.
maximum: 12
minimum: 1
type: integer
expirationYear:
description: |
Expiration year of the card.
maximum: 2500
minimum: 1980
type: integer
securityCode:
description: |
CVV or CVV2 security code of the card. To ensure PCI compliance, Zuora does not store the value of this field.
type: string
type: object
SoldToContactPostOrder:
allOf:
- description: |
Contact details associated with an account.
properties:
address1:
description: |
First line of the contact's address. This is often a street address or a business name.
maxLength: 255
type: string
address2:
description: |
Second line of the contact's address.
maxLength: 255
type: string
city:
description: |
City of the contact's address.
maxLength: 100
type: string
contactDescription:
description: |
A description for the contact.
maxLength: 100
type: string
country:
description: |
Country; must be a valid country name or abbreviation. If using Zuora Tax, you must specify a country in the sold-to contact to calculate tax. A bill-to contact may be used if no sold-to contact is provided.
maxLength: 64
type: string
county:
description: |
County of the contact's address.
maxLength: 100
type: string
fax:
description: |
Fax number of the contact.
maxLength: 40
type: string
firstName:
description: |
First name of the contact.
maxLength: 100
type: string
homePhone:
description: |
Home phone number of the contact.
maxLength: 40
type: string
lastName:
description: |
Last name of the contact.
maxLength: 100
type: string
mobilePhone:
description: |
Mobile phone number of the contact.
maxLength: 40
type: string
nickname:
description: |
Nickname of the contact.
maxLength: 100
type: string
otherPhone:
description: |
Additional phone number of the contact. Use the `otherPhoneType` field to specify the type of phone number.
maxLength: 40
type: string
otherPhoneType:
description: |
Specifies the type of phone number in the `otherPhone` field.
enum:
- Work
- Mobile
- Home
- Other
type: string
personalEmail:
description: |
Personal email address of the contact.
format: email
maxLength: 80
type: string
postalCode:
description: |
ZIP code or other postal code of the contact's address.
maxLength: 20
type: string
state:
description: |
State or province of the contact's address.
maxLength: 100
type: string
taxRegion:
description: |
Region defined in your taxation rules. Only applicable if you use Zuora Tax.
maxLength: 100
type: string
nullable: true
workEmail:
description: |
Business email address of the contact.
format: email
maxLength: 80
type: string
workPhone:
description: |
Business phone number of the contact.
maxLength: 40
type: string
required:
- firstName
- lastName
type: object
- $ref: '#/components/schemas/ContactObjectCustomFields'
TaxInfo:
description: |
Information about the tax exempt status of a customer account.
properties:
VATId:
description: |
EU Value Added Tax ID.
**Note:** This feature is in Limited Availability. If you wish to have access to the feature, submit a request at [Zuora Global Support](https://support.zuora.com).
maxLength: 25
type: string
companyCode:
description: |
Unique code that identifies a company account in Avalara. Use this field to calculate taxes based on origin and sold-to addresses in Avalara.
**Note:** This feature is in Limited Availability. If you wish to have access to the feature, submit a request at [Zuora Global Support](https://support.zuora.com).
maxLength: 50
type: string
exemptCertificateId:
description: |
ID of the customer tax exemption certificate. Applicable if you use Zuora Tax or Connect tax engines.
maxLength: 32
type: string
exemptCertificateType:
description: |
Type of tax exemption certificate that the customer holds. Applicable if you use Zuora Tax or Connect tax engines.
maxLength: 32
type: string
exemptDescription:
description: |
Description of the tax exemption certificate that the customer holds. Applicable if you use Zuora Tax or Connect tax engines.
maxLength: 500
type: string
exemptEffectiveDate:
description: |
Date when the customer tax exemption starts, in YYYY-MM-DD format. Applicable if you use Zuora Tax or Connect tax engines.
format: date
type: string
exemptExpirationDate:
description: |
Date when the customer tax exemption expires, in YYYY-MM-DD format. Applicable if you use Zuora Tax or Connect tax engines.
format: date
type: string
exemptIssuingJurisdiction:
description: |
Jurisdiction in which the customer tax exemption certificate was issued.
maxLength: 32
type: string
exemptStatus:
default: 'No'
description: |
Status of the account tax exemption. Applicable if you use Zuora Tax or Connect tax engines. Required if you use Zuora Tax.
enum:
- 'No'
- 'Yes'
- PendingVerification
type: string
title: taxInfo
type: object
AccountCreditCardHolder:
description: |
Information about the cardholder of a credit card payment method associated with an account. If you do not provide information about the cardholder, Zuora uses the account's bill-to contact.
properties:
addressLine1:
description: |
First line of the cardholder's address.
maxLength: 255
type: string
addressLine2:
description: |
Second line of the cardholder's address.
maxLength: 255
type: string
cardHolderName:
description: Full name of the cardholder as it appears on the card. For example, "John J Smith", 50 characters or less. The value must consist only of US-ASCII characters and must not include special characters.
maxLength: 50
type: string
city:
description: |
City of the cardholder's address.
It is recommended to provide the city and country information when creating a payment method. The information will be used to process payments. If the information is not provided during payment method creation, the city and country data will be missing during payment processing.
maxLength: 40
type: string
country:
description: |
Country of the cardholder's address. The value of this field must be a valid country name or abbreviation.
It is recommended to provide the city and country information when creating a payment method. The information will be used to process payments. If the information is not provided during payment method creation, the city and country data will be missing during payment processing.
maxLength: 64
type: string
email:
description: |
Email address of the cardholder.
maxLength: 80
type: string
phone:
description: |
Phone number of the cardholder.
maxLength: 40
type: string
state:
description: |
State or province of the cardholder's address.
maxLength: 50
type: string
zipCode:
description: |
ZIP code or other postal code of the cardholder's address.
maxLength: 20
type: string
type: object
PreviewOrderChangePlanRatePlanOverride:
description: |
Information about the new product rate plan to add.
properties:
chargeOverrides:
description: |
List of charges associated with the rate plan.
items:
$ref: '#/components/schemas/PreviewOrderChangePlanChargeOverride'
type: array
clearingExistingFeatures:
description: |
Specifies whether all features in the rate plan will be cleared.
type: boolean
customFields:
$ref: '#/components/schemas/OrdersRatePlanObjectCustomFields'
externalCatalogPlanId:
description: |
An external ID of the product rate plan to be added. You can use this field to specify a product rate plan that is imported from an external system. The value of the `externalCatalogPlanId` field must match one of the values that are predefined in the `externallyManagedPlanIds` field on a product rate plan.
**Note:** If both `externalCatalogPlanId` and `productRatePlanId` are provided. They must point to the same product rate plan. Otherwise, the request would fail.
type: string
externallyManagedPlanId:
description: |
Indicates the unique identifier for the rate plan purchased on a third-party store. This field is used to represent a subscription rate plan created through third-party stores.
type: string
subscriptionRatePlanNumber:
description: |
Number of a subscription rate plan for this subscription.
maxLength: 50
type: string
isFromExternalCatalog:
description: |
Indicates whether the rate plan is created from the Zuora product catalog or from an external product catalog.
**Note:** This field is available when the Standalone Orders feature is enabled.
type: boolean
productRatePlanId:
description: |
Internal identifier of the product rate plan that the rate plan is based on.
type: string
productRatePlanNumber:
description: |
Number of a product rate plan for this subscription.
type: string
ratePlanName:
description: |
Name of the standalone rate plan.
**Note:** This field is available when the Standalone Orders feature is enabled.
type: string
subscriptionProductFeatures:
description: |
List of features associated with the rate plan.
The system compares the `subscriptionProductFeatures` and `featureId` fields in the request with the counterpart fields in a rate plan. The comparison results are as follows:
* If there is no `subscriptionProductFeatures` field or the field is empty, features in the rate plan remain unchanged. But if the `clearingExistingFeatures` field is additionally set to true, all features in the rate plan are cleared.
* If the `subscriptionProductFeatures` field contains the `featureId` nested fields, as well as the optional `description` and `customFields` nested fields, the features indicated by the featureId nested fields in the request overwrite all features in the rate plan.
items:
$ref: '#/components/schemas/CreateOrderRatePlanFeatureOverride'
type: array
uniqueToken:
description: |
Unique identifier for the rate plan. This identifier enables you to refer to the rate plan before the rate plan has an internal identifier in Zuora.
For instance, suppose that you want to use a single order to add a product to a subscription and later update the same product. When you add the product, you can set a unique identifier for the rate plan. Then when you update the product, you can use the same unique identifier to specify which rate plan to modify.
maxLength: 50
type: string
title: ratePlan
type: object
PreviewOrderChangePlanChargeOverride:
description: |
Charge associated with a rate plan.
properties:
accountReceivableAccountingCode:
description: |
The accountReceivableAccountingCode of a standalone charge.
**Note:** This field is available when the Standalone Orders, Zuora Finance, and Invoice Settlement features are enabled.
type: string
adjustmentLiabilityAccountingCode:
description: |
The adjustmentLiabilityAccountingCode of a standalone charge.
**Note:** This field is available when the Standalone Orders feature and the Billing - Revenue Integration or Order to Revenue feature are enabled.
type: string
adjustmentRevenueAccountingCode:
description: |
The adjustmentRevenueAccountingCode of a standalone charge.
**Note:** This field is available when the Standalone Orders feature and the Billing - Revenue Integration or Order to Revenue feature are enabled.
type: string
billing:
description: |
Billing information about the charge.
properties:
billCycleDay:
description: |
Day of the month that each billing period begins on. Only applicable if the value of the `billCycleType` field is `SpecificDayofMonth`.
maximum: 31
minimum: 0
type: integer
billCycleType:
description: |
Specifies how Zuora determines the day that each billing period begins on.
* `DefaultFromCustomer` - Each billing period begins on the bill cycle day of the account that owns the subscription.
* `SpecificDayofMonth` - Use the `billCycleDay` field to specify the day of the month that each billing period begins on.
* `SubscriptionStartDay` - Each billing period begins on the same day of the month as the start date of the subscription.
* `ChargeTriggerDay` - Each billing period begins on the same day of the month as the date when the charge becomes active.
* `SpecificDayofWeek` - Use the `weeklyBillCycleDay` field to specify the day of the week that each billing period begins on.
enum:
- DefaultFromCustomer
- SpecificDayofMonth
- SubscriptionStartDay
- ChargeTriggerDay
- SpecificDayofWeek
type: string
billingPeriod:
description: |
Billing frequency of the charge. The value of this field controls the duration of each billing period.
If the value of this field is `Specific_Days`, `Specific_Months` or `Specific_Weeks`, use the `specificBillingPeriod` field to specify the duration of each billing period.
enum:
- Month
- Quarter
- Semi_Annual
- Annual
- Eighteen_Months
- Two_Years
- Three_Years
- Five_Years
- Specific_Months
- Subscription_Term
- Week
- Specific_Weeks
- Specific_Days
type: string
billingPeriodAlignment:
description: |
Specifies how Zuora determines when to start new billing periods. You can use this field to align the billing periods of different charges.
* `AlignToCharge` - Zuora starts a new billing period on the first billing day that falls on or after the date when the charge becomes active.
* `AlignToSubscriptionStart` - Zuora starts a new billing period on the first billing day that falls on or after the start date of the subscription.
* `AlignToTermStart` - For each term of the subscription, Zuora starts a new billing period on the first billing day that falls on or after the start date of the term.
See the `billCycleType` field for information about how Zuora determines the billing day.
**Note**: This field is not supported in one time charges.
enum:
- AlignToCharge
- AlignToSubscriptionStart
- AlignToTermStart
type: string
billingTiming:
description: |
Specifies whether to invoice for a billing period on the first day of the billing period (billing in advance) or the first day of the next billing period (billing in arrears).
enum:
- IN_ADVANCE
- IN_ARREARS
type: string
specificBillingPeriod:
description: |
Duration of each billing period in months or weeks, depending on the value of the `billingPeriod` field. Only applicable if the value of the `billingPeriod` field is `Specific_Months` or `Specific_Weeks`.
type: integer
weeklyBillCycleDay:
description: |
Day of the week that each billing period begins on. Only applicable if the value of the `billCycleType` field is `SpecificDayofWeek`.
enum:
- Sunday
- Monday
- Tuesday
- Wednesday
- Thursday
- Friday
- Saturday
type: string
type: object
chargeFunction:
description: |
**Note**: This field is only available if you have both the Prepaid with Drawdown and Standalone Orders features enabled.
With this field, you can use a standalone order to subscribe to a minimum commitment subscription.
This field defines what type of charge it is:
* CommitmentTrueUp: For recurring charges. Currency based minimum commitment charge.
* CreditCommitment: For usage charges. Credit to minimum commitment funds.
enum:
- CommitmentTrueUp
- CreditCommitment
type: string
commitmentType:
description: |
**Note**: This field is only available if you have both the Prepaid with Drawdown and Standalone Orders features enabled.
With this field, you can use a standalone order to subscribe to a minimum commitment subscription.
This field defines the type of the commitment for both the commitment true-up charge and credit commitment charge, and so you must define the type as `CURRENCY`.
enum:
- CURRENCY
type: string
creditOption:
description: |
**Note**: This field is only available if you have both the Minimum Commitment and Standalone Orders features enabled.
With this field, you can use a standalone order to subscribe to a minimum commitment subscription.
This field defines the way to calculate credit. See [Credit Option](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge#Credit_Option) for more information.
enum:
- TimeBased
- ConsumptionBased
- FullCreditBack
type: string
chargeModel:
description: |
The chargeModel of a standalone charge.
Supported charge models:
* `FlatFee`
* `PerUnit`
* `Volume`
* `Tiered`
* `DiscountFixedAmount`
* `DiscountPercentage`
**Note:** This field is available when the Standalone Orders feature is enabled.
type: string
chargeNumber:
description: |
Charge number of the charge. For example, C-00000307.
* If you do not set this field, Zuora will generate a charge number starting with a default prefix, for example, C-. This default prefix is predefined in **Billing Settings** > **Define Default Subscription and Order Settings**.
* If you want to use a custom charge number, do not use the default prefix predefined in **Billing Settings** > **Define Default Subscription and Order Settings**. Use your own prefix, for example, SC-.
maxLength: 50
type: string
chargeType:
description: |
The chargeType of a standalone charge.
Supported charge types:
* `OneTime`
* `Recurring`
* `Usage`
**Note:** This field is available when the Standalone Orders feature is enabled.
type: string
contractAssetAccountingCode:
description: |
The contractAssetAccountingCode of a standalone charge.
**Note:** This field is available when the Standalone Orders feature and the Billing - Revenue Integration or Order to Revenue feature are enabled.
type: string
contractLiabilityAccountingCode:
description: |
The contractLiabilityAccountingCode of a standalone charge.
**Note:** This field is available when the Standalone Orders feature and the Billing - Revenue Integration or Order to Revenue feature are enabled.
type: string
contractRecognizedRevenueAccountingCode:
description: |
The contractRecognizedRevenueAccountingCode of a standalone charge.
**Note:** This field is available when the Standalone Orders feature and the Billing - Revenue Integration or Order to Revenue feature are enabled.
type: string
customFields:
$ref: '#/components/schemas/RatePlanChargeObjectCustomFields'
deferredRevenueAccountingCode:
description: |
The deferredRevenueAccountingCode of a standalone charge.
**Note:** This field is available when the Standalone Orders and Zuora Finance features are enabled.
type: string
description:
description: |
Description of the charge.
maxLength: 500
type: string
drawdownRate:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
The [conversion rate](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_drawdown_charge#UOM_Conversion) between Usage UOM and Drawdown UOM for a [drawdown charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_drawdown_charge). Must be a positive number (>0).
type: number
endDate:
$ref: '#/components/schemas/EndConditions'
estimatedStartDate:
type: string
format: date
description: |
The estimated start date of the pending charge in an active subscription.
If you specify `SpecificDate` in the `startDate` > `triggerEvent` field and want to create a completed order and an active subscription, you must specify either the `estimatedStartDate` or `startDate` > `specificTriggerDate` field:
- `estimatedStartDate`: The charge will be in pending status.
- `specificTriggerDate`: The charge will be in active status.
The value of this field must be a date within the subscription term. The system will then automatically calculate the estimated end date for the pending charge. The estimated start and end dates are used to manage the estimated charge duration and forecast the revenue for the pending charge.
**Note:** This field is available only when the Pending Subscription Processing feature is turned on.
excludeItemBillingFromRevenueAccounting:
default: false
description: |
The flag to exclude rate plan charge related invoice items, invoice item adjustments, credit memo items, and debit memo items from revenue accounting.
**Note**: This field is only available if you have the Order to Revenue or [Zuora Billing - Revenue Integration](https://knowledgecenter.zuora.com/Zuora_Revenue/Zuora_Billing_-_Revenue_Integration) feature enabled.
type: boolean
excludeItemBookingFromRevenueAccounting:
default: false
description: |
The flag to exclude rate plan charges from revenue accounting.
**Note**: This field is only available if you have the Order to Revenue or [Zuora Billing - Revenue Integration](https://knowledgecenter.zuora.com/Zuora_Revenue/Zuora_Billing_-_Revenue_Integration) feature enabled.
type: boolean
isAllocationEligible:
description: |
This field is used to identify if the charge segment is allocation
eligible in revenue recognition.
**Note**: The field is only available if you have the Order to Revenue feature enabled. To enable this field, submit a request at Zuora Global Support.
type: boolean
isRollover:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
The value is either "True" or "False". It determines whether the rollover fields are needed.
type: boolean
isUnbilled:
description: |
This field is used to dictate how to perform the accounting during revenue
recognition.
**Note**: The field is only available if you have the Order to Revenue feature enabled. To enable this field, submit a request at Zuora Global Support.
type: boolean
negotiatedPriceTable:
description: |
Array of negotiated price table information. The rate card entries provided in the array will override
the existing rate card entries in the standard price table to form a negotiated price table that will be
used during pricing evaluation.
**Note:** To enable the Negotiated Price Table feature, submit a request to Zuora Global Support.
items:
$ref: '#/components/schemas/NegotiatedItems'
type: array
name:
description: |
The name of a standalone charge.
**Note:** This field is available when the Standalone Orders feature is enabled.
type: string
pobPolicy:
description: |
The pobPolicy of a standalone charge.
**Note:** This field is available when the Standalone Orders feature is enabled.
type: string
prepaidQuantity:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
The number of units included in a [prepayment charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge). Must be a positive number (>0).
type: number
pricing:
description: |
Pricing information about the charge.
properties:
chargeModelData:
$ref: '#/components/schemas/ChargeModelDataOverride'
discount:
$ref: '#/components/schemas/DiscountPricingOverride'
oneTimeFlatFee:
$ref: '#/components/schemas/OneTimeFlatFeePricingOverride'
oneTimePerUnit:
$ref: '#/components/schemas/OneTimePerUnitPricingOverride'
oneTimeTiered:
$ref: '#/components/schemas/OneTimeTieredPricingOverride'
oneTimeVolume:
$ref: '#/components/schemas/OneTimeVolumePricingOverride'
recurringDeliveryBased:
$ref: '#/components/schemas/RecurringDeliveryPricingOverride'
recurringFlatFee:
$ref: '#/components/schemas/RecurringFlatFeePricingOverride'
recurringPerUnit:
$ref: '#/components/schemas/RecurringPerUnitPricingOverride'
recurringTiered:
$ref: '#/components/schemas/RecurringTieredPricingOverride'
recurringVolume:
$ref: '#/components/schemas/RecurringVolumePricingOverride'
type: object
pricingAttributes:
description: |
Container for pricing attribute and value that provide additional context for dynamic pricing. The pricing attribute values are used to get the charge’s list price from the product catalog. For the pricing attribute mapped to a Zuora object field, Zuora will retrieve the value automatically, you don’t need to pass its value explicitly. If you pass a value that doesn’t match the actual value of the Zuora object, an error will be returned.
Note that for any pricing attribute mapped to the field of Zuora object Usage, because its value is only determined when the usage record arrives, you can’t provide a value via Orders API payload and Zuora will not retrieve its value automatically.
**Note:** To enable Dynamic Pricing, submit a request to Zuora Global Support.
type: object
additionalProperties: true
productCategory:
description: |
The productCategory of a standalone charge.
**Note:** This field is available when the Standalone Orders feature is enabled.
type: string
productClass:
description: |
The productClass of a standalone charge.
**Note:** This field is available when the Standalone Orders feature is enabled.
type: string
productFamily:
description: |
The productFamily of a standalone charge.
**Note:** This field is available when the Standalone Orders feature is enabled.
type: string
productLine:
description: |
The productLine of a standalone charge.
**Note:** This field is available when the Standalone Orders feature is enabled.
type: string
productRatePlanChargeId:
description: |
Internal identifier of the product rate plan charge that the charge is based on.
type: string
productRatePlanChargeNumber:
description: |
Number of a product rate-plan charge for this subscription.
type: string
prorationOption:
description: |
**Note**: This field is only available if you have the Charge Level Proration feature enabled. For more information, see Usage charge proration and Charge level proration option for a recurring charge.
You can use this field to specify the charge-level proration option for a usage charge or recurring charge when you creating or adding a subscription rate plan charge through an order. The tenant-level proration option will be overridden.
* `NoProration`: charge-level proration option that you can set for a usage charge. This option means to not use any proration, which is the default current system behavior for a usage charge.
* `TimeBasedProration`: charge-level proration option that you can set for a usage charge. This option means to prorate the usage charge amount using the actual number of days if the billing period is a partial period.
* `DefaultFromTenantSetting`: charge-level proration option that you can set for a recurring charge. This option means to follow the customer billing rule proration setting.
* `ChargeFullPeriod`: charge-level proration option that you can set for a recurring charge. This options means to charge the full period amount for a partial billing period. Note that this setting means that there is no proration for either collecting or refunding. Even if you cancel the recurring charge in the middle of a billing period, there is no refund for this billing period.
* `CustomizeProrationOptionOverrides`: charge-level proration option that you can set for a recurring charge. This option means to use the customized charge proration settings that is specified by the `ratingPropertiesOverride` field.
enum:
- NoProration
- TimeBasedProration
- DefaultFromTenantSetting
- ChargeFullPeriod
- CustomizeProrationOptionOverrides
type: string
ratingPropertiesOverride:
description: |
**Note**: This field is only available if you have the Charge Level Proration feature enabled. For more information, see Charge level proration option for a recurring charge.
This field is used only when the value of the `prorationOption` field is set to `CustomizeProrationOptionOverrides`.
Use this field to specify more customized proration options for a recurring charge when you creating or adding a subscription rate plan charge through an order. The tenant-level proration option will be overridden.
type: object
properties:
isProratePartialMonth:
description: |
**Note**: This field is only available if you have the Charge Level Proration feature enabled. For more information, see Charge level proration option for a recurring charge.
Use this field to specify whether to prorate the recurring charge for a partial month. The tenant-level proration option will be overridden.
type: boolean
prorationUnit:
description: |
**Note**: This field is only available if you have the Charge Level Proration feature enabled. For more information, see Charge level proration option for a recurring charge.
Use this field to specify the unit of proration for a recurring charge. The tenant-level proration option will be overridden.
enum:
- ProrateByDay
- ProrateByMonthFirst
type: string
daysInMonth:
description: |
**Note**: This field is only available if you have the Charge Level Proration feature enabled. For more information, see Charge level proration option for a recurring charge.
Use this field to specify the number of days counted for a month when prorating a recurring charge. The tenant-level proration option will be overridden. See more details for each of the following enum values in Proration.
enum:
- UseActualDays
- Assume30Days
- Assume30DaysStrict
type: string
recognizedRevenueAccountingCode:
description: |
The recognizedRevenueAccountingCode of a standalone charge.
**Note:** This field is available when the Standalone Orders and Zuora Finance features are enabled.
type: string
revRecCode:
description: |
Revenue Recognition Code
maxLength: 70
type: string
revRecTriggerCondition:
description: |
Specifies the revenue recognition trigger condition.
* `Contract Effective Date`
* `Service Activation Date`
* `Customer Acceptance Date`
enum:
- Contract Effective Date
- Service Activation Date
- Customer Acceptance Date
type: string
revenueRecognitionRuleName:
description: |
Specifies the revenue recognition rule, such as `Recognize upon invoicing` or `Recognize daily over time`.
type: string
revenueRecognitionTiming:
description: |
Specifies the type of revenue recognition timing.
Predefined options are listed as enum values in this API Reference. Other options might also be avaliable depending on the revenue recognition policy configuration in the Zuora Billing UI.
**Note**: This field is only available if you have both the Order to Revenue feature and the Standalone Orders feature enabled.
maxLength: 200
type: string
enum:
- Upon Billing Document Posting Date
- Upon Order Activation Date
revenueAmortizationMethod:
description: |
Specifies the type of revenue amortization method.
Predefined options are listed as enum values in this API Reference. Other options might also be avaliable depending on the revenue recognition policy configuration in the Zuora Billing UI.
**Note**: This field is only available if you have both the Order to Revenue feature and the Standalone Orders feature enabled.
maxLength: 200
type: string
enum:
- Immediate
- Ratable Using Start And End Dates
rolloverApply:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
This field defines the priority of rollover, which is either first or last.
enum:
- ApplyFirst
- ApplyLast
type: string
rolloverPeriodLength:
default: null
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
The period length of the rollover fund.
type: integer
rolloverPeriods:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
This field defines the number of rollover periods, it is restricted to 3.
type: number
startDate:
$ref: '#/components/schemas/CreateOrderTriggerParams'
taxCode:
description: |
The taxCode of a standalone charge.
**Note:** This field is available when the Standalone Orders feature is enabled.
type: string
taxMode:
description: |
The taxMode of a standalone charge.
Values:
* `TaxExclusive`
* `TaxInclusive`
**Note:** This field is available when the Standalone Orders feature is enabled.
type: string
unBilledReceivablesAccountingCode:
description: |
The unBilledReceivablesAccountingCode of a standalone charge.
**Note:** This field is available when the Standalone Orders feature and the Billing - Revenue Integration or Order to Revenue feature are enabled.
type: string
uniqueToken:
description: |
Unique identifier for the charge. This identifier enables you to refer to the charge before the charge has an internal identifier in Zuora.
For instance, suppose that you want to use a single order to add a product to a subscription and later update the same product. When you add the product, you can set a unique identifier for the charge. Then when you update the product, you can use the same unique identifier to specify which charge to modify.
maxLength: 50
type: string
upsellOriginChargeNumber:
description: |
The identifier of the original upselling charge associated with the current charge.
For a termed subscription, you can now use the "Create an order" API operation to perform an Add Product order action to make a product quantity upsell for per unit recurring charges. The benefit is that the charge added by this approach will be automatically combined with the original existing charge for which you want to upsell when the subscription is renewed. The approach is as follows:
* Use an Add Product order action to add a charge that is of the same charge type, charge model, and charge end date as the existing per unit recurring charge for which you want to make a quantity upsell.
* In the preceding charge to add, use the `upsellOriginChargeNumber` field to specify the existing rate plan charge for which you want to make the quantity upsell.
Note that a termed subscription with such upsell charges can not be changed to an evergreen subscription.
**Note**: The Quantity Upsell feature is in the **Early Adopter** phase. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available. If you want to join this early adopter program, submit a request at [Zuora Global
Support](https://support.zuora.com).
type: string
validityPeriodType:
description: |
**Note**: This field is only available if you have enabled either of the following:
* Prepaid with Drawdown
* Minimum Commitment
* Both Minimum Commitment and Standalone Orders
You can use this field in the following scenarios:
* When you create a [prepayment charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge), use this field to define the period in which the prepayment units are valid to use.
* When you override the setting of commitment true-up charge from the product catalog, set this field consistently with the value of the `billing` > `billingPeriod` field in this charge.
* When you use a standalone order to create a commitment true-up charge, set this field consistently with the value of the `billing` > `billingPeriod` field in this charge.
enum:
- SUBSCRIPTION_TERM
- ANNUAL
- SEMI_ANNUAL
- QUARTER
- MONTH
type: string
required:
- productRatePlanChargeId
title: charge
type: object
EndConditions:
description: |
Specifies when a charge becomes inactive.
properties:
endDateCondition:
description: |
Condition for the charge to become inactive.
- If the value of this field is `Fixed_Period`, the charge is active for a predefined duration based on the value of the `upToPeriodsType` and `upToPeriods` fields.
- If the value of this field is `Specific_End_Date`, use the `specificEndDate` field to specify the date when the charge becomes inactive.
enum:
- Subscription_End
- Fixed_Period
- Specific_End_Date
type: string
endDatePolicy:
description: |
End date policy of the discount charge to become active when the **Apply to billing period partially** checkbox is selected from the product catalog UI or the `applyToBillingPeriodPartially` field is set as true from the "CRUD: Create a product rate plan charge" operation.
- If the value of this field is `FixedPeriod`, the charge is active for a predefined duration based on the value of the `upToPeriodsType` and `upToPeriods` fields.
- If the value of this field is `SpecificEndDate`, use the `specificEndDate` field to specify the date when the charge becomes inactive.
**Notes**:
- You must enable the [Enhanced Discounts](https://knowledgecenter.zuora.com/Zuora_Billing/Build_products_and_prices/Basic_concepts_and_terms/B_Charge_Models/D_Manage_Enhanced_Discount) feature to access this field.
- You can use either `endDateCondition` or `endDatePolicy` to define when a discount charge ends, but not both at the same time.
enum:
- AlignToApplyToCharge
- SpecificEndDate
- FixedPeriod
type: string
specificEndDate:
description: |
Date in YYYY-MM-DD format. Only applicable if the value of the `endDateCondition` field is `Specific_End_Date`.
format: date
type: string
upToPeriods:
description: |
Duration of the charge in billing periods, days, weeks, months, or years, depending on the value of the `upToPeriodsType` field. Only applicable if the value of the `endDateCondition` field is `Fixed_Period`.
type: integer
upToPeriodsType:
description: |
Unit of time that the charge duration is measured in. Only applicable if the value of the `endDateCondition` field is `Fixed_Period`.
enum:
- Billing_Periods
- Days
- Weeks
- Months
- Years
type: string
title: endDate
type: object
DiscountPricingOverride:
description: |
Pricing information about a discount charge.
properties:
applyDiscountTo:
description: |
Specifies which type of charge the discount charge applies to.
enum:
- ONETIME
- RECURRING
- USAGE
- ONETIMERECURRING
- ONETIMEUSAGE
- RECURRINGUSAGE
- ONETIMERECURRINGUSAGE
type: string
applyToBillingPeriodPartially:
description: |
Allow the discount duration to be aligned with the billing period partially.
**Note**: You must enable the [Enhanced Discounts](https://knowledgecenter.zuora.com/Zuora_Billing/Build_products_and_prices/Basic_concepts_and_terms/B_Charge_Models/D_Manage_Enhanced_Discount) feature to access this field.
type: boolean
discountAmount:
description: |
Only applicable if the discount charge is a fixed-amount discount.
type: number
discountApplyDetails:
description: |
Charge list of discount be applied to.
**Note**: You must enable the [Enhanced Discounts](https://knowledgecenter.zuora.com/Zuora_Billing/Build_products_and_prices/Basic_concepts_and_terms/B_Charge_Models/D_Manage_Enhanced_Discount) feature to access this field.
items:
$ref: '#/components/schemas/DiscountApplyDetail'
type: array
discountClass:
description: |
The discount class defines the sequence in which discount product rate plan charges are applied.
**Note**: You must enable the [Enhanced Discounts](https://knowledgecenter.zuora.com/Zuora_Billing/Build_products_and_prices/Basic_concepts_and_terms/B_Charge_Models/D_Manage_Enhanced_Discount) feature to access this field.
type: string
discountLevel:
description: |
Application scope of the discount charge. For example, if the value of this field is `subscription` and the value of the `applyDiscountTo` field is `RECURRING`, the discount charge applies to all recurring charges in the same subscription as the discount charge.
enum:
- rateplan
- subscription
- account
type: string
discountPercentage:
description: |
Only applicable if the discount charge is a percentage discount.
type: number
originalDiscountAmount:
description: |
The manufacturer's suggested retail discount price for standalone charge.
Only applicable if the standalone discount charge is a fixed-amount discount.
**Note:** This field is available when the Standalone Orders feature is enabled.
type: number
originalDiscountPercentage:
description: |
The manufacturer's suggested retail discount percentage for standalone charge.
Only applicable if the standalone discount charge is a percentage discount.
**Note:** This field is available when the Standalone Orders feature is enabled.
type: number
priceChangeOption:
description: |
Specifies how Zuora changes the price of the charge each time the subscription renews.
enum:
- NoChange
- UseLatestProductCatalogPricing
type: string
title: discount
type: object
OneTimeFlatFeePricingOverride:
description: |
Pricing information about a one-time charge that uses the "flat fee" charge model. In this charge model, the charge has a fixed price.
properties:
listPrice:
description: |
Price of the charge.
type: number
originalListPrice:
description: |
The original list price is the price of a product or service at which it is listed for sale by a manufacturer or retailer.
type: number
required:
- listPrice
title: oneTimeFlatFee
type: object
OneTimePerUnitPricingOverride:
description: |
Pricing information about a one-time charge that uses the "per unit" charge model. In this charge model, the charge has a fixed price per unit purchased.
properties:
listPrice:
description: |
Per-unit price of the charge.
type: number
originalListPrice:
description: |
The original list price is the price of a product or service at which it is listed for sale by a manufacturer or retailer.
type: number
quantity:
description: |
Number of units purchased.
minimum: 0
type: number
uom:
description: |
Unit of measure of the standalone charge.
**Note:** This field is available when the Standalone Orders feature is enabled.
type: number
title: oneTimePerUnit
type: object
OneTimeTieredPricingOverride:
description: |
Pricing information about a one-time charge that uses the "tiered pricing" charge model. In this charge model, the charge has cumulative pricing tiers that become effective as units are purchased.
properties:
quantity:
description: |
Number of units purchased.
minimum: 0
type: number
tiers:
description: |
List of cumulative pricing tiers in the charge.
items:
$ref: '#/components/schemas/ChargeTier'
type: array
uom:
description: |
Unit of measure of the standalone charge.
**Note:** This field is available when the Standalone Orders feature is enabled.
type: number
title: oneTimeTiered
type: object
OneTimeVolumePricingOverride:
description: |
Pricing information about a one-time charge that uses the "volume pricing" charge model. In this charge model, the charge has a variable price per unit, depending on how many units are purchased.
properties:
quantity:
description: |
Number of units purchased.
minimum: 0
type: number
tiers:
description: |
List of variable pricing tiers in the charge.
items:
$ref: '#/components/schemas/ChargeTier'
type: array
uom:
description: |
Unit of measure of the standalone charge.
**Note:** This field is available when the Standalone Orders feature is enabled.
type: number
title: oneTimeVolume
type: object
RecurringDeliveryPricingOverride:
allOf:
- $ref: '#/components/schemas/PriceChangeParams'
- properties:
deliverySchedule:
$ref: '#/components/schemas/DeliveryScheduleParams'
listPrice:
description: |
Price of the charge in each recurring period.
type: number
description: |
Pricing information about a recurring charge that uses the Delivery Pricing charge model. In this charge model, the charge has a fixed price. This field is only available if you have the Delivery Pricing charge model enabled.
title: recurringDelivery
RecurringFlatFeePricingOverride:
allOf:
- $ref: '#/components/schemas/PriceChangeParams'
- properties:
listPrice:
description: |
Price of the charge in each recurring period.
type: number
listPriceBase:
description: |
Specifies the duration of each recurring period.
enum:
- Per_Billing_Period
- Per_Month
- Per_Week
- Per_Year
- Per_Specific_Months
type: string
originalListPrice:
description: |
The original list price is the price of a product or service at which it is listed for sale by a manufacturer or retailer.
type: number
specificListPriceBase:
description: |
The number of months for the list price base of the charge. This field is required if you set the value of the `listPriceBase` field to `Per_Specific_Months`.
**Note**:
- This field is available only if you have the Annual List Price feature enabled.
- The value of this field is `null` if you do not set the value of the `listPriceBase` field to `Per_Specific_Months`.
format: int32
maximum: 200
minimum: 1
type: integer
type: object
description: |
Pricing information about a recurring charge that uses the "flat fee" charge model. In this charge model, the charge has a fixed price.
title: recurringFlatFee
RecurringPerUnitPricingOverride:
allOf:
- $ref: '#/components/schemas/PriceChangeParams'
- properties:
listPrice:
description: |
Per-unit price of the charge in each recurring period.
type: number
listPriceBase:
description: |
Specifies the duration of each recurring period.
enum:
- Per_Billing_Period
- Per_Month
- Per_Week
- Per_Year
- Per_Specific_Months
type: string
originalListPrice:
description: |
The original list price is the price of a product or service at which it is listed for sale by a manufacturer or retailer.
type: number
quantity:
description: |
Number of units purchased.
minimum: 0
type: number
specificListPriceBase:
description: |
The number of months for the list price base of the charge. This field is required if you set the value of the `listPriceBase` field to `Per_Specific_Months`.
**Note**:
- This field is available only if you have the Annual List Price feature enabled.
- The value of this field is `null` if you do not set the value of the `listPriceBase` field to `Per_Specific_Months`.
format: int32
maximum: 200
minimum: 1
type: integer
uom:
description: |
Unit of measure of the standalone charge.
**Note:** This field is available when the Standalone Orders feature is enabled.
type: number
type: object
description: |
Pricing information about a recurring charge that uses the "per unit" charge model. In this charge model, the charge has a fixed price per unit purchased.
title: recurringPerUnit
RecurringTieredPricingOverride:
allOf:
- $ref: '#/components/schemas/PriceChangeParams'
- properties:
listPriceBase:
description: |
Specifies the duration of each recurring period.
enum:
- Per_Billing_Period
- Per_Month
- Per_Week
- Per_Year
- Per_Specific_Months
type: string
quantity:
description: |
Number of units purchased.
minimum: 0
type: number
specificListPriceBase:
description: |
The number of months for the list price base of the charge. This field is required if you set the value of the `listPriceBase` field to `Per_Specific_Months`.
**Note**:
- This field is available only if you have the Annual List Price feature enabled.
- The value of this field is `null` if you do not set the value of the `listPriceBase` field to `Per_Specific_Months`.
format: int32
maximum: 200
minimum: 1
type: integer
tiers:
description: |
List of cumulative pricing tiers in the charge.
items:
$ref: '#/components/schemas/ChargeTier'
type: array
uom:
description: |
Unit of measure of the standalone charge.
**Note:** This field is available when the Standalone Orders feature is enabled.
type: number
type: object
description: |
Pricing information about a recurring charge that uses the "tiered pricing" charge model. In this charge model, the charge has cumulative pricing tiers that become effective as units are purchased.
title: recurringTiered
RecurringVolumePricingOverride:
allOf:
- $ref: '#/components/schemas/PriceChangeParams'
- properties:
listPriceBase:
description: |
Specifies the duration of each recurring period.
enum:
- Per_Billing_Period
- Per_Month
- Per_Week
- Per_Year
- Per_Specific_Months
type: string
quantity:
description: |
Number of units purchased.
minimum: 0
type: number
specificListPriceBase:
description: |
The number of months for the list price base of the charge. This field is required if you set the value of the `listPriceBase` field to `Per_Specific_Months`.
**Note**:
- This field is available only if you have the Annual List Price feature enabled.
- The value of this field is `null` if you do not set the value of the `listPriceBase` field to `Per_Specific_Months`.
format: int32
maximum: 200
minimum: 1
type: integer
tiers:
description: |
List of variable pricing tiers in the charge.
items:
$ref: '#/components/schemas/ChargeTier'
type: array
uom:
description: |
Unit of measure of the standalone charge.
**Note:** This field is available when the Standalone Orders feature is enabled.
type: number
type: object
description: |
Pricing information about a recurring charge that uses the "volume pricing" charge model. In this charge model, the charge has a variable price per unit, depending on how many units are purchased.
title: recurringVolume
CreateOrderTriggerParams:
description: |
Specifies when a charge becomes active.
properties:
periodsAfterChargeStart:
description: |
Duration of the discount charge in days, weeks, months, or years, depending on the value of the `startPeriodsType` field. Only applicable if the value of the `startDatePolicy` field is `FixedPeriodAfterApplyToChargeStartDate`.
**Note**: You must enable the [Enhanced Discounts](https://knowledgecenter.zuora.com/Zuora_Billing/Build_products_and_prices/Basic_concepts_and_terms/B_Charge_Models/D_Manage_Enhanced_Discount) feature to access this field.
type: integer
specificTriggerDate:
description: |
Date in YYYY-MM-DD format. Only applicable if the value of the `triggerEvent` field is `SpecificDate`.
While this field is applicable, if this field is not set, your `CreateSubscription` order action creates a `Pending` order and a `Pending Acceptance` subscription. If at the same time the service activation date is required and not set, a `Pending Activation` subscription is created.
While this field is applicable, if this field is not set, the following order actions create a `Pending` order but do not impact the subscription status. **Note**: This feature is in **Limited Availability**. If you want to have access to the feature, submit a request at [Zuora Global Support](http://support.zuora.com/).
* AddProduct
* UpdateProduct
* RemoveProduct
* RenewSubscription
* TermsAndConditions
format: date
type: string
startDatePolicy:
description: |
Start date policy of the discount charge to become active when the **Apply to billing period partially** checkbox is selected from the product catalog UI or the `applyToBillingPeriodPartially` field is set as true from the "CRUD: Create a product rate plan charge" operation.
- If the value of this field is `SpecificDate`, use the `specificTriggerDate` field to specify the date when the charge becomes active.
- If the value of this field is `FixedPeriodAfterApplyToChargeStartDate`, the charge is active for a predefined duration based on the value of the `upToPeriodsType` and `upToPeriods` fields.
**Notes**:
- You must enable the [Enhanced Discounts](https://knowledgecenter.zuora.com/Zuora_Billing/Build_products_and_prices/Basic_concepts_and_terms/B_Charge_Models/D_Manage_Enhanced_Discount) feature to access this field.
- You can use either `triggerEvent` or `startDatePolicy` to define when a discount charge starts, but not both at the same time.
enum:
- AlignToApplyToCharge
- SpecificDate
- EndOfLastInvoicePeriodOfApplyToCharge
- FixedPeriodAfterApplyToChargeStartDate
type: string
startPeriodsType:
description: |
Unit of time that the discount charge duration is measured in. Only applicable if the value of the `startDatePolicy` field is `FixedPeriodAfterApplyToChargeStartDate`.
**Note**: You must enable the [Enhanced Discounts](https://knowledgecenter.zuora.com/Zuora_Billing/Build_products_and_prices/Basic_concepts_and_terms/B_Charge_Models/D_Manage_Enhanced_Discount) feature to access this field.
enum:
- Days
- Weeks
- Months
- Years
type: string
triggerEvent:
description: |
Condition for the charge to become active.
If the value of this field is `SpecificDate`, use the `specificTriggerDate` field to specify the date when the charge becomes active.
enum:
- ContractEffective
- ServiceActivation
- CustomerAcceptance
- SpecificDate
type: string
title: startDate
type: object
DeliveryScheduleParams:
properties:
frequency:
description: |
Specifies the frequency for delivery schedule
enum:
- Weekly
type: string
friday:
description: |
Indicates whether delivery on friday.
type: boolean
monday:
description: |
Indicates whether delivery on monday.
type: boolean
saturday:
description: |
Indicates whether delivery on saturday.
type: boolean
sunday:
description: |
Indicates whether delivery on sunday.
type: boolean
thursday:
description: |
Indicates whether delivery on thursday.
type: boolean
tuesday:
description: |
Indicates whether delivery on tuesday.
type: boolean
wednesday:
description: |
Indicates whether delivery on wednesday.
type: boolean
type: object
DiscountApplyDetail:
properties:
productRatePlanChargeId:
description: |
Product Rate Plan Charge Id of the discount apply to.
type: string
productRatePlanId:
description: |
Product Rate Plan Id of the discount apply to.
type: string
required:
- productRatePlanId
- productRatePlanChargeId
title: discountApplyDetail
type: object
PreviewOrderChargeOverride:
description: |
Charge associated with a rate plan.
properties:
accountReceivableAccountingCode:
description: |
The accountReceivableAccountingCode of a standalone charge.
**Note:** This field is available when the Standalone Orders, Zuora Finance, and Invoice Settlement features are enabled.
type: string
adjustmentLiabilityAccountingCode:
description: |
The adjustmentLiabilityAccountingCode of a standalone charge.
**Note:** This field is available when the Standalone Orders feature and the Billing - Revenue Integration or Order to Revenue feature are enabled.
type: string
adjustmentRevenueAccountingCode:
description: |
The adjustmentRevenueAccountingCode of a standalone charge.
**Note:** This field is available when the Standalone Orders feature and the Billing - Revenue Integration or Order to Revenue feature are enabled.
type: string
billing:
description: |
Billing information about the charge.
properties:
billCycleDay:
description: |
Day of the month that each billing period begins on. Only applicable if the value of the `billCycleType` field is `SpecificDayofMonth`.
maximum: 31
minimum: 0
type: integer
billCycleType:
description: |
Specifies how Zuora determines the day that each billing period begins on.
* `DefaultFromCustomer` - Each billing period begins on the bill cycle day of the account that owns the subscription.
* `SpecificDayofMonth` - Use the `billCycleDay` field to specify the day of the month that each billing period begins on.
* `SubscriptionStartDay` - Each billing period begins on the same day of the month as the start date of the subscription.
* `ChargeTriggerDay` - Each billing period begins on the same day of the month as the date when the charge becomes active.
* `SpecificDayofWeek` - Use the `weeklyBillCycleDay` field to specify the day of the week that each billing period begins on.
enum:
- DefaultFromCustomer
- SpecificDayofMonth
- SubscriptionStartDay
- ChargeTriggerDay
- SpecificDayofWeek
type: string
billingPeriod:
description: |
Billing frequency of the charge. The value of this field controls the duration of each billing period.
If the value of this field is `Specific_Days`, `Specific_Months` or `Specific_Weeks`, use the `specificBillingPeriod` field to specify the duration of each billing period.
enum:
- Month
- Quarter
- Semi_Annual
- Annual
- Eighteen_Months
- Two_Years
- Three_Years
- Five_Years
- Specific_Months
- Subscription_Term
- Week
- Specific_Weeks
- Specific_Days
type: string
billingPeriodAlignment:
description: |
Specifies how Zuora determines when to start new billing periods. You can use this field to align the billing periods of different charges.
* `AlignToCharge` - Zuora starts a new billing period on the first billing day that falls on or after the date when the charge becomes active.
* `AlignToSubscriptionStart` - Zuora starts a new billing period on the first billing day that falls on or after the start date of the subscription.
* `AlignToTermStart` - For each term of the subscription, Zuora starts a new billing period on the first billing day that falls on or after the start date of the term.
See the `billCycleType` field for information about how Zuora determines the billing day.
**Note**: This field is not supported in one time charges.
enum:
- AlignToCharge
- AlignToSubscriptionStart
- AlignToTermStart
type: string
billingTiming:
description: |
Specifies whether to invoice for a billing period on the first day of the billing period (billing in advance) or the first day of the next billing period (billing in arrears).
enum:
- IN_ADVANCE
- IN_ARREARS
type: string
specificBillingPeriod:
description: |
Duration of each billing period in months or weeks, depending on the value of the `billingPeriod` field. Only applicable if the value of the `billingPeriod` field is `Specific_Months` or `Specific_Weeks`.
type: integer
weeklyBillCycleDay:
description: |
Day of the week that each billing period begins on. Only applicable if the value of the `billCycleType` field is `SpecificDayofWeek`.
enum:
- Sunday
- Monday
- Tuesday
- Wednesday
- Thursday
- Friday
- Saturday
type: string
type: object
chargeFunction:
description: |
**Note**: This field is only available if you have both the Prepaid with Drawdown and Standalone Orders features enabled.
With this field, you can use a standalone order to subscribe to a minimum commitment subscription.
This field defines what type of charge it is:
* CommitmentTrueUp: For recurring charges. Currency based minimum commitment charge.
* CreditCommitment: For usage charges. Credit to minimum commitment funds.
enum:
- CommitmentTrueUp
- CreditCommitment
type: string
commitmentType:
description: |
**Note**: This field is only available if you have both the Prepaid with Drawdown target="_blank">Minimum Commitment and Standalone Orders features enabled.
With this field, you can use a standalone order to subscribe to a minimum commitment subscription.
This field defines the type of the commitment for both the commitment true-up charge and credit commitment charge, and so you must define the type as `CURRENCY`.
enum:
- CURRENCY
type: string
creditOption:
description: |
**Note**: This field is only available if you have both the Minimum Commitment and Standalone Orders features enabled.
With this field, you can use a standalone order to subscribe to a minimum commitment subscription.
This field defines the way to calculate credit. See [Credit Option](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge#Credit_Option) for more information.
enum:
- TimeBased
- ConsumptionBased
- FullCreditBack
type: string
chargeModel:
description: |
The chargeModel of a standalone charge.
Supported charge models:
* `FlatFee`
* `PerUnit`
* `Volume`
* `Tiered`
* `DiscountFixedAmount`
* `DiscountPercentage`
**Note:** This field is available when the Standalone Orders feature is enabled.
type: string
chargeNumber:
description: |
Charge number of the charge. For example, C-00000307.
* If you do not set this field, Zuora will generate a charge number starting with a default prefix, for example, C-. This default prefix is predefined in **Billing Settings** > **Define Default Subscription and Order Settings**.
* If you want to use a custom charge number, do not use the default prefix predefined in **Billing Settings** > **Define Default Subscription and Order Settings**. Use your own prefix, for example, SC-.
maxLength: 50
type: string
chargeType:
description: |
The chargeType of a standalone charge.
Supported charge types:
* `OneTime`
* `Recurring`
* `Usage`
**Note:** This field is available when the Standalone Orders feature is enabled.
type: string
contractAssetAccountingCode:
description: |
The contractAssetAccountingCode of a standalone charge.
**Note:** This field is available when the Standalone Orders feature and the Billing - Revenue Integration or Order to Revenue feature are enabled.
type: string
contractLiabilityAccountingCode:
description: |
The contractLiabilityAccountingCode of a standalone charge.
**Note:** This field is available when the Standalone Orders feature and the Billing - Revenue Integration or Order to Revenue feature are enabled.
type: string
contractRecognizedRevenueAccountingCode:
description: |
The contractRecognizedRevenueAccountingCode of a standalone charge.
**Note:** This field is available when the Standalone Orders feature and the Billing - Revenue Integration or Order to Revenue feature are enabled.
type: string
customFields:
$ref: '#/components/schemas/RatePlanChargeObjectCustomFields'
deferredRevenueAccountingCode:
description: |
The deferredRevenueAccountingCode of a standalone charge.
**Note:** This field is available when the Standalone Orders and Zuora Finance features are enabled.
type: string
description:
description: |
Description of the charge.
maxLength: 500
type: string
drawdownRate:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
The [conversion rate](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_drawdown_charge#UOM_Conversion) between Usage UOM and Drawdown UOM for a [drawdown charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_drawdown_charge). Must be a positive number (>0).
type: number
endDate:
$ref: '#/components/schemas/EndConditions'
estimatedStartDate:
type: string
format: date
description: |
The estimated start date of the pending charge in an active subscription.
If you specify `SpecificDate` in the `startDate` > `triggerEvent` field and want to create a completed order and an active subscription, you must specify either the `estimatedStartDate` or `startDate` > `specificTriggerDate` field:
- `estimatedStartDate`: The charge will be in pending status.
- `specificTriggerDate`: The charge will be in active status.
The value of this field must be a date within the subscription term. The system will then automatically calculate the estimated end date for the pending charge. The estimated start and end dates are used to manage the estimated charge duration and forecast the revenue for the pending charge.
**Note:** This field is available only when the Pending Subscription Processing feature is turned on.
excludeItemBillingFromRevenueAccounting:
default: false
description: |
The flag to exclude rate plan charge related invoice items, invoice item adjustments, credit memo items, and debit memo items from revenue accounting.
If both the following features are enabled in your tenant, you must ensure the `excludeItemBillingFromRevenueAccounting` field is set consistently for a prepayment charge and the corresponding drawdown charge. In addition, if the `excludeItemBookingFromRevenueAccounting` field in a Create Subscription or Add Product order action is set to `false`, you must also set the `excludeItemBillingFromRevenueAccounting` field in this order action to `false`.
* Prepaid with Drawdown
* Unbilled Usage
**Note**: This field is only available if you have the Order to Revenue or [Zuora Billing - Revenue Integration](https://knowledgecenter.zuora.com/Zuora_Revenue/Zuora_Billing_-_Revenue_Integration) feature enabled.
type: boolean
excludeItemBookingFromRevenueAccounting:
default: false
description: |
The flag to exclude rate plan charges from revenue accounting.
If both the following features are enabled in your tenant, you must ensure the `excludeItemBookingFromRevenueAccounting` field is set consistently for a prepayment charge and the corresponding drawdown charge.
* Prepaid with Drawdown
* Unbilled Usage
**Note**: This field is only available if you have the Order to Revenue or [Zuora Billing - Revenue Integration](https://knowledgecenter.zuora.com/Zuora_Revenue/Zuora_Billing_-_Revenue_Integration) feature enabled.
type: boolean
isAllocationEligible:
description: |
This field is used to identify if the charge segment is allocation
eligible in revenue recognition.
**Note**: The field is only available if you have the Order to Revenue feature enabled. To enable this field, submit a request at Zuora Global Support.
type: boolean
isRollover:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
The value is either "True" or "False". It determines whether the rollover fields are needed.
type: boolean
isUnbilled:
description: |
This field is used to dictate how to perform the accounting during revenue
recognition.
**Note**: The field is only available if you have the Order to Revenue feature enabled. To enable this field, submit a request at Zuora Global Support.
type: boolean
name:
description: |
The name of a standalone charge.
**Note:** This field is available when the Standalone Orders feature is enabled.
type: string
negotiatedPriceTable:
description: |
Array of negotiated price table information. The rate card entries provided in the array will override
the existing rate card entries in the standard price table to form a negotiated price table that will be
used during pricing evaluation.
**Note:** To enable the Negotiated Price Table feature, submit a request to Zuora Global Support.
items:
$ref: '#/components/schemas/NegotiatedItems'
type: array
pobPolicy:
description: |
The pobPolicy of a standalone charge.
**Note:** This field is available when the Standalone Orders feature is enabled.
type: string
prepaidQuantity:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
The number of units included in a [prepayment charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge). Must be a positive number (>0).
type: number
pricing:
description: |
Pricing information about the charge.
properties:
chargeModelData:
$ref: '#/components/schemas/ChargeModelDataOverride'
discount:
$ref: '#/components/schemas/DiscountPricingOverride'
oneTimeFlatFee:
$ref: '#/components/schemas/OneTimeFlatFeePricingOverride'
oneTimePerUnit:
$ref: '#/components/schemas/OneTimePerUnitPricingOverride'
oneTimeTiered:
$ref: '#/components/schemas/OneTimeTieredPricingOverride'
oneTimeVolume:
$ref: '#/components/schemas/OneTimeVolumePricingOverride'
recurringDeliveryBased:
$ref: '#/components/schemas/RecurringDeliveryPricingOverride'
recurringFlatFee:
$ref: '#/components/schemas/RecurringFlatFeePricingOverride'
recurringPerUnit:
$ref: '#/components/schemas/RecurringPerUnitPricingOverride'
recurringTiered:
$ref: '#/components/schemas/RecurringTieredPricingOverride'
recurringVolume:
$ref: '#/components/schemas/RecurringVolumePricingOverride'
type: object
pricingAttributes:
description: |
Container for pricing attribute and value that provide additional context for dynamic pricing. The pricing attribute values are used to get the charge’s list price from the product catalog. For the pricing attribute mapped to a Zuora object field, Zuora will retrieve the value automatically, you don’t need to pass its value explicitly. If you pass a value that doesn’t match the actual value of the Zuora object, an error will be returned.
Note that for any pricing attribute mapped to the field of Zuora object Usage, because its value is only determined when the usage record arrives, you can’t provide a value via Orders API payload and Zuora will not retrieve its value automatically.
**Note:** To enable Dynamic Pricing, submit a request to Zuora Global Support.
type: object
additionalProperties: true
productCategory:
description: |
The productCategory of a standalone charge.
**Note:** This field is available when the Standalone Orders feature is enabled.
type: string
productClass:
description: |
The productClass of a standalone charge.
**Note:** This field is available when the Standalone Orders feature is enabled.
type: string
productFamily:
description: |
The productFamily of a standalone charge.
**Note:** This field is available when the Standalone Orders feature is enabled.
type: string
productLine:
description: |
The productLine of a standalone charge.
**Note:** This field is available when the Standalone Orders feature is enabled.
type: string
productRatePlanChargeId:
description: |
Internal identifier of the product rate plan charge that the charge is based on.
type: string
productRatePlanChargeNumber:
description: |
Number of a product rate-plan charge for this subscription.
type: string
prorationOption:
description: |
**Note**: This field is only available if you have the Charge Level Proration feature enabled. For more information, see Usage charge proration and Charge level proration option for a recurring charge.
You can use this field to specify the charge-level proration option for a usage charge or recurring charge when you creating or adding a subscription rate plan charge through an order. The tenant-level proration option will be overridden.
* `NoProration`: charge-level proration option that you can set for a usage charge. This option means to not use any proration, which is the default current system behavior for a usage charge.
* `TimeBasedProration`: charge-level proration option that you can set for a usage charge. This option means to prorate the usage charge amount using the actual number of days if the billing period is a partial period.
* `DefaultFromTenantSetting`: charge-level proration option that you can set for a recurring charge. This option means to follow the customer billing rule proration setting.
* `ChargeFullPeriod`: charge-level proration option that you can set for a recurring charge. This options means to charge the full period amount for a partial billing period. Note that this setting means that there is no proration for either collecting or refunding. Even if you cancel the recurring charge in the middle of a billing period, there is no refund for this billing period.
* `CustomizeProrationOptionOverrides`: charge-level proration option that you can set for a recurring charge. This option means to use the customized charge proration settings that is specified by the `ratingPropertiesOverride` field.
enum:
- NoProration
- TimeBasedProration
- DefaultFromTenantSetting
- ChargeFullPeriod
- CustomizeProrationOptionOverrides
type: string
ratingPropertiesOverride:
description: |
**Note**: This field is only available if you have the Charge Level Proration feature enabled. For more information, see Charge level proration option for a recurring charge.
This field is used only when the value of the `prorationOption` field is set to `CustomizeProrationOptionOverrides`.
Use this field to specify more customized proration options for a recurring charge when you creating or adding a subscription rate plan charge through an order. The tenant-level proration option will be overridden.
type: object
properties:
isProratePartialMonth:
description: |
**Note**: This field is only available if you have the Charge Level Proration feature enabled. For more information, see Charge level proration option for a recurring charge.
Use this field to specify whether to prorate the recurring charge for a partial month. The tenant-level proration option will be overridden.
type: boolean
prorationUnit:
description: |
**Note**: This field is only available if you have the Charge Level Proration feature enabled. For more information, see Charge level proration option for a recurring charge.
Use this field to specify the unit of proration for a recurring charge. The tenant-level proration option will be overridden.
enum:
- ProrateByDay
- ProrateByMonthFirst
type: string
daysInMonth:
description: |
**Note**: This field is only available if you have the Charge Level Proration feature enabled. For more information, see Charge level proration option for a recurring charge.
Use this field to specify the number of days counted for a month when prorating a recurring charge. The tenant-level proration option will be overridden. See more details for each of the following enum values in Proration.
enum:
- UseActualDays
- Assume30Days
- Assume30DaysStrict
type: string
recognizedRevenueAccountingCode:
description: |
The recognizedRevenueAccountingCode of a standalone charge.
**Note:** This field is available when the Standalone Orders and Zuora Finance features are enabled.
type: string
revRecCode:
description: |
Revenue Recognition Code
maxLength: 70
type: string
revRecTriggerCondition:
description: |
Specifies the revenue recognition trigger condition.
* `Contract Effective Date`
* `Service Activation Date`
* `Customer Acceptance Date`
enum:
- Contract Effective Date
- Service Activation Date
- Customer Acceptance Date
type: string
revenueRecognitionRuleName:
description: |
Specifies the revenue recognition rule, such as `Recognize upon invoicing` or `Recognize daily over time`.
type: string
revenueRecognitionTiming:
description: |
Specifies the type of revenue recognition timing.
Predefined options are listed as enum values in this API Reference. Other options might also be avaliable depending on the revenue recognition policy configuration in the Zuora Billing UI.
**Note**: This field is only available if you have both the Order to Revenue feature and the Standalone Orders feature enabled.
maxLength: 200
type: string
enum:
- Upon Billing Document Posting Date
- Upon Order Activation Date
revenueAmortizationMethod:
description: |
Specifies the type of revenue amortization method.
Predefined options are listed as enum values in this API Reference. Other options might also be avaliable depending on the revenue recognition policy configuration in the Zuora Billing UI.
**Note**: This field is only available if you have both the Order to Revenue feature and the Standalone Orders feature enabled.
maxLength: 200
type: string
enum:
- Immediate
- Ratable Using Start And End Dates
rolloverApply:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
This field defines the priority of rollover, which is either first or last.
enum:
- ApplyFirst
- ApplyLast
type: string
rolloverPeriodLength:
default: null
description: |
**Note**: This field is only available if you have the [Prepaid with
Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown)
feature enabled.
Use this field when you want to set the rollover fund's period length shorter than the prepayment charge's validity period. In this case, you must set the `rolloverPeriods` field to 1. For example, you can define the rollover fund's period length as 5 months, shorter than the prepayment charge's validity period: a year.
type: integer
rolloverPeriods:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
This field defines the number of rollover periods, it is restricted to 3.
type: number
startDate:
$ref: '#/components/schemas/PreviewOrderTriggerParams'
unBilledReceivablesAccountingCode:
description: |
The unBilledReceivablesAccountingCode of a standalone charge.
**Note:** This field is available when the Standalone Orders feature and the Billing - Revenue Integration or Order to Revenue feature are enabled.
type: string
uniqueToken:
description: |
Unique identifier for the charge. This identifier enables you to refer to the charge before the charge has an internal identifier in Zuora.
For instance, suppose that you want to use a single order to add a product to a subscription and later update the same product. When you add the product, you can set a unique identifier for the charge. Then when you update the product, you can use the same unique identifier to specify which charge to modify.
maxLength: 50
type: string
upsellOriginChargeNumber:
description: |
The identifier of the original upselling charge associated with the current charge.
For a termed subscription, you can now use the "Create an order" API operation to perform an Add Product order action to make a product quantity upsell for per unit recurring charges. The benefit is that the charge added by this approach will be automatically combined with the original existing charge for which you want to upsell when the subscription is renewed. The approach is as follows:
* Use an Add Product order action to add a charge that is of the same charge type, charge model, and charge end date as the existing per unit recurring charge for which you want to make a quantity upsell.
* In the preceding charge to add, use the `upsellOriginChargeNumber` field to specify the existing rate plan charge for which you want to make the quantity upsell.
Note that a termed subscription with such upsell charges can not be changed to an evergreen subscription.
**Note**: The Quantity Upsell feature is in the **Early Adopter** phase. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available. If you want to join this early adopter program, submit a request at [Zuora Global
Support](https://support.zuora.com).
type: string
validityPeriodType:
description: |
**Note**: This field is only available if you have enabled either of the following:
* Prepaid with Drawdown
* Minimum Commitment
* Both Minimum Commitment and Standalone Orders
You can use this field in the following scenarios:
* When you create a [prepayment charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge), use this field to define the period in which the prepayment units are valid to use.
* When you override the setting of commitment true-up charge from the product catalog, set this field consistently with the value of the `billing` > `billingPeriod` field in this charge.
* When you use a standalone order to create a commitment true-up charge, set this field consistently with the value of the `billing` > `billingPeriod` field in this charge.
enum:
- SUBSCRIPTION_TERM
- ANNUAL
- SEMI_ANNUAL
- QUARTER
- MONTH
type: string
taxCode:
description: |
The tax code of a charge. This field is available when the `taxable` field is set to `true`.
type: string
taxMode:
description: |
The tax mode of a charge. This field is available when the `taxable` field is set to `true`.
enum:
- TaxInclusive
- TaxExclusive
type: string
taxable:
description: |
The flag indicates whether the charge is taxable. If this field is set to `true`, you must specify the `taxCode` and `taxMode` fields.
type: boolean
required:
- productRatePlanChargeId
title: charge
type: object
PreviewContactInfo:
description: |
Contact details associated with an account.
properties:
address1:
description: |
First line of the contact's address. This is often a street address or a business name.
maxLength: 255
type: string
address2:
description: |
Second line of the contact's address.
maxLength: 255
type: string
city:
maxLength: 100
type: string
country:
description: Country; must be a valid country name or abbreviation. If using Zuora Tax, you must specify a country to calculate tax.
maxLength: 64
type: string
county:
maxLength: 100
type: string
postalCode:
maxLength: 20
type: string
state:
maxLength: 100
type: string
taxRegion:
maxLength: 100
type: string
type: object
OrderLineItemCommonPostOrder:
properties:
UOM:
description: |
Specifies the units to measure usage.
type: string
accountingCode:
description: |
The accounting code for the Order Line Item.
type: string
adjustmentLiabilityAccountingCode:
description: |
The accounting code on the Order Line Item object for customers using [Zuora Billing - Revenue Integration](https://knowledgecenter.zuora.com/Zuora_Revenue/Zuora_Billing_-_Revenue_Integration).
type: string
adjustmentRevenueAccountingCode:
description: |
The accounting code on the Order Line Item object for customers using [Zuora Billing - Revenue Integration](https://knowledgecenter.zuora.com/Zuora_Revenue/Zuora_Billing_-_Revenue_Integration).
type: string
amountPerUnit:
description: |
The actual charged amount per unit for the Order Line Item.
If you set the `inlineDiscountType`, `inlineDiscountPerUnit`, and `listPricePerUnit` fields, the system will automatically generate the `amountPerUnit` field. You shall not set the `amountPerUnit` field by yourself.
type: number
billTargetDate:
description: |
The target date for the Order Line Item to be picked up by bill run for billing.
format: date
type: string
billTo:
description: |
The ID of the bill-to contact of an order line item. Specify an existing contact under the billing account as the bill-to contact of the order line item. The billing account is the order account.
**Note**: If an order's category is set to **Return** in a return Order Line Item, it will inherit the original Order Line Item's `billTo` contact automatically. You cannot specify a different value.
type: string
billingRule:
default: TriggerWithoutFulfillment
description: |
The billing rule for the Order Line Item.
enum:
- TriggerWithoutFulfillment
- TriggerAsFulfillmentOccurs
type: string
contractAssetAccountingCode:
description: |
The accounting code on the Order Line Item object for customers using [Zuora Billing - Revenue Integration](https://knowledgecenter.zuora.com/Zuora_Revenue/Zuora_Billing_-_Revenue_Integration).
type: string
contractLiabilityAccountingCode:
description: |
The accounting code on the Order Line Item object for customers using [Zuora Billing - Revenue Integration](https://knowledgecenter.zuora.com/Zuora_Revenue/Zuora_Billing_-_Revenue_Integration).
type: string
contractRecognizedRevenueAccountingCode:
description: |
The accounting code on the Order Line Item object for customers using [Zuora Billing - Revenue Integration](https://knowledgecenter.zuora.com/Zuora_Revenue/Zuora_Billing_-_Revenue_Integration).
type: string
currency:
description: |
The currency for the order line item. You can specify a currency when creating an order line item through the "Create an order" operation.
type: string
customFields:
$ref: '#/components/schemas/OrderLineItemCustomFields'
deferredRevenueAccountingCode:
description: |
The deferred revenue accounting code for the Order Line Item.
type: string
description:
description: |
The description of the Order Line Item.
type: string
maxLength: 500
excludeItemBillingFromRevenueAccounting:
default: false
description: |
The flag to exclude Order Line Item related invoice items, invoice item adjustments, credit memo items, and debit memo items from revenue accounting.
**Note**: This field is only available if you have the Order to Revenue or [Zuora Billing - Revenue Integration](https://knowledgecenter.zuora.com/Zuora_Revenue/Zuora_Billing_-_Revenue_Integration) feature enabled.
type: boolean
excludeItemBookingFromRevenueAccounting:
default: false
description: |
The flag to exclude Order Line Item from revenue accounting.
**Note**: This field is only available if you have the Order to Revenue or [Zuora Billing - Revenue Integration](https://knowledgecenter.zuora.com/Zuora_Revenue/Zuora_Billing_-_Revenue_Integration) feature enabled.
type: boolean
inlineDiscountPerUnit:
description: |
Use this field in accordance with the `inlineDiscountType` field, in the following manner:
* If the `inlineDiscountType` field is set as `Percentage`, this field specifies the discount percentage for each unit of the order line item. For exmaple, if you specify `5` in this field, the discount percentage is 5%.
* If the `inlineDiscountType` field is set as `FixedAmount`, this field specifies the discount amount on each unit of the order line item. For exmaple, if you specify `10` in this field, the discount amount on each unit of the order line item is 10.
Once you set the `inlineDiscountType`, `inlineDiscountPerUnit`, and `listPricePerUnit` fields, the system will automatically generate the `amountPerUnit` field. You shall not set the `amountPerUnit` field by yourself.
type: number
inlineDiscountType:
description: |
Use this field to specify the inline discount type, which can be `Percentage`, `FixedAmount`, or `None`. The default value is `Percentage`.
Use this field together with the `inlineDiscountPerUnit` field to specify inline discounts for order line items. The inline discount is applied to the list price of an order line item.
Once you set the `inlineDiscountType`, `inlineDiscountPerUnit`, and `listPricePerUnit` fields, the system will automatically generate the `amountPerUnit` field. You shall not set the `amountPerUnit` field by yourself.
enum:
- Percentage
- FixedAmount
- None
type: string
isAllocationEligible:
description: |
This field is used to identify if the charge segment is allocation
eligible in revenue recognition.
**Note**: The field is only available if you have the Order to Revenue feature enabled. To enable this field, submit a request at Zuora Global Support.
type: boolean
isUnbilled:
description: |
This field is used to dictate how to perform the accounting during revenue
recognition.
**Note**: The field is only available if you have the Order to Revenue feature enabled. To enable this field, submit a request at Zuora Global Support.
type: boolean
itemCategory:
default: Sales
description: |
The category for the Order Line Item, to indicate a product sale or return.
enum:
- Sales
- Return
type: string
itemName:
description: |
The name of the Order Line Item.
type: string
itemNumber:
description: |
The number of the Order Line Item. Use this field to specify a custom item number for your Order Line Item. If you are to use this field, you must set all the item numbers in an order when there are several order line items in the order.
type: string
itemState:
description: |
The state of an Order Line Item. If you want to generate billing documents for order line items, you must set this field to `SentToBilling`. For invoice preview, you do not need to set this field.
See [State transitions for an order, order line item, and fulfillment](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Order_Line_Items/AB_Order_Line_Item_States_and_Order_States) for more information.
enum:
- Executing
- Booked
- SentToBilling
- Complete
- Cancelled
type: string
itemType:
description: |
The type of the Order Line Item.
enum:
- Product
- Fee
- Services
type: string
listPricePerUnit:
description: |
The list price per unit for the Order Line Item.
type: number
originalOrderLineItemNumber:
description: |
The number of the original sale order line item for a return order line item.
type: string
originalOrderNumber:
description: |
The number of the original sale order for a return order line item.
type: string
ownerAccountNumber:
description: |
Use this field to assign an existing account as the owner of an order line item.
type: string
productCode:
description: |
The product code for the Order Line Item.
type: string
productRatePlanChargeId:
description: |
ID of a product rate plan charge. Only one-time charges are supported.
If you do not have the **Create Order Line Items Without Product Catalog** billing permission, you must specify this field to create the order line item from an existing product rate plan charge.
type: string
purchaseOrderNumber:
description: |
Used by customers to specify the Purchase Order Number provided by the buyer.
type: string
quantity:
description: |
The quantity of units, such as the number of authors in a hosted wiki service.
type: number
recognizedRevenueAccountingCode:
description: |
The recognized revenue accounting code for the Order Line Item.
type: string
relatedSubscriptionNumber:
description: |
Use this field to relate an order line item to a subscription when you create the order line item.
* To relate an order line item to a new subscription which is yet to create in the same "Create an order" call, use this field in combination with the `subscriptions` > `subscriptionNumber` field in the "Create an order" operation. Specify this field to the same value as that of the `subscriptions` > `subscriptionNumber` field when you make the "Create an order" call.
* To relate an order line item to an existing subscription, specify this field to the subscription number of the existing subscription.
type: string
revenueRecognitionRule:
description: |
The Revenue Recognition rule for the Order Line Item.
type: string
revenueRecognitionTiming:
description: |
Specifies the type of revenue recognition timing.
Predefined options are listed as enum values in this API Reference. Other options might also be avaliable depending on the revenue recognition policy configuration in the Zuora Billing UI.
**Note**: This field is only available if you have the Order to Revenue feature enabled.
maxLength: 200
type: string
enum:
- Upon Billing Document Posting Date
- Upon Order Activation Date
revenueAmortizationMethod:
description: |
Specifies the type of revenue amortization method.
Predefined options are listed as enum values in this API Reference. Other options might also be avaliable depending on the revenue recognition policy configuration in the Zuora Billing UI.
**Note**: This field is only available if you have the Order to Revenue feature enabled.
maxLength: 200
type: string
enum:
- Immediate
- Ratable Using Start And End Dates
invoiceGroupNumber:
description: |
The number of the invoice group associated with the order line item.
After enabling the Invoice Grouping feature, you can specify invoice group numbers to bill subscriptions and order line items based on specific criteria. For the same account, Zuora generates separate invoices for subscriptions and order line items, each identified by unique invoice group numbers. For more information, see [Invoice Grouping](https://knowledgecenter.zuora.com/Billing/Subscriptions/Invoice_Grouping).
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request during subscription creation, the value of this field is automatically set to `null` in the response body.
- You can specify this field on a sales order line item when its state (that is, the `itemState` field) is `Executing`, `Booked`, or `SentToBilling`.
type: string
maxLength: 255
nullable: true
sequenceSetId:
description: |
The ID of the sequence set associated with the order line item.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request during subscription creation, the value of this field is automatically set to `null` in the response body.
- You can specify this field on a sales order line item when its state (that is, the `itemState` field) is `Executing`, `Booked`, or `SentToBilling`.
type: string
paymentTerm:
description: |
The payment term name associated with the order line item.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request during subscription creation, the value of this field is automatically set to `null` in the response body.
- You can specify this field on a sales order line item when its state (that is, the `itemState` field) is `Executing`, `Booked`, or `SentToBilling`.
type: string
invoiceTemplateId:
description: |
The ID of the invoice template associated with the order line item.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request during subscription creation, the value of this field is automatically set to `null` in the response body.
- You can specify this field on a sales order line item when its state (that is, the `itemState` field) is `Executing`, `Booked`, or `SentToBilling`.
type: string
shipTo:
description: |
Use this field to assign an existing account as the ship-to contact of an order line item, by the following rules:
* If the `ownerAccountNumber` field is set, then this field must be the ID of a contact that belongs to the owner account of the order line item.
* If the `ownerAccountNumber` field is not set, then this field must be the ID of a contact that belongs to the billing account of the order line item. The billing account is the order account.
**Note**: If an order's category is set to **Return** in a return Order Line Item, it will inherit the original Order Line Item's `shipTo` contact automatically. You cannot specify a different value.
type: string
soldTo:
description: |
Use this field to assign an existing account as the sold-to contact of an order line item, by the following rules:
* If the `ownerAccountNumber` field is set, then this field must be the ID of a contact that belongs to the owner account of the order line item.
* If the `ownerAccountNumber` field is not set, then this field must be the ID of a contact that belongs to the billing account of the order line item. The billing account is the order account.
**Note**: If an order's category is set to **Return** in a return Order Line Item, it will inherit the original Order Line Item's `soldTo` contact automatically. You cannot specify a different value.
taxCode:
description: |
The tax code for the Order Line Item.
type: string
taxMode:
description: |
The tax mode for the Order Line Item.
enum:
- TaxInclusive
- TaxExclusive
type: string
transactionEndDate:
description: |
The date a transaction is completed. The default value of this field is the transaction start date. Also, the value of this field should always equal or be later than the value of the `transactionStartDate` field.
format: date
type: string
transactionStartDate:
description: |
The date a transaction starts. The default value of this field is the order date.
format: date
type: string
unbilledReceivablesAccountingCode:
description: |
The accounting code on the Order Line Item object for customers using [Zuora Billing - Revenue Integration](https://knowledgecenter.zuora.com/Zuora_Revenue/Zuora_Billing_-_Revenue_Integration).
type: string
title: OrderLineItem
type: object
OrderLineItemCustomFields:
additionalProperties:
description: |
Custom fields of the Order Line Item object. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
description: |
Container for custom fields of an Order Line Item object.
title: OrderLineItemCustomFields
type: object
POSTOrderPreviewAsyncRequestType:
example:
existingAccountNumber: A00000097
orderDate: '2024-07-01'
previewOptions:
previewTypes:
- BillingDocs
previewThruType: SpecificDate
specificPreviewThruDate: '2024-07-31'
subscriptions:
- orderActions:
- type: CreateSubscription
createSubscription:
terms:
initialTerm:
period: 12
periodType: Month
termType: TERMED
renewalSetting: RENEW_WITH_SPECIFIC_TERM
renewalTerms:
- period: 12
periodType: Month
subscribeToRatePlans:
- productRatePlanId: 8ad081dd9096ef9501909b40bb4e74a4
triggerDates:
- name: ContractEffective
triggerDate: '2024-07-01'
- name: ServiceActivation
triggerDate: '2024-07-01'
- name: CustomerAcceptance
triggerDate: '2024-07-01'
properties:
category:
default: NewSales
description: |
Category of the order to indicate a product sale or return. Default value is `NewSales`.
enum:
- NewSales
- Return
type: string
customFields:
$ref: '#/components/schemas/OrderObjectCustomFields'
description:
description: A description of the order.
maxLength: 500
type: string
existingAccountId:
description: |
The account ID under which this order will be created. This field sets the default invoice owner account and subscription owner account for any new subscriptions in the order. To override these defaults for individual subscriptions, use the `subscriptionOwnerAccountNumber` and `invoiceOwnerAccountNumber` nested fields in the `subscriptions` field.
**Note:** You can specify either the `existingAccountNumber` or `existingAccountId` field, but not both.
type: string
existingAccountNumber:
description: |
The account number under which this order will be created. This field sets the default invoice owner account and subscription owner account for any new subscriptions in the order. To override these defaults for individual subscriptions, use the `subscriptionOwnerAccountNumber` and `invoiceOwnerAccountNumber` nested fields in the `subscriptions` field.
maxLength: 70
type: string
orderDate:
description: The date when the order is signed. All of the order actions under this order will use this order date as the contract effective date.
format: date
type: string
orderLineItems:
description: |
[Order Line Items](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Order_Line_Items/AA_Overview_of_Order_Line_Items) are non subscription based items created by an Order, representing transactional charges such as one-time fees, physical goods, or professional service charges that are not sold as subscription services.
With the Order Line Items feature enabled, you can now launch non-subscription and unified monetization business models in Zuora, in addition to subscription business models.
If you do not have the **Create Order Line Items Without Product Catalog** billing permission, you can only create order line items from existing products by specifying the product rate plan charge ID in the `productRatePlanChargeId` field. For more information about billing permissions, see Billing Roles.
**Note:** The [Order Line Items](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Order_Line_Items/AA_Overview_of_Order_Line_Items) feature is now generally available to all Zuora customers. You need to enable the [Orders](https://knowledgecenter.zuora.com/BC_Subscription_Management/Orders/AA_Overview_of_Orders#Orders) feature to access the [Order Line Items](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Order_Line_Items/AA_Overview_of_Order_Line_Items) feature. As of Zuora Billing Release 313 (November 2021), new customers who onboard on [Orders](https://docs.zuora.com/en/zuora-billing/manage-accounts-subscriptions-and-non-subscriptions/manage-subscription-transactions/orders/orders-introduction/overview-of-orders) will have the [Order Line Items](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Order_Line_Items) feature enabled by default.
items:
$ref: '#/components/schemas/CreateOrderOrderLineItem'
type: array
orderNumber:
description: |
The order number of this order.
**Note:** The characters `#`, `?`, and `/` are not allowed in this field. Additionally, to ensure compatibility with the UI when viewing orders, use only the following special characters: `_`,`-`, `.`, `~`, `*`, `(`, `)`, and `'`.
maxLength: 100
type: string
previewAccountInfo:
$ref: '#/components/schemas/PreviewAccountInfo'
previewOptions:
$ref: '#/components/schemas/PreviewOptions'
reasonCode:
description: |
Values of reason code configured in **Billing Settings** > **Configure Reason Codes** through Zuora UI. Indicates the reason when a return order line item occurs.
maxLength: 255
type: string
subscriptions:
description: 'Each item includes a set of order actions, which will be applied to the same base subscription. When you create an order that involves multiple subscriptions, these subscriptions can have different invoice owner accounts or subscription owner accounts. '
items:
properties:
customFields:
$ref: '#/components/schemas/SubscriptionObjectCustomFields'
notes:
description: |
Notes about the subscription. These notes are only visible to Zuora users. Notes set in this field will override the value of the `notes` field within the createSubscription order action.
type: string
maxLength: 1000
orderActions:
description: The actions to be applied to the subscription. Order actions will be stored with the sequence when it was provided in the request.
items:
$ref: '#/components/schemas/PreviewOrderOrderAction'
type: array
quote:
$ref: '#/components/schemas/QuoteObjectFields'
ramp:
$ref: '#/components/schemas/RampRequest'
subscriptionNumber:
description: |
Leave this field empty to represent new subscription creation, or specify a subscription number to update an existing subscription.
type: string
type: object
type: array
required:
- orderDate
- previewOptions
type: object
GetAllOrdersResponseType:
properties:
nextPage:
description: |
URL to retrieve the next page of the response if it exists; otherwise absent.
format: URL
type: string
orders:
items:
$ref: '#/components/schemas/Order'
type: array
success:
description: |
Indicates whether the call succeeded.
type: boolean
type: object
Order:
description: Represents the order information that will be returned in the GET call.
properties:
category:
default: NewSales
description: |
Category of the order to indicate a product sale or return. Default value is `NewSales`.
enum:
- NewSales
- Return
type: string
commitments:
items:
$ref: '#/components/schemas/GetCommitmentOutputListOrders'
type: array
description: |
A list of commitments.
createdBy:
description: The ID of the user who created this order.
type: string
createdDate:
description: The time that the order gets created in the system, in the `YYYY-MM-DD HH:MM:SS` format.
format: datetime
type: string
currency:
description: Currency code.
type: string
customFields:
$ref: '#/components/schemas/OrderObjectCustomFields'
description:
description: A description of the order.
maxLength: 500
type: string
existingAccountNumber:
description: |
The account number that this order has been created under.
type: string
existingAccountDetails:
description: |
The account basic information that this order has been created under.
properties:
basicInfo:
$ref: '#/components/schemas/GETAccountTypeBasicInfo'
billToContact:
$ref: '#/components/schemas/GETAccountTypeBillToContact'
type: object
invoiceScheduleId:
description: |
The ID of the invoice schedule associated with the order.
**Note**: This field is available only if you have the Billing Schedule feature enabled.
type: integer
orderDate:
description: The date when the order is signed. All the order actions under this order will use this order date as the contract effective date if no additinal contractEffectiveDate is provided.
format: date
type: string
orderLineItems:
description: |
[Order Line Items](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Order_Line_Items/AA_Overview_of_Order_Line_Items) are non subscription based items created by an Order, representing transactional charges such as one-time fees, physical goods, or professional service charges that are not sold as subscription services.
With the Order Line Items feature enabled, you can now launch non-subscription and unified monetization business models in Zuora, in addition to subscription business models.
**Note:** The [Order Line Items](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Order_Line_Items/AA_Overview_of_Order_Line_Items) feature is now generally available to all Zuora customers. You need to enable the [Orders](https://knowledgecenter.zuora.com/BC_Subscription_Management/Orders/AA_Overview_of_Orders#Orders) feature to access the [Order Line Items](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Order_Line_Items/AA_Overview_of_Order_Line_Items) feature. As of Zuora Billing Release 313 (November 2021), new customers who onboard on [Orders](https://docs.zuora.com/en/zuora-billing/manage-accounts-subscriptions-and-non-subscriptions/manage-subscription-transactions/orders/orders-introduction/overview-of-orders) will have the [Order Line Items](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Order_Line_Items) feature enabled by default.
items:
$ref: '#/components/schemas/OrderLineItemRetrieveOrder'
type: array
orderNumber:
description: The order number of the order.
type: string
organizationLabel:
description: |
The organization that this object belongs to.
Note: This field is available only when the Multi-Org feature is enabled.
type: string
reasonCode:
description: |
Values of reason code configured in **Billing Settings** > **Configure Reason Codes** through Zuora UI. Indicates the reason when a return order line item occurs.
maxLength: 255
type: string
schedulingOptions:
description: |
Information of scheduled order.
properties:
scheduledDate:
description: |
The date for the order scheduled.
format: date
type: string
scheduledDatePolicy:
description: Date policy of the scheduled order.
enum:
- SpecificDate
type: string
type: object
scheduledOrderActivationResponse:
$ref: '#/components/schemas/PostOrderResponseType'
status:
description: |
The status of the order. If the order contains any `Pending Activation` or `Pending Acceptance` subscription, the order status will be `Pending`; If the order is in draft status, the order status will be `Draft`; otherwise the order status is `Completed`.
The available order statuses are as follow:
- `Draft`: The order is in draft status.
- `Pending`: The order is in pending status.
- `Completed`: The order is in completed status.
- `Cancelled`: The draft or scheduled order is cancelled.
- `Scheduled`: The order is in scheduled status and it is only valid if the Scheduled Orders feature is enabled.
- `Executing`: The scheduled order is executed by a scheduler and it is only valid if the Scheduled Orders feature is enabled.
- `Failed`: The scheduled order has failed.
- `Reverted`: The order is reverted. This status is only available to the orders that include single version subscriptions. See Single Version Subscription.
enum:
- Draft
- Pending
- Completed
- Cancelled
- Scheduled
- Executing
- Failed
- Reverted
type: string
subscriptions:
description: Represents a processed subscription, including the origin request (order actions) that create this version of subscription and the processing result (order metrics). The reference part in the request will be overridden with the info in the new subscription version.
items:
properties:
baseVersion:
description: The base version of the subscription.
type: integer
customFields:
$ref: '#/components/schemas/SubscriptionObjectCustomFields'
externallyManagedBy:
description: |
An enum field on the Subscription object to indicate the name of a third-party store. This field is used to represent subscriptions created through third-party stores.
enum:
- Amazon
- Apple
- Google
- Roku
type: string
nullable: true
newVersion:
description: The latest version of the subscription.
type: integer
notes:
description: Notes about the subscription.
type: string
orderActions:
items:
$ref: '#/components/schemas/OrderAction'
type: array
quote:
$ref: '#/components/schemas/QuoteObjectFields'
ramp:
$ref: '#/components/schemas/RampResponse'
sequence:
description: The sequence number of a certain subscription processed by the order.
type: integer
subscriptionNumber:
description: The new subscription number for a new subscription created, or the existing subscription number. Unlike the order request, the subscription number here always has a value.
type: string
subscriptionOwnerAccountNumber:
description: The number of the account that owns the subscription.
type: string
subscriptionOwnerAccountDetails:
description: |
The account basic information that this order has been created under. This is
also the invoice owner of the subscriptions included in this order.
properties:
basicInfo:
$ref: '#/components/schemas/GETAccountTypeBasicInfo'
soldToContact:
$ref: '#/components/schemas/GETAccountTypeSoldToContact'
type: object
type: object
type: array
updatedBy:
description: The ID of the user who updated this order.
type: string
updatedDate:
description: The time that the order gets updated in the system(for example, an order description update), in the `YYYY-MM-DD HH:MM:SS` format.
format: datetime
type: string
type: object
GetCommitmentOutputListOrders:
type: object
allOf:
- $ref: '#/components/schemas/CommitmentBaseAttributesListOrders'
- $ref: '#/components/schemas/CommonRevenueAttributes'
- $ref: '#/components/schemas/CommonTaxationAttributes'
- properties:
id:
type: string
description: |
ID of the commitment.
version:
type: integer
description: |
Version of the commitment.
currency:
type: string
description: |
Currency of the commitment.
excludeItemBookingFromRevenueAccounting:
type: boolean
default: true
description: The flag to exclude Commitment period from revenue accounting.
eligibleAccountConditions:
$ref: '#/components/schemas/EligibleAccountCondition'
eligibleChargeConditions:
$ref: '#/components/schemas/EligibleChargeCondition'
OrderLineItemRetrieveOrder:
allOf:
- properties:
amendedByOrderOn:
description: |
The date when the rate plan charge is amended through an order or amendment. This field is to standardize the booking date information to increase audit ability and traceability of data between Zuora Billing and Zuora Revenue. It is mapped as the booking date for a sale order line in Zuora Revenue.
type: string
amount:
description: |
The calculated gross amount for the Order Line Item.
type: number
amountWithoutTax:
description: |
The calculated gross amount for an order line item excluding tax. If the tax mode is tax exclusive, the value of this field equals that of the `amount` field.
If the tax mode of an order line item is not set, the system treats it as tax exclusive by default. The value of the `amountWithoutTax` field equals that of the `amount` field.
If you create an order line item from the product catalog, the tax mode and tax code of the product rate plan charge are used for the order line item by default. You can still overwrite this default set-up by setting the tax mode and tax code of the order line item.
type: number
id:
description: |
The sytem generated Id for the Order Line Item.
format: UUID
type: string
invoiceGroupNumber:
description: |
The number of the invoice group associated with the order line item.
The value of this field is `null` if you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled.
type: string
nullable: true
sequenceSetId:
description: |
The ID of the sequence set associated with the order line item.
The value of this field is `null` if you have the [Flexible Billing
Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes)
feature disabled.
type: string
communicationProfileId:
description: |
The ID of the communication profile associated with the order line item.
**Note**: This field is available in the request body only if you have the Flexible Billing Attributes
feature turned on. The value is `null` in the response body without this feature turned on.
type: string
nullable: true
paymentTerm:
description: |
The payment term name associated with the order line item.
The value of this field is `null` if you have the [Flexible Billing
Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes)
feature disabled.
type: string
invoiceTemplateId:
description: |
The ID of the invoice template associated with the order line item.
The value of this field is `null` if you have the [Flexible Billing
Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes)
feature disabled.
type: string
itemNumber:
description: |
The number for the Order Line Item.
type: string
originalOrderDate:
description: |
The date when the rate plan charge is created through an order or amendment. This field is to standardize the booking date information to increase audit ability and traceability of data between Zuora Billing and Zuora Revenue. It is mapped as the booking date for a sale order line in Zuora Revenue.
format: date
type: string
quantityFulfilled:
description: |
The quantity that has been fulfilled by fulfillments for the order line item. This field will be updated automatically when related fulfillments become 'SentToBilling' or 'Complete' state.
type: number
quantityPendingFulfillment:
description: |
The quantity that's need to be fulfilled by fulfillments for the order line item. This field will be updated automatically when related fulfillments become 'SentToBilling' or 'Complete' state.
type: number
type: object
- $ref: '#/components/schemas/OrderLineItemCommonRetrieveOrder'
PostOrderResponseType:
description: Response information of orders.
allOf:
- $ref: '#/components/schemas/CommonResponse'
- $ref: '#/components/schemas/CreateOrderResult'
OrderAction:
description: Represents the processed order action.
properties:
addProduct:
$ref: '#/components/schemas/RatePlanOverride'
cancelSubscription:
$ref: '#/components/schemas/CancelSubscription'
changePlan:
$ref: '#/components/schemas/ChangePlan'
changeReason:
description: |
The change reason set for an order action when an order is created.
type: string
createSubscription:
$ref: '#/components/schemas/CreateSubscription'
customFields:
$ref: '#/components/schemas/OrderActionObjectCustomFields'
id:
description: The Id of the order action processed in the order.
type: string
orderItems:
description: |
The `orderItems` nested field is only available to existing Orders customers who already have access to the field.
**Note:** The following objects and fields of the Order Metrics are end of support. Any new customers who onboard on [Orders](https://docs.zuora.com/en/zuora-billing/manage-accounts-subscriptions-and-non-subscriptions/manage-subscription-transactions/orders/orders-introduction/overview-of-orders) or [Orders Harmonization](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Orders_Harmonization/Orders_Harmonization) will not get these metrics.
* The Order ELP and Order Item objects
* The "Generated Reason" and "Order Item ID" fields in the Order MRR, Order TCB, Order TCV, and Order Quantity objects
Zuora no longer provides product support, and bug fixes or security issues are no longer addressed.
items:
$ref: '#/components/schemas/OrderItem'
type: array
orderMetrics:
description: |
The container for order metrics.
**Note:** The following objects and fields of the Order Metrics are end of support. Any new customers who onboard on [Orders](https://docs.zuora.com/en/zuora-billing/manage-accounts-subscriptions-and-non-subscriptions/manage-subscription-transactions/orders/orders-introduction/overview-of-orders) or [Orders Harmonization](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Orders_Harmonization/Orders_Harmonization) will not get these metrics.
* The Order ELP and Order Item objects
* The "Generated Reason" and "Order Item ID" fields in the Order MRR, Order TCB, Order TCV, and Order Quantity objects
Zuora no longer provides product support, and bug fixes or security issues are no longer addressed.
**Note:** As of Zuora Billing Release 306, Zuora has upgraded the methodologies for calculating metrics in [Orders](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders). The new methodologies are reflected in the following Order Delta Metrics objects.
* [Order Delta Mrr](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Order_Delta_Metrics/Order_Delta_Mrr)
* [Order Delta Tcv](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Order_Delta_Metrics/Order_Delta_Tcv)
* [Order Delta Tcb](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Order_Delta_Metrics/Order_Delta_Tcb)
It is recommended that all customers use the new [Order Delta Metrics](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Order_Delta_Metrics/AA_Overview_of_Order_Delta_Metrics). If you are an existing [Order Metrics](https://docs.zuora.com/en/zuora-billing/manage-accounts-subscriptions-and-non-subscriptions/manage-subscription-transactions/orders/orders-introduction/overview-of-orders/Key_Metrics_for_Orders) customer and want to migrate to Order Delta Metrics, submit a request at [Zuora Global Support](https://support.zuora.com/).
Whereas new customers, and existing customers not currently on [Order Metrics](https://docs.zuora.com/en/zuora-billing/manage-accounts-subscriptions-and-non-subscriptions/manage-subscription-transactions/orders/orders-introduction/overview-of-orders/Key_Metrics_for_Orders), will no longer have access to Order Metrics, existing customers currently using Order Metrics will continue to be supported.
items:
$ref: '#/components/schemas/orderMetric'
type: array
ownerTransfer:
$ref: '#/components/schemas/OwnerTransfer'
removeProduct:
$ref: '#/components/schemas/RemoveProduct'
renewSubscription:
$ref: '#/components/schemas/RenewSubscription'
resume:
$ref: '#/components/schemas/GetOrderResume'
sequence:
description: The sequence of the order actions processed in the order.
type: integer
suspend:
$ref: '#/components/schemas/GetOrderSuspend'
termsAndConditions:
$ref: '#/components/schemas/TermsAndConditions'
triggerDates:
description: |
Container for the contract effective, service activation, and customer acceptance dates of the order action.
If [Zuora is configured to require service activation](https://knowledgecenter.zuora.com/CB_Billing/Billing_Settings/Define_Default_Subscription_Settings#Require_Service_Activation_of_Orders.3F) and the `ServiceActivation` field is not set for a `CreateSubscription` order action, a `Pending` order and a `Pending Activation` subscription are created.
If [Zuora is configured to require customer acceptance](https://knowledgecenter.zuora.com/CB_Billing/Billing_Settings/Define_Default_Subscription_Settings#Require_Customer_Acceptance_of_Orders.3F) and the `CustomerAcceptance` field is not set for a `CreateSubscription` order action, a `Pending` order and a `Pending Acceptance` subscription are created. At the same time, if the service activation date field is also required and not set, a `Pending` order and a `Pending Activation` subscription are created instead.
If [Zuora is configured to require service activation](https://knowledgecenter.zuora.com/CB_Billing/Billing_Settings/Define_Default_Subscription_Settings#Require_Service_Activation_of_Orders.3F) and the `ServiceActivation` field is not set for either of the following order actions, a `Pending` order is created. The subscription status is not impacted. **Note:** This feature is in **Limited Availability**. If you want to have access to the feature, submit a request at [Zuora Global Support](http://support.zuora.com/).
* AddProduct
* UpdateProduct
* RemoveProduct
* RenewSubscription
* TermsAndConditions
If [Zuora is configured to require customer acceptance](https://knowledgecenter.zuora.com/CB_Billing/Billing_Settings/Define_Default_Subscription_Settings#Require_Customer_Acceptance_of_Orders.3F) and the `CustomerAcceptance` field is not set for either of the following order actions, a `Pending` order is created. The subscription status is not impacted. **Note:** This feature is in **Limited Availability**. If you want to have access to the feature, submit a request at [Zuora Global Support](http://support.zuora.com/).
* AddProduct
* UpdateProduct
* RemoveProduct
* RenewSubscription
* TermsAndConditions
items:
$ref: '#/components/schemas/TriggerDate'
type: array
type:
description: |
Type of the order action.
**Note**: The change plan type of order action is supported for the Order to Revenue feature. However, it is currently not supported for the Billing - Revenue Integration feature. When Billing - Revenue Integration is enabled, the change plan type of order action will no longer be applicable in Zuora Billing.
enum:
- CreateSubscription
- TermsAndConditions
- AddProduct
- UpdateProduct
- RemoveProduct
- RenewSubscription
- CancelSubscription
- OwnerTransfer
- Suspend
- Resume
- ChangePlan
type: string
updateProduct:
$ref: '#/components/schemas/RatePlanUpdate'
description: ''
type: object
RampResponse:
properties:
charges:
description: Container for the rate plan charges that are considered as part of the ramp deal.
items:
$ref: '#/components/schemas/RampChargeResponse'
type: array
description:
description: The short description of the ramp.
type: string
id:
description: The ID of the ramp.
type: string
intervals:
description: Container for the intervals that the ramp is split into in its timeline.
items:
$ref: '#/components/schemas/RampIntervalResponse'
type: array
name:
description: The name of the ramp.
type: string
number:
description: The number of the ramp. It is automaticcally generated by the billing system.
type: string
subscriptionNumber:
description: The number of the subscription that is considered as part of the ramp deal.
type: string
title: Ramp
type: object
description: |
**Note**: This field is only available if you have the Ramps feature
enabled. The
[Orders](https://docs.zuora.com/en/zuora-billing/manage-accounts-subscriptions-and-non-subscriptions/manage-subscription-transactions/orders/orders-introduction/overview-of-orders)
feature must be enabled before you can access the
[Ramps](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Ramps_and_Ramp_Metrics/A_Overview_of_Ramps_and_Ramp_Metrics)
feature. The Ramps feature is available for customers with
Enterprise and Nine editions by default. If you are a Growth
customer, see [Zuora
Editions](https://docs.zuora.com/en/entitlements/current-entitlements/zuora-editions)
for pricing information coming October 2020.
The ramp definition.
RampChargeResponse:
properties:
chargeNumber:
description: The number of the rate plan charge.
type: string
title: charges
type: object
RampIntervalResponse:
properties:
description:
description: The short description of the interval.
type: string
endDate:
description: The end date of the interval.
format: date
type: string
name:
description: The name of the interval.
type: string
startDate:
description: The start date of the interval.
format: date
type: string
title: intervals
type: object
RatePlanOverride:
description: |
Rate plan associated with a subscription.
properties:
chargeOverrides:
description: |
List of charges associated with the rate plan.
items:
$ref: '#/components/schemas/ChargeOverride'
type: array
clearingExistingFeatures:
description: |
Specifies whether all features in the rate plan will be cleared.
type: boolean
customFields:
$ref: '#/components/schemas/OrdersRatePlanObjectCustomFields'
externallyManagedPlanId:
description: |
Indicates the unique identifier for the rate plan purchased on a third-party store. This field is used to represent a subscription rate plan created through third-party stores.
type: string
isFromExternalCatalog:
description: |
Indicates whether the rate plan is created from the Zuora product catalog or from an external product catalog.
**Note:** This field is available when the Standalone Orders feature is enabled.
type: boolean
newRatePlanId:
description: |
Internal identifier of the rate plan.
type: string
productRatePlanId:
description: |
Internal identifier of the product rate plan that the rate plan is based on.
type: string
productRatePlanNumber:
description: |
Number of a product rate plan for this subscription.
type: string
ratePlanName:
description: |
Name of the standalone rate plan.
**Note:** This field is available when the Standalone Orders feature is enabled.
type: string
subscriptionProductFeatures:
description: |
List of features associated with the rate plan.
The system compares the `subscriptionProductFeatures` and `featureId` fields in the request with the counterpart fields in a rate plan. The comparison results are as follows:
* If there is no `subscriptionProductFeatures` field or the field is empty, features in the rate plan remain unchanged. But if the `clearingExistingFeatures` field is additionally set to true, all features in the rate plan are cleared.
* If the `subscriptionProductFeatures` field contains the `featureId` nested fields, as well as the optional `description` and `customFields` nested fields, the features indicated by the featureId nested fields in the request overwrite all features in the rate plan.
items:
$ref: '#/components/schemas/RatePlanFeatureOverride'
type: array
uniqueToken:
description: |
Unique identifier for the rate plan. This identifier enables you to refer to the rate plan before the rate plan has an internal identifier in Zuora.
For instance, suppose that you want to use a single order to add a product to a subscription and later update the same product. When you add the product, you can set a unique identifier for the rate plan. Then when you update the product, you can use the same unique identifier to specify which rate plan to modify.
maxLength: 50
type: string
subscriptionRatePlanNumber:
description: |
Number of a subscription rate plan for this subscription.
maxLength: 50
type: string
required:
- productRatePlanId
title: ratePlan
type: object
ChangePlan:
description: |
Information about an order action of type `ChangePlan`.
**Note**: The change plan type of order action is supported for the Order to Revenue feature. However, it is currently not supported for the Billing - Revenue Integration feature. When Billing - Revenue Integration is enabled, the change plan type of order action will no longer be applicable in Zuora Billing.
properties:
effectivePolicy:
description: |
* If the rate plan change (from old to new) is an upgrade, the effective policy is `EffectiveImmediately` by default.
* If the rate plan change (from old to new) is a downgrade, the effective policy is `EffectiveEndOfBillingPeriod` by default.
* Otherwise, the effective policy is `SpecificDate` by default.
enum:
- EffectiveImmediately
- EffectiveEndOfBillingPeriod
- SpecificDate
type: string
newProductRatePlan:
$ref: '#/components/schemas/ChangePlanRatePlanOverride'
productRatePlanId:
description: |
ID of the rate plan to remove. This can be the latest version or any history version of ID.
type: string
productRatePlanNumber:
description: |
Number of a product rate plan for this subscription.
type: string
ratePlanId:
description: |
ID of the rate plan to remove. This can be the latest version or any history version of ID.
type: string
subType:
description: |
This field is used to choose the sub type for your change plan order action.
However, if you do not set this field, the field will be automatically generated by the system according to the following rules:
When the old and new rate plans are within the same Grading catalog group:
* If the grade of new plan is greater than that of the old plan, this is an "Upgrade".
* If the grade of new plan is less than that of the old plan, this is a "Downgrade".
* If the grade of new plan equals that of the old plan, this is a "Crossgrade".
When the old and new rate plans are not in the same Grading catalog group, or either has no group, this is "PlanChanged".
enum:
- Upgrade
- Downgrade
- Crossgrade
- PlanChanged
type: string
subscriptionRatePlanNumber:
description: |
Number of a rate plan for this subscription.
type: string
title: changePlan
type: object
CreateSubscription:
description: |
Information about an order action of type `CreateSubscription`.
properties:
billToContactId:
description: |
The ID of the bill-to contact associated with the subscription.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request or you select **Default Contact from Account** for this field during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
currency:
description: |
The code of currency that is used for this subscription. If the currency is not selected, the default currency from the account will be used.
All subscriptions in the same order must use the same currency. The currency for a subscription cannot be changed.
**Note**: This field is available only if you have the Multiple Currencies feature enabled.
maxLength: 3
type: string
invoiceGroupNumber:
description: |
The number of the invoice group associated with the subscription.
After enabling the Invoice Grouping feature, you can specify invoice group numbers to bill subscriptions and order line items based on specific criteria. For the same account, Zuora generates separate invoices for subscriptions and order line items, each identified by unique invoice group numbers. For more information, see [Invoice Grouping](https://knowledgecenter.zuora.com/Billing/Subscriptions/Invoice_Grouping).
The value of this field is `null` if you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled.
type: string
maxLength: 255
nullable: true
invoiceSeparately:
description: |
Specifies whether the subscription appears on a separate invoice when Zuora generates invoices.
type: boolean
invoiceTemplateId:
description: |
The ID of the invoice template associated with the subscription.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request or you select **Default Template from Account** for this field during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
newSubscriptionOwnerAccount:
description: |
Information about a new account that will own the subscription. Only available if you have enabled the Owner Transfer feature.
**Note:** The Owner Transfer feature is in **Limited Availability**. If you wish to have access to the feature, submit a request at [Zuora Global Support](http://support.zuora.com/).
If you do not set this field or the `subscriptionOwnerAccountNumber` field, the account that owns the order will also own the subscription. Zuora will return an error if you set this field and the `subscriptionOwnerAccountNumber` field.
properties:
accountNumber:
description: |
Account number. For example, A00000001.
maxLength: 70
type: string
autoPay:
description: |
Specifies whether future payments are automatically billed when they are due.
type: boolean
batch:
description: |
Name of the billing batch that the account belongs to. For example, Batch1.
type: string
billCycleDay:
description: |
Day of the month that the account prefers billing periods to begin on. If set to 0, the bill cycle day will be set as "AutoSet".
maximum: 31
minimum: 0
type: integer
billToContact:
$ref: '#/components/schemas/BillToContact'
communicationProfileId:
description: |
Internal identifier of the communication profile that Zuora uses when sending notifications to the account's contacts.
type: string
creditCard:
$ref: '#/components/schemas/creditCard'
crmId:
description: |
External identifier of the account in a CRM system.
maxLength: 100
type: string
currency:
description: |
ISO 3-letter currency code (uppercase). For example, USD.
type: string
customFields:
$ref: '#/components/schemas/AccountObjectCustomFields'
hpmCreditCardPaymentMethodId:
description: |
The ID of the payment method associated with this account. The payment method specified for this field will be set as the default payment method of the account.
If the `autoPay` field is set to `true`, you must provide the credit card payment method ID for either this field or the `creditCard` field,
but not both.
For the Credit Card Reference Transaction payment method, you can specify the payment method ID in this field or use the `paymentMethod` field to create a CC Reference Transaction payment method for an account.
type: string
invoiceDeliveryPrefsEmail:
description: |
Specifies whether to turn on the invoice delivery method 'Email' for the new account.
Values are:
* `true` (default). Turn on the invoice delivery method 'Email' for the new account.
* `false`. Turn off the invoice delivery method 'Email' for the new account.
type: boolean
invoiceDeliveryPrefsPrint:
description: |
Specifies whether to turn on the invoice delivery method 'Print' for the new account.
Values are:
* `true`. Turn on the invoice delivery method 'Print' for the new account.
* `false` (default). Turn off the invoice delivery method 'Print' for the new account.
type: boolean
invoiceTemplateId:
description: |
Internal identifier of the invoice template that Zuora uses when generating invoices for the account.
type: string
name:
description: |
Account name.
maxLength: 70
type: string
notes:
description: |
Notes about the account. These notes are only visible to Zuora users.
maxLength: 65535
type: string
parentId:
description: Identifier of the parent customer account for this Account object. Use this field if you have Customer Hierarchy enabled.
type: string
paymentGateway:
description: |
The payment gateway that Zuora uses when processing electronic payments and refunds for the account. If you do not specify this field or if the value of this field is null, Zuora uses your default payment gateway.
maxLength: 40
type: string
paymentMethod:
$ref: '#/components/schemas/POSTPaymentMethodRequest'
paymentTerm:
description: |
Name of the payment term associated with the account. For example, "Net 30". The payment term determines the due dates of invoices.
type: string
soldToContact:
$ref: '#/components/schemas/SoldToContact'
taxInfo:
$ref: '#/components/schemas/TaxInfo'
required:
- name
- currency
- billCycleDay
- billToContact
type: object
notes:
description: |
Notes about the subscription. These notes are only visible to Zuora users.
maxLength: 500
type: string
paymentTerm:
description: |
The name of the payment term associated with the subscription. For example, `Net 30`. The payment term determines the due dates of invoices.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request or you select **Default Term from Account** for this field during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
sequenceSetId:
description: |
The ID of the sequence set associated with the subscription.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request or you select **Default Set from Account** for this field during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
nullable: true
shipToContactId:
description: |
The ID of the ship-to contact associated with the subscription.
**Note:**
To access this field, you must have the ShipToContactSupport permission. If you want to enable this permission, submit a request at Zuora Global Support.
type: string
soldToContactId:
description: |
The ID of the sold-to contact associated with the subscription.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request or you select **Default Contact from Account** for this field during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
subscribeToRatePlans:
description: |
List of rate plans associated with the subscription.
items:
$ref: '#/components/schemas/RatePlanOverride'
type: array
subscriptionNumber:
description: |
Subscription number of the subscription. For example, A-S00000001.
If you do not set this field, Zuora will generate the subscription number.
maxLength: 100
type: string
subscriptionOwnerAccountNumber:
description: |
Account number of an existing account that will own the subscription. For example, A00000001.
If you do not set this field or the `newSubscriptionOwnerAccount` field, the account that owns the order will also own the subscription. Zuora will return an error if you set this field and the `newSubscriptionOwnerAccount` field.
maxLength: 70
type: string
invoiceOwnerAccountNumber:
description: |
Account number of an existing account that will own the invoice. For example, A00000001. If you do not set this field, the account that owns the order will also own this invoice.
maxLength: 70
type: string
terms:
description: |
Container for the terms and renewal settings of the subscription.
properties:
autoRenew:
description: |
Specifies whether the subscription automatically renews at the end of the each term. Only applicable if the type of the first term is `TERMED`.
type: boolean
initialTerm:
description: |
Information about the first term of the subscription.
properties:
period:
description: |
Duration of the first term in months, years, days, or weeks, depending on the value of the `periodType` field. Only applicable if the value of the `termType` field is `TERMED`.
type: integer
periodType:
description: |
Unit of time that the first term is measured in. Only applicable if the value of the `termType` field is `TERMED`.
enum:
- Month
- Year
- Day
- Week
type: string
startDate:
description: |
Start date of the first term, in YYYY-MM-DD format.
format: date
type: string
termType:
description: |
Type of the first term. If the value of this field is `TERMED`, the first term has a predefined duration based on the value of the `period` field. If the value of this field is `EVERGREEN`, the first term does not have a predefined duration.
enum:
- TERMED
- EVERGREEN
type: string
required:
- termType
type: object
renewalSetting:
description: |
Specifies the type of the terms that follow the first term if the subscription is renewed. Only applicable if the type of the first term is `TERMED`.
* `RENEW_WITH_SPECIFIC_TERM` - Each renewal term has a predefined duration. The first entry in `renewalTerms` specifies the duration of the second term of the subscription, the second entry in `renewalTerms` specifies the duration of the third term of the subscription, and so on. The last entry in `renewalTerms` specifies the ultimate duration of each renewal term.
* `RENEW_TO_EVERGREEN` - The second term of the subscription does not have a predefined duration.
enum:
- RENEW_WITH_SPECIFIC_TERM
- RENEW_TO_EVERGREEN
type: string
renewalTerms:
description: |
List of renewal terms of the subscription. Only applicable if the type of the first term is `TERMED` and the value of the `renewalSetting` field is `RENEW_WITH_SPECIFIC_TERM`.
items:
$ref: '#/components/schemas/RenewalTerm'
type: array
required:
- initialTerm
- renewalTerms
type: object
title: createSubscription
type: object
GetOrderResume:
description: |
Information about an order action of type `Resume`.
properties:
extendsTerm:
description: |
Specifies whether to extend the subscription term by the length of time the suspension is in effect. Note this field is not applicable in a Resume order action auto-created by the Order Metrics migration.
type: boolean
resumeDate:
description: |
The resume date when the resumption takes effect.
format: date
type: string
resumePeriods:
description: |
This field is applicable only when the `resumePolicy` field is set to `FixedPeriodsFromToday` or `FixedPeriodsFromSuspendDate`. It must be used together with the `resumePeriodsType` field. Note this field is not applicable in a Resume order action auto-created by the Order Metrics migration.
The total number of the periods used to specify when a subscription resumption takes effect. The subscription resumption will take place after the specified time frame (`suspendPeriods` multiplied by `suspendPeriodsType`) from today's date.
type: integer
resumePeriodsType:
description: |
This field is applicable only when the `resumePolicy` field is set to `FixedPeriodsFromToday` or `FixedPeriodsFromSuspendDate`. It must be used together with the `resumePeriods` field. Note this field is not applicable in a Resume order action auto-created by the Order Metrics migration.
The period type used to specify when a subscription resumption takes effect. The subscription suspension will take place after the specified time frame (`suspendPeriods` multiplied by `suspendPeriodsType`) from today's date.
enum:
- Day
- Week
- Month
- Year
type: string
resumePolicy:
description: |
Resume methods. Specify a way to resume a subscription. See [Resume Date](https://knowledgecenter.zuora.com/BC_Subscription_Management/Subscriptions/Resume_a_Subscription#Resume_Date) for more information. Note this field is not applicable in a Resume order action auto-created by the Order Metrics migration.
If `SuspendDate` is specfied, the resumption will take place on the same day as the suspension.
enum:
- Today
- FixedPeriodsFromSuspendDate
- FixedPeriodsFromToday
- SpecificDate
- SuspendDate
type: string
resumeSpecificDate:
description: |
This field is applicable only when the `resumePolicy` field is set to `SpecificDate`. Note this field is not applicable in a Resume order action auto-created by the Order Metrics migration.
A specific date when the subscription resumption takes effect, in YYYY-MM-DD format. The value should not be earlier than the subscription suspension date.
format: date
type: string
nullable: true
title: Resume
type: object
GetOrderSuspend:
description: |
Information about an order action of type `Suspend`.
properties:
suspendDate:
description: |
The suspend date when the suspension takes effect.
format: date
type: string
suspendPeriods:
description: |
This field is applicable only when the `suspendPolicy` field is set to `FixedPeriodsFromToday`. It must be used together with the `suspendPeriodsType` field. Note this field is not applicable in a Suspend order action auto-created by the Order Metrics migration.
The total number of the periods used to specify when a subscription suspension takes effect. The subscription suspension will take place after the specified time frame (`suspendPeriods` multiplied by `suspendPeriodsType`) from today's date.
type: integer
nullable: true
suspendPeriodsType:
description: |
This field is applicable only when the `suspendPolicy` field is set to `FixedPeriodsFromToday`. It must be used together with the `suspendPeriods` field. Note this field is not applicable in a Suspend order action auto-created by the Order Metrics migration.
The period type used to specify when a subscription suspension takes effect. The subscription suspension will take place after the specified time frame (`suspendPeriods` multiplied by `suspendPeriodsType`) from today's date.
enum:
- Day
- Week
- Month
- Year
type: string
nullable: true
suspendPolicy:
description: |
Suspend methods. Specify a way to suspend a subscription. See [Suspend Date](https://knowledgecenter.zuora.com/BC_Subscription_Management/Subscriptions/Suspend_a_Subscription#Suspend_Date) for more information. Note this field is not applicable in a Suspend order action auto-created by the Order Metrics migration.
enum:
- Today
- EndOfLastInvoicePeriod
- FixedPeriodsFromToday
- SpecificDate
type: string
nullable: true
suspendSpecificDate:
description: |
This field is applicable only when the `suspendPolicy` field is set to `SpecificDate`. Note this field is not applicable in a Suspend order action auto-created by the Order Metrics migration.
A specific date when the subscription suspension takes effect, in YYYY-MM-DD format. The value should not be earlier than the subscription's contract effective date or later [available versions](https://developer.zuora.com/api-references/api/overview/#section/API-Versions/Minor-Version) than the subscription's term end date.
format: date
type: string
nullable: true
title: Suspend
type: object
TermsAndConditions:
description: |
Information about an order action of type `TermsAndConditions`.
properties:
autoRenew:
type: boolean
billToContactId:
description: |
The ID of the bill-to contact associated with the subscription.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request or you select **Default Contact from Account** for this field during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
clearingExistingBillToContact:
default: false
description: |
Whether to clear the existing bill-to contact ID at the subscription level. This field is mutually exclusive with the `billToContactId` field.
**Note**: If you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
type: boolean
clearingExistingInvoiceGroupNumber:
default: false
description: |
Whether to clear the existing invoice group number at the subscription level. This field is mutually exclusive with the `invoiceGroupNumber` field.
**Note**: If you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
type: boolean
clearingExistingInvoiceTemplate:
default: false
description: |
Whether to clear the existing invoice template ID at the subscription level. This field is mutually exclusive with the `invoiceTemplateId` field.
**Note**: If you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
type: boolean
clearingExistingPaymentTerm:
default: false
description: |
Whether to clear the existing payment term at the subscription level. This field is mutually exclusive with the `paymentTerm` field.
**Note**: If you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
type: boolean
clearingExistingSequenceSet:
default: false
description: |
Whether to clear the existing sequence set ID at the subscription level. This field is mutually exclusive with the `sequenceSetId` field.
**Note**: If you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
type: boolean
clearingExistingShipToContact:
default: false
description: |
Whether to clear the existing ship-to contact ID at the subscription level. This field is mutually exclusive with the `shipToContactId` field.
To access this field, you must have the ShipToContactSupport permission. If you want to enable this permission, submit a request at Zuora Global Support.
type: boolean
clearingExistingSoldToContact:
default: false
description: |
Whether to clear the existing sold-to contact ID at the subscription level. This field is mutually exclusive with the `soldToContactId` field.
**Note**: If you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
type: boolean
initialTerm:
$ref: '#/components/schemas/InitialTerm'
communicationProfileId:
description: |
The ID of the communication profile associated with the subscription.
**Note**: This field is available in the request body only if you have the Flexible Billing Attributes
feature turned on. The value is `null` in the response body without this feature turned on.
type: string
nullable: true
clearingExistingCommunicationProfile:
default: false
description: |
Whether to clear the existing communication profile at the subscription
level. This field is mutually exclusive with the `communicationProfileId` field.
type: boolean
invoiceGroupNumber:
description: |
The number of the invoice group associated with the subscription.
After enabling the Invoice Grouping feature, you can specify invoice group numbers to bill subscriptions and order line items based on specific criteria. For the same account, Zuora generates separate invoices for subscriptions and order line items, each identified by unique invoice group numbers. For more information, see [Invoice Grouping](https://knowledgecenter.zuora.com/Billing/Subscriptions/Invoice_Grouping).
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
maxLength: 255
nullable: true
invoiceTemplateId:
description: |
The ID of the invoice template associated with the subscription.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request or you select **Default Template from Account** for this field during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
nullable: true
paymentTerm:
description: |
The name of the payment term associated with the subscription. For example, `Net 30`. The payment term determines the due dates of invoices.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request or you select **Default Term from Account** for this field during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
scheduledCancelDate:
description: The date when the subscription is scheduled to be canceled. The subscription is not canceled until the date specified in this field.
type: string
format: date
scheduledSuspendDate:
description: The date when the subscription is scheduled to be suspended. The subscription is not suspended until the date specified in this field.
type: string
format: date
scheduledResumeDate:
description: The date when the subscription is scheduled to be resumed. The subscription is not resumed until the date specified in this field.
type: string
format: date
clearingScheduledCancelDate:
description: Whether to clear the value of the `scheduledCancelDate` field.
type: boolean
clearingScheduledSuspendDate:
description: Whether to clear the value of the `scheduledSuspendDate` field.
type: boolean
clearingScheduledResumeDate:
description: Whether to clear the value of the `scheduledResumeDate` field.
type: boolean
renewalSetting:
enum:
- RENEW_WITH_SPECIFIC_TERM
- RENEW_TO_EVERGREEN
type: string
renewalTerms:
items:
$ref: '#/components/schemas/RenewalTerm'
type: array
sequenceSetId:
description: |
The ID of the sequence set associated with the subscription.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request or you select **Default Set from Account** for this field during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
nullable: true
shipToContactId:
description: |
The ID of the ship-to contact associated with the subscription.
**Note:**
To access this field, you must have the ShipToContactSupport permission. If you want to enable this permission, submit a request at Zuora Global Support.
type: string
soldToContactId:
description: |
The ID of the sold-to contact associated with the subscription.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request or you select **Default Contact from Account** for this field during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
title: termsAndConditions
type: object
RatePlanUpdate:
description: |
Information about an order action of type `UpdateProduct`.
properties:
chargeUpdates:
description: |
Array of the JSON objects containing the information for a charge update in the `updateProduct` type of order action.
items:
$ref: '#/components/schemas/ChargeUpdate'
type: array
clearingExistingFeatures:
description: |
Specifies whether all features in the rate plan will be cleared.
type: boolean
customFields:
$ref: '#/components/schemas/OrdersRatePlanObjectCustomFields'
externallyManagedPlanId:
description: |
Indicates the unique identifier for the rate plan purchased on a third-party store. This field is used to represent a subscription rate plan created through third-party stores.
type: string
newRatePlanId:
description: |
Internal identifier of the updated rate plan in the new subscription version.
type: string
productRatePlanNumber:
description: |
Number of a product rate plan for this subscription.
type: string
ratePlanId:
description: |
Internal identifier of the rate plan that was updated. It can be the latest version or any history version id.
type: string
specificUpdateDate:
description: |
The specific date when the Update Product order action takes effect. This field allows you to update a charge before a future-dated Update Product order action on the subscription. The format of the date is yyyy-mm-dd.
**Note**: After you use this option, the charge's `TriggerEvent` field value will be changed to `SpecificDate`.
See [Update a Product on Subscription with Future-dated Updates](https://knowledgecenter.zuora.com/BC_Subscription_Management/Orders/AC_Orders_Tutorials/C_Update_a_Product_in_a_Subscription/Update_a_Product_on_Subscription_with_Future-dated_Updates) for more information about this feature.
format: date
type: string
subscriptionProductFeatures:
description: |
List of features associated with the rate plan.
The system compares the `subscriptionProductFeatures` and `featureId` fields in the request with the counterpart fields in a rate plan. The comparison results are as follows:
* If there is no `subscriptionProductFeatures` field or the field is empty, features in the rate plan remain unchanged. But if the `clearingExistingFeatures` field is additionally set to true, all features in the rate plan are cleared.
* If the `subscriptionProductFeatures` field contains the `featureId` nested fields, as well as the optional `description` and `customFields` nested fields, the features indicated by the featureId nested fields in the request overwrite all features in the rate plan.
items:
$ref: '#/components/schemas/RatePlanFeatureOverride'
type: array
subscriptionRatePlanNumber:
description: |
Number of a rate plan for this subscription.
type: string
uniqueToken:
description: |
A unique string to represent the rate plan in the order. The unique token is used to perform multiple actions against a newly added rate plan. For example, if you want to add and update a product in the same order, assign a unique token to the newly added rate plan and use that token in future order actions.
type: string
title: updateProduct
type: object
ChargeUpdate:
description: The JSON object containing the information for a charge update in the 'UpdateProduct' type order action.
properties:
billing:
$ref: '#/components/schemas/BillingUpdate'
chargeNumber:
description: |
The number of the charge to be updated. The value of this field is inherited from the `subscriptions` > `orderActions` > `addProduct` > `chargeOverrides` > `chargeNumber` field.
type: string
customFields:
$ref: '#/components/schemas/RatePlanChargeObjectCustomFields'
description:
type: string
effectiveDate:
$ref: '#/components/schemas/TriggerParams'
estimatedStartDate:
type: string
format: date
description: |
The estimated start date of the pending charge in an active subscription.
The value must be a date within the subscription term. The system will then automatically calculate the estimated end date for the pending charge. The estimated start and end dates are used to manage the estimated charge duration and forecast the revenue for the pending charge.
**Note:** This field is available only when the Pending Subscription Processing feature is turned on.
pricing:
allOf:
- $ref: '#/components/schemas/PricingUpdate'
description: |
Pricing information about the charge.
uniqueToken:
description: |
description: |
A unique string to represent the rate plan charge in the order. The unique token is used to perform multiple actions against a newly added rate plan charge. For example, if you want to add and update a product in the same order, assign a unique token to the newly added rate plan charge and use that token in future order actions.
type: string
type: object
RatePlanFeatureOverride:
description: |
Information about feature in rate plan.
properties:
customFields:
$ref: '#/components/schemas/RatePlanFeatureOverrideCustomFields'
description:
description: A description of the feature.
maxLength: 500
type: string
featureId:
description: |
Internal identifier of the feature in the product catalog.
type: string
id:
description: |
Internal identifier of the rate plan feature override.
type: string
title: ratePlanFeature
type: object
TriggerParams:
description: |
Specifies when a charge becomes active.
properties:
periodsAfterChargeStart:
description: |
Duration of the discount charge in days, weeks, months, or years, depending on the value of the `startPeriodsType` field. Only applicable if the value of the `startDatePolicy` field is `FixedPeriodAfterApplyToChargeStartDate`.
**Note**: You must enable the [Enhanced Discounts](https://knowledgecenter.zuora.com/Zuora_Billing/Build_products_and_prices/Basic_concepts_and_terms/B_Charge_Models/D_Manage_Enhanced_Discount) feature to access this field.
type: integer
specificTriggerDate:
description: |
Date in YYYY-MM-DD format. Only applicable if the value of the `triggerEvent` field is `SpecificDate`.
While this field is applicable, if this field is not set, your `CreateSubscription` order action creates a `Pending` order and a `Pending Acceptance` subscription. If at the same time the service activation date is required and not set, a `Pending Activation` subscription is created.
While this field is applicable, if this field is not set, the following order actions create a `Pending` order but do not impact the subscription status. **Note**: This feature is in **Limited Availability**. If you want to have access to the feature, submit a request at [Zuora Global Support](http://support.zuora.com/).
* AddProduct
* UpdateProduct
* RemoveProduct
* RenewSubscription
* TermsAndConditions
format: date
type: string
startDatePolicy:
description: |
Start date policy of the discount charge to become active when the **Apply to billing period partially** checkbox is selected from the product catalog UI or the `applyToBillingPeriodPartially` field is set as true from the "CRUD: Create a product rate plan charge" operation.
- If the value of this field is `SpecificDate`, use the `specificTriggerDate` field to specify the date when the charge becomes active.
- If the value of this field is `FixedPeriodAfterApplyToChargeStartDate`, the charge is active for a predefined duration based on the value of the `upToPeriodsType` and `upToPeriods` fields.
**Notes**:
- You must enable the [Enhanced Discounts](https://knowledgecenter.zuora.com/Zuora_Billing/Build_products_and_prices/Basic_concepts_and_terms/B_Charge_Models/D_Manage_Enhanced_Discount) feature to access this field.
- You can use either `triggerEvent` or `startDatePolicy` to define when a discount charge starts, but not both at the same time.
enum:
- AlignToApplyToCharge
- SpecificDate
- EndOfLastInvoicePeriodOfApplyToCharge
- FixedPeriodAfterApplyToChargeStartDate
type: string
startPeriodsType:
description: |
Unit of time that the discount charge duration is measured in. Only applicable if the value of the `startDatePolicy` field is `FixedPeriodAfterApplyToChargeStartDate`.
**Note**: You must enable the [Enhanced Discounts](https://knowledgecenter.zuora.com/Zuora_Billing/Build_products_and_prices/Basic_concepts_and_terms/B_Charge_Models/D_Manage_Enhanced_Discount) feature to access this field.
enum:
- Days
- Weeks
- Months
- Years
type: string
triggerEvent:
description: |
Condition for the charge to become active.
If the value of this field is `SpecificDate`, use the `specificTriggerDate` field to specify the date when the charge becomes active.
enum:
- ContractEffective
- ServiceActivation
- CustomerAcceptance
- SpecificDate
type: string
title: startDate
type: object
PricingUpdate:
properties:
chargeModelData:
allOf:
- $ref: '#/components/schemas/ChargeModelDataOverride'
description: |
Container for charge model configuration data.
**Note**: This field is only available if you have the High Water Mark, Pre-Rated Pricing, or Multi-Attribute Pricing charge models enabled. The High Water Mark and Pre-Rated Pricing charge models are available for customers with Enterprise and Nine editions by default. If you are a Growth customer, see [Zuora Editions](https://docs.zuora.com/en/entitlements/current-entitlements/zuora-editions) for pricing information.
discount:
allOf:
- $ref: '#/components/schemas/DiscountPricingUpdate'
description: |
Pricing information about a discount charge.
recurringDelivery:
allOf:
- $ref: '#/components/schemas/RecurringDeliveryPricingUpdate'
description: |
Pricing information about a recurring charge that uses the "delivery" charge model. This field is only available if you have the Delivery Pricing charge model enabled.
recurringFlatFee:
allOf:
- $ref: '#/components/schemas/RecurringFlatFeePricingUpdate'
description: |
Pricing information about a recurring charge that uses the "flat fee" charge model. In this charge model, the charge has a fixed price.
recurringPerUnit:
allOf:
- $ref: '#/components/schemas/RecurringPerUnitPricingUpdate'
description: |
Pricing information about a recurring charge that uses the "per unit" charge model. In this charge model, the charge has a fixed price per unit purchased.
recurringTiered:
allOf:
- $ref: '#/components/schemas/RecurringTieredPricingUpdate'
description: |
Pricing information about a recurring charge that uses the "tiered pricing" charge model. In this charge model, the charge has cumulative pricing tiers that become effective as units are purchased.
recurringVolume:
allOf:
- $ref: '#/components/schemas/RecurringVolumePricingUpdate'
description: |
Pricing information about a recurring charge that uses the "volume pricing" charge model. In this charge model, the charge has a variable price per unit, depending on how many units are purchased.
usageFlatFee:
allOf:
- $ref: '#/components/schemas/UsageFlatFeePricingUpdate'
description: |
Pricing information about a usage charge that uses the "flat fee" charge model. In this charge model, the charge has a fixed price.
usageOverage:
allOf:
- $ref: '#/components/schemas/UsageOveragePricingUpdate'
description: |
Pricing information about a usage charge that uses the "overage" charge model. In this charge model, the charge has an allowance of free units and a fixed price per additional unit consumed.
usagePerUnit:
allOf:
- $ref: '#/components/schemas/UsagePerUnitPricingUpdate'
description: |
Pricing information about a usage charge that uses the "per unit" charge model. In this charge model, the charge has a fixed price per unit consumed.
usageTiered:
allOf:
- $ref: '#/components/schemas/UsageTieredPricingUpdate'
description: |
Pricing information about a usage charge that uses the "tiered pricing" charge model. In this charge model, the charge has cumulative pricing tiers that become effective as units are consumed.
usageTieredWithOverage:
allOf:
- $ref: '#/components/schemas/UsageTieredWithOveragePricingUpdate'
description: |
Pricing information about a usage charge that uses the "tiered with overage" charge model. In this charge model, the charge has cumulative pricing tiers that become effective as units are consumed. The charge also has a fixed price per unit consumed beyond the limit of the final tier.
usageVolume:
allOf:
- $ref: '#/components/schemas/UsageVolumePricingUpdate'
description: |
Pricing information about a usage charge that uses the "volume pricing" charge model. In this charge model, the charge has a variable price per unit, depending on how many units are consumed.
type: object
RecurringDeliveryPricingUpdate:
allOf:
- $ref: '#/components/schemas/PriceChangeParams'
- properties:
deliverySchedule:
$ref: '#/components/schemas/DeliveryScheduleParams'
listPrice:
type: number
type: object
UsageFlatFeePricingUpdate:
allOf:
- $ref: '#/components/schemas/PriceChangeParams'
- properties:
listPrice:
type: number
originalListPrice:
description: |
The original list price is the price of a product or service at which it is listed for sale by a manufacturer or retailer.
type: number
type: object
UsageOveragePricingUpdate:
allOf:
- $ref: '#/components/schemas/PriceChangeParams'
- properties:
includedUnits:
description: |
A certain quantity of units for free in the overage charge model. It cannot be negative. It must be 0 and above. Decimals are allowed.
type: number
overagePrice:
type: number
type: object
UsagePerUnitPricingUpdate:
allOf:
- $ref: '#/components/schemas/PriceChangeParams'
- properties:
listPrice:
type: number
originalListPrice:
description: |
The original list price is the price of a product or service at which it is listed for sale by a manufacturer or retailer.
type: number
type: object
UsageTieredPricingUpdate:
allOf:
- $ref: '#/components/schemas/PriceChangeParams'
- properties:
tiers:
items:
$ref: '#/components/schemas/ChargeTier'
type: array
type: object
UsageTieredWithOveragePricingUpdate:
allOf:
- $ref: '#/components/schemas/PriceChangeParams'
- properties:
overagePrice:
type: number
tiers:
items:
$ref: '#/components/schemas/ChargeTier'
type: array
type: object
UsageVolumePricingUpdate:
allOf:
- $ref: '#/components/schemas/PriceChangeParams'
- properties:
tiers:
items:
$ref: '#/components/schemas/ChargeTier'
type: array
type: object
InitialTerm:
description: The length of the period for the current subscription term.
properties:
period:
description: Specify only when the termType is 'TERMED'.
minimum: 0
type: integer
periodType:
description: Specify only when the termType is 'TERMED'.
enum:
- Month
- Year
- Day
- Week
type: string
startDate:
description: |
The start date of the current term.
format: date
type: string
termType:
enum:
- TERMED
- EVERGREEN
type: string
required:
- termType
type: object
BillToContact:
allOf:
- description: |
Contact details associated with an account.
properties:
address1:
description: |
First line of the contact's address. This is often a street address or a business name.
maxLength: 255
type: string
address2:
description: |
Second line of the contact's address.
maxLength: 255
type: string
city:
description: |
City of the contact's address.
maxLength: 40
type: string
country:
description: |
Country; must be a valid country name or abbreviation. If using Zuora Tax, you must specify a country in the bill-to contact to calculate tax.
maxLength: 64
type: string
county:
description: |
County of the contact's address.
maxLength: 32
type: string
fax:
description: |
Fax number of the contact.
maxLength: 40
type: string
firstName:
description: |
First name of the contact.
maxLength: 100
type: string
homePhone:
description: |
Home phone number of the contact.
maxLength: 40
type: string
lastName:
description: |
Last name of the contact.
maxLength: 100
type: string
mobilePhone:
description: |
Mobile phone number of the contact.
maxLength: 40
type: string
nickname:
description: |
Nickname of the contact.
maxLength: 100
type: string
otherPhone:
description: |
Additional phone number of the contact. Use the `otherPhoneType` field to specify the type of phone number.
maxLength: 40
type: string
otherPhoneType:
description: |
Specifies the type of phone number in the `otherPhone` field.
enum:
- Work
- Mobile
- Home
- Other
type: string
personalEmail:
description: |
Personal email address of the contact.
format: email
maxLength: 80
type: string
postalCode:
description: |
ZIP code or other postal code of the contact's address.
maxLength: 20
type: string
state:
description: |
State or province of the contact's address.
maxLength: 40
type: string
taxRegion:
description: |
Region defined in your taxation rules. Only applicable if you use Zuora Tax.
maxLength: 32
type: string
workEmail:
description: |
Business email address of the contact.
format: email
maxLength: 80
type: string
workPhone:
description: |
Business phone number of the contact.
maxLength: 40
type: string
required:
- firstName
- lastName
type: object
- $ref: '#/components/schemas/ContactObjectCustomFields'
SoldToContact:
allOf:
- description: |
Contact details associated with an account.
properties:
address1:
description: |
First line of the contact's address. This is often a street address or a business name.
maxLength: 255
type: string
address2:
description: |
Second line of the contact's address.
maxLength: 255
type: string
city:
description: |
City of the contact's address.
maxLength: 40
type: string
country:
description: |
Country; must be a valid country name or abbreviation. If using Zuora Tax, you must specify a country in the sold-to contact to calculate tax. A bill-to contact may be used if no sold-to contact is provided.
maxLength: 64
type: string
county:
description: |
County of the contact's address.
maxLength: 32
type: string
fax:
description: |
Fax number of the contact.
maxLength: 40
type: string
firstName:
description: |
First name of the contact.
maxLength: 100
type: string
homePhone:
description: |
Home phone number of the contact.
maxLength: 40
type: string
lastName:
description: |
Last name of the contact.
maxLength: 100
type: string
mobilePhone:
description: |
Mobile phone number of the contact.
maxLength: 40
type: string
nickname:
description: |
Nickname of the contact.
maxLength: 100
type: string
otherPhone:
description: |
Additional phone number of the contact. Use the `otherPhoneType` field to specify the type of phone number.
maxLength: 40
type: string
otherPhoneType:
description: |
Specifies the type of phone number in the `otherPhone` field.
enum:
- Work
- Mobile
- Home
- Other
type: string
personalEmail:
description: |
Personal email address of the contact.
format: email
maxLength: 80
type: string
postalCode:
description: |
ZIP code or other postal code of the contact's address.
maxLength: 20
type: string
state:
description: |
State or province of the contact's address.
maxLength: 40
type: string
taxRegion:
description: |
Region defined in your taxation rules. Only applicable if you use Zuora Tax.
maxLength: 32
type: string
nullable: true
workEmail:
description: |
Business email address of the contact.
format: email
maxLength: 80
type: string
workPhone:
description: |
Business phone number of the contact.
maxLength: 40
type: string
required:
- firstName
- lastName
type: object
- $ref: '#/components/schemas/ContactObjectCustomFields'
ChangePlanRatePlanOverride:
description: |
Information about the new product rate plan to add.
properties:
chargeOverrides:
description: |
List of charges associated with the rate plan.
items:
$ref: '#/components/schemas/ChangePlanChargeOverride'
type: array
clearingExistingFeatures:
description: |
Specifies whether all features in the rate plan will be cleared.
type: boolean
customFields:
$ref: '#/components/schemas/OrdersRatePlanObjectCustomFields'
externallyManagedPlanId:
description: |
Indicates the unique identifier for the rate plan purchased on a third-party store. This field is used to represent a subscription rate plan created through third-party stores.
type: string
productRatePlanId:
description: |
Internal identifier of the product rate plan that the rate plan is based on.
type: string
productRatePlanNumber:
description: |
Number of a product rate plan for this subscription.
type: string
subscriptionProductFeatures:
description: |
List of features associated with the rate plan.
The system compares the `subscriptionProductFeatures` and `featureId` fields in the request with the counterpart fields in a rate plan. The comparison results are as follows:
* If there is no `subscriptionProductFeatures` field or the field is empty, features in the rate plan remain unchanged. But if the `clearingExistingFeatures` field is additionally set to true, all features in the rate plan are cleared.
* If the `subscriptionProductFeatures` field contains the `featureId` nested fields, as well as the optional `description` and `customFields` nested fields, the features indicated by the featureId nested fields in the request overwrite all features in the rate plan.
items:
$ref: '#/components/schemas/RatePlanFeatureOverride'
type: array
uniqueToken:
description: |
Unique identifier for the rate plan. This identifier enables you to refer to the rate plan before the rate plan has an internal identifier in Zuora.
For instance, suppose that you want to use a single order to add a product to a subscription and later update the same product. When you add the product, you can set a unique identifier for the rate plan. Then when you update the product, you can use the same unique identifier to specify which rate plan to modify.
maxLength: 50
type: string
title: ratePlan
type: object
ChangePlanChargeOverride:
description: |
Charge associated with a rate plan.
properties:
accountReceivableAccountingCode:
description: |
The accountReceivableAccountingCode of a standalone charge.
**Note:** This field is available when the Standalone Orders, Zuora Finance, and Invoice Settlement features are enabled.
type: string
adjustmentLiabilityAccountingCode:
description: |
The adjustmentLiabilityAccountingCode of a standalone charge.
**Note:** This field is available when the Standalone Orders feature and the Billing - Revenue Integration or Order to Revenue feature are enabled.
type: string
adjustmentRevenueAccountingCode:
description: |
The adjustmentRevenueAccountingCode of a standalone charge.
**Note:** This field is available when the Standalone Orders feature and the Billing - Revenue Integration or Order to Revenue feature are enabled.
type: string
billing:
description: |
Billing information about the charge.
properties:
billCycleDay:
description: |
Day of the month that each billing period begins on. Only applicable if the value of the `billCycleType` field is `SpecificDayofMonth`.
maximum: 31
minimum: 0
type: integer
billCycleType:
description: |
Specifies how Zuora determines the day that each billing period begins on.
* `DefaultFromCustomer` - Each billing period begins on the bill cycle day of the account that owns the subscription.
* `SpecificDayofMonth` - Use the `billCycleDay` field to specify the day of the month that each billing period begins on.
* `SubscriptionStartDay` - Each billing period begins on the same day of the month as the start date of the subscription.
* `ChargeTriggerDay` - Each billing period begins on the same day of the month as the date when the charge becomes active.
* `SpecificDayofWeek` - Use the `weeklyBillCycleDay` field to specify the day of the week that each billing period begins on.
enum:
- DefaultFromCustomer
- SpecificDayofMonth
- SubscriptionStartDay
- ChargeTriggerDay
- SpecificDayofWeek
type: string
billingPeriod:
description: |
Billing frequency of the charge. The value of this field controls the duration of each billing period.
If the value of this field is `Specific_Days`, `Specific_Months` or `Specific_Weeks`, use the `specificBillingPeriod` field to specify the duration of each billing period.
enum:
- Month
- Quarter
- Semi_Annual
- Annual
- Eighteen_Months
- Two_Years
- Three_Years
- Five_Years
- Specific_Months
- Subscription_Term
- Week
- Specific_Weeks
- Specific_Days
type: string
billingPeriodAlignment:
description: |
Specifies how Zuora determines when to start new billing periods. You can use this field to align the billing periods of different charges.
* `AlignToCharge` - Zuora starts a new billing period on the first billing day that falls on or after the date when the charge becomes active.
* `AlignToSubscriptionStart` - Zuora starts a new billing period on the first billing day that falls on or after the start date of the subscription.
* `AlignToTermStart` - For each term of the subscription, Zuora starts a new billing period on the first billing day that falls on or after the start date of the term.
See the `billCycleType` field for information about how Zuora determines the billing day.
**Note**: This field is not supported in one time charges.
enum:
- AlignToCharge
- AlignToSubscriptionStart
- AlignToTermStart
type: string
billingTiming:
description: |
Specifies whether to invoice for a billing period on the first day of the billing period (billing in advance) or the first day of the next billing period (billing in arrears).
enum:
- IN_ADVANCE
- IN_ARREARS
type: string
specificBillingPeriod:
description: |
Duration of each billing period in months or weeks, depending on the value of the `billingPeriod` field. Only applicable if the value of the `billingPeriod` field is `Specific_Months` or `Specific_Weeks`.
type: integer
weeklyBillCycleDay:
description: |
Day of the week that each billing period begins on. Only applicable if the value of the `billCycleType` field is `SpecificDayofWeek`.
enum:
- Sunday
- Monday
- Tuesday
- Wednesday
- Thursday
- Friday
- Saturday
type: string
type: object
chargeFunction:
description: |
**Note**: This field is only available if you have both the Prepaid with Drawdown and Standalone Orders features enabled.
With this field, you can use a standalone order to subscribe to a minimum commitment subscription.
This field defines what type of charge it is:
* CommitmentTrueUp: For recurring charges. Currency based minimum commitment charge.
* CreditCommitment: For usage charges. Credit to minimum commitment funds.
enum:
- CommitmentTrueUp
- CreditCommitment
type: string
commitmentType:
description: |
**Note**: This field is only available if you have both the Prepaid with Drawdown and Standalone Orders features enabled.
With this field, you can use a standalone order to subscribe to a minimum commitment subscription.
This field defines the type of the commitment for both the commitment true-up charge and credit commitment charge, and so you must define the type as `CURRENCY`.
enum:
- CURRENCY
type: string
creditOption:
description: |
**Note**: This field is only available if you have both the Minimum Commitment and Standalone Orders features enabled.
With this field, you can use a standalone order to subscribe to a minimum commitment subscription.
This field defines the way to calculate credit. See [Credit Option](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge#Credit_Option) for more information.
enum:
- TimeBased
- ConsumptionBased
- FullCreditBack
type: string
chargeModel:
description: |
The chargeModel of a standalone charge.
Supported charge models:
* `FlatFee`
* `PerUnit`
* `Volume`
* `Tiered`
* `DiscountFixedAmount`
* `DiscountPercentage`
**Note:** This field is available when the Standalone Orders feature is enabled.
type: string
chargeNumber:
description: |
Charge number of the charge. For example, C-00000307.
* If you do not set this field, Zuora will generate a charge number starting with a default prefix, for example, C-. This default prefix is predefined in **Billing Settings** > **Define Default Subscription and Order Settings**.
* If you want to use a custom charge number, do not use the default prefix predefined in **Billing Settings** > **Define Default Subscription and Order Settings**. Use your own prefix, for example, SC-.
maxLength: 50
type: string
chargeType:
description: |
The chargeType of a standalone charge.
Supported charge types:
* `OneTime`
* `Recurring`
* `Usage`
**Note:** This field is available when the Standalone Orders feature is enabled.
type: string
contractAssetAccountingCode:
description: |
The contractAssetAccountingCode of a standalone charge.
**Note:** This field is available when the Standalone Orders feature and the Billing - Revenue Integration or Order to Revenue feature are enabled.
type: string
contractLiabilityAccountingCode:
description: |
The contractLiabilityAccountingCode of a standalone charge.
**Note:** This field is available when the Standalone Orders feature and the Billing - Revenue Integration or Order to Revenue feature are enabled.
type: string
contractRecognizedRevenueAccountingCode:
description: |
The contractRecognizedRevenueAccountingCode of a standalone charge.
**Note:** This field is available when the Standalone Orders feature and the Billing - Revenue Integration or Order to Revenue feature are enabled.
type: string
customFields:
$ref: '#/components/schemas/RatePlanChargeObjectCustomFields'
deferredRevenueAccountingCode:
description: |
The deferredRevenueAccountingCode of a standalone charge.
**Note:** This field is available when the Standalone Orders and Zuora Finance features are enabled.
type: string
description:
description: |
Description of the charge.
maxLength: 500
type: string
drawdownRate:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
The [conversion rate](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_drawdown_charge#UOM_Conversion) between Usage UOM and Drawdown UOM for a [drawdown charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_drawdown_charge). Must be a positive number (>0).
type: number
endDate:
$ref: '#/components/schemas/EndConditions'
estimatedStartDate:
type: string
format: date
description: |
The estimated start date of the pending charge in an active subscription.
If you specify `SpecificDate` in the `startDate` > `triggerEvent` field and want to create a completed order and an active subscription, you must specify either the `estimatedStartDate` or `startDate` > `specificTriggerDate` field:
- `estimatedStartDate`: The charge will be in pending status.
- `specificTriggerDate`: The charge will be in active status.
The value of this field must be a date within the subscription term. The system will then automatically calculate the estimated end date for the pending charge. The estimated start and end dates are used to manage the estimated charge duration and forecast the revenue for the pending charge.
**Note:** This field is available only when the Pending Subscription Processing feature is turned on.
excludeItemBillingFromRevenueAccounting:
default: false
description: |
The flag to exclude rate plan charge related invoice items, invoice item adjustments, credit memo items, and debit memo items from revenue accounting.
**Note**: This field is only available if you have the Order to Revenue or [Zuora Billing - Revenue Integration](https://knowledgecenter.zuora.com/Zuora_Revenue/Zuora_Billing_-_Revenue_Integration) feature enabled.
type: boolean
excludeItemBookingFromRevenueAccounting:
default: false
description: |
The flag to exclude rate plan charges from revenue accounting.
**Note**: This field is only available if you have the Order to Revenue or [Zuora Billing - Revenue Integration](https://knowledgecenter.zuora.com/Zuora_Revenue/Zuora_Billing_-_Revenue_Integration) feature enabled.
type: boolean
isAllocationEligible:
description: |
This field is used to identify if the charge segment is allocation
eligible in revenue recognition.
**Note**: The field is only available if you have the Order to Revenue feature enabled. To enable this field, submit a request at Zuora Global Support.
type: boolean
isRollover:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
The value is either "True" or "False". It determines whether the rollover fields are needed.
type: boolean
isUnbilled:
description: |
This field is used to dictate how to perform the accounting during revenue recognition.
**Note**: The field is only available if you have the Order to Revenue feature enabled. To enable this field, submit a request at Zuora Global Support.
type: boolean
name:
description: |
The name of a standalone charge.
**Note:** This field is available when the Standalone Orders feature is enabled.
type: string
negotiatedPriceTable:
description: |
Array of negotiated price table information. The rate card entries provided in the array will override the existing rate card entries in the standard price table to form a negotiated price table that will be
used during pricing evaluation.
**Note:** To enable the Negotiated Price Table feature, submit a request to Zuora Global Support.
items:
$ref: '#/components/schemas/NegotiatedItems'
type: array
additionalProperties: true
pobPolicy:
description: |
The pobPolicy of a standalone charge.
**Note:** This field is available when the Standalone Orders feature is enabled.
type: string
prepaidQuantity:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
The number of units included in a [prepayment charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge). Must be a positive number (>0).
type: number
pricing:
description: |
Pricing information about the charge.
properties:
chargeModelData:
$ref: '#/components/schemas/ChargeModelDataOverride'
discount:
$ref: '#/components/schemas/DiscountPricingOverride'
oneTimeFlatFee:
$ref: '#/components/schemas/OneTimeFlatFeePricingOverride'
oneTimePerUnit:
$ref: '#/components/schemas/OneTimePerUnitPricingOverride'
oneTimeTiered:
$ref: '#/components/schemas/OneTimeTieredPricingOverride'
oneTimeVolume:
$ref: '#/components/schemas/OneTimeVolumePricingOverride'
recurringDeliveryBased:
$ref: '#/components/schemas/RecurringDeliveryPricingOverride'
recurringFlatFee:
$ref: '#/components/schemas/RecurringFlatFeePricingOverride'
recurringPerUnit:
$ref: '#/components/schemas/RecurringPerUnitPricingOverride'
recurringTiered:
$ref: '#/components/schemas/RecurringTieredPricingOverride'
recurringVolume:
$ref: '#/components/schemas/RecurringVolumePricingOverride'
usageFlatFee:
$ref: '#/components/schemas/UsageFlatFeePricingOverride'
usageOverage:
$ref: '#/components/schemas/UsageOveragePricingOverride'
usagePerUnit:
$ref: '#/components/schemas/UsagePerUnitPricingOverride'
usageTiered:
$ref: '#/components/schemas/UsageTieredPricingOverride'
usageTieredWithOverage:
$ref: '#/components/schemas/UsageTieredWithOveragePricingOverride'
usageVolume:
$ref: '#/components/schemas/UsageVolumePricingOverride'
type: object
pricingAttributes:
description: |
Container for pricing attribute and value that provide additional context for dynamic pricing. The pricing attribute values are used to get the charge’s list price from the product catalog. For the pricing attribute mapped to a Zuora object field, Zuora will retrieve the value automatically, you don’t need to pass its value explicitly. If you pass a value that doesn’t match the actual value of the Zuora object, an error will be returned.
Note that for any pricing attribute mapped to the field of Zuora object Usage, because its value is only determined when the usage record arrives, you can’t provide a value via Orders API payload and Zuora will not retrieve its value automatically.
**Note:** To enable Dynamic Pricing, submit a request to Zuora Global Support.
type: object
additionalProperties: true
productCategory:
description: |
The productCategory of a standalone charge.
**Note:** This field is available when the Standalone Orders feature is enabled.
type: string
productClass:
description: |
The productClass of a standalone charge.
**Note:** This field is available when the Standalone Orders feature is enabled.
type: string
productFamily:
description: |
The productFamily of a standalone charge.
**Note:** This field is available when the Standalone Orders feature is enabled.
type: string
productLine:
description: |
The productLine of a standalone charge.
**Note:** This field is available when the Standalone Orders feature is enabled.
type: string
productRatePlanChargeId:
description: |
Internal identifier of the product rate plan charge that the charge is based on. You can specify either `productRatePlanChargeId` or `productRatePlanChargeNumber`.
type: string
productRatePlanChargeNumber:
description: |
Number of a product rate-plan charge for this subscription. You can specify either `productRatePlanChargeId` or `productRatePlanChargeNumber`.
type: string
prorationOption:
description: |
**Note**: This field is only available if you have the Charge Level Proration feature enabled. For more information, see Usage charge proration and Charge level proration option for a recurring charge.
You can use this field to specify the charge-level proration option for a usage charge or recurring charge when you creating or adding a subscription rate plan charge through an order. The tenant-level proration option will be overridden.
* `NoProration`: charge-level proration option that you can set for a usage charge. This option means to not use any proration, which is the default current system behavior for a usage charge.
* `TimeBasedProration`: charge-level proration option that you can set for a usage charge. This option means to prorate the usage charge amount using the actual number of days if the billing period is a partial period.
* `DefaultFromTenantSetting`: charge-level proration option that you can set for a recurring charge. This option means to follow the customer billing rule proration setting.
* `ChargeFullPeriod`: charge-level proration option that you can set for a recurring charge. This options means to charge the full period amount for a partial billing period. Note that this setting means that there is no proration for either collecting or refunding. Even if you cancel the recurring charge in the middle of a billing period, there is no refund for this billing period.
* `CustomizeProrationOptionOverrides`: charge-level proration option that you can set for a recurring charge. This option means to use the customized charge proration settings that is specified by the `ratingPropertiesOverride` field.
enum:
- NoProration
- TimeBasedProration
- DefaultFromTenantSetting
- ChargeFullPeriod
- CustomizeProrationOptionOverrides
type: string
ratingPropertiesOverride:
description: |
**Note**: This field is only available if you have the Charge Level Proration feature enabled. For more information, see Charge level proration option for a recurring charge.
This field is used only when the value of the `prorationOption` field is set to `CustomizeProrationOptionOverrides`.
Use this field to specify more customized proration options for a recurring charge when you creating or adding a subscription rate plan charge through an order. The tenant-level proration option will be overridden.
type: object
properties:
isProratePartialMonth:
description: |
**Note**: This field is only available if you have the Charge Level Proration feature enabled. For more information, see Charge level proration option for a recurring charge.
Use this field to specify whether to prorate the recurring charge for a partial month. The tenant-level proration option will be overridden.
type: boolean
prorationUnit:
description: |
**Note**: This field is only available if you have the Charge Level Proration feature enabled. For more information, see Charge level proration option for a recurring charge.
Use this field to specify the unit of proration for a recurring charge. The tenant-level proration option will be overridden.
enum:
- ProrateByDay
- ProrateByMonthFirst
type: string
daysInMonth:
description: |
**Note**: This field is only available if you have the Charge Level Proration feature enabled. For more information, see Charge level proration option for a recurring charge.
Use this field to specify the number of days counted for a month when prorating a recurring charge. The tenant-level proration option will be overridden. See more details for each of the following enum values in Proration.
enum:
- UseActualDays
- Assume30Days
- Assume30DaysStrict
type: string
recognizedRevenueAccountingCode:
description: |
The recognizedRevenueAccountingCode of a standalone charge.
**Note:** This field is available when the Standalone Orders and Zuora Finance features are enabled.
type: string
revRecCode:
description: |
Revenue Recognition Code
maxLength: 70
type: string
revRecTriggerCondition:
description: |
Specifies the revenue recognition trigger condition.
* `Contract Effective Date`
* `Service Activation Date`
* `Customer Acceptance Date`
enum:
- Contract Effective Date
- Service Activation Date
- Customer Acceptance Date
type: string
revenueRecognitionRuleName:
description: |
Specifies the revenue recognition rule, such as `Recognize upon invoicing` or `Recognize daily over time`.
type: string
revenueRecognitionTiming:
description: |
Specifies the type of revenue recognition timing.
Predefined options are listed as enum values in this API Reference. Other options might also be avaliable depending on the revenue recognition policy configuration in the Zuora Billing UI.
**Note**: This field is only available if you have both the Order to Revenue feature and the Standalone Orders feature enabled.
maxLength: 200
type: string
enum:
- Upon Billing Document Posting Date
- Upon Order Activation Date
revenueAmortizationMethod:
description: |
Specifies the type of revenue amortization method.
Predefined options are listed as enum values in this API Reference. Other options might also be avaliable depending on the revenue recognition policy configuration in the Zuora Billing UI.
**Note**: This field is only available if you have both the Order to Revenue feature and the Standalone Orders feature enabled.
maxLength: 200
type: string
enum:
- Immediate
- Ratable Using Start And End Dates
rolloverApply:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
This field defines the priority of rollover, which is either first or last.
enum:
- ApplyFirst
- ApplyLast
type: string
rolloverPeriodLength:
default: null
description: |
**Note**: This field is only available if you have the [Prepaid with
Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown)
feature enabled.
Use this field when you want to set the rollover fund's period length shorter than the prepayment charge's validity period. In this case, you must set the `rolloverPeriods` field to 1. For example, you can define the rollover fund's period length as 5 months, shorter than the prepayment charge's validity period: a year.
type: integer
rolloverPeriods:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
This field defines the number of rollover periods, it is restricted to 3.
type: number
startDate:
$ref: '#/components/schemas/CreateOrderTriggerParams'
taxCode:
description: |
The taxCode of a standalone charge.
**Note:** This field is available when the Standalone Orders feature is enabled.
type: string
taxMode:
description: |
The taxMode of a standalone charge.
Values:
* `TaxExclusive`
* `TaxInclusive`
**Note:** This field is available when the Standalone Orders feature is enabled.
type: string
unBilledReceivablesAccountingCode:
description: |
The unBilledReceivablesAccountingCode of a standalone charge.
**Note:** This field is available when the Standalone Orders feature and the Billing - Revenue Integration or Order to Revenue feature are enabled.
type: string
uniqueToken:
description: |
Unique identifier for the charge. This identifier enables you to refer to the charge before the charge has an internal identifier in Zuora.
For instance, suppose that you want to use a single order to add a product to a subscription and later update the same product. When you add the product, you can set a unique identifier for the charge. Then when you update the product, you can use the same unique identifier to specify which charge to modify.
maxLength: 50
type: string
upsellOriginChargeNumber:
description: |
The identifier of the original upselling charge associated with the current charge.
For a termed subscription, you can now use the "Create an order" API operation to perform an Add Product order action to make a product quantity upsell for per unit recurring charges. The benefit is that the charge added by this approach will be automatically combined with the original existing charge for which you want to upsell when the subscription is renewed. The approach is as follows:
* Use an Add Product order action to add a charge that is of the same charge type, charge model, and charge end date as the existing per unit recurring charge for which you want to make a quantity upsell.
* In the preceding charge to add, use the `upsellOriginChargeNumber` field to specify the existing rate plan charge for which you want to make the quantity upsell.
Note that a termed subscription with such upsell charges can not be changed to an evergreen subscription.
**Note**: The Quantity Upsell feature is in the **Early Adopter** phase. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available. If you want to join this early adopter program, submit a request at [Zuora Global
Support](https://support.zuora.com).
type: string
validityPeriodType:
description: |
**Note**: This field is only available if you have enabled either of the following:
* Prepaid with Drawdown
* Minimum Commitment
* Both Minimum Commitment and Standalone Orders
You can use this field in the following scenarios:
* When you create a [prepayment charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge), use this field to define the period in which the prepayment units are valid to use.
* When you override the setting of commitment true-up charge from the product catalog, set this field consistently with the value of the `billing` > `billingPeriod` field in this charge.
* When you use a standalone order to create a commitment true-up charge, set this field consistently with the value of the `billing` > `billingPeriod` field in this charge.
enum:
- SUBSCRIPTION_TERM
- ANNUAL
- SEMI_ANNUAL
- QUARTER
- MONTH
type: string
required:
- productRatePlanChargeId
title: charge
type: object
UsageFlatFeePricingOverride:
allOf:
- $ref: '#/components/schemas/PriceChangeParams'
- properties:
listPrice:
description: |
Price of the charge.
type: number
originalListPrice:
description: |
The original list price is the price of a product or service at which it is listed for sale by a manufacturer or retailer.
type: number
type: object
description: |
Pricing information about a usage charge that uses the "flat fee" charge model. In this charge model, the charge has a fixed price.
title: usageFlatFee
UsageOveragePricingOverride:
allOf:
- $ref: '#/components/schemas/PriceChangeParams'
- properties:
includedUnits:
description: |
Number of free units that may be consumed.
minimum: 0
type: number
numberOfPeriods:
description: |
Number of periods that Zuora considers when calculating overage charges with overage smoothing.
minimum: 1
type: integer
originalListPrice:
description: |
The original list price is the price of a product or service at which it is listed for sale by a manufacturer or retailer.
type: number
overagePrice:
description: |
Price per overage unit consumed.
type: number
overageUnusedUnitsCreditOption:
description: |
Specifies whether to credit the customer for unused units.
If the value of this field is `CreditBySpecificRate`, use the `unusedUnitsCreditRates` field to specify the rate at which to credit the customer for unused units.
enum:
- NoCredit
- CreditBySpecificRate
type: string
unusedUnitsCreditRates:
description: |
Per-unit rate at which to credit the customer for unused units. Only applicable if the value of the `overageUnusedUnitsCreditOption` field is `CreditBySpecificRate`.
type: number
type: object
description: |
Pricing information about a usage charge that uses the "overage" charge model. In this charge model, the charge has an allowance of free units and a fixed price per additional unit consumed.
title: usageOverage
UsagePerUnitPricingOverride:
allOf:
- $ref: '#/components/schemas/PriceChangeParams'
- properties:
listPrice:
description: |
Per-unit price of the charge.
type: number
originalListPrice:
description: |
The original list price is the price of a product or service at which it is listed for sale by a manufacturer or retailer.
type: number
ratingGroup:
description: |
Specifies how Zuora groups usage records when rating usage. See [Usage Rating by Group](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Usage/Usage_Rating_by_Group) for more information.
* ByBillingPeriod (default): The rating is based on all the usages in a billing period.
* ByUsageStartDate: The rating is based on all the usages on the same usage start date.
* ByUsageRecord: The rating is based on each usage record.
* ByUsageUpload: The rating is based on all the usages in a uploaded usage file (.xls or .csv). If you import a mass usage in a single upload, which contains multiple usage files in .xls or .csv format, usage records are grouped for each usage file.
enum:
- ByBillingPeriod
- ByUsageStartDate
- ByUsageRecord
- ByUsageUpload
type: string
uom:
description: |
Unit of measure of the standalone charge.
**Note:** This field is available when the Standalone Orders feature is enabled.
type: number
type: object
description: |
Pricing information about a usage charge that uses the "per unit" charge model. In this charge model, the charge has a fixed price per unit consumed.
title: usagePerUnit
UsageTieredPricingOverride:
allOf:
- $ref: '#/components/schemas/PriceChangeParams'
- properties:
ratingGroup:
description: |
Specifies how Zuora groups usage records when rating usage. See [Usage Rating by Group](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Usage/Usage_Rating_by_Group) for more information.
* ByBillingPeriod (default): The rating is based on all the usages in a billing period.
* ByUsageStartDate: The rating is based on all the usages on the same usage start date.
* ByUsageRecord: The rating is based on each usage record.
* ByUsageUpload: The rating is based on all the usages in a uploaded usage file (.xls or .csv). If you import a mass usage in a single upload, which contains multiple usage files in .xls or .csv format, usage records are grouped for each usage file.
enum:
- ByBillingPeriod
- ByUsageStartDate
- ByUsageRecord
- ByUsageUpload
type: string
tiers:
description: |
List of cumulative pricing tiers in the charge.
items:
$ref: '#/components/schemas/ChargeTier'
type: array
uom:
description: |
Unit of measure of the standalone charge.
**Note:** This field is available when the Standalone Orders feature is enabled.
type: string
type: object
description: |
Pricing information about a usage charge that uses the "tiered pricing" charge model. In this charge model, the charge has cumulative pricing tiers that become effective as units are consumed.
title: usageTiered
UsageTieredWithOveragePricingOverride:
allOf:
- $ref: '#/components/schemas/PriceChangeParams'
- properties:
numberOfPeriods:
description: |
Number of periods that Zuora considers when calculating overage charges with overage smoothing.
minimum: 1
type: integer
originalListPrice:
description: |
The original list price is the price of a product or service at which it is listed for sale by a manufacturer or retailer.
type: number
overagePrice:
description: |
Price per overage unit consumed.
type: number
overageUnusedUnitsCreditOption:
description: |
Specifies whether to credit the customer for unused units.
If the value of this field is `CreditBySpecificRate`, use the `unusedUnitsCreditRates` field to specify the rate at which to credit the customer for unused units.
enum:
- NoCredit
- CreditBySpecificRate
type: string
tiers:
description: |
List of cumulative pricing tiers in the charge.
items:
$ref: '#/components/schemas/ChargeTier'
type: array
unusedUnitsCreditRates:
description: |
Per-unit rate at which to credit the customer for unused units. Only applicable if the value of the `overageUnusedUnitsCreditOption` field is `CreditBySpecificRate`.
type: number
type: object
description: |
Pricing information about a usage charge that uses the "tiered with overage" charge model. In this charge model, the charge has cumulative pricing tiers that become effective as units are consumed. The charge also has a fixed price per unit consumed beyond the limit of the final tier.
title: usageTieredWithOverage
UsageVolumePricingOverride:
allOf:
- $ref: '#/components/schemas/PriceChangeParams'
- properties:
ratingGroup:
description: |
Specifies how Zuora groups usage records when rating usage. See [Usage Rating by Group](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Usage/Usage_Rating_by_Group) for more information.
* ByBillingPeriod (default): The rating is based on all the usages in a billing period.
* ByUsageStartDate: The rating is based on all the usages on the same usage start date.
* ByUsageRecord: The rating is based on each usage record.
* ByUsageUpload: The rating is based on all the usages in a uploaded usage file (.xls or .csv). If you import a mass usage in a single upload, which contains multiple usage files in .xls or .csv format, usage records are grouped for each usage file.
enum:
- ByBillingPeriod
- ByUsageStartDate
- ByUsageRecord
- ByUsageUpload
type: string
tiers:
description: |
List of variable pricing tiers in the charge.
items:
$ref: '#/components/schemas/ChargeTier'
type: array
uom:
description: |
Unit of measure of the standalone charge.
**Note:** This field is available when the Standalone Orders feature is enabled.
type: number
type: object
description: |
Pricing information about a usage charge that uses the "volume pricing" charge model. In this charge model, the charge has a variable price per unit, depending on how many units are consumed.
title: usageVolume
ChargeOverride:
description: |
Charge associated with a rate plan.
properties:
accountReceivableAccountingCode:
description: |
The accountReceivableAccountingCode of a standalone charge.
**Note:** This field is available when the Standalone Orders, Zuora Finance, and Invoice Settlement features are enabled.
type: string
adjustmentLiabilityAccountingCode:
description: |
The adjustmentLiabilityAccountingCode of a standalone charge.
**Note:** This field is available when the Standalone Orders feature and the Billing - Revenue Integration or Order to Revenue feature are enabled.
type: string
adjustmentRevenueAccountingCode:
description: |
The adjustmentRevenueAccountingCode of a standalone charge.
**Note:** This field is available when the Standalone Orders feature and the Billing - Revenue Integration or Order to Revenue feature are enabled.
type: string
billing:
description: |
Billing information about the charge.
properties:
billCycleDay:
description: |
Day of the month that each billing period begins on. Only applicable if the value of the `billCycleType` field is `SpecificDayofMonth`.
maximum: 31
minimum: 0
type: integer
billCycleType:
description: |
Specifies how Zuora determines the day that each billing period begins on.
* `DefaultFromCustomer` - Each billing period begins on the bill cycle day of the account that owns the subscription.
* `SpecificDayofMonth` - Use the `billCycleDay` field to specify the day of the month that each billing period begins on.
* `SubscriptionStartDay` - Each billing period begins on the same day of the month as the start date of the subscription.
* `ChargeTriggerDay` - Each billing period begins on the same day of the month as the date when the charge becomes active.
* `SpecificDayofWeek` - Use the `weeklyBillCycleDay` field to specify the day of the week that each billing period begins on.
enum:
- DefaultFromCustomer
- SpecificDayofMonth
- SubscriptionStartDay
- ChargeTriggerDay
- SpecificDayofWeek
type: string
billingPeriod:
description: |
Billing frequency of the charge. The value of this field controls the duration of each billing period.
If the value of this field is `Specific_Days`, `Specific_Months` or `Specific_Weeks`, use the `specificBillingPeriod` field to specify the duration of each billing period.
enum:
- Month
- Quarter
- Semi_Annual
- Annual
- Eighteen_Months
- Two_Years
- Three_Years
- Five_Years
- Specific_Months
- Subscription_Term
- Week
- Specific_Weeks
- Specific_Days
type: string
billingPeriodAlignment:
description: |
Specifies how Zuora determines when to start new billing periods. You can use this field to align the billing periods of different charges.
* `AlignToCharge` - Zuora starts a new billing period on the first billing day that falls on or after the date when the charge becomes active.
* `AlignToSubscriptionStart` - Zuora starts a new billing period on the first billing day that falls on or after the start date of the subscription.
* `AlignToTermStart` - For each term of the subscription, Zuora starts a new billing period on the first billing day that falls on or after the start date of the term.
See the `billCycleType` field for information about how Zuora determines the billing day.
**Note**: This field is not supported in one time charges.
enum:
- AlignToCharge
- AlignToSubscriptionStart
- AlignToTermStart
type: string
billingTiming:
description: |
Specifies whether to invoice for a billing period on the first day of the billing period (billing in advance) or the first day of the next billing period (billing in arrears).
enum:
- IN_ADVANCE
- IN_ARREARS
type: string
specificBillingPeriod:
description: |
Duration of each billing period in months or weeks, depending on the value of the `billingPeriod` field. Only applicable if the value of the `billingPeriod` field is `Specific_Months` or `Specific_Weeks`.
type: integer
weeklyBillCycleDay:
description: |
Day of the week that each billing period begins on. Only applicable if the value of the `billCycleType` field is `SpecificDayofWeek`.
enum:
- Sunday
- Monday
- Tuesday
- Wednesday
- Thursday
- Friday
- Saturday
type: string
type: object
chargeFunction:
description: |
**Note**: This field is only available if you have both the Prepaid with Drawdown and Standalone Orders features enabled.
With this field, you can use a standalone order to subscribe to a minimum commitment subscription.
This field defines what type of charge it is:
* CommitmentTrueUp: For recurring charges. Currency based minimum commitment charge.
* CreditCommitment: For usage charges. Credit to minimum commitment funds.
enum:
- CommitmentTrueUp
- CreditCommitment
type: string
commitmentType:
description: |
**Note**: This field is only available if you have both the Prepaid with Drawdown and Standalone Orders features enabled.
With this field, you can use a standalone order to subscribe to a minimum commitment subscription.
This field defines the type of the commitment for both the commitment true-up charge and credit commitment charge, and so you must define the type as `CURRENCY`.
enum:
- CURRENCY
type: string
creditOption:
description: |
**Note**: This field is only available if you have both the Minimum Commitment and Standalone Orders features enabled.
With this field, you can use a standalone order to subscribe to a minimum commitment subscription.
This field defines the way to calculate credit. See [Credit Option](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge#Credit_Option) for more information.
enum:
- TimeBased
- ConsumptionBased
- FullCreditBack
type: string
chargeModel:
description: |
The chargeModel of a standalone charge.
Supported charge models:
* `FlatFee`
* `PerUnit`
* `Volume`
* `Tiered`
* `DiscountFixedAmount`
* `DiscountPercentage`
**Note:** This field is available when the Standalone Orders feature is enabled.
type: string
chargeNumber:
description: |
Charge number of the charge. For example, C-00000307.
* If you do not set this field, Zuora will generate a charge number starting with a default prefix, for example, C-. This default prefix is predefined in **Billing Settings** > **Define Default Subscription and Order Settings**.
* If you want to use a custom charge number, do not use the default prefix predefined in **Billing Settings** > **Define Default Subscription and Order Settings**. Use your own prefix, for example, SC-.
maxLength: 50
type: string
chargeType:
description: |
The chargeType of a standalone charge.
Supported charge types:
* `OneTime`
* `Recurring`
* `Usage`
**Note:** This field is available when the Standalone Orders feature is enabled.
type: string
contractAssetAccountingCode:
description: |
The contractAssetAccountingCode of a standalone charge.
**Note:** This field is available when the Standalone Orders feature and the Billing - Revenue Integration or Order to Revenue feature are enabled.
type: string
contractLiabilityAccountingCode:
description: |
The contractLiabilityAccountingCode of a standalone charge.
**Note:** This field is available when the Standalone Orders feature and the Billing - Revenue Integration or Order to Revenue feature are enabled.
type: string
contractRecognizedRevenueAccountingCode:
description: |
The contractRecognizedRevenueAccountingCode of a standalone charge.
**Note:** This field is available when the Standalone Orders feature and the Billing - Revenue Integration or Order to Revenue feature are enabled.
type: string
customFields:
$ref: '#/components/schemas/RatePlanChargeObjectCustomFields'
deferredRevenueAccountingCode:
description: |
The deferredRevenueAccountingCode of a standalone charge.
**Note:** This field is available when the Standalone Orders and Zuora Finance features are enabled.
type: string
description:
description: |
Description of the charge.
maxLength: 500
type: string
drawdownRate:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
The [conversion rate](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_drawdown_charge#UOM_Conversion) between Usage UOM and Drawdown UOM for a [drawdown charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_drawdown_charge). Must be a positive number (>0).
type: number
endDate:
$ref: '#/components/schemas/EndConditions'
estimatedStartDate:
type: string
format: date
description: |
The estimated start date of the pending charge in an active subscription.
The value must be a date within the subscription term. The system will then automatically calculate the estimated end date for the pending charge. The estimated start and end dates are used to manage the estimated charge duration and forecast the revenue for the pending charge.
**Note:** This field is available only when the Pending Subscription Processing feature is turned on.
excludeItemBillingFromRevenueAccounting:
default: false
description: |
The flag to exclude rate plan charge related invoice items, invoice item adjustments, credit memo items, and debit memo items from revenue accounting.
If both the following features are enabled in your tenant, you must ensure the `excludeItemBillingFromRevenueAccounting` field is set consistently for a prepayment charge and the corresponding drawdown charge. In addition, if the `excludeItemBookingFromRevenueAccounting` field in an Create Subscription or Add Product order action is set to `false`, you must also set the `excludeItemBillingFromRevenueAccounting` field in this order action to `false`.
* Prepaid with Drawdown
* Unbilled Usage
**Note**: This field is only available if you have the Order to Revenue or [Zuora Billing - Revenue Integration](https://knowledgecenter.zuora.com/Zuora_Revenue/Zuora_Billing_-_Revenue_Integration) feature enabled.
type: boolean
excludeItemBookingFromRevenueAccounting:
default: false
description: |
The flag to exclude rate plan charges from revenue accounting.
If both the following features are enabled in your tenant, you must ensure the `excludeItemBookingFromRevenueAccounting` field is set consistently for a prepayment charge and the corresponding drawdown charge.
* Prepaid with Drawdown
* Unbilled Usage
**Note**: This field is only available if you have the Order to Revenue or [Zuora Billing - Revenue Integration](https://knowledgecenter.zuora.com/Zuora_Revenue/Zuora_Billing_-_Revenue_Integration) feature enabled.
type: boolean
isAllocationEligible:
description: |
This field is used to identify if the charge segment is allocation
eligible in revenue recognition.
**Note**: The field is only available if you have the Order to Revenue feature enabled. To enable this field, submit a request at Zuora Global Support.
type: boolean
isRollover:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
The value is either "True" or "False". It determines whether the rollover fields are needed.
type: boolean
isUnbilled:
description: |
This field is used to dictate how to perform the accounting during revenue
recognition.
**Note**: The field is only available if you have the Order to Revenue feature enabled. To enable this field, submit a request at Zuora Global Support.
type: boolean
name:
description: |
The name of a standalone charge.
**Note:** This field is available when the Standalone Orders feature is enabled.
type: string
negotiatedPriceTable:
description: |
Array of negotiated price table rate card entries in the order request.
**Note:** To enable the Negotiated Price Table feature, submit a request to Zuora Global Support.
items:
$ref: '#/components/schemas/NegotiatedItems'
type: array
pobPolicy:
description: |
The pobPolicy of a standalone charge.
**Note:** This field is available when the Standalone Orders feature is enabled.
type: string
prepaidQuantity:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
The number of units included in a [prepayment charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge). Must be a positive number (>0).
type: number
pricing:
description: |
Pricing information about the charge.
properties:
chargeModelData:
$ref: '#/components/schemas/ChargeModelDataOverride'
discount:
$ref: '#/components/schemas/DiscountPricingOverride'
oneTimeFlatFee:
$ref: '#/components/schemas/OneTimeFlatFeePricingOverride'
oneTimePerUnit:
$ref: '#/components/schemas/OneTimePerUnitPricingOverride'
oneTimeTiered:
$ref: '#/components/schemas/OneTimeTieredPricingOverride'
oneTimeVolume:
$ref: '#/components/schemas/OneTimeVolumePricingOverride'
recurringDelivery:
$ref: '#/components/schemas/RecurringDeliveryPricingOverride'
recurringFlatFee:
$ref: '#/components/schemas/RecurringFlatFeePricingOverride'
recurringPerUnit:
$ref: '#/components/schemas/RecurringPerUnitPricingOverride'
recurringTiered:
$ref: '#/components/schemas/RecurringTieredPricingOverride'
recurringVolume:
$ref: '#/components/schemas/RecurringVolumePricingOverride'
usageFlatFee:
$ref: '#/components/schemas/UsageFlatFeePricingOverride'
usageOverage:
$ref: '#/components/schemas/UsageOveragePricingOverride'
usagePerUnit:
$ref: '#/components/schemas/UsagePerUnitPricingOverride'
usageTiered:
$ref: '#/components/schemas/UsageTieredPricingOverride'
usageTieredWithOverage:
$ref: '#/components/schemas/UsageTieredWithOveragePricingOverride'
usageVolume:
$ref: '#/components/schemas/UsageVolumePricingOverride'
type: object
pricingAttributes:
description: |
Container for pricing attribute and value in the order request.
**Note:** To enable Dynamic Pricing, submit a request to Zuora Global Support.
type: object
additionalProperties: true
productCategory:
description: |
The productCategory of a standalone charge.
**Note:** This field is available when the Standalone Orders feature is enabled.
type: string
productClass:
description: |
The productClass of a standalone charge.
**Note:** This field is available when the Standalone Orders feature is enabled.
type: string
productFamily:
description: |
The productFamily of a standalone charge.
**Note:** This field is available when the Standalone Orders feature is enabled.
type: string
productLine:
description: |
The productLine of a standalone charge.
**Note:** This field is available when the Standalone Orders feature is enabled.
type: string
productRatePlanChargeNumber:
description: |
Number of a product rate-plan charge for this subscription.
type: string
productRateplanChargeId:
description: |
Internal identifier of the product rate plan charge that the charge is based on.
type: string
prorationOption:
description: |
**Note**: This field is only available if you have the Charge Level Proration feature enabled. For more information, see Usage charge proration and Charge level proration option for a recurring charge.
You can use this field to specify the charge-level proration option for a usage charge or recurring charge when you creating or adding a subscription rate plan charge through an order. The tenant-level proration option will be overridden.
* `NoProration`: charge-level proration option that you can set for a usage charge. This option means to not use any proration, which is the default current system behavior for a usage charge.
* `TimeBasedProration`: charge-level proration option that you can set for a usage charge. This option means to prorate the usage charge amount using the actual number of days if the billing period is a partial period.
* `DefaultFromTenantSetting`: charge-level proration option that you can set for a recurring charge. This option means to follow the customer billing rule proration setting.
* `ChargeFullPeriod`: charge-level proration option that you can set for a recurring charge. This options means to charge the full period amount for a partial billing period. Note that this setting means that there is no proration for either collecting or refunding. Even if you cancel the recurring charge in the middle of a billing period, there is no refund for this billing period.
* `CustomizeProrationOptionOverrides`: charge-level proration option that you can set for a recurring charge. This option means to use the customized charge proration settings that is specified by the `ratingPropertiesOverride` field.
enum:
- NoProration
- TimeBasedProration
- DefaultFromTenantSetting
- ChargeFullPeriod
- CustomizeProrationOptionOverrides
type: string
ratingPropertiesOverride:
description: |
**Note**: This field is only available if you have the Charge Level Proration feature enabled. For more information, see Charge level proration option for a recurring charge.
This field is used only when the value of the `prorationOption` field is set to `CustomizeProrationOptionOverrides`.
Use this field to specify more customized proration options for a recurring charge when you creating or adding a subscription rate plan charge through an order. The tenant-level proration option will be overridden.
type: object
properties:
isProratePartialMonth:
description: |
**Note**: This field is only available if you have the Charge Level Proration feature enabled. For more information, see Charge level proration option for a recurring charge.
Use this field to specify whether to prorate the recurring charge for a partial month. The tenant-level proration option will be overridden.
type: boolean
prorationUnit:
description: |
**Note**: This field is only available if you have the Charge Level Proration feature enabled. For more information, see Charge level proration option for a recurring charge.
Use this field to specify the unit of proration for a recurring charge. The tenant-level proration option will be overridden.
enum:
- ProrateByDay
- ProrateByMonthFirst
type: string
daysInMonth:
description: |
**Note**: This field is only available if you have the Charge Level Proration feature enabled. For more information, see Charge level proration option for a recurring charge.
Use this field to specify the number of days counted for a month when prorating a recurring charge. The tenant-level proration option will be overridden. See more details for each of the following enum values in Proration.
enum:
- UseActualDays
- Assume30Days
- Assume30DaysStrict
type: string
recognizedRevenueAccountingCode:
description: |
The recognizedRevenueAccountingCode of a standalone charge.
**Note:** This field is available when the Standalone Orders and Zuora Finance features are enabled.
type: string
revRecCode:
description: |
Revenue Recognition Code
maxLength: 70
type: string
revRecTriggerCondition:
description: |
Specifies the revenue recognition trigger condition.
* `Contract Effective Date`
* `Service Activation Date`
* `Customer Acceptance Date`
enum:
- Contract Effective Date
- Service Activation Date
- Customer Acceptance Date
type: string
revenueRecognitionRuleName:
description: |
Specifies the revenue recognition rule, such as `Recognize upon invoicing` or `Recognize daily over time`.
type: string
revenueRecognitionTiming:
description: |
Specifies the type of revenue recognition timing.
Predefined options are listed as enum values in this API Reference. Other options might also be avaliable depending on the revenue recognition policy configuration in the Zuora Billing UI.
**Note**: This field is only available if you have the Order to Revenue feature enabled.
maxLength: 200
type: string
enum:
- Upon Billing Document Posting Date
- Upon Order Activation Date
revenueAmortizationMethod:
description: |
Specifies the type of revenue amortization method.
Predefined options are listed as enum values in this API Reference. Other options might also be avaliable depending on the revenue recognition policy configuration in the Zuora Billing UI.
**Note**: This field is only available if you have the Order to Revenue feature enabled.
maxLength: 200
type: string
enum:
- Immediate
- Ratable Using Start And End Dates
rolloverApply:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
This field defines the priority of rollover, which is either first or last.
enum:
- ApplyFirst
- ApplyLast
type: string
rolloverPeriodLength:
default: null
description: |
**Note**: This field is only available if you have the [Prepaid with
Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown)
feature enabled.
Use this field when you want to set the rollover fund's period length shorter than the prepayment charge's validity period. In this case, you must set the `rolloverPeriods` field to 1. For example, you can define the rollover fund's period length as 5 months, shorter than the prepayment charge's validity period: a year.
type: integer
rolloverPeriods:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
This field defines the number of rollover periods, it is restricted to 3.
type: number
startDate:
$ref: '#/components/schemas/TriggerParams'
taxCode:
description: |
The tax code of a charge. This field is available when the `taxable` field is set to `true`.
type: string
taxMode:
description: |
The tax mode of a charge. This field is available when the `taxable` field is set to `true`.
enum:
- TaxExclusive
- TaxInclusive
type: string
taxable:
description: |
The flag indicates whether the charge is taxable. If this field is set to `true`, the `taxCode` and `taxMode` fields must be specified.
type: boolean
unBilledReceivablesAccountingCode:
description: |
The unBilledReceivablesAccountingCode of a standalone charge.
**Note:** This field is available when the Standalone Orders feature and the Billing - Revenue Integration or Order to Revenue feature are enabled.
type: string
uniqueToken:
description: |
Unique identifier for the charge. This identifier enables you to refer to the charge before the charge has an internal identifier in Zuora.
For instance, suppose that you want to use a single order to add a product to a subscription and later update the same product. When you add the product, you can set a unique identifier for the charge. Then when you update the product, you can use the same unique identifier to specify which charge to modify.
maxLength: 50
type: string
validityPeriodType:
description: |
**Note**: This field is only available if you have enabled either of the following:
* Prepaid with Drawdown
* Minimum Commitment
* Both Minimum Commitment and Standalone Orders
You can use this field in the following scenarios:
* When you create a [prepayment charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge), use this field to define the period in which the prepayment units are valid to use.
* When you override the setting of commitment true-up charge from the product catalog, set this field consistently with the value of the `billing` > `billingPeriod` field in this charge.
* When you use a standalone order to create a commitment true-up charge, set this field consistently with the value of the `billing` > `billingPeriod` field in this charge.
enum:
- SUBSCRIPTION_TERM
- ANNUAL
- SEMI_ANNUAL
- QUARTER
- MONTH
type: string
required:
- productRateplanChargeId
title: charge
type: object
CreateOrderResult:
properties:
accountId:
description: The account ID for the order. This field is returned instead of the `accountNumber` field if the `returnIds` query parameter is set to `true`.
maxLength: 32
type: string
accountNumber:
description: The account number for the order.
maxLength: 50
type: string
commitments:
description: The commitments created by this order request.
items:
$ref: '#/components/schemas/CommitmentOutput'
type: array
creditMemoIds:
description: An array of the credit memo IDs generated in this order request. The credit memo is only available if you have the Invoice Settlement feature enabled. This field is returned instead of the `creditMemoNumbers` field if the `returnIds` query parameter is set to `true`.
items:
type: string
maxLength: 32
type: array
creditMemoNumbers:
description: An array of the credit memo numbers generated in this order request. The credit memo is only available if you have the Invoice Settlement feature enabled.
items:
type: string
maxLength: 255
type: array
invoiceIds:
description: An array of the invoice IDs generated in this order request. Normally it includes one invoice ID only, but can include multiple items when a subscription was tagged as invoice separately. This field is returned instead of the `invoiceNumbers` field if the `returnIds` query parameter is set to `true`.
items:
type: string
maxLength: 32
type: array
invoiceNumbers:
description: An array of the invoice numbers generated in this order request. Normally it includes one invoice number only, but can include multiple items when a subscription was tagged as invoice separately.
items:
type: string
maxLength: 255
type: array
orderId:
description: The ID of the order created. This field is returned instead of the `orderNumber` field if the `returnIds` query parameter is set to `true`.
maxLength: 32
type: string
orderLineItems:
description: |
[Order Line Items](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Order_Line_Items/AA_Overview_of_Order_Line_Items) are non subscription based items created by an Order, representing transactional charges such as one-time fees, physical goods, or professional service charges that are not sold as subscription services.
With the Order Line Items feature enabled, you can now launch non-subscription and unified monetization business models in Zuora, in addition to subscription business models.
**Note:** The [Order Line Items](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Order_Line_Items/AA_Overview_of_Order_Line_Items) feature is now generally available to all Zuora customers. You need to enable the [Orders](https://knowledgecenter.zuora.com/BC_Subscription_Management/Orders/AA_Overview_of_Orders#Orders) feature to access the [Order Line Items](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Order_Line_Items/AA_Overview_of_Order_Line_Items) feature. As of Zuora Billing Release 313 (November 2021), new customers who onboard on [Orders](https://docs.zuora.com/en/zuora-billing/manage-accounts-subscriptions-and-non-subscriptions/manage-subscription-transactions/orders/orders-introduction/overview-of-orders) will have the [Order Line Items](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Order_Line_Items) feature enabled by default.
items:
properties:
id:
description: The sytem generated Id for the Order Line Item.
maxLength: 32
type: string
itemNumber:
description: The number for the Order Line Item.
maxLength: 100
type: string
type: object
type: array
orderNumber:
description: The order number of the order created.
maxLength: 100
type: string
paidAmount:
description: The total amount collected in this order request.
maxLength: 22
minLength: 9
type: string
paymentId:
description: The payment Id that is collected in this order request. This field is returned instead of the `paymentNumber` field if the `returnIds` query parameter is set to `true`.
maxLength: 32
type: string
paymentNumber:
description: The payment number that is collected in this order request.
maxLength: 32
type: string
ramps:
description: |
**Note**: This field is only available if you have the Ramps feature enabled. The [Orders](https://docs.zuora.com/en/zuora-billing/manage-accounts-subscriptions-and-non-subscriptions/manage-subscription-transactions/orders/orders-introduction/overview-of-orders) feature must be enabled before you can access the [Ramps](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Ramps_and_Ramp_Metrics/A_Overview_of_Ramps_and_Ramp_Metrics) feature. The Ramps feature is available for customers with Enterprise and Nine editions by default. If you are a Growth customer, see [Zuora Editions](https://docs.zuora.com/en/entitlements/current-entitlements/zuora-editions) for pricing information coming October 2020.
The ramp definitions created by this order request.
items:
properties:
rampNumber:
description: The number of the ramp definition.
maxLength: 50
type: string
subscriptionNumber:
description: The number of the subscription that this ramp deal definition is applied to.
maxLength: 150
type: string
type: object
type: array
refunds:
description: Container for refunds.
items:
properties:
number:
description: The refund number.
example: R-00009564
maxLength: 32
type: string
refundInvoiceNumbers:
description: An array of the refunded invoice numbers generated in this order request.
items:
type: string
maxLength: 255
type: array
status:
description: The status of the refund.
enum:
- Success
- Error
type: string
type: object
type: array
status:
description: Status of the order. `Pending` is only applicable for an order that contains a `CreateSubscription` order action.
enum:
- Draft
- Pending
- Completed
- Scheduled
type: string
subscriptionIds:
description: Container for the subscription IDs of the subscriptions in an order. This field is returned if the `returnIds` query parameter is set to `true`.
items:
type: string
maxLength: 32
type: array
subscriptions:
description: |
This field is available only if you are on the latest Zuora API minor
version, or you set the `Zuora-Version` request header to `223.0` or a
later available version. To use this field in the method, you must set the `Zuora-Version` parameter to the minor version number in the request header.
Container for the subscription numbers and statuses in an order.
items:
properties:
status:
description: Status of the subscription. `Pending Activation` and `Pending Acceptance` are only applicable for an order that contains a `CreateSubscription` order action.
enum:
- Active
- Pending Activation
- Pending Acceptance
- Cancelled
- Suspended
type: string
subscriptionId:
description: Subscription ID of the subscription included in this order. This field is returned instead of the `subscriptionNumber` field if the `returnIds` query parameter is set to `true`.
maxLength: 32
type: string
subscriptionNumber:
description: |
Subscription number of the subscription included in this order.
maxLength: 150
type: string
subscriptionOwnerId:
description: |
Subscription owner account id of the subscription.
type: string
subscriptionOwnerNumber:
description: |
Subscription owner account number of the subscription.
type: string
type: object
writeOff:
description: Container for write-offs.
items:
properties:
amount:
description: The amount written off from the invoice balance.
maximum: 22
minimum: 9
type: number
failedReason:
description: The reason of write-off failure.
type: string
invoiceNumber:
description: The number of the invoice that is written off.
example: INV00051208
maxLength: 255
type: string
status:
description: The status of the write-off.
enum:
- Success
- Failed
type: string
writeOffCreditMemoNumber:
description: The number of the credit memo that is written off.
maxLength: 255
type: string
type: object
type: array
type: object
CommitmentOutput:
type: object
description: |
The Commitment object in the "Create an order" or "Update an order" response.
title: UpsertOrderCommitmentResponse
properties:
id:
type: string
description: |
ID of the commitment
commitmentNumber:
type: string
description: |
Number of the commitment.
type:
$ref: '#/components/schemas/CommitmentTypeEnum'
startDate:
type: string
format: date
description: |
The start date of the commitment.
endDate:
type: string
format: date
description: |
The end date of the commitment.
status:
type: string
description: The status of the commitment.
enum:
- Canceled
- Active
totalAmount:
type: number
format: double
description: The total amount of the commitment.
schedules:
description: |
A list of Commitment schedule objects.
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the schedule.
startDate:
type: string
description: The start date of the schedule.
endDate:
type: string
description: The end date of the schedule.
totalAmount:
type: number
format: double
description: The total amount of the schedule.
status:
type: string
description: The status of the schedule.
enum:
- Active
- Evaluated
- Canceled
CommitmentTypeEnum:
type: string
enum:
- MinCommitment
- MaxCommitment
description: |
The type of the commitment.
OrderLineItemCommonRetrieveOrder:
properties:
UOM:
description: |
Specifies the units to measure usage.
type: string
accountingCode:
description: |
The accounting code for the Order Line Item.
type: string
adjustmentLiabilityAccountingCode:
description: |
The accounting code on the Order Line Item object for customers using [Zuora Billing - Revenue Integration](https://knowledgecenter.zuora.com/Zuora_Revenue/Zuora_Billing_-_Revenue_Integration).
type: string
adjustmentRevenueAccountingCode:
description: |
The accounting code on the Order Line Item object for customers using [Zuora Billing - Revenue Integration](https://knowledgecenter.zuora.com/Zuora_Revenue/Zuora_Billing_-_Revenue_Integration).
type: string
amountPerUnit:
description: |
The actual charged amount per unit for the Order Line Item.
type: number
billTargetDate:
description: |
The target date for the Order Line Item to be picked up by bill run for billing.
format: date
type: string
billTo:
description: |
The ID of the bill-to contact of an order line item. An existing contact under the billing account is specified as the bill-to contact of the order line item. The billing account is the order account.
type: string
billToSnapshotId:
description: |
The snapshot of the ID for an account used as the bill-to contact of an order line item. This field is used to store the original information about the account, in case the information about the account is changed after the creation of the order line item. The `billToSnapshotId` field is exposed while retrieving the order line item details.
type: string
billingRule:
description: |
The billing rule of the Order Line Item.
enum:
- TriggerWithoutFulfillment
- TriggerAsFulfillmentOccurs
type: string
contractAssetAccountingCode:
description: |
The accounting code on the Order Line Item object for customers using [Zuora Billing - Revenue Integration](https://knowledgecenter.zuora.com/Zuora_Revenue/Zuora_Billing_-_Revenue_Integration).
type: string
contractLiabilityAccountingCode:
description: |
The accounting code on the Order Line Item object for customers using [Zuora Billing - Revenue Integration](https://knowledgecenter.zuora.com/Zuora_Revenue/Zuora_Billing_-_Revenue_Integration).
type: string
contractRecognizedRevenueAccountingCode:
description: |
The accounting code on the Order Line Item object for customers using [Zuora Billing - Revenue Integration](https://knowledgecenter.zuora.com/Zuora_Revenue/Zuora_Billing_-_Revenue_Integration).
type: string
currency:
description: |
The currency for the order line item. You can specify a currency when creating an order line item through the "Create an order" operation.
type: string
customFields:
$ref: '#/components/schemas/OrderLineItemCustomFields'
deferredRevenueAccountingCode:
description: |
The deferred revenue accounting code for the Order Line Item.
type: string
description:
description: |
The description of the Order Line Item.
type: string
discount:
description: |
This field shows the total discount amount that is applied to an order line item after the `inlineDiscountType`, `inlineDiscountPerUnit` and `quantity` fields are set.
The inline discount is applied to the list price of an order line item (see the `listPrice` field).
type: number
excludeItemBillingFromRevenueAccounting:
description: |
The flag to exclude Order Line Item related invoice items, invoice item adjustments, credit memo items, and debit memo items from revenue accounting.
**Note**: This field is only available if you have the Order to Revenue or [Zuora Billing - Revenue Integration](https://knowledgecenter.zuora.com/Zuora_Revenue/Zuora_Billing_-_Revenue_Integration) feature enabled.
type: boolean
excludeItemBookingFromRevenueAccounting:
description: |
The flag to exclude Order Line Item from revenue accounting.
**Note**: This field is only available if you have the Order to Revenue or [Zuora Billing - Revenue Integration](https://knowledgecenter.zuora.com/Zuora_Revenue/Zuora_Billing_-_Revenue_Integration) feature enabled.
type: boolean
inlineDiscountPerUnit:
description: |
This field is used in accordance with the `inlineDiscountType` field, in the following manner:
* If the `inlineDiscountType` field is set as `Percentage`, this field specifies the discount percentage for each unit of the order line item. For exmaple, if you specify `5` in this field, the discount percentage is 5%.
* If the `inlineDiscountType` field is set as `FixedAmount`, this field specifies the discount amount on each unit of the order line item. For exmaple, if you specify `10` in this field, the discount amount on each unit of the order line item is 10.
Once you set the `inlineDiscountType`, `inlineDiscountPerUnit`, and `listPricePerUnit` fields, the system will automatically generate the `amountPerUnit` field. You shall not set the `amountPerUnit` field by yourself.
type: number
inlineDiscountType:
description: |
This field is used to specify the inline discount type, which can be `Percentage`, `FixedAmount`, or `None`. The default value is `Percentage`.
This field is used together with the `inlineDiscountPerUnit` field to specify inline discounts for order line items. The inline discount is applied to the list price of an order line item.
Once you set the `inlineDiscountType`, `inlineDiscountPerUnit`, and `listPricePerUnit` fields, the system will automatically generate the `amountPerUnit` field. You shall not set the `amountPerUnit` field by yourself.
enum:
- Percentage
- FixedAmount
- None
type: string
invoiceOwnerAccountId:
description: |
The account ID of the invoice owner of the order line item.
type: string
invoiceOwnerAccountName:
description: |
The account name of the invoice owner of the order line item.
type: string
invoiceOwnerAccountNumber:
description: |
The account number of the invoice owner of the order line item.
type: string
isAllocationEligible:
description: |
This field is used to identify if the charge segment is allocation
eligible in revenue recognition.
**Note**: The field is only available if you have the Order to Revenue feature enabled. To enable this field, submit a request at Zuora Global Support.
type: boolean
isUnbilled:
description: |
This field is used to dictate how to perform the accounting during revenue
recognition.
**Note**: The field is only available if you have the Order to Revenue feature enabled. To enable this field, submit a request at Zuora Global Support.
type: boolean
itemCategory:
default: Sales
description: |
The category of the Order Line Item, to indicate a product sale or return.
enum:
- Sales
- Return
type: string
itemName:
description: |
The name of the Order Line Item.
type: string
itemState:
description: |
The state of an Order Line Item. See [State transitions for an order, order line item, and fulfillment](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Order_Line_Items/AB_Order_Line_Item_States_and_Order_States) for more information.
enum:
- Executing
- Booked
- SentToBilling
- Complete
- Cancelled
type: string
itemType:
description: |
The type of the Order Line Item.
enum:
- Product
- Fee
- Services
type: string
listPrice:
description: |
The extended list price for an order line item, calculated by the formula: listPrice = listPricePerUnit * quantity
type: number
listPricePerUnit:
description: |
The list price per unit for the Order Line Item.
type: number
originalOrderId:
description: |
The ID of the original sale order for a return order line item.
type: string
originalOrderLineItemId:
description: |
The ID of the original sale order line item for a return order line item.
type: string
originalOrderLineItemNumber:
description: |
The number of the original sale order line item for a return order line item.
type: string
originalOrderNumber:
description: |
The number of the original sale order for a return order line item.
type: string
ownerAccountId:
description: |
The account ID of the owner of the order line item.
type: string
ownerAccountName:
description: |
The account name of the owner of the order line item.
type: string
ownerAccountNumber:
description: |
The account number of the owner of the order line item.
type: string
productCode:
description: |
The product code for the Order Line Item.
type: string
productRatePlanChargeId:
description: |
Id of a Product Rate Plan Charge. Only one-time charges are supported.
type: string
purchaseOrderNumber:
description: |
Used by customers to specify the Purchase Order Number provided by the buyer.
type: string
quantity:
description: |
The quantity of units, such as the number of authors in a hosted wiki service.
type: number
quantityAvailableForReturn:
description: |
The quantity that can be returned for an order line item.
type: number
quantityFulfilled:
description: |
The fulfilled quantity for an order line item.
type: number
quantityPendingFulfillment:
description: |
The quantity to fulfill for an order line item.
type: number
recognizedRevenueAccountingCode:
description: |
The recognized revenue accounting code for the Order Line Item.
type: string
relatedSubscriptionNumber:
description: |
Use this field to relate an order line item to a subscription when you create the order line item.
* To relate an order line item to a new subscription which is yet to create in the same "Create an order" call, use this field in combination with the `subscriptions` > `subscriptionNumber` field in the "Create order" operation. Specify this field to the same value as that of the 'subscriptions' > `subscriptionNumber` field when you make the "Create order" call.
* To relate an order line item to an existing subscription, specify this field to the subscription number of the existing subscription.
type: string
requiresFulfillment:
description: |
The flag to show whether fulfillment is needed or not. It's derived from billing rule of the Order Line Item.
type: boolean
revenueRecognitionRule:
description: |
The Revenue Recognition rule for the Order Line Item.
type: string
revenueRecognitionTiming:
description: |
Specifies the type of revenue recognition timing.
Predefined options are listed as enum values in this API Reference. Other options might also be avaliable depending on the revenue recognition policy configuration in the Zuora Billing UI.
**Note**: This field is only available if you have the Order to Revenue feature enabled.
maxLength: 200
type: string
enum:
- Upon Billing Document Posting Date
- Upon Order Activation Date
revenueAmortizationMethod:
description: |
Specifies the type of revenue amortization method.
Predefined options are listed as enum values in this API Reference. Other options might also be avaliable depending on the revenue recognition policy configuration in the Zuora Billing UI.
**Note**: This field is only available if you have the Order to Revenue feature enabled.
maxLength: 200
type: string
enum:
- Immediate
- Ratable Using Start And End Dates
sequenceSetId:
description: |
The ID of the sequence set associated with the OrderLineItem.
type: string
nullable: true
shipTo:
description: |
The ID of a contact that belongs to the owner acount or billing account of the order line item. Use this field to assign an existing account as the ship-to contact of an order line item. The billing account is the order account.
type: string
shipToSnapshotId:
description: |
The snapshot of the ID for an account used as the ship-to contact of an order line item. This field is used to store the original information about the account, in case the information about the account is changed after the creation of the order line item. The `shipToSnapshotId` field is exposed while retrieving the order line item details.
type: string
soldTo:
description: |
The ID of a contact that belongs to the owner acount or billing account of the order line item. Use this field to assign an existing account as the sold-to contact of an order line item. The billing account is the order account.
type: string
soldToSnapshotId:
description: |
The snapshot of the ID for an account used as the sold-to contact of an order line item. This field is used to store the original information about the account, in case the information about the account is changed after the creation of the order line item. The `soldToSnapshotId` field is exposed while retrieving the order line item details.
type: string
taxCode:
description: |
The tax code for the Order Line Item.
type: string
taxMode:
description: |
The tax mode for the Order Line Item.
enum:
- TaxInclusive
- TaxExclusive
type: string
transactionEndDate:
description: |
The date a transaction is completed. The default value of this field is the transaction start date. Also, the value of this field should always equal or be later than the value of the `transactionStartDate` field.
format: date
type: string
transactionStartDate:
description: |
The date a transaction starts. The default value of this field is the order date.
format: date
type: string
unbilledReceivablesAccountingCode:
description: |
The accounting code on the Order Line Item object for customers using [Zuora Billing - Revenue Integration](https://knowledgecenter.zuora.com/Zuora_Revenue/Zuora_Billing_-_Revenue_Integration).
type: string
title: OrderLineItem
type: object
CommitmentBaseAttributesListOrders:
type: object
title: CommitmentBaseAttributesListOrders
properties:
commitmentNumber:
description: |
The commitment number.
type: string
maxLength: 100
id:
description: ID of the Commitment.
type: string
name:
description: |
The name of the commitment.
type: string
maxLength: 255
type:
$ref: '#/components/schemas/CommitmentTypeEnum'
description:
description: |
The description of the commitment.
type: string
maxLength: 500
priority:
description: |
It defines the evaluation order of the commitment. The lower the number, the higher the priority.
When two commitments have the same priority, the commitment that was created initially will be evaluated first.
type: integer
customFields:
type: object
additionalProperties: true
description: Container for custom fields of a Commitment object.
title: CommitmentCustomFields
specificPeriodAlignmentDate:
type: string
description: The specific date for the period alignment. This field is required only if the `periodAlignmentOption` is set to `SpecificDate`.
format: date
example: '2020-01-15'
periodAlignmentOption:
$ref: '#/components/schemas/PeriodAlignmentOptionEnum'
schedules:
description: |
A list of Commitment schedule objects.
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the schedule.
startDate:
type: string
description: The start date of the schedule.
endDate:
type: string
description: The end date of the schedule.
totalAmount:
type: number
format: double
description: The total amount of the schedule.
amountBase:
$ref: '#/components/schemas/AmountBaseEnum'
periodType:
$ref: '#/components/schemas/PeriodTypeEnum'
specificPeriodLength:
type: integer
description: The specific period length of each period in the schedule.
CommonRevenueAttributes:
type: object
properties:
accountReceivableAccountingCode:
description: |
The accounting code on the Commitment object for customers.
type: string
maxLength: 100
adjustmentLiabilityAccountingCode:
description: |
The accounting code on the commitment for customers.
**Note:** This field is only available if you have the Order to Revenue feature enabled.
type: string
maxLength: 100
adjustmentRevenueAccountingCode:
description: |
The accounting code on the commitment for customers.
**Note:** This field is only available if you have the Order to Revenue feature enabled.
type: string
maxLength: 100
contractAssetAccountingCode:
description: |
The accounting code on the commitment for customers.
**Notes:** This field is only available if you have the Order to Revenue feature enabled.
type: string
maxLength: 100
contractLiabilityAccountingCode:
description: |
The accounting code on the commitment for customers.
**Notes:** This field is only available if you have the Order to Revenue feature enabled.
type: string
maxLength: 100
contractRecognizedRevenueAccountingCode:
description: |
The accounting code on the commitment for customers.
**Notes:** This field is only available if you have the Order to Revenue feature enabled.
maxLength: 100
deferredRevenueAccountingCode:
description: |
The deferred revenue accounting code for the commitment.
type: string
maxLength: 100
excludeItemBillingFromRevenueAccounting:
description: |
The flag to exclude commitment related invoice items, invoice item adjustments, credit memo items, and debit memo items from revenue accounting.
**Note:** This field is only available if you have the Order to Revenue feature enabled.
type: boolean
isAllocationEligible:
description: |
This field is used to identify if the commitment is allocation eligible in revenue recognition.
**Note:** This field is only available if you have the Order to Revenue feature enabled.
type: boolean
isUnbilled:
description: |
This field is used to dictate how to perform the accounting during revenue recognition.
**Note:** This field is only available if you have the Order to Revenue feature enabled.
type: boolean
recognizedRevenueAccountingCode:
description: |
The recognized revenue accounting code for the commitment.
type: string
maxLength: 100
revenueAmortizationMethod:
description: |
This field is used to dictate the type of revenue amortization method.
type: string
maxLength: 200
revenueRecognitionRule:
description: |
The revenue recognition rule for the commitment.
type: string
maxLength: 255
revenueRecognitionTiming:
description: |
This field is used to dictate the type of revenue recognition timing.
type: string
maxLength: 200
unbilledReceivablesAccountingCode:
description: |
The accounting code on the commitment for customers.
**Note:** This field is only available if you have the Order to Revenue feature enabled.
type: string
maxLength: 100
CommonTaxationAttributes:
type: object
properties:
taxable:
type: boolean
description: |
The flag to indicate whether the charge is taxable. If this field is set to `true`, both the fields `taxCode` and `taxMode` are required.
taxCode:
type: string
description: |
The tax code of a charge.
**Note:** This field is available when the `taxable` field is set to `true`.
maxLength: 100
taxMode:
type: string
description: |
The tax mode of a charge. This field is available when the `taxable` field is set to `true`.
enum:
- TaxInclusive
- TaxExclusive
EligibleAccountCondition:
type: object
description: The conditions for account level filters for the commitment.
properties:
field:
type: string
description: |
The field name of a single condition.
operator:
type: string
description: |
The operator of a single condition.
Example:
- eq: equal, field = value
- neq: not equal, field != value
- gt: greater than, field > value
- lt: less than, field < value
- gte: greater than or equal, field >= value
- lte: less than or equal, field <= value - lk: like, field like value
- in: in, field in value, multiple values are separated by commas
- nl: null, field is null
- nnl: not null, field is not null
enum:
- eq
- neq
- gt
- lt
- gte
- lte
- lk
- in
- nl
- nnl
value:
type: string
description: |
The value of a single condition, which can be a list of values separated by commas.
**Notes:** Account Condition only contains account related fields. Support is provided only for the indexed custom fields.
conditions:
type: array
description: |
The conditions will be combined by the relation.
items:
$ref: '#/components/schemas/EligibleAccountCondition'
relation:
type: string
description: |
The relation among the conditions.
enum:
- and
- or
EligibleChargeCondition:
type: object
description: The conditions for charge level filters for the commitment.
properties:
field:
type: string
description: |
The field name of a single condition.
operator:
type: string
description: |
The operator of a single condition.
Example:
- eq: equal, field = value
- neq: not equal, field != value
- gt: greater than, field > value
- lt: less than, field < value
- gte: greater than or equal, field >= value
- lte: less than or equal, field <= value
- lk: like, field like value
- in: in, field in value, multiple values are separated by commas
- nl: null, field is null
- nnl: not null, field is not null
enum:
- eq
- neq
- gt
- lt
- gte
- lte
- lk
- in
- nl
- nnl
value:
type: string
description: |
The value of a single condition, which can be a list of values separated by commas.
**Notes:**
- PPDD (PrePaid DrawDown) charge will not be loaded during evaluation.
- Charge condition only contains charge related fields. Support is provided only for the indexed custom fields.
- Charge types supports only the OneTime, Recurring and Usage values.
- Charge models supports only the FlatFee, PerUnit, Overage, Volume Tiered, TieredWithOverage, and Calculated values.
conditions:
type: array
description: |
The conditions will be combined by the relation.
items:
$ref: '#/components/schemas/EligibleChargeCondition'
relation:
type: string
description: |
The relation among the conditions.
enum:
- and
- or
PeriodAlignmentOptionEnum:
type: string
default: CommitmentStartDate
enum:
- CommitmentStartDate
- SpecificDate
description: |
Options for aligning the commitment periods within a commitment.
AmountBaseEnum:
title: AmountBaseEnum
type: string
description: The level for which the committed amount applies to.
default: CommitmentPeriod
enum:
- CommitmentPeriod
PeriodTypeEnum:
title: PeriodTypeEnum
type: string
default: Month
enum:
- Month
- Quarter
- SemiAnnual
- Year
- SpecificMonths
- SinglePeriod
description: |
The frequency type of the period of the commitment schedule.
POSTOrderRequestType:
example:
existingAccountNumber: A00000097
orderDate: '2024-07-01'
subscriptions:
- orderActions:
- type: CreateSubscription
createSubscription:
terms:
initialTerm:
period: 12
periodType: Month
termType: TERMED
renewalSetting: RENEW_WITH_SPECIFIC_TERM
renewalTerms:
- period: 12
periodType: Month
subscribeToRatePlans:
- productRatePlanId: 8ad081dd9096ef9501909b40bb4e74a4
properties:
category:
default: NewSales
description: |
Category of the order to indicate a product sale or return. Default value is `NewSales`.
enum:
- NewSales
- Return
type: string
commitments:
description: |
It contains a list of commitments to create or update.
Use the `action` nested field to indicate whether to create or update the commitment.
items:
$ref: '#/components/schemas/UpsertCommitmentInput'
customFields:
$ref: '#/components/schemas/OrderObjectCustomFields'
description:
description: A description of the order.
maxLength: 500
type: string
existingAccountId:
description: |
The account ID under which this order will be created. This field sets the default invoice owner account and subscription owner account for any new subscriptions in the order. To override these defaults for individual subscriptions, use the `subscriptionOwnerAccountNumber` and `invoiceOwnerAccountNumber` nested fields in the `subscriptions` field. If you want to relax the restriction that the `existingAccountNumber` must be the invoice owner of the subscriptions in this order, submit a request to Zuora Global Support.
**Note:** You can specify either the `existingAccountNumber` or `existingAccountId` field, but not both.
type: string
existingAccountNumber:
description: |
The account number under which this order will be created. This field sets the default invoice owner account and subscription owner account for any new subscriptions in the order. To override these defaults for individual subscriptions, use the `subscriptionOwnerAccountNumber` and `invoiceOwnerAccountNumber` nested fields in the `subscriptions` field. If you want to relax the restriction that the `existingAccountNumber` must be the invoice owner of the subscriptions in this order, submit a request to Zuora Global Support.
maxLength: 70
type: string
newAccount:
$ref: '#/components/schemas/CreateOrderNewAccount'
orderDate:
description: The date when the order is signed. All the order actions under this order will use this order date as the contract effective date if the contract effective date field is skipped or its value is left as null.
format: date
type: string
orderLineItems:
description: |
[Order Line Items](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Order_Line_Items/AA_Overview_of_Order_Line_Items) are non subscription based items created by an Order, representing transactional charges such as one-time fees, physical goods, or professional service charges that are not sold as subscription services.
With the Order Line Items feature enabled, you can now launch non-subscription and unified monetization business models in Zuora, in addition to subscription business models.
If you do not have the **Create Order Line Items Without Product Catalog** billing permission, you can only create order line items from existing products by specifying the product rate plan charge ID in the `productRatePlanChargeId` field. For more information about billing permissions, see Billing Roles.
**Note:** The [Order Line Items](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Order_Line_Items/AA_Overview_of_Order_Line_Items) feature is now generally available to all Zuora customers. You need to enable the [Orders](https://knowledgecenter.zuora.com/BC_Subscription_Management/Orders/AA_Overview_of_Orders#Orders) feature to access the [Order Line Items](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Order_Line_Items/AA_Overview_of_Order_Line_Items) feature. As of Zuora Billing Release 313 (November 2021), new customers who onboard on [Orders](https://docs.zuora.com/en/zuora-billing/manage-accounts-subscriptions-and-non-subscriptions/manage-subscription-transactions/orders/orders-introduction/overview-of-orders) will have the [Order Line Items](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Order_Line_Items) feature enabled by default.
items:
$ref: '#/components/schemas/CreateOrderOrderLineItem'
type: array
orderNumber:
description: |
The order number of the new order. If not provided, system will auto-generate a number for this order.
**Note:** The characters `#`, `?`, and `/` are not allowed in this field. Additionally, to ensure compatibility with the UI when viewing orders, use only the following special characters: `_`,`-`, `.`, `~`, `*`, `(`, `)`, and `'`.
maxLength: 100
type: string
processingOptions:
$ref: '#/components/schemas/processingOptionsOrdersWithDelayedCapturePayment'
reasonCode:
description: |
Values of reason code configured in **Billing Settings** > **Configure Reason Codes** through Zuora UI. Indicates the reason when a return order line item occurs.
maxLength: 255
type: string
schedulingOptions:
description: |
Information of scheduled order.
properties:
scheduledDate:
description: |
The date for the order scheduled.
format: date
type: string
scheduledDatePolicy:
description: Date policy of the scheduled order.
enum:
- SpecificDate
type: string
type: object
status:
description: |
The status of the order. The default value is `Completed`. The following values are supported:
- `Draft`: The order is in draft status.
- `Pending`: The order is in pending status.
- `Completed`: The order is in completed status.
- `Scheduled`: The order is in scheduled status and it is only valid if the Scheduled Orders feature is enabled.
- `Executing`: The scheduled order is executed by a scheduler and it is only valid if the Scheduled Orders feature is enabled.
- `Failed`: The scheduled order has failed.
**Note:** If you have the Pending Subscription Processing feature turned on and want to create a completed order with an active subscription with pending charges, you must specify `Completed` in this field because the default order status is `Pending` for this scenario.
enum:
- Draft
- Pending
- Completed
- Scheduled
- Executing
- Failed
type: string
subscriptions:
description: 'Each item includes a set of order actions, which will be applied to the same base subscription. When you create an order that involves multiple subscriptions, these subscriptions can have different invoice owner accounts or subscription owner accounts. '
items:
properties:
customFields:
$ref: '#/components/schemas/SubscriptionObjectCustomFields'
notes:
description: |
Notes about the subscription. These notes are only visible to Zuora users. Notes set in this field will override the value of the `notes` field within the createSubscription order action.
type: string
maxLength: 1000
orderActions:
description: The actions to be applied to the subscription. Order actions will be stored with the sequence when it was provided in the request.
items:
$ref: '#/components/schemas/CreateOrderOrderAction'
type: array
quote:
$ref: '#/components/schemas/QuoteObjectFields'
ramp:
$ref: '#/components/schemas/RampRequest'
subscriptionNumber:
description: |
Leave this empty to represent new subscription creation. Specify a subscription number to update an existing subscription.
type: string
type: object
type: array
required:
- orderDate
type: object
UpsertCommitmentInput:
title: UpsertCommitmentInput
description: Using the action to indicate whether to create or update the commitment.
type: object
required:
- action
properties:
action:
$ref: '#/components/schemas/ActionType'
oneOf:
- $ref: '#/components/schemas/UpsertCreateCommitmentInput'
- $ref: '#/components/schemas/UpsertUpdateCommitmentInput'
discriminator:
propertyName: action
mapping:
create: '#/components/schemas/UpsertCreateCommitmentInput'
update: '#/components/schemas/UpsertUpdateCommitmentInput'
CreateOrderNewAccount:
allOf:
- description: |
The information of the new account to be created with the order. To create the new account, either a **creditCard** structure or the **hpmCreditCardPaymentMethodId** field (but not both) should be provided. The one provided becomes the default payment method for this account. If the credit card information is declined or can't be verified, then the account is not created.
properties:
accountNumber:
maxLength: 70
type: string
additionalEmailAddresses:
description: |
List of additional email addresses to receive emailed invoices. Values should be a comma-separated list of email addresses.
maxLength: 1200
type: string
allowInvoiceEdit:
description: |
Indicates if associated invoices can be edited.
Values are:
* `true`
* `false` (default)
type: boolean
autoPay:
description: Specifies whether future payments are to be automatically billed when they are due. Possible values are `true`, `false`.
type: boolean
batch:
description: |
**Note**: By default, you have 50 configurable account batches. To increase the limit to 200 batches, you must have the Performance Booster Elite package.
type: string
billCycleDay:
description: Day of the month that the account prefers billing periods to begin on. If set to 0, the bill cycle day will be set as "AutoSet".
maximum: 31
minimum: 0
type: integer
billToContact:
$ref: '#/components/schemas/BillToContactPostOrder'
communicationProfileId:
type: string
creditCard:
$ref: '#/components/schemas/creditCard'
creditMemoTemplateId:
description: |
**Note:** This field is only available if you have [Invoice Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement) 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.
The unique ID of the credit memo template, configured in **Billing Settings** > **Manage Billing Document Configuration** through the Zuora UI. For example, 2c92c08a6246fdf101626b1b3fe0144b.
type: string
crmId:
maxLength: 100
type: string
currency:
description: |
3 uppercase character currency code.
For payment method authorization, if the `paymentMethod` > `currencyCode` field is specified, `currencyCode` is used. Otherwise, this `currency` field is used for payment method authorization. If no currency is specified for the account, the default currency of the account is then used.
type: string
customFields:
$ref: '#/components/schemas/AccountObjectCustomFields'
customerServiceRepName:
description: |
Name of the account's customer service representative, if applicable.
maxLength: 50
type: string
debitMemoTemplateId:
description: |
**Note:** This field is only available if you have [Invoice Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement) 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.
The unique ID of the debit memo template, configured in **Billing Settings** > **Manage Billing Document Configuration** through the Zuora UI. For example, 2c92c08d62470a8501626b19d24f19e2.
type: string
hpmCreditCardPaymentMethodId:
description: |
The ID of the payment method associated with this account. The payment method specified for this field will be set as the default payment method of the account.
If the `autoPay` field is set to `true`, you must provide the credit card payment method ID for either this field or the `creditCard` field,
but not both.
For the Credit Card Reference Transaction payment method, you can specify the payment method ID in this field or use the `paymentMethod` field to create a CC Reference Transaction payment method for an account.
type: string
invoiceDeliveryPrefsEmail:
description: |
Specifies whether to turn on the invoice delivery method 'Email' for the new account.
Values are:
* `true` (default). Turn on the invoice delivery method 'Email' for the new account.
* `false`. Turn off the invoice delivery method 'Email' for the new account.
type: boolean
invoiceDeliveryPrefsPrint:
description: |
Specifies whether to turn on the invoice delivery method 'Print' for the new account.
Values are:
* `true`. Turn on the invoice delivery method 'Print' for the new account.
* `false` (default). Turn off the invoice delivery method 'Print' for the new account.
type: boolean
invoiceTemplateId:
type: string
name:
maxLength: 255
type: string
notes:
maxLength: 65535
type: string
organizationLabel:
description: |
Name of the organization that the account belongs to.
This field is only required when you have already turned on Multi-Org feature.
type: string
parentId:
description: Identifier of the parent customer account for this Account object. Use this field if you have Customer Hierarchy enabled.
type: string
partnerAccount:
default: false
description: |
Whether the customer account is a partner, distributor, or reseller.
You can set this field to `true` if you have business with distributors or resellers, or operating in B2B model to manage numerous subscriptions through concurrent API requests. After this field is set to `true`, the calculation of account metrics is performed asynchronously during operations such as subscription creation, order changes, invoice generation, and payments.
**Note**: This field is available only if you have the Reseller Account feature enabled.
type: boolean
paymentGateway:
maxLength: 40
type: string
paymentMethod:
$ref: '#/components/schemas/POSTPaymentMethodRequest'
paymentTerm:
description: |
**Note**: If you want to specify a payment term when creating a new account, you must set a value in this field. If you do not set a value in this field, Zuora will use the default value set in **Billing Settings** > **Payment Terms** from Zuora UI.
type: string
purchaseOrderNumber:
description: |
The number of the purchase order associated with this account. Purchase order information generally comes from customers.
maxLength: 100
type: string
salesRep:
description: |
The name of the sales representative associated with this account, if applicable.
maxLength: 50
type: string
sequenceSetId:
description: |
The ID of the sequence set to assign to the customer account.
The billing documents to generate for this account will adopt the prefix and starting document number configured in the sequence set.
type: string
nullable: true
shipToContact:
$ref: '#/components/schemas/ShipToContactPostOrder'
shipToSameAsBillTo:
description: |
Whether the ship-to contact and bill-to contact are the same entity.
The created account has the same bill-to contact and ship-to contact entity only when all the following conditions are met in the request body:
- This field is set to `true`.
- A bill-to contact is specified.
- No ship-to contact is specified.
type: boolean
soldToContact:
$ref: '#/components/schemas/SoldToContactPostOrder'
soldToSameAsBillTo:
description: |
Whether the sold-to contact and bill-to contact are the same entity.
The created account has the same bill-to contact and sold-to contact entity only when all the following conditions are met in the request body:
- This field is set to `true`.
- A bill-to contact is specified.
- No sold-to contact is specified.
type: boolean
taxInfo:
$ref: '#/components/schemas/TaxInfo'
required:
- name
- currency
- billCycleDay
- billToContact
type: object
- $ref: '#/components/schemas/DataAccessControlField'
processingOptionsOrdersWithDelayedCapturePayment:
description: |
The container for billing processing options and payment processing options.
**Note:**
- This field is not supported in draft orders.
- When you use the "Create an order" operation to create an account, create a subscription, run billing, and collect payment in a single call, if any error occurs during the call, such as a payment processing failure and a tax engine failure, then all the other steps will be rolled back. In this case, neither the invoice will be generated, nor the subscription nor the account will be created.
- When you use the "Create an order" operation to cancel a subscription with `refund` and `writeOff`, if the `refund` or `writeOff` fails, `cancelSubscription`, `runBilling`, and `collectPayment` still can succeed.
- When you use the "Create an order" operation, the `collectPayment` and `refund` fields cannot be set to `true` simultaneously. Otherwise, the order will not be proceeded.
properties:
applicationOrder:
description: |
The priority order to apply credit memos and/or unapplied payments to an invoice. Possible item values are: `CreditMemo`, `UnappliedPayment`.
**Note:**
- This field is valid only if the `applyCredit` field is set to `true`.
- If no value is specified for this field, the default priority order is used, ["CreditMemo", "UnappliedPayment"], to apply credit memos first and then apply unapplied payments.
- If only one item is specified, only the items of the spedified type are applied to invoices. For example, if the value is `["CreditMemo"]`, only credit memos are used to apply to invoices.
items:
type: string
type: array
applyCredit:
description: |
Whether to automatically apply credit memos or unapplied payments, or both to an invoice.
If the value is true, the credit memo or unapplied payment on the order account will be automatically applied to the invoices generated by this order. The credit memo generated by this order will not be automatically applied to any invoices.
**Note:** This field is only available if you have [Invoice Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement) 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: boolean
applyCreditBalance:
description: |
Indicates if any credit balance on a customer's account is automatically applied to invoices. If no value is specified then this field defaults to false. This feature is not available if you have enabled the Invoice Settlement feature.
type: boolean
billingOptions:
properties:
creditMemoReasonCode:
description: A code identifying the reason for the credit memo transaction that is generated by the request. The value must be an existing reason code. If you do not pass the field or pass the field with empty value, Zuora uses the default reason code.
type: string
documentDate:
description: |
The invoice date displayed on the invoice.
format: date
type: string
generateDraftInvoice:
description: |
Indicates if the current request needs to generate a draft invoice.
Values are:
* `true`
* `false` (default)
type: boolean
targetDate:
description: |
Date through which to calculate charges if an invoice is generated. See [What is a Target Date?](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/G_Bill_Runs/Creating_Bill_Runs#What_is_a_Target_Date.3F).
**Note**: If you do not specify this field, today's date is used by default.
format: date
type: string
chargeTypeToExclude:
description: |
The types of the charges to be excluded from the generation of billing documents.
items:
type: string
enum:
- OneTime
- Recurring
- Usage
type: array
type: object
collectPayment:
description: |
Indicates if the current request needs to collect payments. This value can not be 'true' when 'runBilling' flag is 'false'.
type: boolean
electronicPaymentOptions:
description: |
Container for the electronic payment options.
properties:
authTransactionId:
description: |
The authorization transaction ID from the payment gateway.
When you create a payment to capture the funds that have been authorized through [Create authorization](https://developer.zuora.com/api-references/api/operation/POST_CreateAuthorization/), pass in the `authTransactionId` field. It is highly recommended to also pass in `gatewayOrderId` that you used when authorizing the funds. `authTransactionId` is required, while `gatewayOrderId` is optional.
maxLength: 50
type: string
gatewayOrderId:
description: |
A merchant-specified natural key value that can be passed to the electronic payment gateway when a payment is created. If not specified, the payment number will be passed in instead.
Gateways check duplicates on the gateway order ID to ensure that the same transaction is not entered twice accidentally.
This ID can also be used to do reconciliation and tie the payment to a natural key in external systems. The source of this ID varies by merchant. Some merchants use shopping cart order IDs, and others use something different. Merchants use this ID to track transactions in their eCommerce systems.
When you create a payment to capture the funds that have been authorized through [Create authorization](https://developer.zuora.com/api-references/api/operation/POST_CreateAuthorization/), pass in the `authTransactionId` field. It is highly recommended to also pass in `gatewayOrderId` that you used when authorizing the funds. `authTransactionId` is required, while `gatewayOrderId` is optional.
maxLength: 50
type: string
paymentGatewayId:
description: |
Specifies the ID of a payment gateway to override the default gateway.
If Payment Gateway Routing is enabled:
- If this field is not specified, gateway routing rules will be invoked.
- If this field is specified, the specified gateway will be used to process the payment.
If Payment Gateway Routing is disabled:
- If this field is not specified, the default payment gateway will be used to process the payment. The default gateway of the customer account takes precedence over the default gateway of the tenant.
- If this field is specified, the specified gateway will be used to process the payment.
type: string
paymentMethodId:
description: |
Specifies an electronic payment method. It can be one that has already been associated with an invoice owner, or an orphan payment method, which is not associated with any invoice owner. For an orphan payment method, this operation will then associate it with the account that this order will be created under.
type: string
gatewayOptions:
description: |
The field used to pass gateway-specific parameters and parameter values.
The fields supported by gateways vary. For more information, see the
overview topic of each gateway integration in Zuora Knowledge Center.
Zuora sends all the information that you specified to the gateway. If you
specify any unsupported gateway option parameters, they will be ignored
without error prompts.
type: object
title: gatewayOptions
additionalProperties:
type: string
description: |
The gateway options specification consists of key-value pairs:
- Field name: The name of a gateway-specific parameter.
- Field value: The value of the gateway-specific parameter.
mitTransactionSource:
description: |
Payment transaction source used by the Chase payment gateway to differentiate the transaction source in Stored Credential Transaction framework.
- `C_Unscheduled`: Cardholder-initiated transaction (CIT) that does not occur on scheduled or regularly occurring dates.
- `M_Recurring`: Merchant-initiated transaction (MIT) that occurs at regular intervals.
- `M_Unscheduled`: Merchant-initiated transaction (MIT) that does not occur on scheduled or regularly occurring dates.
enum:
- C_Unscheduled
- M_Recurring
- M_Unscheduled
type: string
type: object
refund:
description: |
Indicates whether to refund after subscription cancelation. Default is `false`.
**Note**: When refunding a subscription that is not invoiced separately, if you do not enable the Invoice Item Settlement feature, you will encounter the following error during the cancel and refund process: “Cancellation/Refund failed because of the following reason: Invoice is linked to multiple subscriptions. Cancellation was not processed.”
type: boolean
refundAmount:
description: |
Indicates the amount to be refunded. Required if the `refund` field is `true`.
type: number
refundReasonCode:
description: |
A code identifying the reason for the refund transaction. The value must be an existing payment refund reason code listed in **Payments Settings** > **Configure Reason Codes**. If you do not specify the field or leave the field with an empty value, Zuora uses the default payment refund reason code.
type: string
runBilling:
description: |
Indicates if the current request needs to generate an invoice. The invoice will be generated against all subscriptions included in this order.
type: boolean
writeOff:
description: |
Indicates whether to write off the outstanding balance on the invoice after refund. Default is `false`.
**Note**:
- When refunding a subscription that is not invoiced separately, if you do not enable the Invoice Item Settlement feature, you will encounter the following error during the cancel and refund process: “Cancellation/Refund failed because of the following reason: Invoice is linked to multiple subscriptions. Cancellation was not processed.”
- The Invoice Settlement feature must have been enabled for write-off.
- When this field is set to `true`, the generated credit memos have a reason code of `Write-off` and it cannot be overridden.
type: boolean
writeOffBehavior:
description: |
The financial information of the credit memo items generated to write off the invoice balance.
**Note:**
- All the credit memo items that are used to write off the invoice will be applied with the same financial information.
- Credit memo items generated from the unconsumed services of the canceled subscription will not be applied with the finance information specified here.
properties:
financeInformation:
description: |
Container for the finance information related to the credit memo items that are created for invoice write-off.
properties:
deferredRevenueAccountingCode:
description: |
The accounting code for the deferred revenue, such as Monthly Recurring Liability.
maxLength: 100
minLength: 0
type: string
onAccountAccountingCode:
description: |
The accounting code that maps to an on account in your accounting system.
maxLength: 100
minLength: 0
type: string
recognizedRevenueAccountingCode:
description: |
The accounting code for the recognized revenue, such as Monthly Recurring Charges or Overage Charges.
maxLength: 100
minLength: 0
type: string
revenueRecognitionRuleName:
description: |
The name of the revenue recognition rule governing the revenue schedule.
maxLength: 100
minLength: 0
type: string
type: object
type: object
type: object
CreateOrderOrderAction:
properties:
addProduct:
$ref: '#/components/schemas/CreateOrderRatePlanOverride'
cancelSubscription:
$ref: '#/components/schemas/CancelSubscription'
changePlan:
$ref: '#/components/schemas/CreateChangePlan'
changeReason:
description: |
The change reason set for an order action when an order is created.
maxLength: 255
type: string
createSubscription:
$ref: '#/components/schemas/CreateOrderCreateSubscription'
customFields:
$ref: '#/components/schemas/OrderActionObjectCustomFields'
ownerTransfer:
$ref: '#/components/schemas/OwnerTransfer'
removeProduct:
$ref: '#/components/schemas/RemoveProduct'
renewSubscription:
$ref: '#/components/schemas/RenewSubscription'
resume:
$ref: '#/components/schemas/CreateOrderResume'
suspend:
$ref: '#/components/schemas/CreateOrderSuspend'
termsAndConditions:
$ref: '#/components/schemas/CreateOrderTermsAndConditions'
triggerDates:
description: |
Container for the contract effective, service activation, and customer acceptance dates of the order action.
If [Zuora is configured to require service activation](https://knowledgecenter.zuora.com/CB_Billing/Billing_Settings/Define_Default_Subscription_Settings#Require_Service_Activation_of_Orders.3F) and the `ServiceActivation` field is not set for a `CreateSubscription` order action, a `Pending` order and a `Pending Activation` subscription are created.
If [Zuora is configured to require customer acceptance](https://knowledgecenter.zuora.com/CB_Billing/Billing_Settings/Define_Default_Subscription_Settings#Require_Customer_Acceptance_of_Orders.3F) and the `CustomerAcceptance` field is not set for a `CreateSubscription` order action, a `Pending` order and a `Pending Acceptance` subscription are created. At the same time, if the service activation date field is also required and not set, a `Pending` order and a `Pending Activation` subscription are created instead.
If [Zuora is configured to require service activation](https://knowledgecenter.zuora.com/CB_Billing/Billing_Settings/Define_Default_Subscription_Settings#Require_Service_Activation_of_Orders.3F) and the `ServiceActivation` field is not set for either of the following order actions, a `Pending` order is created. The subscription status is not impacted. **Note:** This feature is in **Limited Availability**. If you want to have access to the feature, submit a request at [Zuora Global Support](http://support.zuora.com/).
* AddProduct
* UpdateProduct
* RemoveProduct
* RenewSubscription
* TermsAndConditions
If [Zuora is configured to require customer acceptance](https://knowledgecenter.zuora.com/CB_Billing/Billing_Settings/Define_Default_Subscription_Settings#Require_Customer_Acceptance_of_Orders.3F) and the `CustomerAcceptance` field is not set for either of the following order actions, a `Pending` order is created. The subscription status is not impacted. **Note:** This feature is in **Limited Availability**. If you want to have access to the feature, submit a request at [Zuora Global Support](http://support.zuora.com/).
* AddProduct
* UpdateProduct
* RemoveProduct
* RenewSubscription
* TermsAndConditions
items:
$ref: '#/components/schemas/TriggerDate'
type: array
type:
description: |
Type of order action.
Unless the type of order action is `RenewSubscription`, you must use the corresponding field to provide information about the order action. For example, if the type of order action is `AddProduct`, you must set the `addProduct` field.
Zuora returns an error if you set a field that corresponds to a different type of order action. For example, if the type of order action is `AddProduct`, Zuora returns an error if you set the `updateProduct` field.
A [pending order](https://knowledgecenter.zuora.com/BC_Subscription_Management/Orders/Pending_Order_and_Subscription) supports the following order actions:
* CreateSubscription
* AddProduct
* UpdateProduct
* RemoveProduct
* RenewSubscription
* TermsAndConditions
* ChangePlan
However, pending orders created through all order actions except for "Create new subscription":
* Do not impact the subscription status.
* Are in **Limited Availability**. If you want to have access to the feature, submit a request at [Zuora Global Support](https://support.zuora.com).
A pending order is created in either of the following conditions:
* [Zuora is configured to require service activation](https://knowledgecenter.zuora.com/CB_Billing/Billing_Settings/Define_Default_Subscription_Settings#Require_Service_Activation_of_Orders.3F) and the service activation date is not set in your "Create an order" call.
* [Zuora is configured to require customer acceptance](https://knowledgecenter.zuora.com/CB_Billing/Billing_Settings/Define_Default_Subscription_Settings#Require_Customer_Acceptance_of_Orders.3F) and the customer acceptance date is not set in your "Create an order" call.
* When a charge in the subscription has its `triggerEvent` field set as `SpecificDate` and the `specificTriggerDate` field is not set in your "Create an order" API call.
**Note**: The change plan type of order action is supported for the Order to Revenue feature. However, it is currently not supported for the Billing - Revenue Integration feature. When Billing - Revenue Integration is enabled, the change plan type of order action will no longer be applicable in Zuora Billing.
enum:
- CreateSubscription
- TermsAndConditions
- AddProduct
- UpdateProduct
- RemoveProduct
- RenewSubscription
- CancelSubscription
- OwnerTransfer
- Suspend
- Resume
- ChangePlan
type: string
updateProduct:
$ref: '#/components/schemas/CreateOrderRatePlanUpdate'
required:
- type
type: object
CreateOrderRatePlanOverride:
description: |
Information about an order action of type `AddProduct`.
If you want to create a pending order through the "Add product" order action, and if the charge's trigger condition is `Specific Date`, you must set a charge number in the `chargeNumber` field for the "Add product" order action. In this case, if you do not set it, Zuora will not generate the charge number for you.
See more information about pending orders in Pending orders and subscriptions.
properties:
chargeOverrides:
description: |
List of charges associated with the rate plan.
items:
$ref: '#/components/schemas/CreateOrderChargeOverride'
type: array
clearingExistingFeatures:
description: |
Specifies whether all features in the rate plan will be cleared.
type: boolean
customFields:
$ref: '#/components/schemas/OrdersRatePlanObjectCustomFields'
externalCatalogPlanId:
description: |
An external ID of the product rate plan to be added. You can use this field to specify a product rate plan that is imported from an external system. The value of the `externalCatalogPlanId` field must match one of the values that are predefined in the `externallyManagedPlanIds` field on a product rate plan.
**Note:** If both `externalCatalogPlanId` and `productRatePlanId` are provided. They must point to the same product rate plan. Otherwise, the request would fail.
type: string
externallyManagedPlanId:
description: |
Indicates the unique identifier for the rate plan purchased on a third-party store. This field is used to represent a subscription rate plan created through third-party stores.
type: string
isAddingSubsetCharges:
description: |
Specifies whether to add a subset of charges to the subscription.
**Note:** To access this field for adding a subset of charges, submit a request at Zuora Global Support.
type: boolean
isFromExternalCatalog:
description: |
Indicates whether the rate plan is created from the Zuora product catalog or from an external product catalog.
**Note:** This field is available when the Standalone Orders feature is enabled.
type: boolean
productRatePlanId:
description: |
Internal identifier of the product rate plan that the rate plan is based on.
type: string
productRatePlanNumber:
description: |
Number of a product rate plan for this subscription.
type: string
ratePlanName:
description: |
Name of the standalone rate plan.
**Note:** This field is available when the Standalone Orders feature is enabled.
type: string
subscriptionProductFeatures:
description: |
List of features associated with the rate plan.
The system compares the `subscriptionProductFeatures` and `featureId` fields in the request with the counterpart fields in a rate plan. The comparison results are as follows:
* If there is no `subscriptionProductFeatures` field or the field is empty, features in the rate plan remain unchanged. But if the `clearingExistingFeatures` field is additionally set to true, all features in the rate plan are cleared.
* If the `subscriptionProductFeatures` field contains the `featureId` nested fields, as well as the optional `description` and `customFields` nested fields, the features indicated by the featureId nested fields in the request overwrite all features in the rate plan.
items:
$ref: '#/components/schemas/CreateOrderRatePlanFeatureOverride'
type: array
subscriptionRatePlanNumber:
description: |
Number of a subscription rate plan for this subscription.
maxLength: 50
type: string
uniqueToken:
description: |
Unique identifier for the rate plan. This identifier enables you to refer to the rate plan before the rate plan has an internal identifier in Zuora.
For instance, suppose that you want to use a single order to add a product to a subscription and later update the same product. When you add the product, you can set a unique identifier for the rate plan. Then when you update the product, you can use the same unique identifier to specify which rate plan to modify.
maxLength: 50
type: string
title: ratePlan
type: object
CreateChangePlan:
description: |
Information about an order action of type `ChangePlan`.
Use the change plan type of order action to replace the existing rate plans in a subscription with other rate plans.
**Note**: The change plan type of order action is supported for the Order to Revenue feature. However, it is currently not supported for the Billing - Revenue Integration feature. When Billing - Revenue Integration is enabled, the change plan type of order action will no longer be applicable in Zuora Billing.
If you want to create a pending order through the "change plan" order action, and if the charge's trigger condition is `Specific Date`, you must set a charge number in the `chargeNumber` field for the "change plan" order action. In this case, if you do not set it, Zuora will not generate the charge number for you.
See more information about pending orders in Pending orders and subscriptions.
properties:
effectivePolicy:
description: |
The default value for the `effectivePolicy` field is as follows:
* If the rate plan change (from old to new) is an upgrade, the effective policy is `EffectiveImmediately` by default.
* If the rate plan change (from old to new) is a downgrade, the effective policy is `EffectiveEndOfBillingPeriod` by default.
* Otherwise, the effective policy is `SpecificDate` by default.
**Notes**:
* When setting this field to `EffectiveEndOfBillingPeriod`, you cannot set the billing trigger dates for the subscription as the system will automatically set the trigger dates to the end of billing period, and you cannot set the following billing trigger date settings to `Yes`:
* Require Customer Acceptance of Orders?
* Require Service Activation of Orders?
* When setting this field to `SpecificDate`, you must also set the contract effective date in the `triggerDates` field as follows:
* Set the `name` field as `ContractEffective`
* Specify a date for the `triggerDate` field
enum:
- EffectiveImmediately
- EffectiveEndOfBillingPeriod
- SpecificDate
type: string
externalCatalogPlanId:
description: |
An external ID of the rate plan to be removed. You can use this field to specify an existing rate plan in your subscription. The value of the `externalCatalogPlanId` field must match one of the values that are predefined in the `externallyManagedPlanIds` field on a product rate plan. However, if there are multiple rate plans with the same `productRatePlanId` value existing in the subscription, you must use the `ratePlanId` field to remove the rate plan. The `externalCatalogPlanId` field cannot be used to distinguish multiple rate plans in this case.
**Note:** Please provide only one of `externalCatalogPlanId`, `ratePlanId` or `productRatePlanId`. If more than 1 field is provided then the request would fail.
type: string
newProductRatePlan:
$ref: '#/components/schemas/CreateOrderChangePlanRatePlanOverride'
productRatePlanId:
description: |
ID of the product rate plan that the removed rate plan is based on.
type: string
productRatePlanNumber:
description: |
Number of a product rate plan for this subscription.
type: string
ratePlanId:
description: |
ID of the rate plan to remove. This can be the latest version or any history version of ID. Note that the removal of a rate plan through the Change Plan order action supports the function of removal before future-dated removals, as in a Remove Product order action.
type: string
resetBcd:
default: false
description: |
If resetBcd is true then reset the Account BCD to the effective date; if it is false keep the original BCD.
**Note**: If the rate plan change is an upgrade (the `subType` field is `Upgrade`), then the effective policy is `EffectiveImmediately` by default. In this case, if you do not specify the `resetBcd` field, the system sets this field to `true` while BCD is the effective date.
type: boolean
subType:
description: |
Use this field to choose the sub type for your change plan order action.
However, if you do not set this field, the field will be automatically generated by the system according to the following rules:
When the old and new rate plans are within the same Grading catalog group:
* If the grade of new plan is greater than that of the old plan, this is an "Upgrade".
* If the grade of new plan is less than that of the old plan, this is a "Downgrade".
* If the grade of new plan equals that of the old plan, this is a "Crossgrade".
When the old and new rate plans are not in the same Grading catalog group, or either has no group, this is "PlanChanged".
enum:
- Upgrade
- Downgrade
- Crossgrade
- PlanChanged
type: string
subscriptionRatePlanNumber:
description: |
Number of a rate plan for this subscription.
type: string
required:
- newProductRatePlan
title: createChangePlan
type: object
CreateOrderCreateSubscription:
description: |
Information about an order action of type `CreateSubscription`.
properties:
billToContactId:
description: |
The ID of the bill-to contact associated with the subscription.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request or you select **Default Contact from Account** for this field during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
currency:
description: |
The code of currency that is used for this subscription. If the currency is not selected, the default currency from the account will be used.
All subscriptions in the same order must use the same currency. The currency for a subscription cannot be changed.
**Note**:
This field is available only if you have the Multiple Currencies feature enabled.
maxLength: 3
type: string
invoiceGroupNumber:
description: |
The number of the invoice group associated with the subscription.
After enabling the Invoice Grouping feature, you can specify invoice group numbers to bill subscriptions and order line items based on specific criteria. For the same account, Zuora generates separate invoices for subscriptions and order line items, each identified by unique invoice group numbers. For more information, see [Invoice Grouping](https://knowledgecenter.zuora.com/Billing/Subscriptions/Invoice_Grouping).
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
maxLength: 255
nullable: true
invoiceSeparately:
description: |
Specifies whether the subscription appears on a separate invoice when Zuora generates invoices.
type: boolean
invoiceTemplateId:
description: |
The ID of the invoice template associated with the subscription.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request or you select **Default Template from Account** for this field during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
newSubscriptionOwnerAccount:
$ref: '#/components/schemas/CreateOrderCreateSubscriptionNewSubscriptionOwnerAccount'
notes:
description: |
Notes about the subscription. These notes are only visible to Zuora users.
maxLength: 500
type: string
paymentProfile:
description: |
Container for payment gateway and payment method details of a payment. If you do not set this field, the payment method and payment gateway values cannot be set in the subscription.
**Note:**
- If multiple order actions are specified, they will be applied in the same order they appear in the API payload.
- If one or more of these order actions include the `paymentProfile` element, the changes will be applied in sequence, and the result will be consistent with the last `paymentProfile` element.
properties:
paymentGatewayId:
description: |
The ID of the gateway instance that processes the payment.
This field remains unset, if you do not provide value.
type: string
paymentMethodId:
description: |
The ID of the payment method.
This field remains unset, if you do not provide value.
type: string
type: object
paymentTerm:
description: |
The name of the payment term associated with the subscription. For example, `Net 30`. The payment term determines the due dates of invoices.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request or you select **Default Term from Account** for this field during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
sequenceSetId:
description: |
The ID of the sequence set associated with the subscription.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request or you select **Default Set from Account** for this field during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
nullable: true
shipToContactId:
description: |
The ID of the ship-to contact associated with the subscription. It must be a contact of the subscription owner.
**Note:**
To access this field, you must have the ShipToContactSupport permission. If you want to enable this permission, submit a request at Zuora Global Support.
type: string
soldToContactId:
description: |
The ID of the sold-to contact associated with the subscription.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request or you select **Default Contact from Account** for this field during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
subscribeToRatePlans:
description: |
List of rate plans associated with the subscription.
items:
$ref: '#/components/schemas/CreateOrderRatePlanOverride'
type: array
subscriptionNumber:
description: |
Subscription number of the subscription. For example, A-S00000001.
If you do not set this field, Zuora will generate the subscription number.
maxLength: 100
type: string
subscriptionOwnerAccountNumber:
description: |
Account number of an existing account that will own the subscription. For example, A00000001.
If you do not set this field or the `newSubscriptionOwnerAccount` field, the account that owns the order will also own the subscription. Zuora will return an error if you set this field and the `newSubscriptionOwnerAccount` field.
maxLength: 70
type: string
invoiceOwnerAccountNumber:
description: |
Account number of an existing account that will own the invoice. For example, A00000001. If you do not set this field, the account that owns the order will also own this invoice.
maxLength: 70
type: string
terms:
description: |
Container for the terms and renewal settings of the subscription.
properties:
autoRenew:
description: |
Specifies whether the subscription automatically renews at the end of the each term. Only applicable if the type of the first term is `TERMED`.
type: boolean
initialTerm:
description: |
Information about the first term of the subscription.
properties:
period:
description: |
Duration of the first term in months, years, days, or weeks, depending on the value of the `periodType` field. Only applicable if the value of the `termType` field is `TERMED`.
type: integer
periodType:
description: |
Unit of time that the first term is measured in. Only applicable if the value of the `termType` field is `TERMED`.
enum:
- Month
- Year
- Day
- Week
type: string
startDate:
description: |
Start date of the first term, in YYYY-MM-DD format.
format: date
type: string
endDate:
description: |
End date of the first term, in YYYY-MM-DD format.
format: date
type: string
termType:
description: |
Type of the first term. If the value of this field is `TERMED`, the first term has a predefined duration based on the value of the `period` field. If the value of this field is `EVERGREEN`, the first term does not have a predefined duration.
enum:
- TERMED
- EVERGREEN
type: string
required:
- termType
type: object
renewalSetting:
description: |
Specifies the type of the terms that follow the first term if the subscription is renewed. Only applicable if the type of the first term is `TERMED`.
* `RENEW_WITH_SPECIFIC_TERM` - Each renewal term has a predefined duration. The first entry in `renewalTerms` specifies the duration of the second term of the subscription, the second entry in `renewalTerms` specifies the duration of the third term of the subscription, and so on. The last entry in `renewalTerms` specifies the ultimate duration of each renewal term.
* `RENEW_TO_EVERGREEN` - The second term of the subscription does not have a predefined duration.
enum:
- RENEW_WITH_SPECIFIC_TERM
- RENEW_TO_EVERGREEN
type: string
renewalTerms:
description: |
List of renewal terms of the subscription. Only applicable if the type of the first term is `TERMED` and the value of the `renewalSetting` field is `RENEW_WITH_SPECIFIC_TERM`.
items:
$ref: '#/components/schemas/RenewalTerm'
type: array
required:
- initialTerm
type: object
title: createSubscription
type: object
CreateOrderRatePlanUpdate:
description: |
Information about an order action of type `UpdateProduct`.
properties:
chargeUpdates:
description: |
Array of the JSON objects containing the information for a charge update in the `updateProduct` type of order action.
items:
$ref: '#/components/schemas/CreateOrderChargeUpdate'
type: array
clearingExistingFeatures:
description: |
Specifies whether all features in the rate plan will be cleared.
type: boolean
customFields:
$ref: '#/components/schemas/OrdersRatePlanObjectCustomFields'
externalCatalogPlanId:
description: |
An external ID of the rate plan to be updated. You can use this field to specify an existing rate plan in your subscription. The value of the `externalCatalogPlanId` field must match one of the values that are predefined in the `externallyManagedPlanIds` field on a product rate plan. However, if there are multiple rate plans with the same `productRatePlanId` value existing in the subscription, you must use the `ratePlanId` field to update the rate plan. The `externalCatalogPlanId` field cannot be used to distinguish multiple rate plans in this case.
**Note:** If both `externalCatalogPlanId` and `ratePlanId` are provided. They must point to the same product rate plan. Otherwise, the request would fail.
type: string
isAddingSubsetCharges:
description: |
Specifies whether to add a subset of charges to the subscription.
**Note:** To access this field for adding a subset of charges, submit a request at Zuora Global Support.
type: boolean
productRatePlanNumber:
description: |
Number of a product rate plan for this subscription.
type: string
ratePlanId:
description: |
The id of the rate plan to be updated. It can be the latest version or any history version id.
type: string
specificUpdateDate:
description: |
The specific date when the Update Product order action takes effect. This field allows you to update a charge before a future-dated Update Product order action on the subscription. The format of the date is yyyy-mm-dd.
**Note**: After you use this option, the charge's `TriggerEvent` field value will be changed to `SpecificDate`.
See [Update a Product on Subscription with Future-dated Updates](https://knowledgecenter.zuora.com/BC_Subscription_Management/Orders/AC_Orders_Tutorials/C_Update_a_Product_in_a_Subscription/Update_a_Product_on_Subscription_with_Future-dated_Updates) for more information about this feature.
format: date
type: string
subscriptionProductFeatures:
description: |
List of features associated with the rate plan.
The system compares the `subscriptionProductFeatures` and `featureId` fields in the request with the counterpart fields in a rate plan. The comparison results are as follows:
* If there is no `subscriptionProductFeatures` field or the field is empty, features in the rate plan remain unchanged. But if the `clearingExistingFeatures` field is additionally set to true, all features in the rate plan are cleared.
* If the `subscriptionProductFeatures` field contains the `featureId` nested fields, as well as the optional `description` and `customFields` nested fields, the features indicated by the featureId nested fields in the request overwrite all features in the rate plan.
items:
$ref: '#/components/schemas/CreateOrderRatePlanFeatureOverride'
type: array
subscriptionRatePlanNumber:
description: |
Number of a rate plan for this subscription.
type: string
uniqueToken:
description: |
A unique string to represent the rate plan in the order. The unique token is used to perform multiple actions against a newly added rate plan. For example, if you want to add and update a product in the same order, assign a unique token to the newly added rate plan and use that token in future order actions.
type: string
title: updateRateplan
type: object
CreateOrderChargeUpdate:
description: |
The JSON object containing the information for a charge update in the 'UpdateProduct' type order action.
properties:
billing:
$ref: '#/components/schemas/BillingUpdate'
chargeNumber:
description: |
The number of the charge to be updated. The value of this field is inherited from the `subscriptions` > `orderActions` > `addProduct` > `chargeOverrides` > `chargeNumber` field.
type: string
estimatedStartDate:
type: string
format: date
description: |
The estimated start date of the pending charge in an active subscription.
The value of this field must be a date within the subscription term. The system will then automatically calculate the estimated end date for the pending charge. The estimated start and end dates are used to manage the estimated charge duration and forecast the revenue for the pending charge.
**Note:** This field is available only when the Pending Subscription Processing feature is turned on.
negotiatedPriceTable:
description: |
Array of negotiated price table information. The rate card entries provided in the array will override the existing rate card entries in the standard price table to form a negotiated price table that will be
used during pricing evaluation.
**Note:** To enable the Negotiated Price Table feature, submit a request to Zuora Global Support.
items:
$ref: '#/components/schemas/NegotiatedItems'
type: array
pricingAttributes:
description: |
Container for pricing attribute and value that provide additional context for dynamic pricing. The pricing attribute values included in the array will update the existing values. For the pricing attribute mapped to a Zuora object field, Zuora will retrieve the value automatically, you don’t need to pass its value explicitly. If you pass a value that doesn’t match the actual value of the Zuora object, an error will be returned.
Note that for any pricing attribute mapped to the field of Zuora object Usage, because its value is only determined when the usage record arrives, you can’t provide a value via Orders API payload and Zuora will not retrieve its value automatically.
**Note:** To enable Dynamic Pricing, submit a request to Zuora Global Support.
additionalProperties: true
productRatePlanChargeId:
description: |
ID of a product rate plan charge for this subscription. When `isAddingSubsetCharges` is set to true, the product rate charge specified by `productRatePlanChargeId` is added to the existing rate plan specified by `ratePlanId`.
type: string
productRatePlanChargeNumber:
description: |
Number of a product rate plan charge for this subscription. When `isAddingSubsetCharges` is set to true, the product rate charge specified by `productRatePlanChargeNumber` is added to the existing rate plan specified by `ratePlanId`.
type: string
customFields:
$ref: '#/components/schemas/RatePlanChargeObjectCustomFields'
description:
type: string
effectiveDate:
$ref: '#/components/schemas/CreateOrderUpdateProductTriggerParams'
prepaidQuantity:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
The number of units included in a [prepayment charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge). Must be a positive number (>0).
type: number
pricing:
allOf:
- $ref: '#/components/schemas/CreateOrderPricingUpdate'
description: |
Pricing information about the charge.
uniqueToken:
description: |
A unique string to represent the rate plan charge in the order. The unique token is used to perform multiple actions against a newly added rate plan charge. For example, if you want to add and update a product in the same order, assign a unique token to the newly added rate plan charge and use that token in future order actions.
type: string
type: object
CreateOrderUpdateProductTriggerParams:
description: |
Specifies when a charge becomes active.
properties:
specificTriggerDate:
description: |
Date in YYYY-MM-DD format. Only applicable if the value of the `triggerEvent` field is `SpecificDate`.
While this field is applicable, if this field is not set, your `CreateSubscription` order action creates a `Pending` order and a `Pending Acceptance` subscription. If at the same time the service activation date is required and not set, a `Pending Activation` subscription is created.
While this field is applicable, if this field is not set, the following order actions create a `Pending` order but do not impact the subscription status. **Note**: This feature is in **Limited Availability**. If you want to have access to the feature, submit a request at [Zuora Global Support](http://support.zuora.com/).
* AddProduct
* UpdateProduct
* RemoveProduct
* RenewSubscription
* TermsAndConditions
While this field is applicable, for the `updateProduct` order action, if the Pending order feature as above is not enabled, this field must not be set to null.
format: date
type: string
triggerEvent:
description: |
Condition for the charge to become active. If this field is not specified, the value of the field will be defaulted to the trigger event value defined in the product catalog.
If the value of this field is `SpecificDate`, use the `specificTriggerDate` field to specify the date when the charge becomes active.
enum:
- ContractEffective
- ServiceActivation
- CustomerAcceptance
- SpecificDate
type: string
title: startDate
type: object
CreateOrderPricingUpdate:
properties:
chargeModelData:
allOf:
- $ref: '#/components/schemas/ChargeModelDataOverride'
description: |
Container for charge model configuration data.
**Note**: This field is only available if you have the High Water Mark, Pre-Rated Pricing, or Multi-Attribute Pricing charge models enabled. The High Water Mark and Pre-Rated Pricing charge models are available for customers with Enterprise and Nine editions by default. If you are a Growth customer, see [Zuora Editions](https://docs.zuora.com/en/entitlements/current-entitlements/zuora-editions) for pricing information.
discount:
allOf:
- $ref: '#/components/schemas/DiscountPricingUpdate'
description: |
Pricing information about a discount charge.
recurringDeliveryBased:
allOf:
- $ref: '#/components/schemas/RecurringDeliveryPricingUpdate'
description: |
This field is only available if you have the Delivery Pricing charge model enabled.
recurringFlatFee:
allOf:
- $ref: '#/components/schemas/RecurringFlatFeePricingUpdate'
description: |
Pricing information about a recurring charge that uses the "flat fee" charge model. In this charge model, the charge has a fixed price.
recurringPerUnit:
allOf:
- $ref: '#/components/schemas/RecurringPerUnitPricingUpdate'
description: |
Pricing information about a recurring charge that uses the "per unit" charge model. In this charge model, the charge has a fixed price per unit purchased.
recurringTiered:
allOf:
- $ref: '#/components/schemas/RecurringTieredPricingUpdate'
description: |
Pricing information about a recurring charge that uses the "tiered pricing" charge model. In this charge model, the charge has cumulative pricing tiers that become effective as units are purchased.
recurringVolume:
allOf:
- $ref: '#/components/schemas/RecurringVolumePricingUpdate'
description: |
Pricing information about a recurring charge that uses the "volume pricing" charge model. In this charge model, the charge has a variable price per unit, depending on how many units are purchased.
usageFlatFee:
allOf:
- $ref: '#/components/schemas/UsageFlatFeePricingUpdate'
description: |
Pricing information about a usage charge that uses the "flat fee" charge model. In this charge model, the charge has a fixed price.
usageOverage:
allOf:
- $ref: '#/components/schemas/UsageOveragePricingUpdate'
description: |
Pricing information about a usage charge that uses the "overage" charge model. In this charge model, the charge has an allowance of free units and a fixed price per additional unit consumed.
usagePerUnit:
allOf:
- $ref: '#/components/schemas/UsagePerUnitPricingUpdate'
description: |
Pricing information about a usage charge that uses the "per unit" charge model. In this charge model, the charge has a fixed price per unit consumed.
usageTiered:
allOf:
- $ref: '#/components/schemas/UsageTieredPricingUpdate'
description: |
Pricing information about a usage charge that uses the "tiered pricing" charge model. In this charge model, the charge has cumulative pricing tiers that become effective as units are consumed.
usageTieredWithOverage:
allOf:
- $ref: '#/components/schemas/UsageTieredWithOveragePricingUpdate'
description: |
Pricing information about a usage charge that uses the "tiered with overage" charge model. In this charge model, the charge has cumulative pricing tiers that become effective as units are consumed. The charge also has a fixed price per unit consumed beyond the limit of the final tier.
usageVolume:
allOf:
- $ref: '#/components/schemas/UsageVolumePricingUpdate'
description: |
Pricing information about a usage charge that uses the "volume pricing" charge model. In this charge model, the charge has a variable price per unit, depending on how many units are consumed.
type: object
CreateOrderCreateSubscriptionNewSubscriptionOwnerAccount:
allOf:
- description: |
Information about a new account that will own the subscription. Only available if you have enabled the Owner Transfer feature.
**Note:** The Owner Transfer feature is in **Limited Availability**. If you wish to have access to the feature, submit a request at [Zuora Global Support](http://support.zuora.com/).
If you do not set this field or the `subscriptionOwnerAccountNumber` field, the account that owns the order will also own the subscription. Zuora will return an error if you set this field and the `subscriptionOwnerAccountNumber` field.
properties:
accountNumber:
description: |
Account number. For example, A00000001.
maxLength: 70
type: string
additionalEmailAddresses:
description: |
List of additional email addresses to receive emailed invoices. Values should be a comma-separated list of email addresses.
maxLength: 1200
type: string
allowInvoiceEdit:
description: |
Indicates if associated invoices can be edited.
Values are:
* `true`
* `false` (default)
type: boolean
autoPay:
description: |
Specifies whether future payments are automatically billed when they are due.
type: boolean
batch:
description: |
Name of the billing batch that the account belongs to. For example, Batch1.
type: string
billCycleDay:
description: |
Day of the month that the account prefers billing periods to begin on. If set to 0, the bill cycle day will be set as "AutoSet".
maximum: 31
minimum: 0
type: integer
billToContact:
$ref: '#/components/schemas/BillToContactPostOrder'
communicationProfileId:
description: |
Internal identifier of the communication profile that Zuora uses when sending notifications to the account's contacts.
type: string
creditCard:
$ref: '#/components/schemas/creditCard'
creditMemoTemplateId:
description: |
**Note:** This field is only available if you have [Invoice Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement) 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.
The unique ID of the credit memo template, configured in **Billing Settings** > **Manage Billing Document Configuration** through the Zuora UI. For example, 2c92c08a6246fdf101626b1b3fe0144b.
type: string
crmId:
description: |
External identifier of the account in a CRM system.
maxLength: 100
type: string
currency:
description: |
ISO 3-letter currency code (uppercase). For example, USD.
type: string
customFields:
$ref: '#/components/schemas/AccountObjectCustomFields'
customerServiceRepName:
description: |
Name of the account's customer service representative, if applicable.
maxLength: 50
type: string
debitMemoTemplateId:
description: |
**Note:** This field is only available if you have [Invoice Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement) 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.
The unique ID of the debit memo template, configured in **Billing Settings** > **Manage Billing Document Configuration** through the Zuora UI. For example, 2c92c08d62470a8501626b19d24f19e2.
type: string
hpmCreditCardPaymentMethodId:
description: |
The ID of the payment method associated with this account. The payment method specified for this field will be set as the default payment method of the account.
If the `autoPay` field is set to `true`, you must provide the credit card payment method ID for either this field or the `creditCard` field,
but not both.
For the Credit Card Reference Transaction payment method, you can specify the payment method ID in this field or use the `paymentMethod` field to create a CC Reference Transaction payment method for an account.
type: string
invoiceDeliveryPrefsEmail:
description: |
Specifies whether to turn on the invoice delivery method 'Email' for the new account.
Values are:
* `true` (default). Turn on the invoice delivery method 'Email' for the new account.
* `false`. Turn off the invoice delivery method 'Email' for the new account.
type: boolean
invoiceDeliveryPrefsPrint:
description: |
Specifies whether to turn on the invoice delivery method 'Print' for the new account.
Values are:
* `true`. Turn on the invoice delivery method 'Print' for the new account.
* `false` (default). Turn off the invoice delivery method 'Print' for the new account.
type: boolean
invoiceTemplateId:
description: |
Internal identifier of the invoice template that Zuora uses when generating invoices for the account.
type: string
name:
description: |
Account name.
maxLength: 255
type: string
notes:
description: |
Notes about the account. These notes are only visible to Zuora users.
maxLength: 65535
type: string
parentId:
description: Identifier of the parent customer account for this Account object. Use this field if you have Customer Hierarchy enabled.
type: string
paymentGateway:
description: |
The payment gateway that Zuora uses when processing electronic payments and refunds for the account. If you do not specify this field or if the value of this field is null, Zuora uses your default payment gateway.
maxLength: 40
type: string
paymentMethod:
$ref: '#/components/schemas/POSTPaymentMethodRequest'
paymentTerm:
description: |
Name of the payment term associated with the account. For example, "Net 30". The payment term determines the due dates of invoices.
type: string
purchaseOrderNumber:
description: |
The number of the purchase order associated with this account. Purchase order information generally comes from customers.
maxLength: 100
type: string
salesRep:
description: |
The name of the sales representative associated with this account, if applicable.
maxLength: 50
type: string
soldToContact:
$ref: '#/components/schemas/SoldToContactPostOrder'
taxInfo:
$ref: '#/components/schemas/TaxInfo'
required:
- name
- currency
- billCycleDay
- billToContact
type: object
- $ref: '#/components/schemas/DataAccessControlField'
DataAccessControlField:
additionalProperties:
description: |
Field for data access control. The name of the data access control field has the form *customField*__h. The data access control field is case sensitive. See [Data Access Control](https://knowledgecenter.zuora.com/CF_Users_and_Administrators/A_Administrator_Settings/Data_Access_Control) for more information.
type: string
description: |
Container for the data access control field.
title: dataAccessControlField
type: object
CreateOrderChangePlanRatePlanOverride:
description: |
Information about the new product rate plan to add.
properties:
chargeOverrides:
description: |
List of charges associated with the rate plan.
items:
$ref: '#/components/schemas/ChangePlanChargeOverride'
type: array
clearingExistingFeatures:
description: |
Specifies whether all features in the rate plan will be cleared.
type: boolean
customFields:
$ref: '#/components/schemas/OrdersRatePlanObjectCustomFields'
externalCatalogPlanId:
description: |
An external ID of the product rate plan to be added. You can use this field to specify a product rate plan that is imported from an external system. The value of the `externalCatalogPlanId` field must match one of the values that are predefined in the `externallyManagedPlanIds` field on a product rate plan.
**Note:** If both `externalCatalogPlanId` and `productRatePlanId` are provided. They must point to the same product rate plan. Otherwise, the request would fail.
type: string
externallyManagedPlanId:
description: |
Indicates the unique identifier for the rate plan purchased on a third-party store. This field is used to represent a subscription rate plan created through third-party stores.
type: string
subscriptionRatePlanNumber:
description: |
Number of a subscription rate plan for this subscription.
maxLength: 50
type: string
isFromExternalCatalog:
description: |
Indicates whether the rate plan is created from the Zuora product catalog or from an external product catalog.
**Note:** This field is available when the Standalone Orders feature is enabled.
type: boolean
productRatePlanId:
description: |
Internal identifier of the product rate plan that the rate plan is based on.
type: string
productRatePlanNumber:
description: |
Number of a product rate plan for this subscription.
type: string
ratePlanName:
description: |
Name of the standalone rate plan.
**Note:** This field is available when the Standalone Orders feature is enabled.
type: string
subscriptionProductFeatures:
description: |
List of features associated with the rate plan.
The system compares the `subscriptionProductFeatures` and `featureId` fields in the request with the counterpart fields in a rate plan. The comparison results are as follows:
* If there is no `subscriptionProductFeatures` field or the field is empty, features in the rate plan remain unchanged. But if the `clearingExistingFeatures` field is additionally set to true, all features in the rate plan are cleared.
* If the `subscriptionProductFeatures` field contains the `featureId` nested fields, as well as the optional `description` and `customFields` nested fields, the features indicated by the featureId nested fields in the request overwrite all features in the rate plan.
items:
$ref: '#/components/schemas/CreateOrderRatePlanFeatureOverride'
type: array
uniqueToken:
description: |
Unique identifier for the rate plan. This identifier enables you to refer to the rate plan before the rate plan has an internal identifier in Zuora.
For instance, suppose that you want to use a single order to add a product to a subscription and later update the same product. When you add the product, you can set a unique identifier for the rate plan. Then when you update the product, you can use the same unique identifier to specify which rate plan to modify.
maxLength: 50
type: string
title: ratePlan
type: object
CreateOrderChargeOverride:
description: |
Charge associated with a rate plan.
properties:
accountReceivableAccountingCode:
description: |
The accountReceivableAccountingCode of a standalone charge.
**Note:** This field is available when the Standalone Orders, Zuora Finance, and Invoice Settlement features are enabled.
type: string
adjustmentLiabilityAccountingCode:
description: |
The adjustmentLiabilityAccountingCode of a standalone charge.
**Note:** This field is available when the Standalone Orders feature and the Billing - Revenue Integration or Order to Revenue feature are enabled.
type: string
adjustmentRevenueAccountingCode:
description: |
The adjustmentRevenueAccountingCode of a standalone charge.
**Note:** This field is available when the Standalone Orders feature and the Billing - Revenue Integration or Order to Revenue feature are enabled.
type: string
billing:
description: |
Billing information about the charge.
properties:
billCycleDay:
description: |
Day of the month that each billing period begins on. Only applicable if the value of the `billCycleType` field is `SpecificDayofMonth`.
maximum: 31
minimum: 0
type: integer
billCycleType:
description: |
Specifies how Zuora determines the day that each billing period begins on.
* `DefaultFromCustomer` - Each billing period begins on the bill cycle day of the account that owns the subscription.
* `SpecificDayofMonth` - Use the `billCycleDay` field to specify the day of the month that each billing period begins on.
* `SubscriptionStartDay` - Each billing period begins on the same day of the month as the start date of the subscription.
* `ChargeTriggerDay` - Each billing period begins on the same day of the month as the date when the charge becomes active.
* `SpecificDayofWeek` - Use the `weeklyBillCycleDay` field to specify the day of the week that each billing period begins on.
enum:
- DefaultFromCustomer
- SpecificDayofMonth
- SubscriptionStartDay
- ChargeTriggerDay
- SpecificDayofWeek
type: string
billingPeriod:
description: |
Billing frequency of the charge. The value of this field controls the duration of each billing period.
If the value of this field is `Specific_Days`, `Specific_Months` or `Specific_Weeks`, use the `specificBillingPeriod` field to specify the duration of each billing period.
enum:
- Month
- Quarter
- Semi_Annual
- Annual
- Eighteen_Months
- Two_Years
- Three_Years
- Five_Years
- Specific_Months
- Subscription_Term
- Week
- Specific_Weeks
- Specific_Days
type: string
billingPeriodAlignment:
description: |
Specifies how Zuora determines when to start new billing periods. You can use this field to align the billing periods of different charges.
* `AlignToCharge` - Zuora starts a new billing period on the first billing day that falls on or after the date when the charge becomes active.
* `AlignToSubscriptionStart` - Zuora starts a new billing period on the first billing day that falls on or after the start date of the subscription.
* `AlignToTermStart` - For each term of the subscription, Zuora starts a new billing period on the first billing day that falls on or after the start date of the term.
See the `billCycleType` field for information about how Zuora determines the billing day.
**Note**: This field is not supported in one time charges.
enum:
- AlignToCharge
- AlignToSubscriptionStart
- AlignToTermStart
type: string
billingTiming:
description: |
Specifies whether to invoice for a billing period on the first day of the billing period (billing in advance) or the first day of the next billing period (billing in arrears).
enum:
- IN_ADVANCE
- IN_ARREARS
type: string
specificBillingPeriod:
description: |
Duration of each billing period in months or weeks, depending on the value of the `billingPeriod` field. Only applicable if the value of the `billingPeriod` field is `Specific_Months` or `Specific_Weeks`.
type: integer
weeklyBillCycleDay:
description: |
Day of the week that each billing period begins on. Only applicable if the value of the `billCycleType` field is `SpecificDayofWeek`.
enum:
- Sunday
- Monday
- Tuesday
- Wednesday
- Thursday
- Friday
- Saturday
type: string
type: object
chargeFunction:
description: |
**Note**: This field is only available if you have both the Prepaid with Drawdown and Standalone Orders features enabled.
With this field, you can use a standalone order to subscribe to a minimum commitment subscription.
This field defines what type of charge it is:
* CommitmentTrueUp: For recurring charges. Currency based minimum commitment charge.
* CreditCommitment: For usage charges. Credit to minimum commitment funds.
enum:
- CommitmentTrueUp
- CreditCommitment
type: string
commitmentType:
description: |
**Note**: This field is only available if you have both the Prepaid with Drawdown and Standalone Orders features enabled.
With this field, you can use a standalone order to subscribe to a minimum commitment subscription.
This field defines the type of the commitment for both the commitment true-up charge and credit commitment charge, and so you must define the type as `CURRENCY`.
enum:
- CURRENCY
type: string
creditOption:
description: |
**Note**: This field is only available if you have both the Minimum Commitment and Standalone Orders features enabled.
With this field, you can use a standalone order to subscribe to a minimum commitment subscription.
This field defines the way to calculate credit. See [Credit Option](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge#Credit_Option) for more information.
enum:
- TimeBased
- ConsumptionBased
- FullCreditBack
type: string
chargeModel:
description: |
The chargeModel of a standalone charge.
Supported charge models:
* `FlatFee`
* `PerUnit`
* `Volume`
* `Tiered`
* `DiscountFixedAmount`
* `DiscountPercentage`
**Note:** This field is available when the Standalone Orders feature is enabled.
type: string
chargeNumber:
description: |
Charge number of the charge. For example, C-00000307.
* If you do not set this field, Zuora will generate a charge number starting with a default prefix, for example, C-. This default prefix is predefined in **Billing Settings** > **Define Default Subscription and Order Settings**.
* If you want to use a custom charge number, do not use the default prefix predefined in **Billing Settings** > **Define Default Subscription and Order Settings**. Use your own prefix, for example, SC-.
maxLength: 50
type: string
chargeType:
description: |
The chargeType of a standalone charge.
Supported charge types:
* `OneTime`
* `Recurring`
* `Usage`
**Note:** This field is available when the Standalone Orders feature is enabled.
type: string
contractAssetAccountingCode:
description: |
The contractAssetAccountingCode of a standalone charge.
**Note:** This field is available when the Standalone Orders feature and the Billing - Revenue Integration or Order to Revenue feature are enabled.
type: string
contractLiabilityAccountingCode:
description: |
The contractLiabilityAccountingCode of a standalone charge.
**Note:** This field is available when the Standalone Orders feature and the Billing - Revenue Integration or Order to Revenue feature are enabled.
type: string
contractRecognizedRevenueAccountingCode:
description: |
The contractRecognizedRevenueAccountingCode of a standalone charge.
**Note:** This field is available when the Standalone Orders feature and the Billing - Revenue Integration or Order to Revenue feature are enabled.
type: string
customFields:
$ref: '#/components/schemas/RatePlanChargeObjectCustomFields'
deferredRevenueAccountingCode:
description: |
The deferredRevenueAccountingCode of a standalone charge.
**Note:** This field is available when the Standalone Orders and Zuora Finance features are enabled.
type: string
description:
description: |
Description of the charge.
maxLength: 500
type: string
drawdownRate:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
The [conversion rate](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_drawdown_charge#UOM_Conversion) between Usage UOM and Drawdown UOM for a [drawdown charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_drawdown_charge). Must be a positive number (>0).
type: number
endDate:
$ref: '#/components/schemas/EndConditions'
estimatedStartDate:
type: string
format: date
description: |
The estimated start date of the pending charge in an active subscription.
If you specify `SpecificDate` in the `startDate` > `triggerEvent` field and want to create a completed order and an active subscription, you must specify either the `estimatedStartDate` or `startDate` > `specificTriggerDate` field:
- `estimatedStartDate`: The charge will be in pending status.
- `specificTriggerDate`: The charge will be in active status.
The value of this field must be a date within the subscription term. The system will then automatically calculate the estimated end date for the pending charge. The estimated start and end dates are used to manage the estimated charge duration and forecast the revenue for the pending charge.
**Note:** This field is available only when the Pending Subscription Processing feature is turned on.
excludeItemBillingFromRevenueAccounting:
default: false
description: |
The flag to exclude rate plan charge related invoice items, invoice item adjustments, credit memo items, and debit memo items from revenue accounting.
If both the following features are enabled in your tenant, you must ensure the `excludeItemBillingFromRevenueAccounting` field is set consistently for a prepayment charge and the corresponding drawdown charge. In addition, if the `excludeItemBookingFromRevenueAccounting` field in a Create Subscription or Add Product order action is set to `false`, you must also set the `excludeItemBillingFromRevenueAccounting` field in this order action to `false`.
* Prepaid with Drawdown
* Unbilled Usage
**Note**: This field is only available if you have the Order to Revenue or [Zuora Billing - Revenue Integration](https://knowledgecenter.zuora.com/Zuora_Revenue/Zuora_Billing_-_Revenue_Integration) feature enabled.
type: boolean
excludeItemBookingFromRevenueAccounting:
default: false
description: |
The flag to exclude rate plan charges from revenue accounting.
If both the following features are enabled in your tenant, you must ensure the `excludeItemBookingFromRevenueAccounting` field is set consistently for a prepayment charge and the corresponding drawdown charge.
* Prepaid with Drawdown
* Unbilled Usage
**Note**: This field is only available if you have the Order to Revenue or [Zuora Billing - Revenue Integration](https://knowledgecenter.zuora.com/Zuora_Revenue/Zuora_Billing_-_Revenue_Integration) feature enabled.
type: boolean
isAllocationEligible:
description: |
This field is used to identify if the charge segment is allocation
eligible in revenue recognition.
**Note**: The field is only available if you have the Order to Revenue feature enabled. To enable this field, submit a request at Zuora Global Support.
type: boolean
isRollover:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
The value is either "True" or "False". It determines whether the rollover fields are needed.
type: boolean
isUnbilled:
description: |
This field is used to dictate how to perform the accounting during revenue
recognition.
**Note**: The field is only available if you have the Order to Revenue feature enabled. To enable this field, submit a request at Zuora Global Support.
type: boolean
name:
description: |
The name of a standalone charge.
**Note:** This field is available when the Standalone Orders feature is enabled.
type: string
negotiatedPriceTable:
description: |
Array of negotiated price table information. The rate card entries provided in the array will override the existing rate card entries in the standard price table to form a negotiated price table that will be used during pricing evaluation.
**Note:** To enable the Negotiated Price Table feature, submit a request to Zuora Global Support.
items:
$ref: '#/components/schemas/NegotiatedItems'
type: array
pobPolicy:
description: |
The pobPolicy of a standalone charge.
**Note:** This field is available when the Standalone Orders feature is enabled.
type: string
prepaidQuantity:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
The number of units included in a [prepayment charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge). Must be a positive number (>0).
type: number
pricing:
description: |
Pricing information about the charge.
properties:
chargeModelData:
$ref: '#/components/schemas/ChargeModelDataOverride'
discount:
$ref: '#/components/schemas/DiscountPricingOverride'
oneTimeFlatFee:
$ref: '#/components/schemas/OneTimeFlatFeePricingOverride'
oneTimePerUnit:
$ref: '#/components/schemas/OneTimePerUnitPricingOverride'
oneTimeTiered:
$ref: '#/components/schemas/OneTimeTieredPricingOverride'
oneTimeVolume:
$ref: '#/components/schemas/OneTimeVolumePricingOverride'
recurringDeliveryBased:
$ref: '#/components/schemas/RecurringDeliveryPricingOverride'
recurringFlatFee:
$ref: '#/components/schemas/RecurringFlatFeePricingOverride'
recurringPerUnit:
$ref: '#/components/schemas/RecurringPerUnitPricingOverride'
recurringTiered:
$ref: '#/components/schemas/RecurringTieredPricingOverride'
recurringVolume:
$ref: '#/components/schemas/RecurringVolumePricingOverride'
usageFlatFee:
$ref: '#/components/schemas/UsageFlatFeePricingOverride'
usageOverage:
$ref: '#/components/schemas/UsageOveragePricingOverride'
usagePerUnit:
$ref: '#/components/schemas/UsagePerUnitPricingOverride'
usageTiered:
$ref: '#/components/schemas/UsageTieredPricingOverride'
usageTieredWithOverage:
$ref: '#/components/schemas/UsageTieredWithOveragePricingOverride'
usageVolume:
$ref: '#/components/schemas/UsageVolumePricingOverride'
type: object
pricingAttributes:
description: |
Container for pricing attribute and value that provide additional context for dynamic pricing. The pricing attribute values are used to get the charge’s list price from the product catalog. For the pricing attribute mapped to a Zuora object field, Zuora will retrieve the value automatically, you don’t need to pass its value explicitly. If you pass a value that doesn’t match the actual value of the Zuora object, an error will be returned.
Note that for any pricing attribute mapped to the field of Zuora object Usage, because its value is only determined when the usage record arrives, you can’t provide a value via Orders API payload and Zuora will not retrieve its value automatically.
**Note:** To enable Dynamic Pricing, submit a request to Zuora Global Support.
type: object
additionalProperties: true
productCategory:
description: |
The productCategory of a standalone charge.
**Note:** This field is available when the Standalone Orders feature is enabled.
type: string
productClass:
description: |
The productClass of a standalone charge.
**Note:** This field is available when the Standalone Orders feature is enabled.
type: string
productFamily:
description: |
The productFamily of a standalone charge.
**Note:** This field is available when the Standalone Orders feature is enabled.
type: string
productLine:
description: |
The productLine of a standalone charge.
**Note:** This field is available when the Standalone Orders feature is enabled.
type: string
productRatePlanChargeId:
description: |
Internal identifier of the product rate plan charge that the charge is based on. You can specify either `productRatePlanChargeId` or `productRatePlanChargeNumber`. When `isAddingSubsetCharges` is set to true, the product rate charge specified by `productRatePlanChargeId` is added to the existing rate plan specified by `ratePlanId`.
type: string
productRatePlanChargeNumber:
description: |
Number of a product rate-plan charge for this subscription. You can specify either `productRatePlanChargeId` or `productRatePlanChargeNumber`.
type: string
prorationOption:
description: |
**Note**: This field is only available if you have the Charge Level Proration feature enabled. For more information, see Usage charge proration and Charge level proration option for a recurring charge.
You can use this field to specify the charge-level proration option for a usage charge or recurring charge when you creating or adding a subscription rate plan charge through an order. The tenant-level proration option will be overridden.
* `NoProration`: charge-level proration option that you can set for a usage charge. This option means to not use any proration, which is the default current system behavior for a usage charge.
* `TimeBasedProration`: charge-level proration option that you can set for a usage charge. This option means to prorate the usage charge amount using the actual number of days if the billing period is a partial period.
* `DefaultFromTenantSetting`: charge-level proration option that you can set for a recurring charge. This option means to follow the customer billing rule proration setting.
* `ChargeFullPeriod`: charge-level proration option that you can set for a recurring charge. This options means to charge the full period amount for a partial billing period. Note that this setting means that there is no proration for either collecting or refunding. Even if you cancel the recurring charge in the middle of a billing period, there is no refund for this billing period.
* `CustomizeProrationOptionOverrides`: charge-level proration option that you can set for a recurring charge. This option means to use the customized charge proration settings that is specified by the `ratingPropertiesOverride` field.
enum:
- NoProration
- TimeBasedProration
- DefaultFromTenantSetting
- ChargeFullPeriod
- CustomizeProrationOptionOverrides
type: string
ratingPropertiesOverride:
description: |
**Note**: This field is only available if you have the Charge Level Proration feature enabled. For more information, see Charge level proration option for a recurring charge.
This field is used only when the value of the `prorationOption` field is set to `CustomizeProrationOptionOverrides`.
Use this field to specify more customized proration options for a recurring charge when you creating or adding a subscription rate plan charge through an order. The tenant-level proration option will be overridden.
type: object
properties:
isProratePartialMonth:
description: |
**Note**: This field is only available if you have the Charge Level Proration feature enabled. For more information, see Charge level proration option for a recurring charge.
Use this field to specify whether to prorate the recurring charge for a partial month. The tenant-level proration option will be overridden.
type: boolean
prorationUnit:
description: |
**Note**: This field is only available if you have the Charge Level Proration feature enabled. For more information, see Charge level proration option for a recurring charge.
Use this field to specify the unit of proration for a recurring charge. The tenant-level proration option will be overridden.
enum:
- ProrateByDay
- ProrateByMonthFirst
type: string
daysInMonth:
description: |
**Note**: This field is only available if you have the Charge Level Proration feature enabled. For more information, see Charge level proration option for a recurring charge.
Use this field to specify the number of days counted for a month when prorating a recurring charge. The tenant-level proration option will be overridden. See more details for each of the following enum values in Proration.
enum:
- UseActualDays
- Assume30Days
- Assume30DaysStrict
type: string
recognizedRevenueAccountingCode:
description: |
The recognizedRevenueAccountingCode of a standalone charge.
**Note:** This field is available when the Standalone Orders and Zuora Finance features are enabled.
type: string
revRecCode:
description: |
Revenue Recognition Code
maxLength: 70
type: string
revRecTriggerCondition:
description: |
Specifies the revenue recognition trigger condition.
* `Contract Effective Date`
* `Service Activation Date`
* `Customer Acceptance Date`
enum:
- Contract Effective Date
- Service Activation Date
- Customer Acceptance Date
type: string
revenueRecognitionRuleName:
description: |
Specifies the revenue recognition rule, such as `Recognize upon invoicing` or `Recognize daily over time`.
type: string
revenueRecognitionTiming:
description: |
Specifies the type of revenue recognition timing.
Predefined options are listed as enum values in this API Reference. Other options might also be avaliable depending on the revenue recognition policy configuration in the Zuora Billing UI.
**Note**: This field is only available if you have both the Order to Revenue feature and the Standalone Orders feature enabled.
maxLength: 200
type: string
enum:
- Upon Billing Document Posting Date
- Upon Order Activation Date
revenueAmortizationMethod:
description: |
Specifies the type of revenue amortization method.
Predefined options are listed as enum values in this API Reference. Other options might also be avaliable depending on the revenue recognition policy configuration in the Zuora Billing UI.
**Note**: This field is only available if you have both the Order to Revenue feature and the Standalone Orders feature enabled.
maxLength: 200
type: string
enum:
- Immediate
- Ratable Using Start And End Dates
rolloverApply:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
This field defines the priority of rollover, which is either first or last.
enum:
- ApplyFirst
- ApplyLast
type: string
rolloverPeriodLength:
default: null
description: |
**Note**: This field is only available if you have the [Prepaid with
Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown)
feature enabled.
Use this field when you want to set the rollover fund's period length shorter than the prepayment charge's validity period. In this case, you must set the `rolloverPeriods` field to 1. For example, you can define the rollover fund's period length as 5 months, shorter than the prepayment charge's validity period: a year.
type: integer
rolloverPeriods:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
This field defines the number of rollover periods, it is restricted to 3.
type: number
startDate:
$ref: '#/components/schemas/CreateOrderTriggerParams'
taxCode:
description: |
The tax code of a charge. This field is available when the `taxable` field is set to `true`.
type: string
taxMode:
description: |
The tax mode of a charge. This field is available when the `taxable` field is set to `true`.
enum:
- TaxExclusive
- TaxInclusive
type: string
taxable:
type: boolean
description: |
The flag indicates whether the charge is taxable. If this field is set to `true`, you must specify the `taxCode` and `taxMode` fields.
unBilledReceivablesAccountingCode:
description: |
The unBilledReceivablesAccountingCode of a standalone charge.
**Note:** This field is available when the Standalone Orders feature and the Billing - Revenue Integration or Order to Revenue feature are enabled.
type: string
uniqueToken:
description: |
Unique identifier for the charge. This identifier enables you to refer to the charge before the charge has an internal identifier in Zuora.
For instance, suppose that you want to use a single order to add a product to a subscription and later update the same product. When you add the product, you can set a unique identifier for the charge. Then when you update the product, you can use the same unique identifier to specify which charge to modify.
maxLength: 50
type: string
upsellOriginChargeNumber:
description: |
The identifier of the original upselling charge associated with the current charge.
For a termed subscription, you can now use the "Create an order" API operation to perform an Add Product order action to make a product quantity upsell for per unit recurring charges. The benefit is that the charge added by this approach will be automatically combined with the original existing charge for which you want to upsell when the subscription is renewed. The approach is as follows:
* Use an Add Product order action to add a charge that is of the same charge type, charge model, and charge end date as the existing per unit recurring charge for which you want to make a quantity upsell.
* In the preceding charge to add, use the `upsellOriginChargeNumber` field to specify the existing rate plan charge for which you want to make the quantity upsell.
Note that a termed subscription with such upsell charges can not be changed to an evergreen subscription.
**Note**: The Quantity Upsell feature is in the **Early Adopter** phase. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available. If you want to join this early adopter program, submit a request at [Zuora Global
Support](https://support.zuora.com).
type: string
validityPeriodType:
description: |
**Note**: This field is only available if you have enabled either of the following:
* Prepaid with Drawdown
* Minimum Commitment
* Both Minimum Commitment and Standalone Orders
You can use this field in the following scenarios:
* When you create a [prepayment charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge), use this field to define the period in which the prepayment units are valid to use.
* When you override the setting of commitment true-up charge from the product catalog, set this field consistently with the value of the `billing` > `billingPeriod` field in this charge.
* When you use a standalone order to create a commitment true-up charge, set this field consistently with the value of the `billing` > `billingPeriod` field in this charge.
enum:
- SUBSCRIPTION_TERM
- ANNUAL
- SEMI_ANNUAL
- QUARTER
- MONTH
type: string
required:
- productRatePlanChargeId
title: charge
type: object
ShipToContactPostOrder:
allOf:
- description: |
Contact details associated with an account.
properties:
address1:
description: |
First line of the contact's address. This is often a street address or a business name.
maxLength: 255
type: string
address2:
description: |
Second line of the contact's address.
maxLength: 255
type: string
city:
description: |
City of the contact's address.
maxLength: 100
type: string
contactDescription:
description: |
A description for the contact.
maxLength: 100
type: string
country:
description: |
Country; must be a valid country name or abbreviation.
maxLength: 64
type: string
county:
description: |
County of the contact's address.
maxLength: 100
type: string
fax:
description: |
Fax number of the contact.
maxLength: 40
type: string
firstName:
description: |
First name of the contact.
maxLength: 100
type: string
homePhone:
description: |
Home phone number of the contact.
maxLength: 40
type: string
lastName:
description: |
Last name of the contact.
maxLength: 100
type: string
mobilePhone:
description: |
Mobile phone number of the contact.
maxLength: 40
type: string
nickname:
description: |
Nickname of the contact.
maxLength: 100
type: string
otherPhone:
description: |
Additional phone number of the contact. Use the `otherPhoneType` field to specify the type of phone number.
maxLength: 40
type: string
otherPhoneType:
description: |
Specifies the type of phone number in the `otherPhone` field.
enum:
- Work
- Mobile
- Home
- Other
type: string
personalEmail:
description: |
Personal email address of the contact.
format: email
maxLength: 80
type: string
postalCode:
description: |
ZIP code or other postal code of the contact's address.
maxLength: 20
type: string
state:
description: |
State or province of the contact's address.
maxLength: 100
type: string
taxRegion:
description: |
Region defined in your taxation rules. Only applicable if you use Zuora Tax.
maxLength: 100
type: string
nullable: true
workEmail:
description: |
Business email address of the contact.
format: email
maxLength: 80
type: string
workPhone:
description: |
Business phone number of the contact.
maxLength: 40
type: string
required:
- firstName
- lastName
type: object
- $ref: '#/components/schemas/ContactObjectCustomFields'
UpsertCreateCommitmentInput:
title: UpsertCreateCommitmentInput
description: create a new Commitment.
properties:
action:
$ref: '#/components/schemas/ActionTypeCreate'
schedules:
description: The new schedules which are required when creating a new commitment.
type: array
items:
type: object
properties:
action:
type: string
enum:
- create
allOf:
- $ref: '#/components/schemas/CommitmentScheduleInput'
allOf:
- $ref: '#/components/schemas/CommitmentInput'
required:
- action
- schedules
UpsertUpdateCommitmentInput:
type: object
description: Update the existing commitment by the commitment number.
required:
- action
- commitmentNumber
properties:
action:
$ref: '#/components/schemas/ActionType'
commitmentNumber:
type: string
description: The number of the Commitment.
name:
description: The value to update. Set to null to clear the existing value.
type: string
description:
description: The value to update. Set to null to clear the existing value.
type: string
customFields:
type: object
additionalProperties: true
description: Container for custom fields of an commitment object.
title: CommitmentSegmentCustomFields
status:
type: string
description: |-
The status of the commitment.
**Notes:** When the status of the commitment is updated as canceled, a commitment or schedule can be canceled only if none of its periods have been drawdowned.
enum:
- Canceled
schedules:
$ref: '#/components/schemas/UpsertCommitmentScheduleInput'
ActionType:
type: string
enum:
- create
- update
description: |
The action type of the commitment.
UpsertCommitmentScheduleInput:
title: UpsertCommitmentSheduleInput
description: |
Upsert an schedule, when the action is create, create a new schedule, when the action is update, update the schedule.
**Notes:**
- If none of the periods in a schedule has drawdown, you can not only update the schedule amount, but also delete the schedule.
- If any period in a schedule has drawdown, you can update the schedule amount, but you cannot delete the schedule.
- If any period in a schedule has been evaluated, you cannot update the schedule amount. Also, you cannot delete the schedule.
type: object
discriminator:
propertyName: action
mapping:
create: '#/components/schemas/UpsertCreateCommitmentScheduleInput'
update: '#/components/schemas/UpsertUpdateCommitmentScheduleInput'
oneOf:
- $ref: '#/components/schemas/UpsertCreateCommitmentScheduleInput'
- $ref: '#/components/schemas/UpsertUpdateCommitmentScheduleInput'
UpsertCreateCommitmentScheduleInput:
description: Create a new schedule.
type: object
required:
- action
allOf:
- $ref: '#/components/schemas/CommitmentScheduleInput'
- properties:
action:
$ref: '#/components/schemas/ActionTypeSchedule'
UpsertUpdateCommitmentScheduleInput:
description: Update an existing commitment schedule.
required:
- action
- id
type: object
properties:
id:
type: string
description: The ID of the schedule.
action:
$ref: '#/components/schemas/ActionTypeSchedule'
amount:
type: number
format: double
description: |
The amount of each period in the schedule.
**Notes:**
- If none of the periods in a schedule have drawdown, you can update the amount.
- If any period in a schedule has drawdown (but none are evaluated), you can update the amount.
- If any period in a schedule has been evaluated, you cannot update the amount.
status:
type: string
description: |-
The status of the schedule.
**Notes:** Schedules which are evaluated cannot be canceled. When the status of the commitment is updated as canceled, a commitment or schedule can be canceled only if none of its periods have been drawdowned.
enum:
- Canceled
ActionTypeSchedule:
type: string
enum:
- create
- update
description: |
The action type of the schedule.
CommitmentScheduleInput:
title: CommitmentScheduleInput
allOf:
- $ref: '#/components/schemas/CommitmentScheduleAttributes'
CommitmentScheduleAttributes:
title: CommitmentScheduleAttributes
type: object
properties:
amount:
type: number
description: The amount of each period in the schedule.
amountBase:
$ref: '#/components/schemas/AmountBaseEnum'
periodType:
$ref: '#/components/schemas/PeriodTypeEnum'
specificPeriodLength:
type: integer
description: The specific period length of each period in the schedule.
startDate:
description: Ths start date of the schedule.
type: string
format: date
endDate:
description: |-
The end date of the schedule.
**Notes:** A commitment can contain a maximum of 100 periods.
type: string
format: date
required:
- startDate
- endDate
- amount
ActionTypeCreate:
type: string
enum:
- create
description: |
Indicates whether to create a commitment.
CommitmentInput:
type: object
title: CreateCommitmentRequest
allOf:
- $ref: '#/components/schemas/CommitmentBaseAttributesRequest'
- $ref: '#/components/schemas/CommonRevenueAttributes'
- $ref: '#/components/schemas/CommonTaxationAttributes'
- properties:
currency:
type: string
description: |
Currency of the commitment.
eligibleAccountConditions:
$ref: '#/components/schemas/EligibleAccountCondition'
eligibleChargeConditions:
$ref: '#/components/schemas/EligibleChargeCondition'
required:
- eligibleAccountConditions
- currency
CommitmentBaseAttributesRequest:
type: object
title: UpsertOrderCommitmentBaseAttributes
properties:
commitmentNumber:
description: |
The commitment number.
type: string
maxLength: 100
name:
description: |
The name of the commitment.
type: string
maxLength: 255
type:
$ref: '#/components/schemas/CommitmentTypeEnum'
description:
description: |
The description of the commitment.
type: string
maxLength: 500
priority:
description: |
It defines the evaluation order of the commitment. The lower the number, the higher the priority.
When two commitments have the same priority, the commitment that was created initially will be evaluated first.
type: integer
customFields:
type: object
additionalProperties: true
description: |
Custom fields of an Commitment object.
title: CommitmentCustomFields
specificPeriodAlignmentDate:
type: string
description: The specific date for the period alignment. This field is required only if the `periodAlignmentOption` is set to `SpecificDate`.
format: date
example: '2020-01-15'
periodAlignmentOption:
$ref: '#/components/schemas/PeriodAlignmentOptionEnum'
required:
- name
- type
- priority
POSTOrderAsyncRequestType:
example:
existingAccountNumber: A00000097
orderDate: '2024-07-01'
subscriptions:
- orderActions:
- type: CreateSubscription
createSubscription:
terms:
initialTerm:
period: 12
periodType: Month
termType: TERMED
renewalSetting: RENEW_WITH_SPECIFIC_TERM
renewalTerms:
- period: 12
periodType: Month
subscribeToRatePlans:
- productRatePlanId: 8ad081dd9096ef9501909b40bb4e74a4
properties:
category:
default: NewSales
description: |
Category of the order to indicate a product sale or return. Default value is `NewSales`.
enum:
- NewSales
- Return
type: string
customFields:
$ref: '#/components/schemas/OrderObjectCustomFields'
description:
description: A description of the order.
maxLength: 500
type: string
existingAccountId:
description: |
The account ID under which this order will be created. This field sets the default invoice owner account and subscription owner account for any new subscriptions in the order. To override these defaults for individual subscriptions, use the `subscriptionOwnerAccountNumber` and `invoiceOwnerAccountNumber` nested fields in the `subscriptions` field.
**Note:** You can specify either the `existingAccountNumber` or `existingAccountId` field, but not both.
type: string
existingAccountNumber:
description: |
The account number under which this order will be created. This field sets the default invoice owner account and subscription owner account for any new subscriptions in the order. To override these defaults for individual subscriptions, use the `subscriptionOwnerAccountNumber` and `invoiceOwnerAccountNumber` nested fields in the `subscriptions` field.
maxLength: 70
type: string
externallyManagedBy:
description: |
An enum field on the Subscription object to indicate the name of a third-party store. This field is used to represent subscriptions created through third-party stores.
enum:
- Amazon
- Apple
- Google
- Roku
type: string
newAccount:
$ref: '#/components/schemas/CreateOrderNewAccount'
orderDate:
description: The date when the order is signed. All the order actions under this order will use this order date as the contract effective date if the contract effective date field is skipped or its value is left as null.
format: date
type: string
orderLineItems:
description: |
[Order Line Items](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Order_Line_Items/AA_Overview_of_Order_Line_Items) are non subscription based items created by an Order, representing transactional charges such as one-time fees, physical goods, or professional service charges that are not sold as subscription services.
With the Order Line Items feature enabled, you can now launch non-subscription and unified monetization business models in Zuora, in addition to subscription business models.
If you do not have the **Create Order Line Items Without Product Catalog** billing permission, you can only create order line items from existing products by specifying the product rate plan charge ID in the `productRatePlanChargeId` field. For more information about billing permissions, see Billing Roles.
**Note:** The [Order Line Items](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Order_Line_Items/AA_Overview_of_Order_Line_Items) feature is now generally available to all Zuora customers. You need to enable the [Orders](https://knowledgecenter.zuora.com/BC_Subscription_Management/Orders/AA_Overview_of_Orders#Orders) feature to access the [Order Line Items](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Order_Line_Items/AA_Overview_of_Order_Line_Items) feature. As of Zuora Billing Release 313 (November 2021), new customers who onboard on [Orders](https://docs.zuora.com/en/zuora-billing/manage-accounts-subscriptions-and-non-subscriptions/manage-subscription-transactions/orders/orders-introduction/overview-of-orders) will have the [Order Line Items](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Order_Line_Items) feature enabled by default.
items:
$ref: '#/components/schemas/CreateOrderOrderLineItem'
type: array
orderNumber:
description: |
The order number of the new order. If not provided, system will auto-generate a number for this order.
**Note:** The characters `#`, `?`, and `/` are not allowed in this field. Additionally, to ensure compatibility with the UI when viewing orders, use only the following special characters: `_`,`-`, `.`, `~`, `*`, `(`, `)`, and `'`.
maxLength: 100
type: string
processingOptions:
$ref: '#/components/schemas/processingOptionsOrdersAsync'
reasonCode:
description: |
Values of reason code configured in **Billing Settings** > **Configure Reason Codes** through Zuora UI. Indicates the reason when a return order line item occurs.
maxLength: 255
type: string
subscriptions:
description: 'Each item includes a set of order actions, which will be applied to the same base subscription. When you create an order that involves multiple subscriptions, these subscriptions can have different invoice owner accounts or subscription owner accounts. '
items:
properties:
customFields:
$ref: '#/components/schemas/SubscriptionObjectCustomFields'
notes:
description: |
Notes about the subscription. These notes are only visible to Zuora users. Notes set in this field will override the value of the `notes` field within the createSubscription order action.
type: string
maxLength: 1000
orderActions:
description: The actions to be applied to the subscription. Order actions will be stored with the sequence when it was provided in the request.
items:
$ref: '#/components/schemas/CreateOrderOrderAction'
type: array
quote:
$ref: '#/components/schemas/QuoteObjectFields'
ramp:
$ref: '#/components/schemas/RampRequest'
subscriptionNumber:
description: |
Leave this empty to represent new subscription creation. Specify a subscription number to update an existing subscription.
type: string
type: object
type: array
required:
- orderDate
type: object
processingOptionsOrdersAsync:
description: |
The container for billing processing options and payment processing options.
**Note:** This field is not supported in draft orders.
properties:
applicationOrder:
description: |
The priority order to apply credit memos and/or unapplied payments to an invoice. Possible item values are: `CreditMemo`, `UnappliedPayment`.
**Note:**
- This field is valid only if the `applyCredit` field is set to `true`.
- If no value is specified for this field, the default priority order is used, ["CreditMemo", "UnappliedPayment"], to apply credit memos first and then apply unapplied payments.
- If only one item is specified, only the items of the spedified type are applied to invoices. For example, if the value is `["CreditMemo"]`, only credit memos are used to apply to invoices.
items:
type: string
type: array
applyCredit:
description: |
- If the value is true, the credit memo or unapplied payment on the order account will be automatically applied to the invoices generated by this order. The credit memo generated by this order will not be automatically applied to any invoices
**Note:** This field is only available if you have [Invoice Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement) 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: boolean
applyCreditBalance:
description: |
Indicates if any credit balance on a customer's account is automatically applied to invoices. If no value is specified then this field defaults to false. This feature is not available if you have enabled the Invoice Settlement feature.
type: boolean
billingOptions:
properties:
creditMemoReasonCode:
description: A code identifying the reason for the credit memo transaction that is generated by the request. The value must be an existing reason code. If you do not pass the field or pass the field with empty value, Zuora uses the default reason code.
type: string
documentDate:
description: |
The invoice date displayed on the invoice.
format: date
type: string
generateDraftInvoice:
description: |
Indicates if the current request needs to generate a draft invoice.
Values are:
* `true`
* `false` (default)
type: boolean
targetDate:
description: |
Date through which to calculate charges if an invoice is generated. See [What is a Target Date?](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/G_Bill_Runs/Creating_Bill_Runs#What_is_a_Target_Date.3F).
**Note**: If you do not specify this field, today's date is used by default.
format: date
type: string
chargeTypeToExclude:
description: |
The types of the charges to be excluded from the generation of billing documents.
items:
type: string
enum:
- OneTime
- Recurring
- Usage
type: array
type: object
collectPayment:
description: |
Indicates if the current request needs to collect payments. This value can not be 'true' when 'runBilling' flag is 'false'.
type: boolean
electronicPaymentOptions:
description: |
Container for the electronic payment options.
properties:
paymentGatewayId:
description: |
Specifies the ID of a payment gateway to override the default gateway. If this field is not specified, the default payment gateway will be used to process the payment.
type: string
paymentMethodId:
description: |
Specifies an electronic payment method. It can be one that has already been associated with an invoice owner, or an orphan payment method, which is not associated with any invoice owner. For an orphan payment method, this operation will then associate it with the account that this order will be created under.
type: string
gatewayOptions:
description: |
The field used to pass gateway-specific parameters and parameter values.
The fields supported by gateways vary. For more information, see the
overview topic of each gateway integration in Zuora Knowledge Center.
Zuora sends all the information that you specified to the gateway. If you
specify any unsupported gateway option parameters, they will be ignored
without error prompts.
type: object
title: gatewayOptions
additionalProperties:
type: string
description: |
The gateway options specification consists of key-value pairs:
- Field name: The name of a gateway-specific parameter.
- Field value: The value of the gateway-specific parameter.
type: object
runBilling:
description: |
Indicates if the current request needs to generate an invoice. The invoice will be generated against all subscriptions included in this order.
type: boolean
type: object
GetOrderResponse:
allOf:
- $ref: '#/components/schemas/CommonResponse'
- properties:
order:
$ref: '#/components/schemas/Order'
type: object
PUTOrderRequestType:
example:
existingAccountNumber: A00000097
orderDate: '2024-11-11'
subscriptions:
- orderActions:
- createSubscription:
notes: Notes about the subscription
terms:
renewalSetting: RENEW_WITH_SPECIFIC_TERM
initialTerm:
startDate: '2024-11-10'
period: 12
periodType: Month
termType: TERMED
renewalTerms:
- period: 6
periodType: Month
type: CreateSubscription
properties:
category:
default: NewSales
description: |
Category of the order to indicate a product sale or return. Default value is `NewSales`.
enum:
- NewSales
- Return
type: string
commitments:
items:
$ref: '#/components/schemas/UpsertCommitmentInput'
type: array
description: |
A list of commitments you want to create or update.
customFields:
$ref: '#/components/schemas/OrderObjectCustomFields'
description:
description: A description of the order.
maxLength: 500
type: string
existingAccountId:
description: |
The account ID under which this order will be created. This field sets the default invoice owner account and subscription owner account for any new subscriptions in the order. To override these defaults for individual subscriptions, use the `subscriptionOwnerAccountNumber` and `invoiceOwnerAccountNumber` nested fields in the `subscriptions` field.
**Note** You can specify either the `existingAccountNumber` or `existingAccountId` field, but not both.
type: string
existingAccountNumber:
description: |
The account number under which this order will be created. This field sets the default invoice owner account and subscription owner account for any new subscriptions in the order. To override these defaults for individual subscriptions, use the `subscriptionOwnerAccountNumber` and `invoiceOwnerAccountNumber` nested fields in the `subscriptions` field.
maxLength: 70
type: string
orderDate:
description: The date when the order is signed. All the order actions under this order will use this order date as the contract effective date if the contract effective date field is skipped or its value is left as null.
format: date
type: string
orderNumber:
description: |
The order number of the new order. If not provided, system will auto-generate a number for this order.
**Note:** The characters `#`, `?`, and `/` are not allowed in this field.
maxLength: 100
type: string
processingOptions:
$ref: '#/components/schemas/processingOptionsOrders'
reasonCode:
description: |
Values of reason code configured in **Billing Settings** > **Configure Reason Codes** through Zuora UI. Indicates the reason when a return order line item occurs.
maxLength: 255
type: string
schedulingOptions:
description: |
Information of scheduled order.
properties:
scheduledDate:
description: |
The date for the order scheduled.
format: date
type: string
scheduledDatePolicy:
description: Date policy of the scheduled order.
enum:
- SpecificDate
type: string
type: object
status:
description: |
The status of the order. The default value is `Completed`. The following values are supported:
- `Draft`: The order is in draft status.
- `Pending`: The order is in pending status.
- `Completed`: The order is in completed status.
- `Scheduled`: The order is in scheduled status and it is only valid if the Scheduled Orders feature is enabled.
- `Executing`: The scheduled order is executed by a scheduler and it is only valid if the Scheduled Orders feature is enabled.
- `Failed`: The scheduled order has failed.
**Note:** If you have the Pending Subscription Processing feature turned on and want to update a completed order with an active subscription with pending charges, you must specify `Completed` in this field because the default order status is `Pending` for this scenario.
enum:
- Draft
- Pending
- Completed
- Scheduled
- Executing
- Failed
type: string
subscriptions:
description: 'Each item includes a set of order actions, which will be applied to the same base subscription. When you create an order that involves multiple subscriptions, these subscriptions can have different invoice owner accounts or subscription owner accounts. '
items:
properties:
customFields:
$ref: '#/components/schemas/SubscriptionObjectCustomFields'
orderActions:
description: The actions to be applied to the subscription. Order actions will be stored with the sequence when it was provided in the request.
items:
$ref: '#/components/schemas/CreateOrderOrderAction'
type: array
quote:
$ref: '#/components/schemas/QuoteObjectFields'
ramp:
$ref: '#/components/schemas/RampRequest'
subscriptionNumber:
description: |
Leave this empty to represent new subscription creation. Specify a subscription number to update an existing subscription.
type: string
type: object
type: array
required:
- orderDate
type: object
PutOrderResponseType:
description: Response information of orders.
allOf:
- $ref: '#/components/schemas/CommonResponse'
- properties:
accountId:
description: The account ID for the order. This field is returned instead of the `accountNumber` field if the `returnIds` query parameter is set to `true`.
maxLength: 32
type: string
accountNumber:
description: The account number for the order.
maxLength: 50
type: string
creditMemoIds:
description: An array of the credit memo IDs generated in this order request. The credit memo is only available if you have the Invoice Settlement feature enabled. This field is returned instead of the `creditMemoNumbers` field if the `returnIds` query parameter is set to `true`.
items:
type: string
maxLength: 32
type: array
creditMemoNumbers:
description: An array of the credit memo numbers generated in this order request. The credit memo is only available if you have the Invoice Settlement feature enabled.
items:
type: string
maxLength: 255
type: array
invoiceIds:
description: An array of the invoice IDs generated in this order request. Normally it includes one invoice ID only, but can include multiple items when a subscription was tagged as invoice separately. This field is returned instead of the `invoiceNumbers` field if the `returnIds` query parameter is set to `true`.
items:
type: string
maxLength: 32
type: array
invoiceNumbers:
description: An array of the invoice numbers generated in this order request. Normally it includes one invoice number only, but can include multiple items when a subscription was tagged as invoice separately.
items:
type: string
maxLength: 255
type: array
orderId:
description: The ID of the order created. This field is returned instead of the `orderNumber` field if the `returnIds` query parameter is set to `true`.
maxLength: 32
type: string
orderNumber:
description: The order number of the order created.
maxLength: 100
type: string
paidAmount:
description: The total amount collected in this order request.
maxLength: 22
minLength: 9
type: string
paymentId:
description: The payment Id that is collected in this order request. This field is returned instead of the `paymentNumber` field if the `returnIds` query parameter is set to `true`.
maxLength: 32
type: string
paymentNumber:
description: The payment number that is collected in this order request.
maxLength: 32
type: string
ramps:
description: |
**Note**: This field is only available if you have the Ramps feature enabled. The Orders feature must be enabled before you can access the Ramps feature. The Ramps feature is available for customers with Enterprise and Nine editions by default. If you are a Growth customer, see Zuora Editions for pricing information coming October 2020. The ramp definitions created by this order request.
items:
properties:
rampNumber:
description: The number of the ramp definition.
maxLength: 50
type: string
subscriptionNumber:
description: The number of the subscription that this ramp deal definition is applied to.
maxLength: 150
type: string
type: object
type: array
refunds:
items:
properties:
number:
description: The refund number. For example, `R-00009564`.
maxLength: 32
type: string
refundInvoiceNumbers:
description: An array of the refunded invoice numbers generated in this order request.
items:
type: string
maxLength: 255
type: array
status:
description: The status of the refund.
enum:
- Success
- Error
type: string
type: object
type: array
status:
description: Status of the order. `Pending` is only applicable for an order that contains a `CreateSubscription` order action.
enum:
- Draft
- Pending
- Completed
- Scheduled
type: string
subscriptionIds:
description: Container for the subscription IDs of the subscriptions in an order. This field is returned if the `returnIds` query parameter is set to `true`.
items:
type: string
maxLength: 32
type: array
subscriptionOwnerId:
description: Subscription owner account ID of the subscription.
type: string
subscriptionOwnerNumber:
description: Subscription owner account number of the subscription.
type: string
subscriptions:
description: |
This field is available only if you are on the latest Zuora API minor
version, or you set the `Zuora-Version` request header to `223.0` or a
later available version.
items:
properties:
status:
description: Status of the subscription. `Pending Activation` and `Pending Acceptance` are only applicable for an order that contains a `CreateSubscription` order action.
enum:
- Active
- Pending Activation
- Pending Acceptance
- Cancelled
- Suspended
type: string
subscriptionId:
description: Subscription ID of the subscription included in this order. This field is returned instead of the `subscriptionNumber` field if the `returnIds` query parameter is set to `true`.
maxLength: 32
type: string
subscriptionNumber:
description: Subscription number of the subscription included in this order.
maxLength: 150
type: string
type: object
type: array
writeOff:
items:
properties:
amount:
description: The amount written off from the invoice balance.
maximum: 22
minimum: 9
type: number
failedReason:
description: The reason of write-off failure.
type: string
invoiceNumber:
description: The number of the invoice that is written off. For example, `INV00051208`.
maxLength: 255
type: string
status:
description: The status of the write-off.
enum:
- Success
- Failed
type: string
writeOffCreditMemoNumber:
description: The number of the credit memo that is written off.
maxLength: 255
type: string
type: object
type: array
commitments:
$ref: '#/components/schemas/CommitmentOutput'
type: object
processingOptionsOrders:
description: |
The container for billing processing options and payment processing options.
**Note:**
- This field is not supported in draft orders.
- When you use the "Create an order" operation to create an account, create a subscription, run billing, and collect payment in a single call, if any error occurs during the call, such as a payment processing failure and a tax engine failure, then all the other steps will be rolled back. In this case, neither the invoice will be generated, nor the subscription nor the account will be created.
- When you use the "Create an order" operation to cancel a subscription with `refund` and `writeOff`, if the `refund` or `writeOff` fails, `cancelSubscription`, `runBilling`, and `collectPayment` still can succeed.
- When you use the "Create an order" operation, the `collectPayment` and `refund` fields cannot be set to `true` simultaneously. Otherwise, the order will not be proceeded.
properties:
applicationOrder:
description: |
The priority order to apply credit memos and/or unapplied payments to an invoice. Possible item values are: `CreditMemo`, `UnappliedPayment`.
**Note:**
- This field is valid only if the `applyCredit` field is set to `true`.
- If no value is specified for this field, the default priority order is used, ["CreditMemo", "UnappliedPayment"], to apply credit memos first and then apply unapplied payments.
- If only one item is specified, only the items of the spedified type are applied to invoices. For example, if the value is `["CreditMemo"]`, only credit memos are used to apply to invoices.
items:
type: string
type: array
applyCredit:
description: |
Whether to automatically apply credit memos or unapplied payments, or both to an invoice.
If the value is true, the credit memo or unapplied payment on the order account will be automatically applied to the invoices generated by this order. The credit memo generated by this order will not be automatically applied to any invoices.
**Note:** This field is only available if you have [Invoice Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement) 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: boolean
applyCreditBalance:
description: |
Indicates if any credit balance on a customer's account is automatically applied to invoices. If no value is specified then this field defaults to false. This feature is not available if you have enabled the Invoice Settlement feature.
type: boolean
billingOptions:
properties:
creditMemoReasonCode:
description: A code identifying the reason for the credit memo transaction that is generated by the request. The value must be an existing reason code. If you do not pass the field or pass the field with empty value, Zuora uses the default reason code.
type: string
documentDate:
description: |
The invoice date displayed on the invoice.
format: date
type: string
generateDraftInvoice:
description: |
Indicates if the current request needs to generate a draft invoice.
Values are:
* `true`
* `false` (default)
type: boolean
targetDate:
description: |
Date through which to calculate charges if an invoice is generated. See [What is a Target Date?](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/G_Bill_Runs/Creating_Bill_Runs#What_is_a_Target_Date.3F).
format: date
type: string
type: object
collectPayment:
description: |
Indicates if the current request needs to collect payments. This value can not be 'true' when 'runBilling' flag is 'false'.
type: boolean
electronicPaymentOptions:
description: |
Container for the electronic payment options.
properties:
paymentGatewayId:
description: |
Specifies the ID of a payment gateway to override the default gateway. If this field is not specified, the default payment gateway will be used to process the payment.
type: string
paymentMethodId:
description: |
Specifies an electronic payment method. It can be one that has already been associated with an invoice owner, or an orphan payment method, which is not associated with any invoice owner. For an orphan payment method, this operation will then associate it with the account that this order will be created under.
type: string
gatewayOptions:
description: |
The field used to pass gateway-specific parameters and parameter values.
The fields supported by gateways vary. For more information, see the
overview topic of each gateway integration in Zuora Knowledge Center.
Zuora sends all the information that you specified to the gateway. If you
specify any unsupported gateway option parameters, they will be ignored
without error prompts.
type: object
title: gatewayOptions
additionalProperties:
type: string
description: |
The gateway options specification consists of key-value pairs:
- Field name: The name of a gateway-specific parameter.
- Field value: The value of the gateway-specific parameter.
type: object
refund:
description: |
Indicates whether to refund after subscription cancelation. Default is `false`.
**Note**: When refunding a subscription that is not invoiced separately, if you do not enable the Invoice Item Settlement feature, you will encounter the following error during the cancel and refund process: “Cancellation/Refund failed because of the following reason: Invoice is linked to multiple subscriptions. Cancellation was not processed.”
type: boolean
refundAmount:
description: |
Indicates the amount to be refunded. Required if the `refund` field is `true`.
type: number
refundReasonCode:
description: |
A code identifying the reason for the refund transaction. The value must be an existing payment refund reason code listed in **Payments Settings** > **Configure Reason Codes**. If you do not specify the field or leave the field with an empty value, Zuora uses the default payment refund reason code.
type: string
runBilling:
description: |
Indicates if the current request needs to generate an invoice. The invoice will be generated against all subscriptions included in this order.
type: boolean
writeOff:
description: |
Indicates whether to write off the outstanding balance on the invoice after refund. Default is `false`.
**Note**:
- When refunding a subscription that is not invoiced separately, if you do not enable the Invoice Item Settlement feature, you will encounter the following error during the cancel and refund process: “Cancellation/Refund failed because of the following reason: Invoice is linked to multiple subscriptions. Cancellation was not processed.”
- The Invoice Settlement feature must have been enabled for write-off.
type: boolean
writeOffBehavior:
description: |
The financial information of the credit memo items generated to write off the invoice balance.
**Note:**
- All the credit memo items that are used to write off the invoice will be applied with the same financial information.
- Credit memo items generated from the unconsumed services of the canceled subscription will not be applied with the finance information specified here.
properties:
financeInformation:
description: |
Container for the finance information related to the credit memo items that are created for invoice write-off.
properties:
deferredRevenueAccountingCode:
description: |
The accounting code for the deferred revenue, such as Monthly Recurring Liability.
maxLength: 100
minLength: 0
type: string
onAccountAccountingCode:
description: |
The accounting code that maps to an on account in your accounting system.
maxLength: 100
minLength: 0
type: string
recognizedRevenueAccountingCode:
description: |
The accounting code for the recognized revenue, such as Monthly Recurring Charges or Overage Charges.
maxLength: 100
minLength: 0
type: string
revenueRecognitionRuleName:
description: |
The name of the revenue recognition rule governing the revenue schedule.
maxLength: 100
minLength: 0
type: string
type: object
type: object
type: object
DeleteOrderAsyncResponse:
properties:
jobId:
description: The ID of an asynchronous job that will be returned for tracking the status and result of the job.
type: string
success:
description: Indicates whether the call succeeded.
type: boolean
type: object
GetAsyncOrderJobResponse:
properties:
errors:
description: Error messages returned if the job failed.
type: string
nullable: true
result:
$ref: '#/components/schemas/GetAsyncOrderJobResponseResult'
status:
description: Type of job status.
enum:
- Processing
- Failed
- Completed
type: string
success:
description: Indicates whether the operation call succeeded.
type: boolean
type: object
GetAsyncOrderJobResponseResult:
oneOf:
- $ref: '#/components/schemas/GetAsyncCreateOrderJobResponse'
- $ref: '#/components/schemas/GetAsyncPreviewOrderJobResponse'
discriminator:
propertyName: jobType
mapping:
AsyncCreateOrder: '#/components/schemas/GetAsyncCreateOrderJobResponse'
AsyncPreviewOrder: '#/components/schemas/GetAsyncPreviewOrderJobResponse'
GetAsyncCreateOrderJobResponse:
allOf:
- $ref: '#/components/schemas/CommonResponse'
- $ref: '#/components/schemas/CreateOrderResult'
- type: object
properties:
jobType:
description: The type of job.
type: string
enum:
- AsyncCreateOrder
default: AsyncCreateOrder
GetAsyncPreviewOrderJobResponse:
allOf:
- $ref: '#/components/schemas/CommonResponse'
- $ref: '#/components/schemas/PreviewOrderResult'
- type: object
properties:
jobType:
description: The type of job.
type: string
enum:
- AsyncPreviewOrder
default: AsyncPreviewOrder
GetOrdersResponse:
allOf:
- $ref: '#/components/schemas/CommonResponse'
- properties:
nextPage:
description: |
URL to retrieve the next page of the response if it exists; otherwise absent.
format: URL
type: string
orders:
items:
$ref: '#/components/schemas/Order'
type: array
type: object
PUTOrderPatchRequestType:
example:
customFields:
CustomTag__c: internal
properties:
customFields:
$ref: '#/components/schemas/OrderObjectCustomFields'
subscriptions:
items:
properties:
orderActions:
items:
properties:
customFields:
$ref: '#/components/schemas/OrderActionObjectCustomFields'
orderActionId:
description: |
The Id of the order action in the order. You can provide either the `sequence` or the `orderActionId` field to specify which order action to update. You cannot use then both at the same time.
type: string
sequence:
description: |
The sequence number of the order action in the order. You can provide either the `sequence` or the `orderActionId` field to specify which order action to update. You cannot use then both at the same time.
type: integer
type: object
type: array
subscriptionNumber:
type: string
type: object
type: array
type: object
PUTSubscriptionPatchRequestType:
example:
customFields:
CustomTag__c: internal
properties:
customFields:
$ref: '#/components/schemas/SubscriptionObjectCustomFields'
ratePlans:
items:
properties:
charges:
items:
properties:
chargeId:
description: |
Use either this field or the `chargeNumber` field to specify the charge for which you will be updating the custom fields. By using this field you actually specify a specific charge segment of a charge. See Segmented rate plan charges for more information about charge segments.
type: string
chargeNumber:
description: |
Use either this field or the `chargeId` field to specify the charge for which you will be updating the custom fields. By using this field you actually specify the last charge segment of a charge. See Segmented rate plan charges for more information about charge segments.
type: string
customFields:
$ref: '#/components/schemas/RatePlanChargeObjectCustomFields'
type: object
type: array
customFields:
$ref: '#/components/schemas/OrdersRatePlanObjectCustomFields'
ratePlanId:
description: The rate plan id in any version of the subscription. This will be linked to the only one rate plan in the current version.
type: string
type: object
type: array
type: object
PUTOrderActionTriggerDatesRequestType:
example:
subscriptions:
- subscriptionNumber: A-S00000143
orderActions:
- sequence: 0
triggerDates:
- name: CustomerAcceptance
triggerDate: '2024-07-22'
properties:
subscriptions:
items:
properties:
orderActions:
items:
properties:
charges:
items:
properties:
chargeNumber:
description: Charge number of the charge which needs the triggering date to be provided. The charge's `triggerEvent` must have been set as `SpecificDate`.
type: string
specificTriggerDate:
description: Date in YYYY-MM-DD format. The specific trigger date you are to set for the charge.
format: date
type: string
type: object
type: array
sequence:
description: |
Identifies which order action will have its triggering dates updated.
type: integer
triggerDates:
description: Container for the service activation and customer acceptance dates of the order action.
items:
properties:
name:
description: Name of the trigger date of the order action.
enum:
- ServiceActivation
- CustomerAcceptance
type: string
triggerDate:
description: |
Trigger date in YYYY-MM-DD format. The date you are to set as the service activation date or the customer acceptance date.
format: date
type: string
type: object
type: array
required:
- sequence
type: object
type: array
subscriptionNumber:
description: |
Subscription number of a subscription in the `Pending` order for which you are to update the triggering dates. For example, A-S00000001.
maxLength: 100
type: string
required:
- subscriptionNumber
type: object
type: array
type: object
PUTOrderTriggerDatesResponseType:
allOf:
- $ref: '#/components/schemas/CommonResponse'
- properties:
accountNumber:
description: The account number for the order.
type: string
orderNumber:
description: The order number of the order updated.
type: string
status:
description: Status of the order.
enum:
- Completed
- Pending
type: string
subscriptions:
description: The subscriptions updated.
items:
properties:
status:
description: Status of the subscription. `Pending Activation` and `Pending Acceptance` are only applicable for an order that contains a `CreateSubscription` order action.
enum:
- Active
- Pending Activation
- Pending Acceptance
type: string
subscriptionNumber:
description: Subscription number of the subscription updated.
type: string
type: object
type: array
type: object
PutOrderCancelResponse:
allOf:
- $ref: '#/components/schemas/CommonResponse'
- properties:
accountNumber:
description: The account number for the order.
type: string
cancelReason:
description: The reason for cancelling the order.
type: string
orderNumber:
description: The order number of the order created.
type: string
status:
description: Status of the order. `Cancelled` is only valid value.
enum:
- Cancelled
type: string
type: object
RevertOrderRequest:
example:
orderDate: '2000-01-23'
properties:
orderDate:
description: The order date when order is booked in YYYY-MM-DD format.
format: date
type: string
required:
- orderDate
title: RevertOrderRequest
type: object
RevertOrderResponse:
allOf:
- properties:
accountNumber:
description: The account number for the order.
type: string
orderNumber:
description: The order number of the order created(reverting order).
type: string
subscriptionNumbers:
description: The subscription numbers on which revert is applied.
items:
type: string
type: array
success:
description: Indicates whether the call succeeded.
type: boolean
status:
description: Status of the order. `Completed` is only valid value.
enum:
- Completed
type: string
type: object
PUTOrderActionsRequestType:
example:
changeReason: string
customFields:
PICKLIST_CF__c: option_1
type: object
allOf:
- $ref: '#/components/schemas/OrderActionCommon'
OrderActionCommon:
properties:
changeReason:
description: |
The change reason set for an order action when the order action is updated.
type: string
customFields:
$ref: '#/components/schemas/OrderActionCustomFields'
title: OrderAction
type: object
OrderActionCustomFields:
additionalProperties:
description: |
Custom fields of the Order Action object. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Manage Custom Fields for more information.
description: |
Container for custom fields of an Order Action object.
title: OrderActionCustomFields
type: object
GetOrderLineItemResponseType:
allOf:
- $ref: '#/components/schemas/CommonResponse'
- properties:
orderLineItem:
$ref: '#/components/schemas/OrderLineItem'
type: object
example:
success: true
orderLineItems:
- id: 8a90e4a7932049480193247166783bfe
itemState: Executing
OrderLineItem:
allOf:
- properties:
amount:
description: |
The calculated gross amount for the Order Line Item.
type: number
amountWithoutTax:
description: |
The calculated gross amount for an order line item excluding tax. If the tax mode is tax exclusive, the value of this field equals that of the `amount` field.
If the tax mode of an order line item is not set, the system treats it as tax exclusive by default. The value of the `amountWithoutTax` field equals that of the `amount` field.
If you create an order line item from the product catalog, the tax mode and tax code of the product rate plan charge are used for the order line item by default. You can still overwrite this default set-up by setting the tax mode and tax code of the order line item.
type: number
id:
description: |
The sytem generated Id for the Order Line Item.
format: UUID
type: string
invoiceGroupNumber:
description: |
The number of the invoice group associated with the order line item.
After enabling the Invoice Grouping feature, you can specify invoice group numbers to bill subscriptions and order line items based on specific criteria. For the same account, Zuora generates separate invoices for subscriptions and order line items, each identified by unique invoice group numbers. For more information, see [Invoice Grouping](https://knowledgecenter.zuora.com/Billing/Subscriptions/Invoice_Grouping).
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
maxLength: 255
nullable: true
quantityFulfilled:
description: |
The quantity that has been fulfilled by fulfillments for the order line item. This field will be updated automatically when related fulfillments become 'SentToBilling' or 'Complete' state.
type: number
quantityPendingFulfillment:
description: |
The quantity that needs to be fulfilled by fulfillments for the order line item. This field will be updated automatically when related fulfillments become 'SentToBilling' or 'Complete' state.
type: number
type: object
- $ref: '#/components/schemas/OrderLineItemCommonRetrieveOrderLineItem'
- properties:
fulfillments:
description: |
Container for the fulfillments attached to an order line item.
items:
$ref: '#/components/schemas/FulfillmentGet'
type: array
type: object
OrderLineItemCommonRetrieveOrderLineItem:
properties:
UOM:
description: |
Specifies the units to measure usage.
type: string
accountingCode:
description: |
The accountingCode for the Order Line Item.
type: string
adjustmentLiabilityAccountingCode:
description: |
The accounting code on the Order Line Item object. This field is available in the request body schema only if you have enabled Order to Revenue or Zuora Billing - Revenue Integration feature.
type: string
adjustmentRevenueAccountingCode:
description: |
The accounting code on the Order Line Item object. This field is available in the request body schema only if you have enabled Order to Revenue or Zuora Billing - Revenue Integration feature.
type: string
amendedByOrderOn:
description: |
The date when the rate plan charge is amended through an order or amendment. This field is to standardize the booking date information to increase audit ability and traceability of data between Zuora Billing and Zuora Revenue. It is mapped as the booking date for a sales order line in Zuora Revenue.
format: date
type: string
amountPerUnit:
description: |
The actual charged amount per unit for the Order Line Item.
type: number
billTargetDate:
description: |
The target date for the Order Line Item to be picked up by bill run for billing.
format: date
type: string
billTo:
description: |
The ID of the bill-to contact of an order line item. An existing contact under the billing account is specified as the bill-to contact of the order line item. The billing account is the order account.
type: string
billToSnapshotId:
description: |
The snapshot of the ID for an account used as the bill-to contact of an order line item. This field is used to store the original information about the account, in case the information about the account is changed after the creation of the order line item. The `billToSnapshotId` field is exposed while retrieving the order line item details.
type: string
billingRule:
description: |
The billing rule for the Order Line Item.
enum:
- TriggerWithoutFulfillment
- TriggerAsFulfillmentOccurs
type: string
contractAssetAccountingCode:
description: |
The accounting code on the Order Line Item object. This field is available in the request body schema only if you have enabled Order to Revenue or Zuora Billing - Revenue Integration feature.
type: string
contractLiabilityAccountingCode:
description: |
The accounting code on the Order Line Item object. This field is available in the request body schema only if you have enabled Order to Revenue or Zuora Billing - Revenue Integration feature.
type: string
contractRecognizedRevenueAccountingCode:
description: |
The accounting code on the Order Line Item object. This field is available in the request body schema only if you have enabled Order to Revenue or Zuora Billing - Revenue Integration feature.
type: string
currency:
description: |
The currency for the order line item. You can specify a currency when creating an order line item through the "Create an order" operation.
type: string
customFields:
$ref: '#/components/schemas/OrderLineItemCustomFieldsRetrieveOrderLineItem'
deferredRevenueAccountingCode:
description: |
The deferred revenue accounting code for the Order Line Item.
type: string
description:
description: |
The description of the Order Line Item.
type: string
discount:
description: |
This field shows the total discount amount that is applied to an order line item after the `inlineDiscountType`, `inlineDiscountPerUnit` and `quantity` fields are set.
The inline discount is applied to the list price of an order line item (see the `listPrice` field).
type: number
excludeItemBillingFromRevenueAccounting:
description: |
The flag to exclude Order Line Item related invoice items, invoice item adjustments, credit memo items, and debit memo items from revenue accounting.
**Note**: This field is only available if you have the Order to Revenue or [Zuora Billing - Revenue Integration](https://knowledgecenter.zuora.com/Zuora_Revenue/Zuora_Billing_-_Revenue_Integration) feature enabled.
type: boolean
excludeItemBookingFromRevenueAccounting:
description: |
The flag to exclude Order Line Item from revenue accounting.
**Note**: This field is only available if you have the Order to Revenue or [Zuora Billing - Revenue Integration](https://knowledgecenter.zuora.com/Zuora_Revenue/Zuora_Billing_-_Revenue_Integration) feature enabled.
type: boolean
inlineDiscountPerUnit:
description: |
This field is used in accordance with the `inlineDiscountType` field, in the following manner:
* If the `inlineDiscountType` field is set as `Percentage`, this field specifies the discount percentage for each unit of the order line item. For exmaple, if you specify `5` in this field, the discount percentage is 5%.
* If the `inlineDiscountType` field is set as `FixedAmount`, this field specifies the discount amount on each unit of the order line item. For exmaple, if you specify `10` in this field, the discount amount on each unit of the order line item is 10.
Once you set the `inlineDiscountType`, `inlineDiscountPerUnit`, and `listPricePerUnit` fields, the system will automatically generate the `amountPerUnit` field. You shall not set the `amountPerUnit` field by yourself.
type: number
inlineDiscountType:
description: |
This field is used to specify the inline discount type, which can be `Percentage`, `FixedAmount`, or `None`. The default value is `Percentage`.
This field is used together with the `inlineDiscountPerUnit` field to specify inline discounts for order line items. The inline discount is applied to the list price of an order line item.
Once you set the `inlineDiscountType`, `inlineDiscountPerUnit`, and `listPricePerUnit` fields, the system will automatically generate the `amountPerUnit` field. You shall not set the `amountPerUnit` field by yourself.
enum:
- Percentage
- FixedAmount
- None
type: string
invoiceOwnerAccountId:
description: |
The account ID of the invoice owner of the order line item.
type: string
invoiceOwnerAccountName:
description: |
The account name of the invoice owner of the order line item.
type: string
invoiceOwnerAccountNumber:
description: |
The account number of the invoice owner of the order line item.
type: string
isAllocationEligible:
description: |
This field is used to identify if the charge segment is allocation
eligible in revenue recognition.
**Note**: The field is only available if you have the Order to Revenue feature enabled. To enable this field, submit a request at Zuora Global Support.
type: boolean
isUnbilled:
description: |
This field is used to dictate how to perform the accounting during revenue
recognition.
**Note**: The field is only available if you have the Order to Revenue feature enabled. To enable this field, submit a request at Zuora Global Support.
type: boolean
itemCategory:
default: Sales
description: |
The category for the Order Line Item, to indicate a product sales or return.
enum:
- Sales
- Return
type: string
itemName:
description: |
The name of the Order Line Item.
type: string
itemNumber:
description: |
The number for the Order Line Item.
type: string
itemState:
description: |
The state of the Order Line Item. See [State transitions for an order, order line item, and fulfillment](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Order_Line_Items/AB_Order_Line_Item_States_and_Order_States) for more information.
enum:
- Executing
- Booked
- SentToBilling
- Complete
- Cancelled
type: string
itemType:
description: |
The type of the Order Line Item.
enum:
- Product
- Fee
- Services
type: string
listPrice:
description: |
The extended list price for an order line item, calculated by the formula: listPrice = listPricePerUnit * quantity
type: number
listPricePerUnit:
description: |
The list price per unit for the Order Line Item.
type: number
originalOrderDate:
description: |
The date when the rate plan charge is created through an order or amendment. This field is to standardize the booking date information to increase audit ability and traceability of data between Zuora Billing and Zuora Revenue. It is mapped as the booking date for a sales order line in Zuora Revenue.
format: date
type: string
originalOrderId:
description: |
The ID of the original sales order for a return order line item.
type: string
originalOrderLineItemId:
description: |
The ID of the original sales order line item for a return order line item.
type: string
originalOrderLineItemNumber:
description: |
The number of the original sales order line item for a return order line item.
type: string
originalOrderNumber:
description: |
The number of the original sales order for a return order line item.
type: string
ownerAccountId:
description: |
The account ID of the owner of the order line item.
type: string
ownerAccountName:
description: |
The account name of the owner of the order line item.
type: string
ownerAccountNumber:
description: |
The account number of the owner of the order line item.
type: string
productCode:
description: |
The product code for the Order Line Item.
type: string
productRatePlanChargeId:
description: |
Id of a Product Rate Plan Charge. Only one-time charges are supported.
type: string
purchaseOrderNumber:
description: |
Used by customers to specify the Purchase Order Number provided by the buyer.
type: string
quantity:
description: |
The quantity of units, such as the number of authors in a hosted wiki service.
type: number
quantityAvailableForReturn:
description: |
The quantity that can be returned for an order line item.
type: number
quantityFulfilled:
description: |
The fulfilled quantity for an order line item.
type: number
quantityPendingFulfillment:
description: |
The quantity to fulfill for an order line item.
type: number
recognizedRevenueAccountingCode:
description: |
The recognized revenue accounting code for the Order Line Item.
type: string
relatedSubscriptionNumber:
description: |
Use this field to relate an order line item to an subscription. Specify this field to the subscription number of the subscription to relate.
type: string
requiresFulfillment:
description: |
The flag to show whether fulfillment is needed or not. It's derived from billing rule of the Order Line Item.
type: boolean
revenueRecognitionRule:
description: |
The Revenue Recognition rule for the Order Line Item.
type: string
revenueRecognitionTiming:
description: |
Specifies the type of revenue recognition timing.
Predefined options are listed as enum values in this API Reference. Other options might also be avaliable depending on the revenue recognition policy configuration in the Zuora Billing UI.
**Note**: This field is only available if you have the Order to Revenue feature enabled.
maxLength: 200
type: string
enum:
- Upon Billing Document Posting Date
- Upon Order Activation Date
revenueAmortizationMethod:
description: |
Specifies the type of revenue amortization method.
Predefined options are listed as enum values in this API Reference. Other options might also be avaliable depending on the revenue recognition policy configuration in the Zuora Billing UI.
**Note**: This field is only available if you have the Order to Revenue feature enabled.
maxLength: 200
type: string
enum:
- Immediate
- Ratable Using Start And End Dates
sequenceSetId:
description: |
The ID of the sequence set associated with the OrderLineItem.
type: string
nullable: true
communicationProfileId:
description: |
The ID of the communication profile associated with the subscription.
type: string
nullable: true
shipTo:
description: |
The ID of a contact that belongs to the owner account or billing account of the order line item. Use this field to assign an existing account as the ship-to contact of an order line item.
type: string
shipToSnapshotId:
description: |
The snapshot of the ID for an account used as the ship-to contact of an order line item. This field is used to store the original information about the account, in case the information about the account is changed after the creation of the order line item. The `shipToSnapshotId` field is exposed while retrieving the order line item details.
type: string
soldTo:
description: |
The ID of a contact that belongs to the owner account or billing account of the order line item. Use this field to assign an existing account as the sold-to contact of an order line item.
type: string
soldToSnapshotId:
description: |
The snapshot of the ID for an account used as the sold-to contact of an order line item. This field is used to store the original information about the account, in case the information about the account is changed after the creation of the order line item. The `soldToSnapshotId` field is exposed while retrieving the order line item details.
type: string
taxCode:
description: |
The tax code for the Order Line Item.
type: string
taxMode:
description: |
The tax mode for the Order Line Item.
enum:
- TaxInclusive
- TaxExclusive
type: string
transactionEndDate:
description: |
The date a transaction is completed. The default value of this field is the transaction start date. Also, the value of this field should always equal or be later than the value of the `transactionStartDate` field.
format: date
type: string
transactionStartDate:
description: |
The date a transaction starts. The default value of this field is the order date.
format: date
type: string
unbilledReceivablesAccountingCode:
description: |
The accounting code on the Order Line Item object. This field is available in the request body schema only if you have enabled Order to Revenue or Zuora Billing - Revenue Integration feature.
type: string
title: OrderLineItem
type: object
FulfillmentGet:
allOf:
- properties:
fulfillmentNumber:
description: |
The sytem generated number for the Fulfillment.
type: string
id:
description: |
The sytem generated Id.
format: UUID
type: string
type: object
- $ref: '#/components/schemas/FulfillmentCommon'
FulfillmentCommon:
properties:
billTargetDate:
description: |
The target date for the Fulfillment to be picked up by bill run for billing.
format: date
type: string
carrier:
description: |
The carrier of the Fulfillment. The available values can be configured in **Billing Settings** > **Fulfillment Settings** through Zuora UI.
type: string
customFields:
$ref: '#/components/schemas/FulfillmentCustomFields'
description:
description: |
The description of the Fulfillment.
type: string
excludeItemBillingFromRevenueAccounting:
description: |
The flag to exclude Fulfillment related invoice items, invoice item adjustments, credit memo items, and debit memo items from revenue accounting.
**Note**: This field is only available if you have the Order to Revenue or [Zuora Billing - Revenue Integration](https://knowledgecenter.zuora.com/Zuora_Revenue/Zuora_Billing_-_Revenue_Integration) feature enabled.
type: boolean
excludeItemBookingFromRevenueAccounting:
description: |
The flag to exclude Fulfillment from revenue accounting.
**Note**: This field is only available if you have the Order to Revenue or [Zuora Billing - Revenue Integration](https://knowledgecenter.zuora.com/Zuora_Revenue/Zuora_Billing_-_Revenue_Integration) feature enabled.
type: boolean
externalId:
description: |
The external id of the Fulfillment.
type: string
fulfillmentDate:
description: |
The date of the Fulfillment.
format: date
type: string
fulfillmentLocation:
description: |
The fulfillment location of the Fulfillment. The available values can be configured in **Billing Settings** > **Fulfillment Settings** through Zuora UI.
type: string
fulfillmentSystem:
description: |
The fulfillment system of the Fulfillment. The available values can be configured in **Billing Settings** > **Fulfillment Settings** through Zuora UI.
type: string
fulfillmentType:
description: |
The type of the Fulfillment.
enum:
- Delivery
- Return
type: string
orderLineItemId:
description: |
The reference id of the related Order Line Item.
format: UUID
type: string
quantity:
description: |
The quantity of the Fulfillment.
type: number
state:
description: |
The state of the Fulfillment. See [State transitions for an order, order line item, and fulfillment](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Order_Line_Items/AB_Order_Line_Item_States_and_Order_States) for more information.
enum:
- Executing
- Booked
- SentToBilling
- Complete
- Cancelled
type: string
trackingNumber:
description: |
The tracking number of the Fulfillment.
type: string
title: Fulfillment
type: object
FulfillmentCustomFields:
additionalProperties:
description: |
Custom fields of the Fulfillment object. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
description: |
Container for custom fields of a Fulfillment object.
title: FulfillmentCustomFields
type: object
OrderLineItemCustomFieldsRetrieveOrderLineItem:
additionalProperties:
description: |
Custom fields of the Order Line Item object. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
description: |
Container for custom fields of an Order Line Item object.
title: OrderLineItemCustomFields
type: object
PUTOrderLineItemRequestType:
allOf:
- $ref: '#/components/schemas/PutOrderLineItemUpdateType'
example:
description": Details of the order line item
PutOrderLineItemResponseType:
allOf:
- $ref: '#/components/schemas/CommonResponse'
PutOrderLineItemUpdateType:
allOf:
- $ref: '#/components/schemas/OrderLineItemCommon'
OrderLineItemCommon:
properties:
UOM:
description: |
Specifies the units to measure usage.
You can update this field only for a sales OLI and only when the sales OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
type: string
accountingCode:
description: |
The accountingCode for the Order Line Item (OLI).
You can update this field only for a sales OLI and only when the sales OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
type: string
adjustmentLiabilityAccountingCode:
description: |
The accounting code on the Order Line Item object. This field is available only if you have enabled Order to Revenue or Zuora Billing - Revenue Integration feature.
You can update this field only for a sales OLI and only when the sales OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
type: string
adjustmentRevenueAccountingCode:
description: |
The accounting code on the Order Line Item object. This field is available only if you have enabled Order to Revenue or Zuora Billing - Revenue Integration feature.
You can update this field only for a sales OLI and only when the sales OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
type: string
amountPerUnit:
description: |
The actual charged amount per unit for the Order Line Item (OLI).
You can update this field only for a sales OLI and only when the sales OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
type: number
billTargetDate:
description: |
The target date for the Order Line Item (OLI) to be picked up by bill run for generating billing documents.
To generate billing documents for an OLI, you must set this field and set the `itemState` field to `SentToBilling`.
You can update this field for a sales or return OLI only when the OLI is in the `Executing` or `Booked` state.
format: date
type: string
billTo:
description: |
The ID of the bill-to contact of an order line item. Specify an existing contact under the billing account as the bill-to contact of the order line item. The billing account is the order account.
You can update this field only for a sales OLI and only when the sales OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
type: string
billingRule:
default: TriggerWithoutFulfillment
description: |
The rule for billing of the Order Line Item (OLI).
You can update this field for a sales or return OLI only when it is in the `Executing` state (when the `itemState` field is set as `Executing`).
enum:
- TriggerWithoutFulfillment
- TriggerAsFulfillmentOccurs
type: string
contractAssetAccountingCode:
description: |
The accounting code on the Order Line Item object. This field is available only if you have enabled Order to Revenue or Zuora Billing - Revenue Integration feature.
You can update this field only for a sales OLI and only when the sales OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
type: string
contractLiabilityAccountingCode:
description: |
The accounting code on the Order Line Item object. This field is available only if you have enabled Order to Revenue or Zuora Billing - Revenue Integration feature.
You can update this field only for a sales OLI and only when the sales OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
type: string
contractRecognizedRevenueAccountingCode:
description: |
The accounting code on the Order Line Item object. This field is available only if you have enabled Order to Revenue or Zuora Billing - Revenue Integration feature.
You can update this field only for a sales OLI and only when the sales OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
type: string
customFields:
$ref: '#/components/schemas/OrderLineItemCustomFields'
deferredRevenueAccountingCode:
description: |
The deferred revenue accounting code for the Order Line Item (OLI).
You can update this field only for a sales OLI and only when the sales OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
type: string
description:
description: |
The description of the Order Line Item (OLI).
You can update this field for a sales or return OLI only when the OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
type: string
excludeItemBillingFromRevenueAccounting:
type: boolean
description: |
Indicates whether to exclude the related invoice items, invoice item adjustments, credit memo items, and debit memo items from revenue accounting.
**Note**: This field is only available if you have the Order to Revenue or Billing - Revenue Integration feature enabled.
excludeItemBookingFromRevenueAccounting:
type: boolean
description: |
Indicates whether to exclude the related rate plan charges and order line items from revenue accounting.
**Note**: This field is only available if you have the Order to Revenue or Billing - Revenue Integration feature enabled.
inlineDiscountPerUnit:
description: |
You can update this field only for a sales OLI and only when the sales OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
Use this field in accordance with the `inlineDiscountType` field, in the following manner:
* If the `inlineDiscountType` field is set as `Percentage`, this field specifies the discount percentage for each unit of the order line item. For exmaple, if you specify `5` in this field, the discount percentage is 5%.
* If the `inlineDiscountType` field is set as `FixedAmount`, this field specifies the discount amount on each unit of the order line item. For exmaple, if you specify `10` in this field, the discount amount on each unit of the order line item is 10.
Once you set the `inlineDiscountType`, `inlineDiscountPerUnit`, and `listPricePerUnit` fields, the system will automatically generate the `amountPerUnit` field. You shall not set the `amountPerUnit` field by yourself.
type: number
inlineDiscountType:
description: |
You can update this field only for a sales OLI and only when the sales OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
Use this field to specify the inline discount type, which can be `Percentage`, `FixedAmount`, or `None`. The default value is `Percentage`.
Use this field together with the `inlineDiscountPerUnit` field to specify inline discounts for order line items. The inline discount is applied to the list price of an order line item.
Once you set the `inlineDiscountType`, `inlineDiscountPerUnit`, and `listPricePerUnit` fields, the system will automatically generate the `amountPerUnit` field. You shall not set the `amountPerUnit` field by yourself.
enum:
- Percentage
- FixedAmount
- None
type: string
isAllocationEligible:
description: |
This field is used to identify if the charge segment is allocation
eligible in revenue recognition.
**Note**: The field is only available if you have the Order to Revenue feature enabled. To enable this field, submit a request at Zuora Global Support.
type: boolean
isUnbilled:
description: |
This field is used to dictate how to perform the accounting during revenue
recognition.
**Note**: The field is only available if you have the Order to Revenue feature enabled. To enable this field, submit a request at Zuora Global Support.
type: boolean
itemName:
description: |
The name of the Order Line Item (OLI).
You can update this field for a sales or return OLI only when the OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
type: string
itemState:
description: |
The state of the Order Line Item (OLI). See [State transitions for an order, order line item, and fulfillment](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Order_Line_Items/AB_Order_Line_Item_States_and_Order_States) for more information.
To generate invoice for an OLI, you must set this field to `SentToBilling` and set the `billTargetDate` field .
You can update this field for a sales or return OLI only when the OLI is in the `Executing` or 'Booked' or `SentToBilling`state (when the `itemState` field is set as `Executing` or `SentToBilling`).
enum:
- Executing
- Booked
- SentToBilling
- Complete
- Canceled
type: string
itemType:
description: |
The type of the Order Line Item (OLI).
You can update this field only for a sales OLI and only when the sales OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
enum:
- Product
- Fee
- Services
type: string
listPricePerUnit:
description: |
The list price per unit for the Order Line Item (OLI).
You can update this field only for a sales OLI and only when the sales OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
type: number
ownerAccountNumber:
description: |
Use this field to assign an existing account as the owner of an order line item.
You can update this field only for a sales OLI and only when the sales OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
type: string
productCode:
description: |
The product code for the Order Line Item (OLI).
You can update this field only for a sales OLI and only when the sales OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
type: string
purchaseOrderNumber:
description: |
Used by customers to specify the Purchase Order Number provided by the buyer.
You can update this field only for a sales OLI and only when the sales OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
type: string
quantity:
description: |
The quantity of units, such as the number of authors in a hosted wiki service.
You can update this field for a sales or return OLI only when the OLI in the `Executing` state (when the `itemState` field is set as `Executing`).
type: number
recognizedRevenueAccountingCode:
description: |
The recognized revenue accounting code for the Order Line Item (OLI).
You can update this field only for a sales OLI and only when the sales OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
type: string
relatedSubscriptionNumber:
description: |
Use this field to relate an order line item to an subscription. Specify this field to the subscription number of the subscription to relate.
You can update this field only for a sales OLI and only when the sales OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
type: string
revenueRecognitionRule:
description: |
The Revenue Recognition rule for the Order Line Item (OLI).
You can update this field only for a sales OLI and only when the sales OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
type: string
revenueRecognitionTiming:
description: |
Specifies the type of revenue recognition timing.
Predefined options are listed as enum values in this API Reference. Other options might also be avaliable depending on the revenue recognition policy configuration in the Zuora Billing UI.
You can update this field only for a sales OLI and only when the sales OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
**Note**: This field is only available if you have the Order to Revenue feature enabled.
maxLength: 200
type: string
enum:
- Upon Billing Document Posting Date
- Upon Order Activation Date
revenueAmortizationMethod:
description: |
Specifies the type of revenue amortization method.
Predefined options are listed as enum values in this API Reference. Other options might also be avaliable depending on the revenue recognition policy configuration in the Zuora Billing UI.
You can update this field only for a sales OLI and only when the sales OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
**Note**: This field is only available if you have the Order to Revenue feature enabled.
maxLength: 200
type: string
enum:
- Immediate
- Ratable Using Start And End Dates
invoiceGroupNumber:
description: |
The number of the invoice group associated with the order line item.
After enabling the Invoice Grouping feature, you can specify invoice group numbers to bill subscriptions and order line items based on specific criteria. For the same account, Zuora generates separate invoices for subscriptions and order line items, each identified by unique invoice group numbers. For more information, see [Invoice Grouping](https://knowledgecenter.zuora.com/Billing/Subscriptions/Invoice_Grouping).
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request during subscription creation, the value of this field is automatically set to `null` in the response body.
- You can specify this field on a sales order line item when its state (that is, the `itemState` field) is `Executing`, `Booked`, or `SentToBilling`.
type: string
maxLength: 255
nullable: true
sequenceSetId:
description: |
The ID or number of the sequence set associated with the order line item.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request during subscription creation, the value of this field is automatically set to `null` in the response body.
- You can specify this field on a sales order line item when its state (that is, the `itemState` field) is `Executing`, `Booked`, or `SentToBilling`.
type: string
paymentTerm:
description: |
The payment term name associated with the order line item.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request during subscription creation, the value of this field is automatically set to `null` in the response body.
- You can specify this field on a sales order line item when its state (that is, the `itemState` field) is `Executing`, `Booked`, or `SentToBilling`.
type: string
invoiceTemplateId:
description: |
The ID of the invoice template associated with the order line item.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request during subscription creation, the value of this field is automatically set to `null` in the response body.
- You can specify this field on a sales order line item when its state (that is, the `itemState` field) is `Executing`, `Booked`, or `SentToBilling`.
type: string
shipTo:
description: |
Use this field to assign an existing account as the ship-to contact of an order line item, by the following rules:
* If the `ownerAccountNumber` field is set, then this field must be the ID of a contact that belongs to the owner account of the order line item.
* If the `ownerAccountNumber` field is not set, then this field must be the ID of a contact that belongs to the billing account of the order line item. The billing account is the order account.
You can update this field only for a sales OLI and only when the sales OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
type: string
soldTo:
description: |
Use this field to assign an existing account as the sold-to contact of an order line item, by the following rules:
* If the `ownerAccountNumber` field is set, then this field must be the ID of a contact that belongs to the owner account of the order line item.
* If the `ownerAccountNumber` field is not set, then this field must be the ID of a contact that belongs to the billing account of the order line item. The billing account is the order account.
You can update this field only for a sales OLI and only when the sales OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
type: string
taxCode:
description: |
The tax code for the Order Line Item (OLI).
You can update this field only for a sales OLI and only when the sales OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
type: string
taxMode:
description: |
The tax mode for the Order Line Item (OLI).
You can update this field only for a sales OLI and only when the sales OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
enum:
- TaxInclusive
- TaxExclusive
type: string
transactionEndDate:
description: |
The date a transaction is completed. The default value of this field is the transaction start date. Also, the value of this field should always equal or be later than the value of the `transactionStartDate` field.
You can update this field for a sales or return OLI only when the OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
format: date
type: string
transactionStartDate:
description: |
The date a transaction starts. The default value of this field is the order date.
You can update this field for a sales or return OLI only when the OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
format: date
type: string
unbilledReceivablesAccountingCode:
description: |
The accounting code on the Order Line Item object. This field is available only if you have enabled Order to Revenue or Zuora Billing - Revenue Integration feature.
You can update this field only for a sales OLI and only when the sales OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
type: string
title: OrderLineItem
type: object
PostOrderLineItemsRequestType:
example:
orderLineItems:
- id: 8a90e4a7932049480193247166783bfe
description: Details of the order line item
properties:
orderLineItems:
items:
$ref: '#/components/schemas/PostOrderLineItemUpdateType'
type: array
processingOptions:
$ref: '#/components/schemas/ProcessingOptions'
type: object
PostOrderLineItemUpdateType:
allOf:
- properties:
id:
description: |
The sytem generated Id for the Order Line Item(OLI). Use this field to specify which OLI to update.
format: UUID
type: string
required:
- id
type: object
- $ref: '#/components/schemas/OrderLineItemCommon'
ProcessingOptions:
description: Processing options for generating billing documents.
properties:
billingOptions:
$ref: '#/components/schemas/BillingOptions'
runBilling:
description: Indicates if the current request needs to generate a billing document. The billing document will be generated against all Order Line Items included in this order.
type: boolean
type: object
BillingOptions:
properties:
documentDate:
description: The invoice date displayed on the billing document.
format: date
type: string
targetDate:
description: Date through which to calculate charges for order line items if a billing document is generated. See [What is a Target Date?](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/G_Bill_Runs/Creating_Bill_Runs#What_is_a_Target_Date.3F).
format: date
type: string
type: object
PostFulfillmentsRequestType:
example:
fulfillments:
- billTargetDate: '2022-01-01'
fulfillmentDate: '2022-01-01'
fulfillmentType: Delivery
orderLineItemId: 4028828c82819b740182821bb23e15c4
quantity: 5
state: SentToBilling
- billTargetDate: '2022-01-01'
fulfillmentDate: '2022-01-01'
fulfillmentType: Delivery
orderLineItemId: 4028828c82819b740182821bb23e15c4
quantity: 5
state: SentToBilling
processingOptions:
billingOptions:
documentDate: '2022-01-01'
targetDate: '2022-01-01'
collectPayment: true
runBilling: true
properties:
fulfillments:
items:
$ref: '#/components/schemas/FulfillmentPost'
type: array
processingOptions:
$ref: '#/components/schemas/ProcessingOptions'
type: object
PostFulfillmentsResponseType:
allOf:
- $ref: '#/components/schemas/CommonResponse'
- properties:
creditMemoNumbers:
description: |
An array of the credit memo numbers generated in this request. The credit memo is only available if you have the Invoice Settlement feature enabled.
items:
type: string
type: array
fulfillments:
items:
properties:
fulfillmentItems:
items:
properties:
id:
description: |
The sytem generated Id.
format: UUID
type: string
type: object
type: array
fulfillmentNumber:
description: |
The sytem generated number for the Fulfillment.
type: string
id:
description: |
The sytem generated Id.
format: UUID
type: string
type: object
type: array
invoiceNumbers:
description: |
An array of the invoice numbers generated in this request. Normally it includes one invoice number only.
items:
type: string
type: array
paidAmount:
description: |
The total amount collected in this request.
type: number
paymentNumber:
description: |
The payment number collected in this request.
type: string
type: object
FulfillmentPost:
allOf:
- properties:
orderLineItemId:
description: |
The reference id of the related Order Line Item.
format: UUID
type: string
type: object
- $ref: '#/components/schemas/FulfillmentCommon'
- properties:
fulfillmentItems:
items:
$ref: '#/components/schemas/FulfillmentItemPostFromFulfillmentPost'
type: array
type: object
FulfillmentItemPostFromFulfillmentPost:
allOf:
- $ref: '#/components/schemas/FulfillmentItemCommon'
FulfillmentItemCommon:
properties:
customFields:
$ref: '#/components/schemas/FulfillmentItemCustomFields'
description:
description: |
The description of the Fulfillment Item.
type: string
itemIdentifier:
description: |
The external identifier of the Fulfillment Item.
type: string
title: FulfillmentItem
type: object
FulfillmentItemCustomFields:
additionalProperties:
description: |
Custom fields of the Fulfillment Item object. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
description: |
Container for custom fields of a Fulfillment Item object.
title: FulfillmentItemCustomFields
type: object
GetFulfillmentResponseType:
allOf:
- $ref: '#/components/schemas/CommonResponse'
- properties:
fulfillment:
$ref: '#/components/schemas/FulfillmentGet'
type: object
PutFulfillmentRequestType:
example:
billTargetDate: '2022-01-01'
fulfillmentDate: '2022-01-01'
fulfillmentType: Delivery
quantity: 5
state: SentToBilling
properties:
billTargetDate:
description: |
The target date for the Fulfillment to be picked up by bill run for billing.
format: date
type: string
carrier:
description: |
The carrier of the Fulfillment. The available values can be managed in the Fulfillment Settings page under Billing Settings.
type: string
customFields:
$ref: '#/components/schemas/FulfillmentCustomFields'
description:
description: |
The description of the Fulfillment.
type: string
externalId:
description: |
The external id of the Fulfillment.
type: string
fulfillmentDate:
description: |
The date of the Fulfillment.
format: date
type: string
fulfillmentLocation:
description: |
The fulfillment location of the Fulfillment. The available values can be managed in the Fulfillment Settings page under Billing Settings.
type: string
fulfillmentSystem:
description: |
The fulfillment system of the Fulfillment. The available values can be managed in the Fulfillment Settings page under Billing Settings.
type: string
quantity:
description: |
The quantity of the Fulfillment.
type: number
state:
description: |
The state of the Fulfillment. See [Order Line Item states, Order states, and state transitions](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Order_Line_Items/AB_Order_Line_Item_States_and_Order_States) for more information.
enum:
- Executing
- Booked
- SentToBilling
- Complete
- Cancelled
type: string
trackingNumber:
description: |
The tracking number of the Fulfillment.
type: string
type: object
PostFulfillmentItemsRequestType:
example:
fulfillmentItems:
- customFields:
PICKLIST_CF__c: option_1
description: description1
fulfillmentNumber: F-00000001
itemIdentifier: 0c27b769-5bba-46a5-80aa-cdd95f931216
- customFields:
PICKLIST_CF__c: option_2
description: description2
fulfillmentNumber: F-00000001
itemIdentifier: 456d3812-33d2-454c-b272-4c5a9a3e2742
properties:
fulfillmentItems:
items:
$ref: '#/components/schemas/FulfillmentItemPost'
type: array
type: object
PostFulfillmentItemsResponseType:
allOf:
- $ref: '#/components/schemas/CommonResponse'
- properties:
fulfillmentItems:
items:
properties:
id:
description: |
The sytem generated Id.
format: UUID
type: string
type: object
type: array
type: object
FulfillmentItemPost:
allOf:
- properties:
fulfillmentNumber:
description: |
The reference of the related Fulfillment.
type: string
type: object
- $ref: '#/components/schemas/FulfillmentItemCommon'
GetFulfillmentItemResponseType:
allOf:
- $ref: '#/components/schemas/CommonResponse'
- properties:
fulfillmentItem:
$ref: '#/components/schemas/FulfillmentItemGet'
type: object
FulfillmentItemGet:
allOf:
- properties:
fulfillmentId:
description: |
The reference id of the related Fulfillment.
format: UUID
type: string
id:
description: |
The sytem generated Id.
format: UUID
type: string
type: object
- $ref: '#/components/schemas/FulfillmentItemCommon'
PutFulfillmentItemRequestType:
example:
customFields:
PICKLIST_CF__c: option_1
description: description1
itemIdentifier: 0c27b769-5bba-46a5-80aa-cdd95f931216
properties:
customFields:
$ref: '#/components/schemas/FulfillmentItemCustomFields'
description:
description: |
The description of the Fulfillment Item.
type: string
itemIdentifier:
description: |
The external identifier of the Fulfillment Item.
type: string
type: object
GETRampByRampNumberResponseType:
allOf:
- properties:
ramp:
$ref: '#/components/schemas/RampResponse'
type: object
- $ref: '#/components/schemas/CommonResponse'
GETRampMetricsByRampNumberResponseType:
allOf:
- properties:
rampMetrics:
$ref: '#/components/schemas/RampMetrics'
type: object
- $ref: '#/components/schemas/CommonResponse'
RampMetrics:
properties:
description:
description: The short description of the ramp.
type: string
discountTcb:
description: The discount amount for the TCB.
type: number
discountTcv:
description: The discount amount for the TCV.
type: number
grossTcb:
description: The gross TCB value before discount charges are applied.
type: number
grossTcv:
description: The gross TCV value before discount charges are applied.
type: number
intervals:
description: Container for the intervals that the ramp is split into in its timeline.
items:
$ref: '#/components/schemas/RampIntervalMetrics'
type: array
name:
description: The name of the ramp.
type: string
netTcb:
description: The net TCB value after discount charges are applied.
type: number
netTcv:
description: The net TCV value after discount charges are applied.
type: number
number:
description: The number of the ramp. It is automaticcally generated by the billing system.
type: string
type: object
RampIntervalMetrics:
properties:
description:
description: The short description of the interval.
type: string
discountTcb:
description: The discount amount for the TCB.
type: number
discountTcv:
description: The discount amount for the TCV.
type: number
endDate:
description: The end date of the interval.
format: date
type: string
grossTcb:
description: The gross TCB value before discount charges are applied.
type: number
grossTcv:
description: The gross TCV value before discount charges are applied.
type: number
intervalMetrics:
description: Container for the detailed metrics for each rate plan charge in each ramp interval.
items:
$ref: '#/components/schemas/RampIntervalChargeMetrics'
type: array
name:
description: The name of the interval.
type: string
netTcb:
description: The net TCB value after discount charges are applied.
type: number
netTcv:
description: The net TCV value after discount charges are applied.
type: number
startDate:
description: The start date of the interval.
format: date
type: string
type: object
GETRampsBySubscriptionKeyResponseType:
allOf:
- properties:
ramps:
items:
$ref: '#/components/schemas/RampResponse'
type: array
type: object
- $ref: '#/components/schemas/CommonResponse'
GETRampMetricsBySubscriptionKeyResponseType:
allOf:
- properties:
rampMetrics:
$ref: '#/components/schemas/RampMetrics'
type: object
- $ref: '#/components/schemas/CommonResponse'
GETRampMetricsByOrderNumberResponseType:
allOf:
- properties:
rampMetrics:
items:
$ref: '#/components/schemas/OrderRampMetrics'
type: array
type: object
- $ref: '#/components/schemas/CommonResponse'
POSTSubscriptionPreviewType:
allOf:
- properties:
accountKey:
description: |
Customer account number or ID.
You must specify the account information either in this field or in the `previewAccountInfo` field with the following conditions:
* If you already have a customer account, specify the account number or ID in this field.
* If you do not have a customer account, provide account information in the `previewAccountInfo` field.
type: string
contractEffectiveDate:
description: |
Effective contract date for this subscription, as yyyy-mm-dd.
format: date
type: string
customerAcceptanceDate:
description: |
The date on which the services or products within a subscription have been accepted by the customer, as yyyy-mm-dd.
Default value is dependent on the value of other fields. See **Notes** section for more details.
format: date
type: string
documentDate:
description: |
The date of the billing document, in `yyyy-mm-dd` format. It represents the invoice date for invoices, credit memo date for credit memos, and debit memo date for debit memos.
- If this field is specified, the specified date is used as the billing document date.
- If this field is not specified, the date specified in the `targetDate` is used as the billing document date.
format: date
type: string
includeExistingDraftDocItems:
description: |
Specifies whether to include draft invoice items in subscription previews.
Values are:
* `true` (default). Includes draft invoice items in the preview result.
* `false`. Excludes draft invoice items in the preview result.
**Note**: This field is available only if you are on the latest Zuora API minor version, or you set the `Zuora-Version` request header to `207.0` or [a later available version](https://developer.zuora.com/v1-api-reference/api-versions/#minor-version).
type: boolean
initialTerm:
description: |
Duration of the first term of the subscription, in whole months. If `termType` is `TERMED`, then this field is required, and the value must be greater than `0`. If `termType` is `EVERGREEN`, this field is ignored.
format: int64
type: integer
initialTermPeriodType:
description: |+
The period type of the initial term.
Supported values are:
* `Month`
* `Year`
* `Day`
* `Week`
The default period type is `Month`.
type: string
invoiceOwnerAccountKey:
description: |
Invoice owner account number or ID.
**Note:** This feature is in **Limited Availability**. If you wish to have access to the feature, submit a request at [Zuora Global Support](http://support.zuora.com/).
type: string
notes:
description: The notes for the subscription.
maxLength: 1000
type: string
previewAccountInfo:
$ref: '#/components/schemas/POSTSubscriptionPreviewTypePreviewAccountInfo'
previewType:
description: |
The type of preview you will receive.
**Note**: If your API minor version is earlier than `206.0` or you specify the `Zuora-Version` header for this request to `206.0` or earlier, the following values are supported for the `previewType` field:
- `InvoiceItem` (default)
- `ChargeMetrics`
- `InvoiceItemChargeMetrics`
enum:
- LegalDoc
- ChargeMetrics
- LegalDocChargeMetrics
type: string
default: LegalDoc
serviceActivationDate:
description: |
The date on which the services or products within a subscription have been activated and access has been provided to the customer, as yyyy-mm-dd.
Default value is dependent on the value of other fields. See **Notes** section for more details.
format: date
type: string
subscribeToRatePlans:
description: |
Container for one or more rate plans for this subscription.
items:
$ref: '#/components/schemas/POSTSrpCreateType'
type: array
targetDate:
description: |
Date through which to calculate charges if an invoice is generated, as yyyy-mm-dd. Default is current date.
**Note:** This field is only available if you are on the latest Zuora API minor version, or you set the `Zuora-Version` request header to `207.0` or [a later available version](https://developer.zuora.com/v1-api-reference/api-versions/#minor-version).
format: date
type: string
termStartDate:
description: |
The date on which the subscription term begins, as yyyy-mm-dd. If this is a renewal subscription, this date is different from the subscription start date.
format: date
type: string
termType:
description: |
Possible values are: `TERMED`, `EVERGREEN`.
type: string
required:
- termType
- contractEffectiveDate
- subscribeToRatePlans
type: object
- $ref: '#/components/schemas/SubscriptionObjectCustomFields'
example:
accountKey: 8ad09be48db5aba7018db604776d4854
contractEffectiveDate: '2024-07-01'
termType: TERMED
initialTerm: 12
subscribeToRatePlans:
- productRatePlanId: 8ad081dd9096ef9501909b40bb4e74a4
POSTSubscriptionPreviewResponseType:
properties:
chargeMetrics:
description: |
Container for charge metrics.
properties:
dmrr:
description: |
Change in monthly recurring revenue.
type: string
dtcv:
description: |
Change in total contract value.
type: string
mrr:
description: |
Monthly recurring revenue.
type: string
number:
description: |
The charge number of the subscription. Only available for update subscription.
type: string
originRatePlanId:
description: |
The origin rate plan ID. Only available for update subscription.
type: string
originalId:
description: |
The original rate plan charge ID. Only available for update subscription.
type: string
productRatePlanChargeId:
description: |
The product rate plan charge ID.
type: string
productRatePlanId:
description: |
The product rate plan ID.
type: string
tcv:
description: |
Total contract value.
type: string
type: object
contractedMrr:
description: |
Monthly recurring revenue of the subscription.
type: number
creditMemo:
description: |
Container for credit memos.
**Note:** This container is only available if you are on the latest Zuora API version or you set the `Zuora-Version` request header to `207.0` or [a later available version](https://developer.zuora.com/v1-api-reference/api-versions/#minor-version), and you have [Invoice Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement) 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.
properties:
amount:
description: Credit memo amount.
format: double
type: number
amountWithoutTax:
description: Credit memo amount minus tax.
format: double
type: number
creditMemoItems:
description: ''
items:
$ref: '#/components/schemas/POSTSubscriptionPreviewCreditMemoItemsType'
type: array
taxAmount:
description: Tax amount on the credit memo.
format: double
type: number
type: object
documentDate:
description: |
The date of the billing document, in `yyyy-mm-dd` format. It represents the invoice date for invoices, credit memo date for credit memos, and debit memo date for debit memos.
- If this field is specified, the specified date is used as the billing document date.
- If this field is not specified, the date specified in the `targetDate` is used as the billing document date.
format: date
type: string
invoice:
description: |
Container for invoices.
**Note:** This field is only available if you set the Zuora REST API minor version to `207.0` or [a later available version](https://developer.zuora.com/v1-api-reference/api-versions/#minor-version) in the request header. Also, the response structure is changed and the following invoice related response fields are moved to this **invoice** container:
* amount
* amountWithoutTax
* taxAmount
* invoiceItems
properties:
amount:
description: Invoice amount.
type: number
amountWithoutTax:
description: |
Invoice amount minus tax.
type: number
invoiceItems:
description: |
Container for invoice items.
items:
$ref: '#/components/schemas/POSTSubscriptionPreviewInvoiceItemsType'
type: array
targetDate:
description: |
Date through which to calculate charges if an invoice is generated, as yyyy-mm-dd. Default is current date.
**Note:** This field is only available if you set the Zuora REST API minor version to 207.0 or later [available versions](https://developer.zuora.com/api-references/api/overview/#section/API-Versions/Minor-Version) in the request header.
type: string
taxAmount:
description: |
The tax amount of the invoice.
type: number
type: object
success:
description: |
Returns `true` if the request was processed successfully.
type: boolean
targetDate:
description: |
Date through which to calculate charges if an invoice is generated, as yyyy-mm-dd. Default is current date.
**Note:** This field is only available if you set the Zuora REST API minor version to `207.0` or [a later available version](https://developer.zuora.com/v1-api-reference/api-versions/#minor-version) in the request header.
format: date
type: string
taxAmount:
description: |
Tax amount on the invoice.
type: number
totalContractedValue:
description: |
Total contracted value of the subscription.
type: number
type: object
POSTSubscriptionPreviewCreditMemoItemsType:
properties:
amountWithoutTax:
description: |
The credit memo item amount excluding tax.
format: double
type: number
chargeAmount:
description: |
The amount of the credit memo item. For tax-inclusive credit memo items, the amount indicates the credit memo item amount including tax. For tax-exclusive credit memo items, the amount indicates the credit memo item amount excluding tax
format: double
type: number
chargeDescription:
description: |
Description of this credit memo item.
type: string
chargeName:
description: |
Name of this credit memo item.
type: string
productName:
description: |
Name of the product associated with this credit memo item.
type: string
productRatePlanChargeId:
description: |
ID of the product rate plan charge associated with this credit memo item.
type: string
quantity:
description: |
Quantity of the charge associated with this credit memo item.
type: integer
serviceEndDate:
description: |
End date of the service period for this credit memo item, as yyyy-mm-dd.
format: date
type: string
serviceStartDate:
description: |
Service start date of this credit memo item, as yyyy-mm-dd.
format: date
type: string
taxAmount:
description: |
The tax amount of the credit memo item.
format: double
type: number
taxationItems:
description: |-
List of taxation items.
**Note**: This field is available only if you are on the latest Zuora API version, or you set the `Zuora-Version` request header to `315.0` or [a later available version](https://developer.zuora.com/v1-api-reference/api-versions/#minor-version).
items:
$ref: '#/components/schemas/POSTSubscriptionPreviewTaxationItemsType'
type: array
unitOfMeasure:
description: Unit used to measure consumption.
type: string
title: creditMemoItems
type: object
POSTSubscriptionPreviewInvoiceItemsType:
properties:
chargeAmount:
description: |
The amount of the charge. This amount doesn't include taxes unless the charge's tax mode is inclusive.
type: number
chargeDescription:
description: |
Description of the charge.
type: string
chargeName:
description: |
Name of the charge.
type: string
productName:
description: |
Name of the product associated with this item.
type: string
productRatePlanChargeId:
description: |
ID of the product rate plan charge.
type: string
quantity:
description: |
Quantity of this item.
type: number
serviceEndDate:
description: |
End date of the service period for this item, i.e., the last day of the period, as yyyy-mm-dd.
format: date
type: string
serviceStartDate:
description: |
Service start date as yyyy-mm-dd. If the charge is a one-time fee, this is the date of that charge.
format: date
type: string
taxAmount:
description: |
The tax amount of the invoice item.
format: double
type: number
taxationItems:
description: |-
List of taxation items.
**Note**: This field is available only if you are on the latest Zuora API version, or you set the `Zuora-Version` request header to `315.0` or [a later available version](https://developer.zuora.com/v1-api-reference/api-versions/#minor-version).
items:
$ref: '#/components/schemas/POSTSubscriptionPreviewTaxationItemsType'
type: array
unitOfMeasure:
description: ''
type: string
title: invoiceItems
type: object
POSTSubscriptionPreviewTaxationItemsType:
properties:
exemptAmount:
description: |
The calculated tax amount excluded due to the exemption.
type: number
jurisdiction:
description: |
The jurisdiction that applies the tax or VAT. This value is typically a state, province, county, or city.
type: string
locationCode:
description: |
The identifier for the location based on the value of the taxCode field.
type: string
name:
description: |
The name of the taxation item.
type: string
taxAmount:
description: |
The tax amount of the invoice item.
format: double
type: number
taxCode:
description: |
The tax code identifies which tax rules and tax rates to apply to a specific invoice.
type: string
taxCodeDescription:
description: |
The description of the tax code.
type: string
taxDate:
description: |
The date when the tax is applied to the invoice.
type: string
taxRate:
description: 'The tax rate applied to the invoice. '
type: number
taxRateDescription:
description: |
The description of the tax rate.
type: string
taxRateType:
description: |
Enum:"Percentage" "FlatFee". The type of the tax rate applied to the invoice.
enum:
- Percentage
- FlatFee
type: string
title: taxationItems
type: object
POSTSubscriptionPreviewTypePreviewAccountInfo:
allOf:
- properties:
billCycleDay:
description: |
The account's bill cycle day (BCD), when bill runs generate invoices for the account. Specify any day of the month (`1`-`31`, where `31` = end-of-month), or `0` for auto-set.
format: int64
type: integer
billToContact:
description: |
Container for bill-to contact information of this account.
properties:
city:
description: |
The city of the bill-to address. The value should be 40 characters or less.
type: string
country:
description: |
The country of the bill-to address. The value must be a valid country name or abbreviation.
**Note:** You must specify this field if you are using Zuora Tax for this account.
type: string
county:
description: |
The county of the bill-to address. The value should be 32 characters or less.
type: string
state:
description: |
The state of the bill-to address. The value must be a valid subregion (state or province) name or code. For more information, see View subregions of a specific country or region.
**Note:** You must specify this field if you are using Zuora Tax for this account and the country is `USA` or `Canada`.
type: string
taxRegion:
description: |
If using Zuora Tax, a region string as optionally defined in your tax rules.
type: string
nullable: true
zipCode:
description: |
The zip code of the bill-to address. The value should be 20 characters or less.
type: string
type: object
currency:
description: |
A currency as defined in Billing Settings.
type: string
required:
- billCycleDay
- billToContact
- currency
type: object
- $ref: '#/components/schemas/AccountObjectNSFields'
- $ref: '#/components/schemas/AccountObjectCustomFields'
description: |
A container for providing a customer account information if you do not have an existing customer account. This customer account information is only used for subscription preview.
You must specify the account information either in this field or in the `accountKey` field with the following conditions:
* If you already have a customer account, specify the account number or ID in the accountKey field.
* If you do not have a customer account, provide account information in this field.
title: previewAccountInfo
PreviewExistingSubscriptionRequest:
description: |
Preview the existing subscription by subscription ID or number.
properties:
previewStartDate:
$ref: '#/components/schemas/PreviewStartDate'
previewThroughDate:
$ref: '#/components/schemas/PreviewThroughDate'
quantityForUsageCharges:
items:
$ref: '#/components/schemas/QuantityForUsageCharges'
type: array
description: |
Container for usage charges.
type: object
example:
previewStartDate:
previewStartDatePolicy: specificDate
specificDate: '2024-01-01'
previewThroughDate:
previewThruDatePolicy: nextBillingPeriods
nextBillingPeriods: '2'
quantityForUsageCharges:
- chargeId: 402880e78ccd1743018cce026efb002d
quantity: 20
PreviewExistingSubscriptionResponse:
allOf:
- $ref: '#/components/schemas/CommonResponse'
- properties:
invoices:
description: Container for invoices.
items:
$ref: '#/components/schemas/PreviewExistingSubscriptionResultInvoices'
type: array
creditMemos:
description: |
Container for credit memos.
**Note**: This field is only available if you have the Invoice Settlement feature enabled.
items:
$ref: '#/components/schemas/PreviewExistingSubscriptionResultCreditMemos'
type: array
type: object
PreviewExistingSubscriptionResultInvoices:
properties:
invoiceNumber:
type: string
description: |
The invoice number.
amount:
type: number
description: |
Invoice amount.
format: double
amountWithoutTax:
type: number
description: |
Invoice amount minus tax.
format: double
taxAmount:
type: number
description: |
The tax amount of the invoice.
format: double
targetDate:
format: date
type: string
description: |
Date through which to calculate charges if an invoice is generated, as yyyy-mm-dd.
invoiceItems:
items:
$ref: '#/components/schemas/PreviewExistingSubscriptionInvoiceItemResult'
type: array
description: |
The container for invoice items.
status:
type: string
description: |
The status of the invoice.
enum:
- Draft
- Posted
- null
nullable: true
isFromExistingInvoice:
type: boolean
description: |
Indicates whether the invoice information is from an existing invoice.
type: object
PreviewExistingSubscriptionResultCreditMemos:
properties:
creditMemoNumber:
type: string
description: The credit memo number.
amount:
type: number
description: Credit memo amount.
format: double
amountWithoutTax:
type: number
description: Credit memo amount minus tax.
format: double
taxAmount:
type: number
description: The tax amount of the credit memo.
format: double
targetDate:
format: date
type: string
description: Date through which to calculate charges if a credit memo is generated, as yyyy-mm-dd.
creditMemoItems:
items:
$ref: '#/components/schemas/PreviewExistingSubscriptionCreditMemoItemResult'
type: array
description: Container for credit memo items.
status:
type: string
description: The status of the credit memo.
nullable: true
isFromExistingCreditMemo:
type: boolean
description: Indicates whether the credit memo information is from an existing credit memo.
type: object
PreviewExistingSubscriptionCreditMemoItemResult:
properties:
serviceStartDate:
format: date
type: string
description: Service start date as yyyy-mm-dd. If the charge is a one-time fee, this is the date of that charge.
serviceEndDate:
format: date
type: string
description: End date of the service period for this item, i.e., the last day of the period, as yyyy-mm-dd.
amountWithoutTax:
type: number
description: Credit memo amount minus tax.
format: double
taxAmount:
type: number
description: The tax amount of the credit memo item.
format: double
chargeDescription:
type: string
description: Description of the charge.
chargeName:
type: string
description: Name of the charge.
chargeNumber:
description: Available when the `chargeNumber` field was specified in the request or when the order is amending an existing subscription.
type: string
productName:
type: string
description: Name of the product.
productRatePlanChargeId:
type: string
description: The ID of the product rate plan charge.
processingType:
type: string
description: The processing type of the credit memo item.
enum:
- Charge
- Discount
- Tax
unitPrice:
type: number
description: The unit price of the charge.
format: double
quantity:
type: number
description: The quantity of the charge.
unitOfMeasure:
type: string
description: The unit of measure of the charge.
nullable: true
discountDetails:
items:
$ref: '#/components/schemas/PreviewExistingSubscriptionDiscountDetails'
type: array
description: Container for discount details.
type: object
PreviewExistingSubscriptionDiscountDetails:
properties:
discountChargeName:
type: string
description: The charge name of the discount.
discountChargeNumber:
type: string
description: The charge number of the discount.
discountRate:
type: number
description: The discount rate.
serviceStartDate:
format: date
type: string
description: Start date of the service period for this discount charge.
serviceEndDate:
format: date
type: string
description: End date of the service period for this discount charge.
type: object
PreviewExistingSubscriptionInvoiceItemResult:
properties:
serviceStartDate:
format: date
type: string
description: Service start date as yyyy-mm-dd. If the charge is a one-time fee, this is the date of that charge.
serviceEndDate:
format: date
type: string
description: End date of the service period for this item, i.e., the last day of the period, as yyyy-mm-dd.
amountWithoutTax:
type: number
description: Invoice amount minus tax.
format: double
taxAmount:
type: number
description: The tax amount of the invoice item.
format: double
chargeDescription:
type: string
description: Description of the charge.
chargeName:
type: string
description: Name of the charge.
chargeNumber:
description: Available when the `chargeNumber` field was specified in the request or when the order is amending an existing subscription.
type: string
productName:
type: string
description: Name of the product.
productRatePlanChargeId:
type: string
description: The ID of the product rate plan charge.
processingType:
type: string
description: The processing type of the invoice item.
enum:
- Charge
- Discount
- Tax
unitPrice:
type: number
description: The unit price of the charge.
format: double
quantity:
type: number
description: The quantity of the charge.
unitOfMeasure:
type: string
description: The unit of measure of the charge.
nullable: true
discountDetails:
items:
$ref: '#/components/schemas/PreviewExistingSubscriptionDiscountDetails'
type: array
description: Container for discount details.
type: object
PreviewStartDate:
description: |
The start date of the preview.
properties:
previewStartDatePolicy:
$ref: '#/components/schemas/PreviewStartDatePolicy'
specificDate:
description: |
The specific date for the preview start date. Required if `previewStartDatePolicy` is `specificDate`.
type: string
type: object
PreviewThroughDate:
description: |
The preview through date.
properties:
previewThruDatePolicy:
$ref: '#/components/schemas/PreviewThruDatePolicy'
nextBillingPeriods:
description: |
The number of billing periods to preview. Required if `previewThruDatePolicy` is `nextBillingPeriods`.
type: number
specificDate:
description: |
The specific date for the preview start date. Required if `previewThruDatePolicy` is `specificDate`.
type: string
type: object
QuantityForUsageCharges:
allOf:
- properties:
chargeId:
description: |
The ID of the subscription charge.
type: string
quantity:
description: |
The quantity of the subscription charge.
type: number
type: object
PreviewThruDatePolicy:
description: |
The options on how the preview through date is calculated.
- If you set this field to `nextBillingPeriods`, you must specify the number of billing periods to preview in the `nextBillingPeriods` field.
- If you set this field to `endOfTerm`, the preview through date is the end date of the subscription term.
- If you set this field to `specificDate`, you must specify a specific date in the `specificDate` field. The date must be in the format `yyyy-mm-dd`.
enum:
- nextBillingPeriods
- endOfTerm
- specificDate
type: string
PreviewStartDatePolicy:
description: |
The options on how the preview start date is calculated.
- If you set this field to `startOfTerm`, the preview start date is the start date of the subscription term.
- If you set this field to `today`, the preview start date is today.
- If you set this field to `specificDate`, you must specify a specific date in the `specificDate` field. The date must be in the format `yyyy-mm-dd`.
enum:
- startOfTerm
- today
- specificDate
type: string
POSTSubscriptionType:
allOf:
- properties:
accountKey:
description: |
Customer account number or ID
type: string
applicationOrder:
description: |
The priority order to apply credit memos and/or unapplied payments to an invoice. Possible item values are: `CreditMemo`, `UnappliedPayment`.
**Note:**
- This field is valid only if the `applyCredit` field is set to `true`.
- If no value is specified for this field, the default priority order is used, ["CreditMemo", "UnappliedPayment"], to apply credit memos first and then apply unapplied payments.
- If only one item is specified, only the items of the spedified type are applied to invoices. For example, if the value is `["CreditMemo"]`, only credit memos are used to apply to invoices.
items:
type: string
type: array
applyCredit:
description: |
If the value is true, the credit memo or unapplied payment on the order account will be automatically applied to the invoices generated by this order. The credit memo generated by this order will not be automatically applied to any invoices.
**Note:** This field is only available if you have [Invoice Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement) 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: boolean
applyCreditBalance:
description: |
Whether to automatically apply a credit balance to an invoice.
If the value is `true`, the credit balance is applied to the invoice. If the value is `false`, no action is taken.
To view the credit balance adjustment, retrieve the details of the invoice using the Get Invoices method.
Prerequisite: `invoice` must be `true`.
**Note:**
- If you are using the field `invoiceCollect` rather than the field `invoice`, the `invoiceCollect` value must be `true`.
- This field is deprecated if you have the Invoice Settlement feature enabled.
type: boolean
autoRenew:
default: false
description: |
If true, this subscription automatically renews at the end of the subscription term.
This field is only required if the `termType` field is set to `TERMED`.
type: boolean
collect:
default: true
description: |
Collects an automatic payment for a subscription. The collection generated in this operation is only for this subscription, not for the entire customer account.
If the value is `true`, the automatic payment is collected. If the value is `false`, no action is taken.
Prerequisite: The `invoice` or `runBilling` field must be `true`.
**Note**: This field is available only if you are on the latest Zuora API minor version, or you set the `Zuora-Version` request header to `196.0` or [a later available version](https://developer.zuora.com/v1-api-reference/api-versions/#minor-version).
type: boolean
contractEffectiveDate:
description: |
Effective contract date for this subscription, as yyyy-mm-dd
format: date
type: string
creditMemoReasonCode:
description: A code identifying the reason for the credit memo transaction that is generated by the request. The value must be an existing reason code. If you do not pass the field or pass the field with empty value, Zuora uses the default reason code.
type: string
customerAcceptanceDate:
description: |
The date on which the services or products within a subscription have been accepted by the customer, as yyyy-mm-dd.
Default value is dependent on the value of other fields. See **Notes** section for more details.
format: date
type: string
documentDate:
description: |
The date of the billing document, in `yyyy-mm-dd` format. It represents the invoice date for invoices, credit memo date for credit memos, and debit memo date for debit memos.
- If this field is specified, the specified date is used as the billing document date.
- If this field is not specified, the date specified in the `targetDate` is used as the billing document date.
format: date
type: string
externallyManagedBy:
description: |
An enum field on the Subscription object to indicate the name of a third-party store. This field is used to represent subscriptions created through third-party stores.
enum:
- Amazon
- Apple
- Google
- Roku
type: string
gatewayId:
description: |
The ID of the payment gateway instance. For example, `2c92c0f86078c4d5016091674bcc3e92`.
If Payment Gateway Routing is enabled:
- If this field is not specified, gateway routing rules will be invoked.
- If this field is specified, the specified gateway will be used to process the payment.
If Payment Gateway Routing is disabled:
- If this field is not specified, the default payment gateway will be used to process the payment. The default gateway of the customer account takes precedence over the default gateway of the tenant.
- If this field is specified, the specified gateway will be used to process the payment.
type: string
initialTerm:
description: |
The length of the period for the first subscription term. If `termType` is `TERMED`, then this field is required, and the value must be greater than `0`. If `termType` is `EVERGREEN`, this field is ignored.
format: int64
type: integer
initialTermPeriodType:
description: |
The period type for the first subscription term.
This field is used with the `InitialTerm` field to specify the initial subscription term.
Values are:
* `Month` (default)
* `Year`
* `Day`
* `Week`
type: string
invoiceOwnerAccountKey:
description: |
Invoice owner account number or ID.
**Note:** This feature is in **Limited Availability**. If you wish to have access to the feature, submit a request at [Zuora Global Support](http://support.zuora.com/).
type: string
invoiceSeparately:
description: |
Separates a single subscription from other subscriptions and invoices the charge independently.
If the value is `true`, the subscription is billed separately from other subscriptions. If the value is `false`, the subscription is included with other subscriptions in the account invoice.
The default value is `false`.
Prerequisite: The default subscription setting Enable Subscriptions to be Invoiced Separately must be set to Yes.
type: boolean
lastBookingDate:
description: |-
The last booking date of the subscription object. This field is writable only when the subscription is newly created as a first version subscription. You can override the date value when creating a subscription through the Subscribe and Amend API or the subscription creation UI (non-Orders). Otherwise, the default value `today` is set per the user's timezone. The value of this field is as follows:
* For a new subscription created by the [Subscribe and Amend APIs](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Orders_Harmonization/Orders_Migration_Guidance#Subscribe_and_Amend_APIs_to_Migrate), this field has the value of the subscription creation date.
* For a subscription changed by an amendment, this field has the value of the amendment booking date.
* For a subscription created or changed by an order, this field has the value of the order date.
format: date
type: string
notes:
description: |
The notes for the subscription.
maxLength: 1000
type: string
paymentMethodId:
description: |
The ID of the payment method used for the payment.
type: string
prepayment:
description: |
Indicates whether the subscription will consume the reserved payment amount of the customer account. See [Prepaid Cash with Drawdown](https://knowledgecenter.zuora.com/Zuora_Billing/Billing_and_Invoicing/JA_Advanced_Consumption_Billing/Prepaid_Cash_with_Drawdown) for more information.
type: boolean
renewalSetting:
description: |
Specifies whether a termed subscription will remain termed or change to evergreen when it is renewed.
Values:
* `RENEW_WITH_SPECIFIC_TERM` (default)
* `RENEW_TO_EVERGREEN`
type: string
renewalTerm:
description: |
The length of the period for the subscription renewal term. Default is `0`.
format: int64
type: integer
renewalTermPeriodType:
description: |
The period type for the subscription renewal term.
This field is used with the `renewalTerm` field to specify the subscription renewal term.
Values are:
* `Month` (default)
* `Year`
* `Day`
* `Week`
type: string
runBilling:
default: true
description: |
Creates an invoice for a subscription. If you have the Invoice Settlement feature enabled, a credit memo might also be created based on the [invoice and credit memo generation rule](https://knowledgecenter.zuora.com/CB_Billing/Invoice_Settlement/Credit_and_Debit_Memos/Rules_for_Generating_Invoices_and_Credit_Memos).
The billing documents generated
in this operation is only for this subscription, not for the entire
customer account.
**Note**: This field is available only if you are on the latest Zuora API minor version, or you set the `Zuora-Version` request header to `211.0` or [a later available version](https://developer.zuora.com/v1-api-reference/api-versions/#minor-version).
Possible values:
- `true`: An invoice is created. If you have the Invoice Settlement feature enabled, a credit memo might also be created.
- `false`: No invoice is created.
type: boolean
serviceActivationDate:
description: |
The date on which the services or products within a subscription have been activated and access has been provided to the customer, as yyyy-mm-dd.
Default value is dependent on the value of other fields. See **Notes** section for more details.
format: date
type: string
subscribeToRatePlans:
description: |
Container for one or more rate plans for this subscription.
items:
$ref: '#/components/schemas/POSTSrpCreateType'
type: array
subscriptionNumber:
description: |
Subscription Number. The value can be up to 1000 characters.
If you do not specify a subscription number when creating a subscription, Zuora will generate a subscription number automatically.
If the account is created successfully, the subscription number is returned in the `subscriptionNumber` response field.
type: string
targetDate:
description: |
Date through which to calculate charges if an invoice or a credit memo is generated, as
yyyy-mm-dd. Default is current date.
**Note**: - This field is available only if you are on the latest Zuora API minor version, or you set the `Zuora-Version` request header to `211.0` or [a later available version](https://developer.zuora.com/v1-api-reference/api-versions/#minor-version).
- The credit memo is only available if you have the Invoice Settlement feature enabled.
format: date
type: string
termStartDate:
description: |
The date on which the subscription term begins, as yyyy-mm-dd. If this is a renewal subscription, this date is different from the subscription start date.
format: date
type: string
termType:
description: |
Possible values are: `TERMED`, `EVERGREEN`.
type: string
required:
- accountKey
- contractEffectiveDate
- subscribeToRatePlans
- termType
- renewalTerm
type: object
- $ref: '#/components/schemas/SubscriptionObjectQTFields'
- $ref: '#/components/schemas/SubscriptionObjectNSFields'
- $ref: '#/components/schemas/SubscriptionObjectCustomFields'
example:
accountKey: 8ad09be48db5aba7018db604776d4854
contractEffectiveDate: '2024-07-16'
termType: TERMED
initialTerm: 12
renewalTerm: 12
autoRenew: true
subscribeToRatePlans:
- productRatePlanId: 8ad081dd9096ef9501909b40bb4e74a4
POSTSubscriptionResponseType:
properties:
contractedMrr:
description: |
Monthly recurring revenue of the subscription.
type: number
creditMemoId:
description: |
The credit memo ID, if a credit memo is generated during the subscription process.
**Note:** This container is only available if you set the Zuora REST API minor version to 207.0 or later [available versions](https://developer.zuora.com/api-references/api/overview/#section/API-Versions/Minor-Version) in the request header, and you have [Invoice Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement) 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
invoiceId:
description: |
Invoice ID, if an invoice is generated during the subscription process.
type: string
paidAmount:
description: |
Payment amount, if a payment is collected.
type: number
paymentId:
description: |
Payment ID, if a payment is collected.
type: string
subscriptionId:
description: ''
type: string
subscriptionNumber:
description: ''
type: string
success:
description: |
Returns `true` if the request was processed successfully.
type: boolean
totalContractedValue:
description: |
Total contracted value of the subscription.
type: number
type: object
GETSubscriptionWrapper:
properties:
nextPage:
description: |
URL to retrieve the next page of the response if it exists; otherwise absent.
format: URL
type: string
subscriptions:
description: |
Array of subscriptions.
items:
$ref: '#/components/schemas/GETSubscriptionType'
type: array
success:
description: |
Returns `true` if the request was processed successfully.
type: boolean
type: object
GETSubscriptionType:
allOf:
- properties:
accountId:
description: ''
type: string
accountName:
description: ''
type: string
accountNumber:
description: ''
type: string
autoRenew:
description: |
If `true`, the subscription automatically renews at the end of the term. Default is `false`.
type: boolean
billToContact:
$ref: '#/components/schemas/GETAccountSummaryTypeBillToContact'
cancelReason:
description: |
The reason for a subscription cancellation copied from the `changeReason` field of a Cancel Subscription order action.
This field contains valid value only if a subscription is cancelled through the Orders UI or API. Otherwise, the value for this field will always be `null`.
type: string
contractEffectiveDate:
description: |
Effective contract date for this subscription, as yyyy-mm-dd.
format: date
type: string
contractedMrr:
description: |
Monthly recurring revenue of the subscription.
type: number
contractedNetMrr:
description: |
Monthly recurring revenue of the subscription inclusive of all the discounts applicable, including the fixed-amount discounts and percentage discounts.
type: number
asOfDayGrossMrr:
description: |
Monthly recurring revenue of the subscription exclusive of any discounts applicable as of specified day.
type: number
asOfDayNetMrr:
description: |
Monthly recurring revenue of the subscription inclusive of all the discounts applicable, including the fixed-amount discounts and percentage discounts as of specified day.
type: number
netTotalContractedValue:
description: |
Total contracted value of the subscription inclusive of all the discounts applicable, including the fixed-amount discounts and percentage discounts.
type: number
currency:
description: |
The currency of the subscription.
**Note**: This field is available only if you have the Multiple Currencies feature enabled.
type: string
currentTerm:
description: |
The length of the period for the current subscription term.
format: int64
type: integer
currentTermPeriodType:
description: |
The period type for the current subscription term.
Values are:
* `Month` (default)
* `Year`
* `Day`
* `Week`
type: string
customerAcceptanceDate:
description: |
The date on which the services or products within a subscription have been accepted by the customer, as yyyy-mm-dd.
format: date
type: string
externallyManagedBy:
description: |
An enum field on the Subscription object to indicate the name of a third-party store. This field is used to represent subscriptions created through third-party stores.
enum:
- Amazon
- Apple
- Google
- Roku
type: string
id:
description: |
Subscription ID.
type: string
initialTerm:
description: |
The length of the period for the first subscription term.
format: int64
type: integer
initialTermPeriodType:
description: |
The period type for the first subscription term.
Values are:
* `Month` (default)
* `Year`
* `Day`
* `Week`
type: string
invoiceGroupNumber:
description: |
The number of the invoice group associated with the subscription.
The value of this field is `null` if you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled.
type: string
nullable: true
invoiceOwnerAccountId:
description: ''
type: string
invoiceOwnerAccountName:
description: ''
type: string
invoiceOwnerAccountNumber:
description: ''
type: string
invoiceScheduleId:
description: |
The ID of the invoice schedule associated with the subscription.
If multiple invoice schedules are created for different terms of a subscription, this field stores the latest invoice schedule.
**Note**: This field is available only if you have the Billing Schedule feature enabled.
type: integer
invoiceSeparately:
description: |
Separates a single subscription from other subscriptions and creates an invoice for the subscription.
If the value is `true`, the subscription is billed separately from other subscriptions. If the value is `false`, the subscription is included with other subscriptions in the account invoice.
type: boolean
invoiceTemplateId:
description: |
The ID of the invoice template associated with the subscription.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request or you select **Default Template from Account** for this field during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
invoiceTemplateName:
description: |
The name of the invoice template associated with the subscription.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify the `invoiceTemplateId` field in the request or you select **Default Template from Account** for the `invoiceTemplateId` field during subscription creation, the value of the `invoiceTemplateName` field is automatically set to `null` in the response body.
type: string
isLatestVersion:
description: If `true`, the current subscription object is the latest version.
type: boolean
lastBookingDate:
description: |-
The last booking date of the subscription object. This field is writable only when the subscription is newly created as a first version subscription. You can override the date value when creating a subscription through the Subscribe and Amend API or the subscription creation UI (non-Orders). Otherwise, the default value `today` is set per the user's timezone. The value of this field is as follows:
* For a new subscription created by the [Subscribe and Amend APIs](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Orders_Harmonization/Orders_Migration_Guidance#Subscribe_and_Amend_APIs_to_Migrate), this field has the value of the subscription creation date.
* For a subscription changed by an amendment, this field has the value of the amendment booking date.
* For a subscription created or changed by an order, this field has the value of the order date.
format: date
type: string
notes:
description: |
A string of up to 65,535 characters.
type: string
orderNumber:
description: |
The order number of the order in which the changes on the subscription are made.
**Note:** This field is only available if you have the [Order Metrics](https://knowledgecenter.zuora.com/BC_Subscription_Management/Orders/AA_Overview_of_Orders#Order_Metrics) feature enabled. If you wish to have access to the feature, submit a request at [Zuora Global Support](http://support.zuora.com/). We will investigate your use cases and data before enabling this feature for you.
type: string
organizationLabel:
description: |
The organization that this object belongs to.
Note: This field is available only when the Multi-Org feature is enabled.
type: string
paymentTerm:
description: |
The name of the payment term associated with the subscription. For example, `Net 30`. The payment term determines the due dates of invoices.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request or you select **Default Term from Account** for this field during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
ratePlans:
description: |
Container for rate plans.
items:
$ref: '#/components/schemas/GETSubscriptionRatePlanType'
type: array
renewalSetting:
description: |
Specifies whether a termed subscription will remain `TERMED` or change to `EVERGREEN` when it is renewed.
Values are:
* `RENEW_WITH_SPECIFIC_TERM` (default)
* `RENEW_TO_EVERGREEN`
type: string
renewalTerm:
description: |
The length of the period for the subscription renewal term.
format: int64
type: integer
renewalTermPeriodType:
description: |
The period type for the subscription renewal term.
Values are:
* `Month` (default)
* `Year`
* `Day`
* `Week`
type: string
revision:
description: |
An auto-generated decimal value uniquely tagged with a subscription. The value always contains one decimal place, for example, the revision of a new subscription is 1.0. If a further version of the subscription is created, the revision value will be increased by 1. Also, the revision value is always incremental regardless of deletion of subscription versions.
type: string
sequenceSetId:
description: |
The ID of the sequence set associated with the subscription.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request or you select **Default Set from Account** for this field during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
nullable: true
communicationProfileId:
description: |
The ID of the communication profile associated with the subscription.
**Note**: This field is available in the request body only if you have the Flexible Billing Attributes
feature turned on. The value is `null` in the response body without this feature turned on.
type: string
nullable: true
ramp:
description: |
Ramp information associated with the subscription.
$ref: '#/components/schemas/SubscriptionRampResponse'
type: object
sequenceSetName:
description: |
The name of the sequence set associated with the subscription.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify the `sequenceSetId` field in the request or you select **Default Template from Account** for the `sequenceSetId` field during subscription creation, the value of the `sequenceSetName` field is automatically set to `null` in the response body.
type: string
serviceActivationDate:
description: |
The date on which the services or products within a subscription have been activated and access has been provided to the customer, as yyyy-mm-dd
format: date
type: string
shipToContact:
$ref: '#/components/schemas/GetAccountSummaryTypeShipToContact'
soldToContact:
$ref: '#/components/schemas/GETAccountSummaryTypeSoldToContact'
status:
description: |
Subscription status; possible values are:
* `Draft`
* `Pending Activation`
* `Pending Acceptance`
* `Active`
* `Cancelled`
* `Suspended`
type: string
statusHistory:
description: |
Container for status history.
items:
$ref: '#/components/schemas/GETSubscriptionStatusHistoryType'
type: array
subscriptionEndDate:
description: |
The date when the subscription term ends, where the subscription ends at midnight the day before.
For example, if the `subscriptionEndDate` is 12/31/2016, the subscriptions ends at midnight (00:00:00 hours) on 12/30/2016.
This date is the same as the term end date or the cancelation date, as appropriate.
format: date
type: string
subscriptionNumber:
description: ''
type: string
subscriptionStartDate:
description: |
Date the subscription becomes effective.
format: date
type: string
termEndDate:
description: |
Date the subscription term ends. If the subscription is evergreen, this is null or is the cancellation date (if one has been set).
format: date
type: string
termStartDate:
description: |
Date the subscription term begins. If this is a renewal subscription, this date is different from the subscription start date.
format: date
type: string
termType:
description: |
Possible values are: `TERMED`, `EVERGREEN`.
type: string
scheduledCancelDate:
description: The date when the subscription is scheduled to be canceled.
format: date
type: string
scheduledSuspendDate:
description: The date when the subscription is scheduled to be suspended.
format: date
type: string
scheduledResumeDate:
description: The date when the subscription is scheduled to be resumed.
format: date
type: string
totalContractedValue:
description: |
Total contracted value of the subscription.
type: number
version:
description: This is the subscription version automatically generated by Zuora Billing. Each order or amendment creates a new version of the subscription, which incorporates the changes made in the order or amendment.
format: int64
type: integer
type: object
- $ref: '#/components/schemas/SubscriptionObjectQTFields'
- $ref: '#/components/schemas/SubscriptionObjectNSFields'
- $ref: '#/components/schemas/SubscriptionObjectCustomFields'
title: subscriptions
GETSubscriptionRatePlanType:
allOf:
- properties:
externallyManagedPlanId:
description: |
Indicates the unique identifier for the rate plan purchased on a third-party store. This field is used to represent a subscription rate plan created through third-party stores.
type: string
id:
description: |
Rate plan ID.
type: string
lastChangeType:
description: |
The last amendment on the rate plan.
**Note:** If a subscription is created through an order, this field is only available if multiple orders are created on the subscription.
Possible Values:
* `Add`
* `Update`
* `Remove`
type: string
productId:
description: ''
type: string
productName:
description: ''
type: string
productRatePlanId:
description: ''
type: string
productSku:
description: |
The unique SKU for the product.
type: string
contractedMrr:
description: |
Monthly recurring revenue of the subscription rate plan exclusive of all the discounts applicable.
type: number
contractedNetMrr:
description: |
Monthly recurring revenue of the subscription rate plan inclusive of all the discounts applicable, including the fixed-amount discounts and percentage discounts.
type: number
asOfDayGrossMrr:
description: |
Monthly recurring revenue of the subscription rate plan exclusive of any discounts applicable as of specified day.
type: number
asOfDayNetMrr:
description: |
Monthly recurring revenue of the subscription rate plan inclusive of all the discounts applicable, including the fixed-amount discounts and percentage discounts as of specified day.
type: number
ratePlanCharges:
description: |
Container for one or more charges.
items:
$ref: '#/components/schemas/GETSubscriptionRatePlanChargesType'
type: array
ratePlanName:
description: |
Name of the rate plan.
type: string
subscriptionProductFeatures:
description: |-
Container for one or more features.
Only available when the following settings are enabled:
* The Entitlements feature in your tenant.
* The Enable Feature Specification in Product and Subscriptions setting in Zuora Billing Settings
items:
$ref: '#/components/schemas/GETSubscriptionProductFeatureType'
type: array
type: object
- $ref: '#/components/schemas/RatePlanObjectCustomFields'
title: ratePlans
SubscriptionRampResponse:
description: Ramp information associated with the subscription including the ramp intervals and the charges.
properties:
id:
description: The ID of the ramp.
type: string
name:
description: The name of the ramp.
type: string
number:
description: |-
The number of the ramp. It is automatically generated by the billing
system.
type: string
description:
description: The short description of the ramp.
type: string
intervals:
description: Container for the intervals that the ramp is split into in its timeline.
items:
$ref: '#/components/schemas/SubscriptionRampIntervalResponse'
type: array
charges:
description: |-
Container for the rate plan charges that are considered as part of the
ramp deal.
items:
$ref: '#/components/schemas/SubscriptionRampChargeResponse'
type: array
title: SubscriptionRamp
type: object
GETSubscriptionStatusHistoryType:
allOf:
- properties:
endDate:
description: The effective end date of the status history.
format: date
type: string
startDate:
description: The effective start date of the status history.
format: date
type: string
status:
description: |
The status of the subscription.
Values are:
* `Pending Activation`
* `Pending Acceptance`
* `Active`
* `Cancelled`
* `Suspended`
* `OutOfTerm`
type: string
type: object
title: statusHistory
SubscriptionRampIntervalResponse:
properties:
description:
description: The short description of the interval.
type: string
endDate:
description: The end date of the interval.
format: date
type: string
name:
description: The name of the interval.
type: string
startDate:
description: The start date of the interval.
format: date
type: string
title: RampInterval
type: object
SubscriptionRampChargeResponse:
properties:
chargeNumber:
description: The number of the rate plan charge.
type: string
title: RampCharge
type: object
GETSubscriptionRatePlanChargesType:
allOf:
- properties:
amendedByOrderOn:
description: |
The date when the rate plan charge is amended through an order or amendment. This field is to standardize the booking date information to increase audit ability and traceability of data between Zuora Billing and Zuora Revenue. It is mapped as the booking date for a sale order line in Zuora Revenue.
type: string
applyDiscountTo:
description: |
Specifies the type of charges a specific discount applies to.
This field is only used when applied to a discount charge model. If you are not using a discount charge model, the value is null.
Possible values:
* `RECURRING`
* `USAGE`
* `ONETIMERECURRING`
* `ONETIMEUSAGE`
* `RECURRINGUSAGE`
* `ONETIMERECURRINGUSAGE`
type: string
applyToBillingPeriodPartially:
description: |
Allow the discount duration to be aligned with the billing period partially.
**Note**: This field is only available if you have the [Enhanced Discounts](https://knowledgecenter.zuora.com/Zuora_Billing/Build_products_and_prices/Basic_concepts_and_terms/B_Charge_Models/D_Manage_Enhanced_Discount) feature enabled.
type: boolean
billingDay:
description: |
Billing cycle day (BCD), which is when bill runs generate invoices
for charges associated with the product rate plan charge or the account.
Values:
* `DefaultFromCustomer`
* `SpecificDayofMonth(# of the month)`
* `SubscriptionStartDay`
* `ChargeTriggerDay`
* `SpecificDayofWeek/dayofweek`: in which dayofweek is the day in the week you define your billing periods to start.
In the response data, a day-of-the-month ordinal value (`first`-`31st`) appears in place of the hash sign above ("#"). If this value exceeds the number of days in a particular month, the last day of the month is used as the BCD.
type: string
billingPeriod:
description: |
Allows billing period to be overridden on the rate plan charge.
type: string
billingPeriodAlignment:
description: |
Possible values:
* `AlignToCharge`
* `AlignToSubscriptionStart`
* `AlignToTermStart`
type: string
billingTiming:
description: |
The billing timing for the charge. This field is only used if the `ratePlanChargeType` value is `Recurring`.
Possible values are:
* `In Advance`
* `In Arrears`
**Note:** This feature is in **Limited Availability**. If you wish to have access to the feature, submit a request at [Zuora Global Support](http://support.zuora.com/).
type: string
chargeFunction:
description: |
**Note**: This field is only available if you have the Prepaid with Drawdown or Minimum Commitment feature enabled.
To use this field, you must set the `X-Zuora-WSDL-Version` request header to `141` or higher. Otherwise, an error occurs.
This field defines what type of charge it is:
* Standard: Normal charge with no Prepayment or Commitment or Drawdown.
* Prepayment: For recurring charges. Unit or currency based prepaid charge.
* CommitmentTrueUp: For recurring charges. Currency based minimum commitment charge.
* Drawdown: For usage charges. Drawdown from prepaid funds.
* DrawdownAndCreditCommitment: For usage charges. Drawdown from prepaid funds and then credit to minimum commitment funds.
* CreditCommitment: For usage charges. Credit to minimum commitment funds.
enum:
- Standard
- Prepayment
- CommitmentTrueUp
- Drawdown
- CreditCommitment
- DrawdownAndCreditCommitment
type: string
commitmentType:
description: |
**Note**: This field is only available if you have the Prepaid with Drawdown feature enabled.
To use this field, you must set the `X-Zuora-WSDL-Version` request header to `133` or higher. Otherwise, an error occurs.
This field defines the type of commitment. A prepaid charge can be `UNIT` or `CURRENCY`. A minimum commitment(in-arrears) charge can only be `CURRENCY` type. For topup(recurring or one-time) charges, this field indicates what type of funds are created.
* If UNIT, it will create a fund with given prepaidUom.
* If CURRENCY, it will create a fund with the currency amount calculated in list price.
For drawdown(usage) charges, this field indicates what type of funds are drawdown from that created from topup charges.
enum:
- UNIT
- CURRENCY
type: string
chargeModelConfiguration:
$ref: '#/components/schemas/ChargeModelConfigurationType'
chargeSegments:
description: |
This field is returned only if you have set the `charge-detail` query parameter to `all-segments`.
Container for the charge information for all the charge segments.
type: array
items:
$ref: '#/components/schemas/RatePlanChargeSegment'
chargedThroughDate:
description: |
The date through which a customer has been billed for the charge.
format: date
type: string
creditOption:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
To use this field, you must set the `X-Zuora-WSDL-Version` request header to 114 or higher. Otherwise, an error occurs.
The way to calculate credit. See [Credit Option](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge#Credit_Option) for more information.
enum:
- TimeBased
- ConsumptionBased
- FullCreditBack
type: string
currency:
description: |
Currency used by the account. For example, `USD` or `EUR`.
type: string
description:
description: |
Description of the rate plan charge.
type: string
discountAmount:
description: |
The amount of the discount.
type: number
discountApplyDetails:
description: |
Container for the application details about a discount rate plan charge.
Only discount rate plan charges have values in this field.
items:
$ref: '#/components/schemas/DiscountApplyDetails'
type: array
discountClass:
description: |
The class that the discount belongs to. The discount class defines the order in which discount rate plan charges are applied.
For more information, see [Manage Discount Classes](https://knowledgecenter.zuora.com/BC_Subscription_Management/Product_Catalog/B_Charge_Models/Manage_Discount_Classes).
type: string
discountLevel:
description: |
The level of the discount. Values: `RatePlan`, `Subscription`, `Account`.
type: string
discountPercentage:
description: |
The amount of the discount as a percentage.
type: number
dmrc:
description: |
The change (delta) of monthly recurring charge exists when the change in monthly recurring revenue caused by an amendment or a new subscription.
type: number
done:
description: |
A value of `true` indicates that an invoice for a charge segment has been completed. A value of `false` indicates that an invoice has not been completed for the charge segment.
type: boolean
drawdownRate:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
The [conversion rate](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_drawdown_charge#UOM_Conversion) between Usage UOM and Drawdown UOM for a [drawdown charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_drawdown_charge). Must be a positive number (>0).
type: number
drawdownUom:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
Unit of measurement for a [drawdown charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_drawdown_charge).
type: string
dtcv:
description: |
After an amendment or an AutomatedPriceChange event, `dtcv` displays the change (delta) for the total contract value (TCV) amount for this charge, compared with its previous value with recurring charge types.
type: number
effectiveEndDate:
description: |
The effective end date of the rate plan charge.
format: date
type: string
effectiveStartDate:
description: |
The effective start date of the rate plan charge.
format: date
type: string
endDateCondition:
description: |
Defines when the charge ends after the charge trigger date.
If the subscription ends before the charge end date, the charge ends when the subscription ends. But if the subscription end date is subsequently changed through a Renewal, or Terms and Conditions amendment, the charge will end on the charge end date.
Values:
* `Subscription_End`
* `Fixed_Period`
* `Specific_End_Date`
* `One_Time`
type: string
estimatedStartDate:
type: string
format: date
description: |
The estimated start date of the pending charge in an active subscription.
The value must be a date within the subscription term. The system will then automatically calculate the estimated end date for the pending charge. The estimated start and end dates are used to manage the estimated charge duration and forecast the revenue for the pending charge.
**Note:** This field is available only when the Pending Subscription Processing feature is turned on.
estimatedEndDate:
type: string
format: date
description: |
The estimated end date of the pending charge in an active subscription.
The system automatically calculates the estimated end date for the pending charge. The estimated start and end dates are used to manage the estimated charge duration and forecast the revenue for the pending charge.
**Note:** This field is available only when the Pending Subscription Processing feature is turned on.
excludeItemBillingFromRevenueAccounting:
description: |
The flag to exclude rate plan charge related invoice items, invoice item adjustments, credit memo items, and debit memo items from revenue accounting.
**Note**: This field is only available if you have the Order to Revenue or Billing - Revenue Integration feature enabled.
type: boolean
excludeItemBookingFromRevenueAccounting:
description: |
The flag to exclude rate plan charges from revenue accounting.
**Note**: This field is only available if you have the Order to Revenue or Billing - Revenue Integration feature enabled.
type: boolean
id:
description: |
Rate plan charge ID.
type: string
includedUnits:
description: |
Specifies the number of units in the base set of units.
type: number
invoiceScheduleId:
description: |
The ID of the invoice schedule associated with the rate plan charge on the subscription.
**Note**: This field is available only if you have the Billing Schedule feature enabled.
type: string
isAllocationEligible:
description: |
This field is used to identify if the charge segment is allocation
eligible in revenue recognition.
**Note**: The field is only available if you have the Order to Revenue feature enabled. To enable this field, submit a request at Zuora Global Support.
type: boolean
isDimensionalPrice:
description: |
**Note**: This field is only available when the Dynamic Pricing feature is enabled.
Indicates whether the charge uses dimensional pricing. When set to true, this charge enables dynamic pricing.
type: boolean
isPrepaid:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
Indicates whether this charge is a prepayment (topup) charge or a drawdown charge. Values: `true` or `false`.
type: boolean
isPriceNegotiated:
description: |
**Note**: This field is only available when the Negotiated Price Table feature is enabled.
Indicates whether the charge uses negotiated pricing. When set to true, this charge defines a negotiated price table.
type: boolean
isRollover:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
The value is either "True" or "False". It determines whether the rollover fields are needed.
type: boolean
isStackedDiscount:
description: |
**Note**: This field is only applicable to the Discount - Percentage charge model.
To use this field, you must set the `X-Zuora-WSDL-Version` request header to 130 or higher. Otherwise, an error occurs.
This field indicates whether the discount is to be calculated as stacked discount. Possible values are as follows:
- `True`: This is a stacked discount, which should be calculated by stacking with other discounts.
- `False`: This is not a stacked discount, which should be calculated in sequence with other discounts.
For more information, see [Stacked discounts](https://knowledgecenter.zuora.com/Zuora_Billing/Products/Product_Catalog/B_Charge_Models/B_Discount_Charge_Models).
type: boolean
isUnbilled:
description: |
This field is used to dictate how to perform the accounting during
revenue recognition.
**Note**: The field is only available if you have the Order to Revenue feature enabled. To enable this field, submit a request at Zuora Global Support.
type: boolean
listPriceBase:
description: |
List price base; possible values are:
* `Per_Billing_Period`
* `Per_Month`
* `Per_Week`
* `Per_Year`
* `Per_Specific_Months`
type: string
model:
description: |
Charge model; possible values are:
* `FlatFee`
* `PerUnit`
* `Overage`
* `Volume`
* `Tiered`
* `TieredWithOverage`
* `DiscountFixedAmount`
* `DiscountPercentage`
* `MultiAttributePricing`
* `PreratedPerUnit`
* `PreratedPricing`
* `HighWatermarkVolumePricing`
* `HighWatermarkTieredPricing`
* `Delivery`
type: string
mrr:
description: |
Monthly recurring revenue of the rate plan charge.
type: number
name:
description: |
Charge name.
type: string
number:
description: |
Charge number.
type: string
numberOfDeliveries:
description: |
Number of deliveries in the billing period for the charge segment.
The `numberOfDeliveries` is used for the Delivery Pricing charge model only.
type: number
numberOfPeriods:
description: |
Specifies the number of periods to use when calculating charges in an overage smoothing charge model.
format: int64
type: integer
originalChargeId:
description: |
The original ID of the rate plan charge.
type: string
originalListPrice:
description: |
The original list price is the price of a product or service at which it is listed for sale by a manufacturer or retailer.
**Note:** This field applies to the following charges in a subscription created through an order:
- `oneTimeFlatFee`
- `oneTimePerUnit`
- `recurringFlatFee`
- `recurringPerUnit`
- `usageFlatFee`
- `usagePerUnit`
- `usageOverage`
- `usageTieredWithOverage`
type: number
originalOrderDate:
description: |
The date when the rate plan charge is created through an order or amendment.
This field is to standardize the booking date information to increase audit ability and traceability of data between Zuora Billing and Zuora Revenue. It is mapped as the booking date for a sale order line in Zuora Revenue.
format: date
type: string
overageCalculationOption:
description: |
Determines when to calculate overage charges.
type: string
overagePrice:
description: |
The price for units over the allowed amount.
type: number
overageUnusedUnitsCreditOption:
description: |
Determines whether to credit the customer with unused units of usage.
type: string
prepaidOperationType:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
The type of this charge. It is either a prepayment (topup) charge or a drawdown charge.
enum:
- topup
- drawdown
type: string
prepaidQuantity:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
The number of units included in a [prepayment charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge). Must be a positive number (>0).
type: number
prepaidTotalQuantity:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
The total amount of units that end customers can use during a validity period when they subscribe to a [prepayment charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge).
type: number
prepaidUom:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
Unit of measurement for a [prepayment charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge).
type: string
price:
description: |
The price associated with the rate plan charge expressed as a decimal.
type: number
pricingAttributes:
description: |
Container for pricing attributes that provide additional context for dynamic pricing. This field includes all the dynamic pricing attributes and values associated with this charge, except for the pricing attributes mapped to Zuora Usage object fields.
**Note:** To enable Dynamic Pricing, submit a request to Zuora Global Support.
type: object
additionalProperties: true
salesPrice:
description: |
The sales price associated with the rate plan charge expressed as a decimal.
**Notes**:
- This field is only available to subscriptions that are created through orders and exist after 2023-01-10.
- This field applies to the following charge models, and the values vary with the charge models:
- Flat fee: the value equals the value of the `price` field.
- Per unit: the value equals `price` multiplied by `quantity`.
- Fixed amount discount: the value equals the value of the `discountAmount` field.
- Volume: The calculation of the tier price is dependent on whether the price format is the flat fee or per unit.
- Tiered: The calculation of the tier price is dependent on whether the price format is the flat fee or per unit.
type: number
priceChangeOption:
description: |
When the following is true:
1. AutomatedPriceChange setting is on
2. Charge type is not one-time
3. Charge model is not discount percentage
Then an automatic price change can have a value for when a termed subscription is renewed.
Values (one of the following):
* `NoChange` (default)
* `SpecificPercentageValue`
* `UseLatestProductCatalogPricing`
type: string
priceIncreasePercentage:
description: |
A planned future price increase amount as a percentage.
type: number
pricingSummary:
description: |
Concise description of rate plan charge model.
type: string
processedThroughDate:
description: |
The date until when charges have been processed. When billing in arrears, such as usage, this field value is the the same as the `ChargedThroughDate` value. This date is the earliest date when a charge can be amended.
format: date
type: string
productCategory:
description: |
This is used to maintain the product category.
**Note**: This field is only available if you have the Additional Revenue Fields property enabled.
type: string
productClass:
description: |
This is used to maintain the product class.
**Note**: This field is only available if you have the Additional Revenue Fields property enabled.
type: string
productFamily:
description: |
This is used to maintain the product family.
**Note**: This field is only available if you have the Additional Revenue Fields property enabled.
type: string
productLine:
description: |
This is used to maintain the product line.
**Note**: This field is only available if you have the Additional Revenue Fields property enabled.
type: string
productRatePlanChargeId:
description: ''
type: string
quantity:
description: |
The quantity of units, such as the number of authors in a hosted wiki service. Valid for all charge models except for Flat Fee pricing.
type: number
ratingGroup:
description: |
Specifies a rating group based on which usage records are rated.
Possible values:
- `ByBillingPeriod` (default): The rating is based on all the usages in a billing period.
- `ByUsageStartDate`: The rating is based on all the usages on the same usage start date.
- `ByUsageRecord`: The rating is based on each usage record.
- `ByUsageUpload`: The rating is based on all the usages in a uploaded usage file (`.xls` or `.csv`).
- `ByGroupId`: The rating is based on all the usages in a custom group.
**Note:**
- The `ByBillingPeriod` value can be applied for all charge models.
- The `ByUsageStartDate`, `ByUsageRecord`, and `ByUsageUpload` values can only be applied for per unit, volume pricing, and tiered pricing charge models.
- The `ByGroupId` value is only available if you have the Active Rating feature enabled.
- Use this field only for Usage charges. One-Time Charges and Recurring Charges return `NULL`.
type: string
reflectDiscountInNetAmount:
type: boolean
default: false
description: |
When you apply percentage discounts to either of the following charges, you need to set the `reflectDiscountInNetAmount` field on your discount charge to `true`, to enable calculating and displaying the net amount of the following charges in Zuora Revenue.
* delivery pricing charge
* prepayment charge
* drawdown charge
Note the following:
* If you are an Order to Revenue customer, when you set the `reflectDiscountInNetAmount` field to `true`, you must also set both the `excludeItemBookingFromRevenueAccounting` and `excludeItemBillingFromRevenueAccounting` fields to `true`.
* If you are a Billing - Revenue Integration customer, you must set the `reflectDiscountInNetAmount` field to `false`, otherwise an error will be returned. Billing - Revenue Integration does not support discounts on the preceding charges.
* If you are a Zuora Billing customer who does not enable the Order to Revenue or Billing - Revenue Integration feature, when you apply percentage discounts to the preceding charges, you also need to set the `reflectDiscountInNetAmount` field to `true`.
revenueRecognitionTiming:
description: |
Specifies the type of revenue recognition timing.
Predefined options are listed as enum values in this API Reference. Other options might also be avaliable depending on the revenue recognition policy configuration in the Zuora Billing UI.
**Note**: This field is only available if you have the Order to Revenue feature enabled.
maxLength: 200
type: string
enum:
- Upon Billing Document Posting Date
- Upon Order Activation Date
revenueAmortizationMethod:
description: |
Specifies the type of revenue amortization method.
Predefined options are listed as enum values in this API Reference. Other options might also be avaliable depending on the revenue recognition policy configuration in the Zuora Billing UI.
**Note**: This field is only available if you have the Order to Revenue feature enabled.
maxLength: 200
type: string
enum:
- Immediate
- Ratable Using Start And End Dates
rolloverApply:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
This field defines the priority of rollover, which is either first or last.
enum:
- ApplyFirst
- ApplyLast
type: string
rolloverPeriodLength:
default: null
description: |
**Note**: This field is only available if you have the [Prepaid with
Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown)
feature enabled.
Use this field when you want to set the rollover fund's period length shorter than the prepayment charge's validity period. In this case, you must set the `rolloverPeriods` field to 1. For example, you can define the rollover fund's period length as 5 months, shorter than the prepayment charge's validity period: a year.
type: integer
rolloverPeriods:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
This field defines the number of rollover periods, it is restricted to 3.
type: number
segment:
description: |
The identifying number of the subscription rate plan segment. Segments are numbered sequentially, starting with 1.
format: int64
type: integer
smoothingModel:
description: |
Specifies when revenue recognition begins. When charge model is `Overage` or `TieredWithOverage`, `smoothingModel` will be one of the following values:
* `ContractEffectiveDate`
* `ServiceActivationDate`
* `CustomerAcceptanceDate`
type: string
specificBillingPeriod:
description: |
Customizes the number of month or week for the charges billing period. This field is required if you set the value of the `BillingPeriod` field to `Specific_Months` or `Specific_Weeks`.
format: int64
type: integer
specificEndDate:
description: |
The specific date on which the charge ends. If the subscription ends before the specific end date, the charge ends when the subscription ends. But if the subscription end date is subsequently changed through a Renewal, or Terms and Conditions amendment, the charge will end on the specific end date.
format: date
type: string
specificListPriceBase:
description: |
The number of months for the list price base of the charge.
**Note**:
- This field is available only if you have the Annual List Price feature enabled.
- The value of this field is `null` if you do not set the value of the `listPriceBase` field to `Per_Specific_Months`.
subscriptionChargeDeliverySchedule:
$ref: '#/components/schemas/GETDeliveryScheduleType'
subscriptionChargeIntervalPricing:
description: |
Interval Pricing information. This field is available if the Offers feature is enabled.
items:
$ref: '#/components/schemas/GETIntervalPriceType'
type: array
tcv:
description: |
The total contract value.
type: number
tiers:
description: |
One or many defined ranges with distinct pricing.
items:
$ref: '#/components/schemas/GETTierType'
type: array
triggerDate:
description: |
The date that the rate plan charge will be triggered.
format: date
type: string
triggerEvent:
description: |
The event that will cause the rate plan charge to be triggered.
Possible values:
* `ContractEffective`
* `ServiceActivation`
* `CustomerAcceptance`
* `SpecificDate`
type: string
type:
description: |
Charge type. Possible values are: `OneTime`, `Recurring`, `Usage`.
type: string
unusedUnitsCreditRates:
description: |
Specifies the rate to credit a customer for unused units of usage. This field is applicable only for overage charge models when the
`OverageUnusedUnitsCreditOption` field value is `CreditBySpecificRate`.
type: number
upsellOriginChargeNumber:
description: |
The identifier of the original upselling charge associated with the current charge.
For a termed subscription, you can now use the "Create an order" API operation to perform an Add Product order action to make a product quantity upsell for per unit recurring charges. The benefit is that the charge added by this approach will be automatically combined with the original existing charge for which you want to upsell when the subscription is renewed. The approach is as follows:
* Use an Add Product order action to add a charge that is of the same charge type, charge model, and charge end date as the existing per unit recurring charge for which you want to make a quantity upsell.
* In the preceding charge to add, use the `upsellOriginChargeNumber` field to specify the existing rate plan charge for which you want to make the quantity upsell.
Note that a termed subscription with such upsell charges can not be changed to an evergreen subscription.
**Note**: The Quantity Upsell feature is in the **Early Adopter** phase. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available. If you want to join this early adopter program, submit a request at [Zuora Global
Support](https://support.zuora.com).
type: string
uom:
description: |
Specifies the units to measure usage.
type: string
upToPeriods:
description: |
Specifies the length of the period during which the charge is active. If this period ends before the subscription ends, the charge ends when this period ends.
If the subscription end date is subsequently changed through a Renewal, or Terms and Conditions amendment, the charge end date will change accordingly up to the original period end.
type: string
upToPeriodsType:
description: |
The period type used to define when the charge ends.
Values:
* `Billing_Periods`
* `Days`
* `Weeks`
* `Months`
* `Years`
type: string
usageRecordRatingOption:
description: |
Determines how Zuora processes usage records for per-unit usage charges.
type: string
validityPeriodType:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
The period in which the prepayment units are valid to use as defined in a [prepayment charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge).
enum:
- SUBSCRIPTION_TERM
- ANNUAL
- SEMI_ANNUAL
- QUARTER
- MONTH
type: string
version:
description: |
Rate plan charge revision number.
format: int64
type: integer
type: object
- $ref: '#/components/schemas/RatePlanChargeObjectCustomFields'
title: ratePlanCharges
GETSubscriptionProductFeatureType:
properties:
description:
description: |
Feature description.
type: string
featureCode:
description: |
Feature code, up to 255 characters long.
type: string
id:
description: |
SubscriptionProductFeature ID.
type: string
name:
description: |
Feature name, up to 255 characters long.
type: string
title: subscriptionProductFeatures
type: object
RatePlanChargeSegment:
type: object
title: ratePlanChargeSegment
properties:
id:
type: string
description: |
ID of the charge.
amendedByOrderOn:
description: |
The date when the rate plan charge is amended through an order or amendment. This field is to standardize the booking date information to increase audit ability and traceability of data between Zuora Billing and Zuora Revenue. It is mapped as the booking date for a sale order line in Zuora Revenue.
format: date
type: string
applyDiscountTo:
type: string
enum:
- ONETIME
- RECURRING
- USAGE
- ONETIMERECURRING
- ONETIMEUSAGE
- RECURRINGUSAGE
- ONETIMERECURRINGUSAGE
- null
description: |
Specifies the type of charges a specific discount applies to.
This field is only used when applied to a discount charge model. If you are not using a discount charge model, the value is `null`.
nullable: true
chargeFunction:
description: |
**Note**: This field is only available if you have the Unbilled Usage feature enabled.
Define what type of charge it is in Advanced consumption billing: * `Standard`: Normal charge with no Prepayment or Commitment or Drawdown. * `Prepayment`: For recurring charges. Unit or currency based prepaid charge. * `CommitmentTrueUp`: For recurring charges. Currency based minimum commitment charge. * `Drawdown`: For usage charges. Drawdown from prepaid funds. * `DrawdownAndCreditCommitment`: For usage charges. Drawdown from prepaid funds and then credit to minimum commitment funds. * `CreditCommitment`: For usage charges. Credit to minimum commitment funds.
enum:
- Standard
- Prepayment
- CommitmentTrueUp
- Drawdown
- CreditCommitment
- DrawdownAndCreditCommitment
type: string
chargeModelConfiguration:
$ref: '#/components/schemas/ChargeModelConfigurationType'
chargedThroughDate:
description: |
The date through which a customer has been billed for the charge.
format: date
type: string
commitmentType:
description: |
**Note**: This field is only available if you have the Unbilled Usage
feature enabled.
The type of commitment. A prepaid charge can be `UNIT` or `CURRENCY`. And a min commitment(in-arrears) charge can only be CURRENCY type.
For topup(recurring/one-time) charges, this field indicates what type of funds are created.
* If `UNIT`, it will create a fund with given prepaidUom.
* If `CURRENCY`, it will create a fund with the currency amount calculated in list price.
For drawdown(usage) charges, this field indicates what type of funds are drawdown from that created from topup charges.
enum:
- UNIT
- CURRENCY
type: string
prepaidCommittedAmount:
type: string
description: |
**Note**: This field is only available if you have the Prepaid with Drawdown enabled.
The amount of the prepaid committed amount.
nullable: true
creditOption:
description: |
**Note**: This field is only available if you have the Prepaid with Drawdown
feature enabled. \nTo use this field, you must set the `X-Zuora-WSDL-Version` request header to 114 or higher. Otherwise, an error occurs.
The way to calculate credit. See Credit Option for more information.
enum:
- TimeBased
- ConsumptionBased
- FullCreditBack
- null
type: string
nullable: true
currency:
$ref: '#/components/schemas/Currency'
deliverySchedule:
$ref: '#/components/schemas/GETDeliveryScheduleType'
numberOfDeliveries:
type: number
description: |
The number of the deliveries.
nullable: true
description:
description: Description of the rate plan charge segment.
type: string
discountAmount:
description: The amount of the discount.
type: number
nullable: true
discountApplyDetails:
description: |
Container for the application details about a discount rate plan charge.
Only discount rate plan charges have values in this field.
items:
$ref: '#/components/schemas/DiscountApplyDetails'
type: array
nullable: true
discountClass:
description: |
The class that the discount belongs to. The discount class defines
the order in which discount rate plan charges are applied.
For more information, see Manage Discount Classes.
type: string
nullable: true
discountLevel:
$ref: '#/components/schemas/DiscountLevel'
discountPercentage:
description: |
The amount of the discount as a percentage.
type: number
nullable: true
applyToBillingPeriodPartially:
type: boolean
description: |
A value of `true` indicates that the charge segment is applied to a billing period
partially. The value of this field is `false` by default.
default: false
dmrc:
description: |
The change (delta) of monthly recurring charge exists when the change
in monthly recurring revenue caused by an amendment or a new subscription.
type: number
format: double
done:
description: |
A value of `true` indicates that an invoice for a charge segment
has been completed. A value of `false` indicates that an invoice has not been
completed for the charge segment.
type: boolean
drawdownRate:
type: number
description: |
**Note**: This field is only available if you have the Prepaid with Drawdown
feature enabled.
The conversion rate
between Usage UOM and Drawdown UOM for a drawdown charge.
Must be a positive number (>0).
drawdownUom:
$ref: '#/components/schemas/Uom'
dtcv:
description: |
After an amendment or an AutomatedPriceChange event, `dtcv` displays the change (delta) for the total contract value (TCV) amount for this charge, compared with its previous value with recurring charge types.
type: number
format: double
effectiveEndDate:
format: date
type: string
description: |
The effective end date of the charge.
effectiveStartDate:
format: date
type: string
description: |
The effective start date of the charge.
endDateCondition:
$ref: '#/components/schemas/EndDateCondition'
includedUnits:
type: number
description: |
The number of units included in this charge segment.
inputArgumentId:
type: string
description: |
The ID of the input argument for the charge segment.
isCommitted:
type: boolean
description: |
Indicates if the charge segment is committed.
isPrepaid:
type: boolean
description: |
**Note**: This field is only available if you have the Prepaid with Drawdown
feature enabled.
Indicates whether this charge is a prepayment (topup) charge or a drawdown charge.
isRollover:
type: boolean
description: |
**Note**: This field is only available if you have the Prepaid with Drawdown
feature enabled.
It determines whether the rollover fields are needed.
mrr:
type: number
format: double
description: |
Monthly recurring revenue (MRR) is the amount of recurring
charges in a given month. The MRR calculation doesn't include one-time
charges nor usage charges.
originalOrderDate:
format: date
type: string
description: |
The date when the rate plan charge is created through an order or
amendment. This field is to standardize the booking date information
to increase audit ability and traceability of data between Zuora
Billing and Zuora Revenue. It is mapped as the booking date for a
sales order line in Zuora Revenue.
overagePrice:
type: number
description: |
Price for units over the allowed amount.
Available for the usage-based charge type for the Overage and Tiered with Overage charge models.
prepaidOperationType:
enum:
- topup
- drawdown
type: string
description: |
**Note**: This field is only available if you have the Prepaid with Drawdown
feature enabled.
The type of this charge. It is either a prepayment (topup) charge or a
drawdown charge.
prepaidQuantity:
type: number
description: |
**Note**: This field is only available if you have the Prepaid with Drawdown
feature enabled.
The number of units included in a prepayment charge.
prepaidTotalQuantity:
type: number
description: |
**Note**: This field is only available if you have the Prepaid with Drawdown feature enabled.
The total amount of units that end customers can use during a validity period when they subscribe to a prepayment charge.
prepaidUOM:
$ref: '#/components/schemas/Uom'
quantity:
type: number
description: |
Number of units purchased.
price:
type: number
description: |
The price of the charge segment.
priceChangeOption:
$ref: '#/components/schemas/PriceChangeOption'
priceIncreasePercentage:
type: number
nullable: true
description: |
Specifies the percentage to increase or decrease the price of a termed
subscription's renewal. Use this field if you set the
`PriceChangeOption` value to `SpecificPercentageValue`.
1. AutomatedPriceChange setting is on
2. Charge type is not one-time
3. Charge model is not discount fixed amount
minimum: -100
maximum: 100
pricingSummary:
type: string
description: |
A concise description of the charge model and pricing that is suitable to
show to your customers.
originalListPrice:
type: number
nullable: true
description: |
The original list price is the price of a product or service at which it
is listed for sale by a manufacturer or retailer.
processedThroughDate:
format: date
type: string
description: |
The date until when charges have been processed. When billing in arrears, such as usage, this field value is the the same as the
`ChargedThroughDate` value.
This date is the earliest date when a charge can be amended.
rolloverApply:
enum:
- ApplyFirst
- ApplyLast
type: string
description: |
**Note**: This field is only available if you have the Prepaid with Drawdown feature enabled.
This field defines the priority of rollover, which is either first or last.
rolloverPeriodLength:
type: integer
description: |
**Note**: This field is only available if you have the Prepaid with Drawdown feature enabled.
Use this field when you want to set the rollover fund's period length shorter than the prepayment charge's validity period.
rolloverPeriods:
format: int64
type: integer
description: |
**Note**: This field is only available if you have the Prepaid with Drawdown feature enabled.
This field defines the number of rollover periods, it is restricted to 3.
prorationOption:
type: string
description: |
**Note**: This field is only available if you have the Charge Level Proration feature enabled.
The charge-level proration option for the product rate plan charge.
segment:
format: int64
type: integer
description: |
Segment number of the charge.
specificEndDate:
format: date
type: string
description: |
Defines when the charge ends after the charge trigger date.
This field is only applicable when the `endDateCondition` field is `Specific_End_Date`.
subscriptionChargeIntervalPricing:
items:
$ref: '#/components/schemas/GETIntervalPriceType'
type: array
tcv:
type: number
format: double
description: |
Total contract value (TCV) is the sum of one-time charges, recurring
charges, and usage charges. The TCV calculation includes one-time
charges, recurring charges, and usage charges.
tiers:
items:
$ref: '#/components/schemas/RatePlanChargeTier'
type: array
nullable: true
triggerDate:
format: date
type: string
nullable: true
description: |
The date when the charge becomes effective and billing begins, in `yyyy-mm-dd` format.
billingPeriodAlignment:
$ref: '#/components/schemas/BillingPeriodAlignment'
triggerEvent:
$ref: '#/components/schemas/TriggerEvent'
upToPeriods:
format: int64
type: integer
nullable: true
description: |
Specifies the length of the period during which the charge is active. If this period ends before the subscription ends, the charge ends when this period ends.
The value is inherited from `ProductRatePlanCharge.UpToPeriods` field.
upToPeriodsType:
$ref: '#/components/schemas/UpToPeriodsType'
validityPeriodType:
$ref: '#/components/schemas/ValidityPeriodType'
salesPrice:
type: number
format: double
description: |
The sales price of the charge segment.
accountingCode:
type: string
nullable: true
description: |
The accounting code of the charge segment.
revenueRecognitionCode:
type: string
nullable: true
description: |
The revenue recognition code of the charge segment.
revRecTriggerCondition:
type: string
nullable: true
description: |
Specifies when revenue recognition begins.
estimatedEndDate:
format: date
type: string
description: |
The estimated end date of the charge segment.
estimatedStartDate:
format: date
type: string
description: |
The estimated start date of the charge segment.
taxable:
type: boolean
nullable: true
description: |
Indicates whether the charge is taxable.
taxCode:
type: string
nullable: true
description: |
The tax code of a charge.
taxMode:
type: string
nullable: true
description: |
Determines how to define taxation for the charge.
It affects the tax calculation of the charge.
enum:
- TaxExclusive
- TaxInclusive
- null
DiscountApplyDetails:
properties:
appliedProductName:
description: |
The name of the product that the discount rate plan charge applies to.
type: string
appliedProductRatePlanChargeId:
description: |
The ID of the product rate plan charge that the discount rate plan charge applies to.
type: string
appliedProductRatePlanChargeName:
description: |
The name of the product rate plan charge that the discount rate plan charge applies to.
type: string
appliedProductRatePlanId:
description: |
The ID of the product rate plan that the discount rate plan charge applies to.
type: string
appliedProductRatePlanName:
description: |
The name of the product rate plan that the discount rate plan charge applies to.
type: string
title: discountApplyDetails
type: object
GETDeliveryScheduleType:
description: |
The `deliverySchedule` is used for the Delivery Pricing charge model only.
**Note**: The Delivery Pricing charge model is in the **Early Adopter** phase. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available. To manage and access this feature through the self-service interface, see [Enable billing features by yourself](https://knowledgecenter.zuora.com/Zuora_Billing/Bill_your_customers/Billing_Settings/Manage_Features) in the Knowledge Center. You can check **Delivery Pricing** in **Billing Settings** > **Enable Charge Types / Models**.
properties:
frequency:
description: |
Specifies delivery frequency for the delivery schedule.
enum:
- Weekly
type: string
friday:
description: |
Indicates whether delivery occurs on Friday.
type: boolean
monday:
description: |
Indicates whether delivery occurs on Monday.
type: boolean
saturday:
description: |
Indicates whether delivery occurs on Saturday.
type: boolean
sunday:
description: |
Indicates whether delivery occurs on Sunday.
type: boolean
thursday:
description: |
Indicates whether delivery occurs on Thursday.
type: boolean
tuesday:
description: |
Indicates whether delivery occurs on Tuesday.
type: boolean
wednesday:
description: |
Indicates whether delivery occurs on Wednesday.
type: boolean
title: deliverySchedule
type: object
GETIntervalPriceType:
properties:
duration:
description: |
Duration period of this interval.
type: integer
price:
description: |
Price of this interval.
type: number
sequence:
description: |
A system-generated number that indicates the sequence in which each interval price is billed.
type: integer
subscriptionChargeIntervalPriceTiers:
items:
$ref: '#/components/schemas/GETIntervalPriceTierType'
type: array
type:
description: |
Interval type of this pricing.
enum:
- Day
- Month
- Infinity
type: string
title: IntervalPricing
type: object
GETTierType:
properties:
endingUnit:
description: |
Decimal defining end of tier range.
type: number
originalListPrice:
description: |
The original list price is the price of a product or service at which it is listed for sale by a manufacturer or retailer.
**Note:** This field applies to the following charges in a subscription created through an order:
- `oneTimeTiered`
- `oneTimeVolume`
- `recurringTiered`
- `recurringVolume`
- `usageTiered`
- `usageVolume`
- `usageTieredWithOverage`
type: number
price:
description: |
The decimal value of the tiered charge model. If the charge model is not a tiered type then this price field will be null and the `price` field directly under the `productRatePlanCharges` applies.
type: number
priceFormat:
description: |
Tier price format. Allowed values: `flat fee`, `per unit`.
type: string
startingUnit:
description: |
Decimal defining start of tier range.
type: number
tier:
description: |
Unique number of the tier.
format: int64
type: integer
title: tiers
type: object
GETIntervalPriceTierType:
properties:
endingUnit:
description: |
Decimal defining end of tier range.
type: number
isOveragePrice:
description: |
True if the price is overage price for the tier.
type: boolean
price:
description: |
The decimal value of the tiered charge model. If the charge model is not a tiered type then this price field will be null and the `price` field directly under the `productRatePlanCharges` applies.
type: number
priceFormat:
description: |
Tier price format. Allowed values: `flat fee`, `per unit`.
type: string
startingUnit:
description: |
Decimal defining start of tier range.
type: number
tier:
description: |
Unique number of the tier.
format: int64
type: integer
title: IntervalPricing
type: object
Currency:
type: string
description: Currency used by the account. For example, `USD` or `EUR`.
DiscountLevel:
type: string
enum:
- rateplan
- subscription
- account
description: |
The level of the discount.
For example, if the value of this field is `subscription` and the value of the `applyDiscountTo` field is `RECURRING`, the discount charge applies to all recurring charges in the same subscription as the discount charge.
Uom:
description: Specifies the units to measure usage.
type: string
EndDateCondition:
description: |
Condition for the charge to become inactive.
If the value of this field is `Fixed_Period`, the charge is active for a predefined duration based on the value of the `upToPeriodsType` and `upToPeriods` fields.
If the value of this field is `Specific_End_Date`, use the `specificEndDate` field to specify the date when then charge becomes inactive.
type: string
enum:
- Subscription_End
- Fixed_Period
- Specific_End_Date
- One_Time
PriceChangeOption:
type: string
description: |
Applies an automatic price change when a termed subscription is renewed.
enum:
- NoChange
- SpecificPercentageValue
- UseLatestProductCatalogPricing
- null
default: NoChange
nullable: true
RatePlanChargeTier:
type: object
title: chargeTier
properties:
tier:
description: |
Unique number of the tier.
format: int64
type: integer
minimum: 1
startingUnit:
description: |
Decimal defining start of tier range.
type: number
format: double
endingUnit:
description: |
Decimal defining end of tier range.
type: number
format: double
price:
description: |
The decimal value of the tiered charge model. If the charge model is not a tiered type then this price field will be null and the `price` field directly under the `productRatePlanCharges` applies.
type: number
priceFormat:
description: |
Tier price format.
type: string
enum:
- FlatFee
- PerUnit
originalListPrice:
type: number
format: double
description: |
The original list price is the price of a product or service at which it is listed for sale by a manufacturer or retailer.
BillingPeriodAlignment:
description: |
Specifies how Zuora determines when to start new billing periods. You
can use this field to align the billing periods of different charges.
* `AlignToCharge` - Zuora starts a new billing period on the first billing day that
falls on or after the date when the charge becomes active.
* `AlignToSubscriptionStart` - Zuora starts a new billing period on the first billing
day that falls on or after the start date of the subscription.
* `AlignToTermStart` - For each term of the subscription, Zuora starts a new billing
period on the first billing day that falls on or after the start date of the term.
See the `billCycleType` field for information about how Zuora determines the billing
day.
**Note:** `AlignToTermEnd` is only available for prepayment charges by default.
To enable this value for non-prepaid recurring charges, contact Zuora Global Support.
enum:
- AlignToCharge
- AlignToSubscriptionStart
- AlignToTermStart
- AlignToTermEnd
type: string
TriggerEvent:
description: |
Condition for the charge to become active. If this field is not specified,
the value of the field will be defaulted to the trigger event value defined in the
product catalog.
If the value of this field is `SpecificDate`, use the `specificTriggerDate` field
to specify the date when the charge becomes active.
type: string
enum:
- ContractEffective
- ServiceActivation
- CustomerAcceptance
- SpecificDate
UpToPeriodsType:
description: |
Unit of time that the charge duration is measured in. Only applicable
if the value of the `endDateCondition` field is `Fixed_Period`.
type: string
enum:
- Days
- Weeks
- Months
- Years
- Billing_Periods
- null
nullable: true
ValidityPeriodType:
description: |
**Note**: This field is only available if you have the
Prepaid with Drawdown
feature enabled.
The period in which the prepayment units are valid to use as defined in a prepayment
charge.
type: string
enum:
- SUBSCRIPTION_TERM
- ANNUAL
- SEMI_ANNUAL
- QUARTER
- MONTH
- null
nullable: true
GETSubscriptionByKeyWithSuccess:
allOf:
- properties:
accountId:
description: The ID of the account associated with this subscription.
type: string
accountName:
description: The name of the account associated with this subscription.
type: string
accountNumber:
description: The number of the account associated with this subscription.
type: string
autoRenew:
description: |
If `true`, the subscription automatically renews at the end of the term. Default is `false`.
type: boolean
billToContact:
$ref: '#/components/schemas/GETAccountSummaryTypeBillToContact'
cancelReason:
description: |
The reason for a subscription cancellation copied from the `changeReason` field of a Cancel Subscription order action.
This field contains valid value only if a subscription is cancelled through the Orders UI or API. Otherwise, the value for this field will always be `null`.
type: string
contractEffectiveDate:
description: |
Effective contract date for this subscription, as yyyy-mm-dd.
format: date
type: string
contractedMrr:
description: |
Monthly recurring revenue of the subscription.
type: number
contractedNetMrr:
description: |
Monthly recurring revenue of the subscription inclusive of all the discounts applicable, including the fixed-amount discounts and percentage discounts.
type: number
asOfDayGrossMrr:
description: |
Monthly recurring revenue of the subscription exclusive of any discounts applicable as of specified day.
type: number
asOfDayNetMrr:
description: |
Monthly recurring revenue of the subscription inclusive of all the discounts applicable, including the fixed-amount discounts and percentage discounts as of specified day.
type: number
netTotalContractedValue:
description: |
Total contracted value of the subscription inclusive of all the discounts applicable, including the fixed-amount discounts and percentage discounts.
type: number
currency:
description: |
The currency of the subscription.
**Note**: This field is available only if you have the Multiple Currencies feature enabled.
type: string
currentTerm:
description: |
The length of the period for the current subscription term.
format: int64
type: integer
currentTermPeriodType:
description: |
The period type for the current subscription term.
Values are:
* `Month` (default)
* `Year`
* `Day`
* `Week`
type: string
customerAcceptanceDate:
description: |
The date on which the services or products within a subscription have been accepted by the customer, as yyyy-mm-dd.
format: date
type: string
externallyManagedBy:
description: |
An enum field on the Subscription object to indicate the name of a third-party store. This field is used to represent subscriptions created through third-party stores.
enum:
- Amazon
- Apple
- Google
- Roku
type: string
id:
description: |
Subscription ID.
type: string
initialTerm:
description: |
The length of the period for the first subscription term.
format: int64
type: integer
initialTermPeriodType:
description: |
The period type for the first subscription term.
Values are:
* `Month` (default)
* `Year`
* `Day`
* `Week`
type: string
invoiceGroupNumber:
description: |
The number of the invoice group associated with the subscription.
The value of this field is `null` if you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled.
type: string
nullable: true
invoiceOwnerAccountId:
description: ''
type: string
invoiceOwnerAccountName:
description: ''
type: string
invoiceOwnerAccountNumber:
description: ''
type: string
invoiceScheduleId:
description: |
The ID of the invoice schedule associated with the subscription.
If multiple invoice schedules are created for different terms of a subscription, this field stores the latest invoice schedule.
**Note**: This field is available only if you have the Billing Schedule feature enabled.
type: integer
invoiceSeparately:
description: |
Separates a single subscription from other subscriptions and creates an invoice for the subscription.
If the value is `true`, the subscription is billed separately from other subscriptions. If the value is `false`, the subscription is included with other subscriptions in the account invoice.
type: boolean
invoiceTemplateId:
description: |
The ID of the invoice template associated with the subscription.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request or you select **Default Template from Account** for this field during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
nullable: true
invoiceTemplateName:
description: |
The name of the invoice template associated with the subscription.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify the `invoiceTemplateId` field in the request or you select **Default Template from Account** for the `invoiceTemplateId` field during subscription creation, the value of the `invoiceTemplateName` field is automatically set to `null` in the response body.
type: string
isLatestVersion:
description: If `true`, the current subscription object is the latest version.
type: boolean
lastBookingDate:
description: |-
The last booking date of the subscription object. This field is writable only when the subscription is newly created as a first version subscription. You can override the date value when creating a subscription through the Subscribe and Amend API or the subscription creation UI (non-Orders). Otherwise, the default value `today` is set per the user's timezone. The value of this field is as follows:
* For a new subscription created by the [Subscribe and Amend APIs](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Orders_Harmonization/Orders_Migration_Guidance#Subscribe_and_Amend_APIs_to_Migrate), this field has the value of the subscription creation date.
* For a subscription changed by an amendment, this field has the value of the amendment booking date.
* For a subscription created or changed by an order, this field has the value of the order date.
format: date
type: string
notes:
description: |
A string of up to 65,535 characters.
type: string
orderNumber:
description: |
The order number of the order in which the changes on the subscription are made.
**Note:** This field is only available if you have the [Order Metrics](https://knowledgecenter.zuora.com/BC_Subscription_Management/Orders/AA_Overview_of_Orders#Order_Metrics) feature enabled. If you wish to have access to the feature, submit a request at [Zuora Global Support](http://support.zuora.com/). We will investigate your use cases and data before enabling this feature for you.
type: string
organizationLabel:
description: |
The organization that this object belongs to.
Note: This field is available only when the Multi-Org feature is enabled.
type: string
originalListPrice:
description: |
The original list price is the price of a product or service at which it is listed for sale by a manufacturer or retailer.
**Note:** This field applies to the following charges in a subscription created through an order:
- `oneTimeFlatFee`
- `oneTimePerUnit`
- `recurringFlatFee`
- `recurringPerUnit`
- `usageFlatFee`
- `usagePerUnit`
- `usageOverage`
- `usageTieredWithOverage`
type: number
paymentTerm:
description: |
The name of the payment term associated with the subscription. For example, `Net 30`. The payment term determines the due dates of invoices.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request or you select **Default Term from Account** for this field during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
ramp:
description: |
Ramp information associated with the subscription.
$ref: '#/components/schemas/SubscriptionRampResponse'
type: object
ratePlans:
description: |
Container for rate plans.
items:
$ref: '#/components/schemas/GETSubscriptionRatePlanType'
type: array
renewalSetting:
description: |
Specifies whether a termed subscription will remain `TERMED` or change to `EVERGREEN` when it is renewed.
Values are:
* `RENEW_WITH_SPECIFIC_TERM` (default)
* `RENEW_TO_EVERGREEN`
type: string
renewalTerm:
description: |
The length of the period for the subscription renewal term.
format: int64
type: integer
renewalTermPeriodType:
description: |
The period type for the subscription renewal term.
Values are:
* `Month` (default)
* `Year`
* `Day`
* `Week`
type: string
revision:
description: |
An auto-generated decimal value uniquely tagged with a subscription. The value always contains one decimal place, for example, the revision of a new subscription is 1.0. If a further version of the subscription is created, the revision value will be increased by 1. Also, the revision value is always incremental regardless of deletion of subscription versions.
type: string
sequenceSetId:
description: |
The ID of the sequence set associated with the subscription.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request or you select **Default Set from Account** for this field during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
nullable: true
communicationProfileId:
description: |
The ID of the communication profile associated with the subscription.
**Note**: This field is available in the request body only if you have the Flexible Billing Attributes
feature turned on. The value is `null` in the response body without this feature turned on.
type: string
nullable: true
sequenceSetName:
description: |
The name of the sequence set associated with the subscription.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify the `sequenceSetId` field in the request or you select **Default Template from Account** for the `sequenceSetId` field during subscription creation, the value of the `sequenceSetName` field is automatically set to `null` in the response body.
type: string
serviceActivationDate:
description: |
The date on which the services or products within a subscription have been activated and access has been provided to the customer, as yyyy-mm-dd
format: date
type: string
shipToContact:
$ref: '#/components/schemas/GetAccountSummaryTypeShipToContact'
soldToContact:
$ref: '#/components/schemas/GETAccountSummaryTypeSoldToContact'
status:
description: |
Subscription status; possible values are:
* `Draft`
* `Pending Activation`
* `Pending Acceptance`
* `Active`
* `Cancelled`
* `Suspended`
type: string
statusHistory:
description: |
Container for status history.
items:
$ref: '#/components/schemas/GETSubscriptionStatusHistoryType'
type: array
subscriptionEndDate:
description: |
The date when the subscription term ends, where the subscription ends at midnight the day before.
For example, if the `subscriptionEndDate` is 12/31/2016, the subscriptions ends at midnight (00:00:00 hours) on 12/30/2016.
This date is the same as the term end date or the cancelation date, as appropriate.
format: date
type: string
subscriptionNumber:
description: Subscription number.
type: string
subscriptionStartDate:
description: |
Date the subscription becomes effective.
format: date
type: string
success:
description: |
Returns `true` if the request was processed successfully.
type: boolean
termEndDate:
description: |
Date the subscription term ends. If the subscription is evergreen, this is null or is the cancellation date (if one has been set).
format: date
type: string
termStartDate:
description: |
Date the subscription term begins. If this is a renewal subscription, this date is different from the subscription start date.
format: date
type: string
termType:
description: |
Possible values are: `TERMED`, `EVERGREEN`.
type: string
scheduledCancelDate:
description: The date when the subscription is scheduled to be canceled.
format: date
type: string
scheduledSuspendDate:
description: The date when the subscription is scheduled to be suspended.
format: date
type: string
scheduledResumeDate:
description: The date when the subscription is scheduled to be resumed.
format: date
type: string
totalContractedValue:
description: |
Total contracted value of the subscription.
type: number
version:
description: This is the subscription version automatically generated by Zuora Billing. Each order or amendment creates a new version of the subscription, which incorporates the changes made in the order or amendment.
format: int64
type: integer
accountOwnerDetails:
$ref: '#/components/schemas/GETAccountTypeBasicInfo'
invoiceOwnerAccountDetails:
$ref: '#/components/schemas/GETAccountTypeBasicInfo'
type: object
- $ref: '#/components/schemas/SubscriptionObjectQTFields'
- $ref: '#/components/schemas/SubscriptionObjectNSFields'
- $ref: '#/components/schemas/SubscriptionObjectCustomFields'
PUTSubscriptionType:
allOf:
- properties:
add:
description: |
Container for adding one or more rate plans.
items:
$ref: '#/components/schemas/PUTSrpAddType'
type: array
applicationOrder:
description: |
The priority order to apply credit memos and/or unapplied payments to an invoice. Possible item values are: `CreditMemo`, `UnappliedPayment`.
**Note:**
- This field is valid only if the `applyCredit` field is set to `true`.
- If no value is specified for this field, the default priority order is used, ["CreditMemo", "UnappliedPayment"], to apply credit memos first and then apply unapplied payments.
- If only one item is specified, only the items of the spedified type are applied to invoices. For example, if the value is `["CreditMemo"]`, only credit memos are used to apply to invoices.
items:
type: string
type: array
applyCredit:
description: |
Whether to automatically apply credit memos or unapplied payments, or both to an invoice.
If the value is `true`, the credit memo or unapplied payment, or both will be automatically applied to the invoice. If no value is specified or the value is `false`, no action is taken.
**Note:** This field is only available if you have [Invoice Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement) 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: boolean
applyCreditBalance:
description: |
Whether to automatically apply a credit balance to an invoice.
If the value is `true`, the credit balance is applied to the invoice. If the value is `false`, no action is taken.
To view the credit balance adjustment, retrieve the details of the invoice using the Get Invoices method.
Prerequisite: `invoice` must be `true`.
**Note:**
- If you are using the field `invoiceCollect` rather than the field `invoice`, the `invoiceCollect` value must be `true`.
- This field is deprecated if you have the Invoice Settlement feature enabled.
type: boolean
autoRenew:
description: |
If `true`, this subscription automatically renews at the end of the subscription term. Default is `false`.
type: boolean
bookingDate:
description: |
The booking date that you want to set for the contract when you change the `termType` field of the subscription and as a result get a new version of subscription created. The booking date of an amendment is the equivalent of the order date of an order. This field must be in the `yyyy-mm-dd` format. The default value is the current date when you make the API call.
format: date
type: string
change:
description: |
Use this field to change one or more rate plans - to replace the existing rate plans in a subscription with other rate plans.
**Note**: Changing rate plans is currently not supported for the Billing - Revenue Integration feature. When Billing - Revenue Integration is enabled, changing rate plans will no longer be applicable in Zuora Billing.
items:
$ref: '#/components/schemas/PUTSrpChangeType'
type: array
collect:
default: false
description: |
Collects an automatic payment for a subscription. The collection generated in this operation is only for this subscription, not for the entire customer account.
If the value is `true`, the automatic payment is collected. If the value is `false`, no action is taken.
Prerequisite: The `invoice` or `runBilling` field must be `true`.
**Note**: This field is available only if you are on the latest Zuora API version, or you set the `Zuora-Version` request header to `196.0` or a later available version.
type: boolean
creditMemoReasonCode:
description: A code identifying the reason for the credit memo transaction that is generated by the request. The value must be an existing reason code. If you do not pass the field or pass the field with empty value, Zuora uses the default reason code.
type: string
currentTerm:
description: |
The length of the period for the current subscription term. If `termType` is `TERMED`, this field is required and must be greater than `0`. If `termType` is `EVERGREEN`, this value is ignored.
format: int64
type: integer
currentTermPeriodType:
description: |
The period type for the current subscription term.
This field is used with the `CurrentTerm` field to specify the current subscription term.
Values are:
* `Month` (default)
* `Year`
* `Day`
* `Week`
type: string
documentDate:
description: |
The date of the billing document, in `yyyy-mm-dd` format. It represents the invoice date for invoices, credit memo date for credit memos, and debit memo date for debit memos.
- If this field is specified, the specified date is used as the billing document date.
- If this field is not specified, the date specified in the `targetDate` is used as the billing document date.
format: date
type: string
externallyManagedBy:
description: |
An enum field on the Subscription object to indicate the name of a third-party store. This field is used to represent subscriptions created through third-party stores.
enum:
- Amazon
- Apple
- Google
- Roku
type: string
includeExistingDraftDocItems:
description: |
Specifies whether to include draft invoice items in subscription previews.
Values are:
* `true` (default). Includes draft invoice items in the preview result.
* `false`. Excludes draft invoice items in the preview result.
**Note**: This field is available only if you are on the latest Zuora API version, or you set the `Zuora-Version` request header to `207.0` or a later available version.
type: boolean
invoiceSeparately:
description: |
Separates a single subscription from other subscriptions and invoices the charge independently.
If the value is `true`, the subscription is billed separately from other subscriptions. If the value is `false`, the subscription is included with other subscriptions in the account invoice.
The default value is `false`.
Prerequisite: The default subscription setting Enable Subscriptions to be Invoiced Separately must be set to Yes.
type: boolean
notes:
description: |
The notes for the subscription.
maxLength: 1000
type: string
preview:
description: |
If `true` the update is made in preview mode. The default setting is `false`.
type: boolean
previewType:
description: |
The type of preview you will receive.
**Note**: If your API minor version is earlier than `206.0` or you specify the `Zuora-Version` header for this request to `206.0` or earlier, the following values are supported for the `previewType` field:
- `InvoiceItem` (default)
- `ChargeMetrics`
- `InvoiceItemChargeMetrics`
enum:
- LegalDoc
- ChargeMetrics
- LegalDocChargeMetrics
default: LegalDoc
type: string
remove:
description: |
Container for removing one or more rate plans.
items:
$ref: '#/components/schemas/PUTSrpRemoveType'
type: array
renewalSetting:
description: |
Specifies whether a termed subscription will remain `TERMED` or change to `EVERGREEN` when it is renewed.
Values are:
* `RENEW_WITH_SPECIFIC_TERM` (default)
* `RENEW_TO_EVERGREEN`
type: string
renewalTerm:
description: |
The length of the period for the subscription renewal term. Default is `0`.
format: int64
type: integer
renewalTermPeriodType:
description: |
The period type for the subscription renewal term.
This field is used with the `renewalTerm` field to specify the subscription renewal term.
Values are:
* `Month` (default)
* `Year`
* `Day`
* `Week`
type: string
runBilling:
default: false
description: |
Creates an invoice for a subscription. If you have the Invoice Settlement feature enabled, a credit memo might also be created based on the [invoice and credit memo generation rule](https://knowledgecenter.zuora.com/CB_Billing/Invoice_Settlement/Credit_and_Debit_Memos/Rules_for_Generating_Invoices_and_Credit_Memos).
The billing documents generated in this operation is only for this subscription, not for the entire customer account.
This field is available only if you are on the latest Zuora API version, or you set the `Zuora-Version` request header to `211.0` or a later available version.
Possible values:
- `true`: An invoice is created. If you have the Invoice Settlement feature enabled, a credit memo might also be created.
- `false`: No invoice is created.
type: boolean
targetDate:
description: |
Date through which to calculate charges if an invoice or a credit memo is generated, as
yyyy-mm-dd. Default is current date.
**Note:** The credit memo is only available if you have the Invoice Settlement feature enabled.
This field is available only if you are on the latest Zuora API minor version, or you set the `Zuora-Version` request header to `211.0` or a later available version.
format: date
type: string
termStartDate:
description: |
Date the subscription term begins, as yyyy-mm-dd. If this is a renewal subscription, this date is different from the subscription start date.
format: date
type: string
termType:
description: |
Possible values are: `TERMED`, `EVERGREEN`.
type: string
update:
description: |
Container for updating one or more rate plans.
items:
$ref: '#/components/schemas/PUTSrpUpdateType'
type: array
type: object
- $ref: '#/components/schemas/SubscriptionObjectQTFields'
- $ref: '#/components/schemas/SubscriptionObjectNSFields'
- $ref: '#/components/schemas/SubscriptionObjectCustomFields'
example:
autoRenew: true
PUTSubscriptionResponseType:
properties:
chargeMetrics:
description: |
Container for charge metrics. This field is available only if the `preview` field in the request body is `true`.
properties:
dmrr:
description: |
Change in total contract value.
type: string
dtcv:
description: |
Change in monthly recurring revenue.
type: string
mrr:
description: |
Monthly recurring revenue.
type: string
number:
description: |
The charge number of the subscription. Only available for update subscription.
type: string
originRatePlanId:
description: |
The origin rate plan ID. Only available for update subscription.
type: string
originalId:
description: |
The original rate plan charge ID. Only available for update subscription.
type: string
productRatePlanChargeId:
description: ''
type: string
productRatePlanId:
description: ''
type: string
tcv:
description: |
Total contract value.
type: string
type: object
creditMemo:
description: |
Container for credit memos. This field is available only if the `preview` field in the request body is `true`.
**Note:** This container is only available if you set the Zuora REST API minor version to 207.0 or later [available versions](https://developer.zuora.com/api-references/api/overview/#section/API-Versions/Minor-Version) in the request header, and you have [Invoice Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement) 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.
properties:
amount:
description: Credit memo amount.
format: double
type: number
amountWithoutTax:
description: Credit memo amount minus tax.
format: double
type: number
creditMemoItems:
description: ''
items:
$ref: '#/components/schemas/POSTSubscriptionPreviewCreditMemoItemsType'
type: array
taxAmount:
description: Tax amount on the credit memo.
format: double
type: number
type: object
creditMemoId:
description: |
The credit memo ID. This field is available only if the `preview` field in the request body is `false` and a credit memo is generated during the update.
**Note:** This container is only available if you set the Zuora REST API minor version to 207.0 or later [available versions](https://developer.zuora.com/api-references/api/overview/#section/API-Versions/Minor-Version) in the request header, and you have [Invoice Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement) 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
invoice:
description: |
Container for invoices. This field is available only if the `preview` field in the request body is `true`.
**Note**: This field is available only if you are on the latest Zuora API version, or you set the `Zuora-Version` request header to `207.0` or
[a later available version](https://developer.zuora.com/v1-api-reference/api-versions/#minor-version). Also, the response structure is changed and the following invoice related response fields are moved to this **invoice** container:
* amount
* amountWithoutTax
* taxAmount
* invoiceItems
* targetDate
properties:
amount:
description: Invoice amount.
format: double
type: number
amountWithoutTax:
description: |
Invoice amount minus tax.
format: double
type: number
invoiceItems:
description: |
Container for invoice items.
items:
$ref: '#/components/schemas/PUTSubscriptionPreviewInvoiceItemsType'
type: array
targetDate:
description: |
Date through which to calculate charges if an invoice is generated, as yyyy-mm-dd. Default is current date.
**Note**: This field is available only if you are on the latest Zuora API version, or you set the `Zuora-Version` request header to `207.0` or [a later available version](https://developer.zuora.com/v1-api-reference/api-versions/#minor-version).
format: date
type: string
taxAmount:
description: |
The tax amount of the invoice.
format: double
type: number
type: object
invoiceId:
description: |
The ID of the generated invoice.
This field is available only if the `preview` field in the request body is `false` and an invoice is generated during the update.
type: string
invoiceItems:
description: |
Container for invoice items. This field is available only if the `preview` field in the request body is `true`.
items:
$ref: '#/components/schemas/PUTSubscriptionPreviewInvoiceItemsType'
type: array
paidAmount:
description: |
Payment amount, if a payment is collected
type: number
paymentId:
description: |
Payment ID, if a payment is collected.
type: string
subscriptionId:
description: |
The ID of the resulting new subscription.
type: string
success:
description: |
Returns `true` if the request was processed successfully.
type: boolean
targetDate:
description: |
Date through which to calculate charges if an invoice is generated, as yyyy-mm-dd. Default is current date. This field is available only if the `preview` field in the request body is `true`.
**Note:** This field is only available if you are on the latest Zuora API minor version, or you set the `Zuora-Version` request header to `207.0` or [a later available version](https://developer.zuora.com/v1-api-reference/api-versions/#minor-version).
format: date
type: string
taxAmount:
description: |
Tax amount on the invoice. This field is available only if the `preview` field in the request body is `true`.
type: number
totalDeltaMrr:
description: |
Change in the subscription monthly recurring revenue as a result of the update.
type: number
totalDeltaTcv:
description: |
Change in the total contracted value of the subscription as a result of the update.
type: number
type: object
PUTSubscriptionPreviewInvoiceItemsType:
properties:
chargeAmount:
description: |
The amount of the charge. This amount doesn't include taxes unless the charge's tax mode is inclusive.
type: number
chargeDescription:
description: |
Description of the charge.
type: string
chargeName:
description: |
Name of the charge
type: string
productName:
description: |
Name of the product associated with this item.
type: string
productRatePlanChargeId:
description: ''
type: string
quantity:
description: |
Quantity of this item.
type: number
serviceEndDate:
description: |
End date of the service period for this item, i.e., the last day of the period, as yyyy-mm-dd.
format: date
type: string
serviceStartDate:
description: |
Service start date as yyyy-mm-dd. If the charge is a one-time fee, this is the date of that charge.
format: date
type: string
taxationItems:
description: |-
List of taxation items.
**Note**: This field is available only if you are on the latest Zuora API version, or you set the `Zuora-Version` request header to `315.0` or a later available version.
items:
$ref: '#/components/schemas/POSTSubscriptionPreviewTaxationItemsType'
type: array
unitOfMeasure:
description: ''
type: string
title: invoiceItems
type: object
PUTSrpAddType:
allOf:
- properties:
bookingDate:
description: |
The booking date that you want to set for the amendment contract. The booking date of an amendment is the equivalent of the order date of an order. This field must be in the `yyyy-mm-dd` format. The default value is the current date when you make the API call.
format: date
type: string
chargeOverrides:
description: |
This optional container is used to override the quantity of one or more product rate plan charges for this subscription.
items:
$ref: '#/components/schemas/PUTScAddType'
type: array
contractEffectiveDate:
description: |
The date when the amendment changes take effect. The format of the date is yyyy-mm-dd.
If there is already a future-dated Update Product amendment on the subscription, the `specificUpdateDate` field will be used instead of this field to specify when the Update Product amendment takes effect.
format: date
type: string
customerAcceptanceDate:
description: |
The date when the customer accepts the contract in yyyy-mm-dd format.
If this field is not set:
* If the `serviceActivationDate` field is not set, the value of this field is set to be the contract effective date.
* If the `serviceActivationDate` field is set, the value of this field is set to be the service activation date.
The billing trigger dates must follow this rule:
contractEffectiveDate <= serviceActivationDate <= contractAcceptanceDate
format: date
type: string
externalCatalogPlanId:
description: |
An external ID of the product rate plan to be added. You can use this field to specify a product rate plan that is imported from an external system. The value of the `externalCatalogPlanId` field must match one of the values that are predefined in the `externallyManagedPlanIds` field on a product rate plan.
**Note:** If both `externalCatalogPlanId` and `productRatePlanId` are provided. They must point to the same product rate plan. Otherwise, the request would fail.
type: string
externalIdSourceSystem:
description: |
The ID of the external source system. You can use this field and `externalCatalogPlanId` to specify a product rate plan that is imported from an external system.
**Note:** If both `externalCatalogPlanId`, `externalIdSourceSystem` and `productRatePlanId` are provided. They must point to the same product rate plan. Otherwise, the request would fail.
type: string
externallyManagedPlanId:
description: |
Indicates the unique identifier for the rate plan purchased on a third-party store. This field is used to represent a subscription rate plan created through third-party stores.
type: string
productRatePlanId:
description: |
ID of a product rate plan for this subscription
type: string
productRatePlanNumber:
description: |
Number of a product rate plan for this subscription
type: string
serviceActivationDate:
description: |
The date when the new product in the subscription is activated in yyyy-mm-dd format.
You must specify a Service Activation date if the Customer Acceptance date is set. If the Customer Acceptance date is not set, the value of the `serviceActivationDate` field defaults to be the Contract Effective Date.
The billing trigger dates must follow this rule:
contractEffectiveDate <= serviceActivationDate <= contractAcceptanceDate
format: date
type: string
required:
- contractEffectiveDate
type: object
- $ref: '#/components/schemas/RatePlanObjectCustomFields'
title: add
PUTSrpChangeType:
allOf:
- properties:
bookingDate:
description: |
The booking date that you want to set for the amendment contract. The booking date of an amendment is the equivalent of the order date of an order. This field must be in the `yyyy-mm-dd` format. The default value is the current date when you make the API call.
format: date
type: string
chargeOverrides:
description: This optional container is used to override one or more product rate plan charges for this subscription.
items:
$ref: '#/components/schemas/PUTScAddType'
type: array
contractEffectiveDate:
description: Effective date of the new subscription, as yyyy-mm-dd.
format: date
type: string
customerAcceptanceDate:
description: |
The date when the customer accepts the contract in yyyy-mm-dd format.
When this field is not set:
* If the `serviceActivationDate` field is not set, the value of this field
is set to be the contract effective date.
* If the `serviceActivationDate` field is set, the value of this field is
set to be the service activation date.
The billing trigger dates must follow this rule: contractEffectiveDate <= serviceActivationDate <= contractAcceptanceDate
format: date
type: string
effectivePolicy:
description: |
The default value for the `effectivePolicy` field is as follows:
* If the rate plan change (from old to new) is an upgrade, the effective policy is `EffectiveImmediately` by default.
* If the rate plan change (from old to new) is a downgrade, the effective policy is `EffectiveEndOfBillingPeriod` by default.
* Otherwise, the effective policy is `SpecificDate` by default.
**Notes**:
* When setting this field to `EffectiveEndOfBillingPeriod`, you cannot set the billing trigger dates for the subscription as the system will automatically set the trigger dates to the end of billing period.
* When setting this field to `SpecificDate`, you must also set the `contractEffectiveDate` field.
enum:
- EffectiveImmediately
- EffectiveEndOfBillingPeriod
- SpecificDate
type: string
externalCatalogPlanId:
description: |
An external ID of the rate plan to be removed. You can use this field to specify an existing rate plan in your subscription. The value of the `externalCatalogPlanId` field must match one of the values that are predefined in the `externallyManagedPlanIds` field on a product rate plan. However, if there are multiple rate plans with the same `productRatePlanId` value existing in the subscription, you must use the `ratePlanId` field to remove the rate plan. The `externalCatalogPlanId` field cannot be used to distinguish multiple rate plans in this case.
**Note:** Provide only one of `externalCatalogPlanId`, `ratePlanId` or `productRatePlanId`. If more than one field is provided then the request would fail.
type: string
externalIdSourceSystem:
description: |
The ID of the external source system. You can use this field and `externalCatalogPlanId` to specify a product rate plan that is imported from an external system.
**Note:** If both `externalCatalogPlanId`, `externalIdSourceSystem` and `productRatePlanId` are provided. They must point to the same product rate plan. Otherwise, the request would fail.
type: string
newExternalCatalogPlanId:
description: |
An external ID of the product rate plan to be added. You can use this field to specify a product rate plan that is imported from an external system. The value of the `externalCatalogPlanId` field must match one of the values that are predefined in the `externallyManagedPlanIds` field on a product rate plan.
**Note:** Provide only one of `newExternalCatalogPlanId` or `newProductRatePlanId`. If both fields are provided then the request would fail.
type: string
newExternalIdSourceSystem:
description: |
The ID of the external source system. You can use this field and `newExternalCatalogPlanId` to specify a product rate plan that is imported from an external system.
**Note:** If both `newExternalCatalogPlanId`, `newExternalIdSourceSystem` and `newProductRatePlanId` are provided. They must point to the same product rate plan. Otherwise, the request would fail.
type: string
newProductRatePlanId:
description: ID of a product rate plan for this subscription.
type: string
newProductRatePlanNumber:
description: Number of a product rate plan for this subscription.
type: string
productRatePlanId:
description: |
ID of the product rate plan that the removed rate plan is based on.
type: string
productRatePlanNumber:
description: 'Number of a product rate plan for this subscription. '
type: string
ratePlanId:
description: |
ID of a rate plan to remove. Note that the removal of a rate plan through the Change Plan amendment supports the function of removal before future-dated removals, as in a Remove Product amendment.
type: string
resetBcd:
default: false
description: |
If resetBcd is true then reset the Account BCD to the effective date; if it is false keep the original BCD.
type: boolean
serviceActivationDate:
description: 'The date when the change in the subscription is activated in yyyy-mm-dd format. You must specify a Service Activation date if the Customer Acceptance date is set. If the Customer Acceptance date is not set, the value of the `serviceActivationDate` field defaults to be the Contract Effective Date. The billing trigger dates must follow this rule: contractEffectiveDate <= serviceActivationDate <= contractAcceptanceDate'
format: date
type: string
subType:
description: |
Use this field to choose the sub type for your change plan amendment.
However, if you do not set this field, the field will be automatically generated by the system according to the following rules:
When the old and new rate plans are within the same Grading catalog group:
* If the grade of new plan is greater than that of the old plan, this is an "Upgrade".
* If the grade of new plan is less than that of the old plan, this is a "Downgrade".
* If the grade of new plan equals that of the old plan, this is a "Crossgrade".
When the old and new rate plans are not in the same Grading catalog group, or either has no group, this is "PlanChanged".
enum:
- Upgrade
- Downgrade
- Crossgrade
- PlanChanged
type: string
subscriptionRatePlanNumber:
description: 'Number of a rate plan for this subscription. '
type: string
type: object
- $ref: '#/components/schemas/RatePlanObjectCustomFields'
title: change
PUTSrpRemoveType:
properties:
bookingDate:
description: |
The booking date that you want to set for the amendment contract. The booking date of an amendment is the equivalent of the order date of an order. This field must be in the `yyyy-mm-dd` format. The default value is the current date when you make the API call.
format: date
type: string
contractEffectiveDate:
description: |
Effective date of the new subscription, as yyyy-mm-dd.
format: date
type: string
customerAcceptanceDate:
description: |
The date when the customer accepts the contract in yyyy-mm-dd format.
If this field is not set:
* If the `serviceActivationDate` field is not set, the value of this field is set to be the contract effective date.
* If the `serviceActivationDate` field is set, the value of this field is set to be the service activation date.
The billing trigger dates must follow this rule:
contractEffectiveDate <= serviceActivationDate <= contractAcceptanceDate
format: date
type: string
externalCatalogPlanId:
description: |
An external ID of the rate plan to be removed. You can use this field to specify an existing rate plan in your subscription. The value of the `externalCatalogPlanId` field must match one of the values that are predefined in the `externallyManagedPlanIds` field on a product rate plan. However, if there are multiple rate plans with the same `productRatePlanId` value existing in the subscription, you must use the `ratePlanId` field to remove the rate plan. The `externalCatalogPlanId` field cannot be used to distinguish multiple rate plans in this case.
**Note:** If both `externalCatalogPlanId` and `ratePlanId` are provided. They must point to the same product rate plan. Otherwise, the request would fail.
type: string
externalIdSourceSystem:
description: |
The ID of the external source system. You can use this field and `externalCatalogPlanId` to specify a product rate plan that is imported from an external system.
**Note:** If both `externalCatalogPlanId`, `externalIdSourceSystem` and `productRatePlanId` are provided. They must point to the same product rate plan. Otherwise, the request would fail.
type: string
productRatePlanNumber:
description: |
Number of a product rate plan for this subscription.
type: string
ratePlanId:
description: |
ID of a rate plan for this subscription. This can be the latest version or any history version of ID.
type: string
serviceActivationDate:
description: |
The date when the remove amendment is activated in yyyy-mm-dd format.
You must specify a Service Activation date if the Customer Acceptance date is set. If the Customer Acceptance date is not set, the value of the `serviceActivationDate` field defaults to be the Contract Effective Date.
The billing trigger dates must follow this rule:
contractEffectiveDate <= serviceActivationDate <= contractAcceptanceDate
format: date
type: string
subscriptionRatePlanNumber:
description: |
Number of a rate plan for this subscription.
type: string
required:
- contractEffectiveDate
title: remove
type: object
PUTSrpUpdateType:
allOf:
- properties:
bookingDate:
description: |
The booking date that you want to set for the amendment contract. The booking date of an amendment is the equivalent of the order date of an order. This field must be in the `yyyy-mm-dd` format. The default value is the current date when you make the API call.
format: date
type: string
chargeUpdateDetails:
description: |
Container for one or more product rate plan charges.
items:
$ref: '#/components/schemas/PUTScUpdateType'
type: array
contractEffectiveDate:
description: |
The date when the amendment changes take effect. The format of the date is yyyy-mm-dd.
If there is already a future-dated Update Product amendment on the subscription, the `specificUpdateDate` field will be used instead of this field to specify when the Update Product amendment takes effect.
format: date
type: string
customerAcceptanceDate:
description: |
The date when the customer accepts the contract in yyyy-mm-dd format.
If this field is not set:
* If the `serviceActivationDate` field is not set, the value of this field is set to be the contract effective date.
* If the `serviceActivationDate` field is set, the value of this field is set to be the service activation date.
The billing trigger dates must follow this rule:
contractEffectiveDate <= serviceActivationDate <= contractAcceptanceDate
format: date
type: string
externalCatalogPlanId:
description: |
An external ID of the rate plan to be updated. You can use this field to specify an existing rate plan in your subscription. The value of the `externalCatalogPlanId` field must match one of the values that are predefined in the `externallyManagedPlanIds` field on a product rate plan. However, if there are multiple rate plans with the same `productRatePlanId` value existing in the subscription, you must use the `ratePlanId` field to update the rate plan. The `externalCatalogPlanId` field cannot be used to distinguish multiple rate plans in this case.
**Note:** If both `externalCatalogPlanId` and `ratePlanId` are provided. They must point to the same product rate plan. Otherwise, the request would fail.
type: string
externalIdSourceSystem:
description: |
The ID of the external source system. You can use this field and `externalCatalogPlanId` to specify a product rate plan that is imported from an external system.
**Note:** If both `externalCatalogPlanId`, `externalIdSourceSystem` and `productRatePlanId` are provided. They must point to the same product rate plan. Otherwise, the request would fail.
type: string
externallyManagedPlanId:
description: |
Indicates the unique identifier for the rate plan purchased on a third-party store. This field is used to represent a subscription rate plan created through third-party stores.
type: string
productRatePlanNumber:
description: |
Number of a product rate plan for this subscription.
type: string
ratePlanId:
description: |
ID of a rate plan for this subscription. This can be the latest version or any history version of ID.
type: string
serviceActivationDate:
description: |
The date when the update amendment is activated in yyyy-mm-dd format.
You must specify a Service Activation date if the Customer Acceptance date is set. If the Customer Acceptance date is not set, the value of the `serviceActivationDate` field defaults to be the Contract Effective Date.
The billing trigger dates must follow this rule:
contractEffectiveDate <= serviceActivationDate <= contractAcceptanceDate
format: date
type: string
specificUpdateDate:
description: |
The date when the Update Product amendment takes effect. This field is only applicable if there is already a future-dated Update Product amendment on the subscription. The format of the date is yyyy-mm-dd.
Required only for Update Product amendments if there is already a future-dated Update Product amendment on the subscription.
format: date
type: string
subscriptionRatePlanNumber:
description: |
Number of a rate plan for this subscription.
type: string
required:
- contractEffectiveDate
type: object
- $ref: '#/components/schemas/RatePlanObjectCustomFields'
title: update
PUTScUpdateType:
allOf:
- properties:
billingPeriodAlignment:
description: |
Aligns charges within the same subscription if multiple charges begin on different dates.
Values:
* `AlignToCharge`
* `AlignToSubscriptionStart`
* `AlignToTermStart`
Available for the following charge types:
* Recurring
* Usage-based
type: string
chargeModelConfiguration:
$ref: '#/components/schemas/ChargeModelConfigurationType'
description:
description: |
Description of the charge.
type: string
includedUnits:
description: |
Specifies the number of units in the base set of units for this charge. Must be >=0.
Available for the following charge type for the Overage charge model:
* Usage-based
type: number
overagePrice:
description: |
Price for units over the allowed amount.
Available for the following charge type for the Overage and Tiered with Overage charge models:
* Usage-based
type: number
price:
description: |
Price for units in the subscription rate plan.
Supports all charge types for the Flat Fee and Per Unit charge models
type: number
priceChangeOption:
description: |
Applies an automatic price change when a termed subscription is renewed. The Billing Admin setting **Enable Automatic Price Change When Subscriptions are Renewed?** must be set to Yes to use this field.
Values:
* `NoChange` (default)
* `SpecificPercentageValue`
* `UseLatestProductCatalogPricing`
Available for the following charge types:
* Recurring
* Usage-based
Not available for the Fixed-Amount Discount charge model.
type: string
priceIncreasePercentage:
description: |
Specifies the percentage to increase or decrease the price of a termed subscription's renewal. Required if you set the `PriceChangeOption` field to `SpecificPercentageValue`.
Decimal between `-100` and `100`.
Available for the following charge types:
* Recurring
* Usage-based
Not available for the Fixed-Amount Discount charge model.
type: number
quantity:
description: |
Quantity of units; must be greater than zero.
type: number
ratePlanChargeId:
description: |
ID of a rate-plan charge for this subscription. It can be the latest version or any history version of ID.
type: string
tiers:
description: |
Container for Volume, Tiered or Tiered with Overage charge models. Supports the following charge types:
* One-time
* Recurring
* Usage-based
items:
$ref: '#/components/schemas/POSTTierType'
type: array
triggerDate:
description: |
Specifies when to start billing the customer for the charge. Required if the `triggerEvent` field is set to USD.
`triggerDate` cannot be updated for the following using the REST update subscription call:
* One-time charge type
* Discount-Fixed Amount charge model
* Discount-Percentage charge model
format: date
type: string
triggerEvent:
description: |
Specifies when to start billing the customer for the charge.
Values:
* `UCE`
* `USA`
* `UCA`
* `USD`
This is the date when charge changes in the REST request become effective.
`triggerEvent` cannot be updated for the following using the REST update subscription call:
* One-time charge type
* Discount-Fixed Amount charge model
* Discount-Percentage charge model
type: string
required:
- ratePlanChargeId
type: object
- $ref: '#/components/schemas/RatePlanChargeObjectCustomFields'
title: chargeUpdateDetails
PUTScAddType:
allOf:
- properties:
amendedByOrderOn:
description: |
The date when the rate plan charge is amended through an order or amendment. This field is not updatable.
This field is to standardize the booking date information to increase audit ability and traceability of data between Zuora Billing and Zuora Revenue. It is mapped as the booking date for a sale order line in Zuora Revenue.
type: string
applyDiscountTo:
description: |
Specifies the type of charges that you want a specific discount to apply to.
Values:
* `ONETIME`
* `RECURRING`
* `USAGE`
* `ONETIMERECURRING`
* `ONETIMEUSAGE`
* `RECURRINGUSAGE`
* `ONETIMERECURRINGUSAGE`
Available for the following charge type for the Discount-Fixed Amount and Discount-Percentage charge models:
* Recurring
type: string
billCycleDay:
description: |
Sets the bill cycle day (BCD) for the charge. The BCD determines which day of the month customer is billed.
Values: `1`-`31`
Available for the following charge types:
* Recurring
* Usage-based
type: string
billCycleType:
description: |
Specifies how to determine the billing day for the charge. When this field is set to `SpecificDayofMonth`, set the `BillCycleDay` field. When this field is set to `SpecificDayofWeek`, set the `weeklyBillCycleDay` field.
Values:
* `DefaultFromCustomer`
* `SpecificDayofMonth`
* `SubscriptionStartDay`
* `ChargeTriggerDay`
* `SpecificDayofWeek`
Available for the following charge types:
* Recurring
* Usage-based
type: string
billingPeriod:
description: |
Billing period for the charge. The start day of the billing period is also called the bill cycle day (BCD). When you renew a subscription, the current subscription term is extended by creating a new term. If any charge in your subscription has the billing period set as `SubscriptionTerm`， a new charge segment is generated for the new term.
Values:
* `Month`
* `Quarter`
* `Semi_Annual`
* `Annual`
* `Eighteen_Months`
* `Two_Years`
* `Three_Years`
* `Five_Years`
* `Specific_Months`
* `Subscription_Term`
* `Week`
* `Specific_Weeks`
Available for the following charge types:
* Recurring
* Usage-based
type: string
billingPeriodAlignment:
description: |
Aligns charges within the same subscription if multiple charges begin on different dates.
Values:
* `AlignToCharge`
* `AlignToSubscriptionStart`
* `AlignToTermStart`
Available for the following charge types:
* Recurring
* Usage-based
type: string
billingTiming:
description: |
Billing timing for the charge for recurring charge types. Not avaliable for one time, usage and discount charges.
Values:
* `IN_ADVANCE` (default)
* `IN_ARREARS`
type: string
chargeModelConfiguration:
$ref: '#/components/schemas/ChargeModelConfigurationType'
description:
description: |
Description of the charge.
type: string
discountAmount:
description: |
Specifies the amount of fixed-amount discount.
Available for the following charge type for the Discount-Fixed Amount charge model:
* Recurring
type: number
discountLevel:
description: |
Specifies if the discount applies to the product rate plan only , the entire subscription, or to any activity in the account.
Values:
* `rateplan`
* `subscription`
* `account`
Available for the following charge type for the Discount-Fixed Amount and Discount-Percentage charge models:
* Recurring
type: string
discountPercentage:
description: |
Specifies the percentage of a percentage discount.
Available for the following charge type for the Discount-Percentage charge model:
* Recurring
type: number
endDateCondition:
description: |
Defines when the charge ends after the charge trigger date. If the subscription ends before the charge end date, the charge ends when the subscription ends. But if the subscription end date is subsequently changed through a Renewal, or Terms and Conditions amendment, the charge will end on the charge end date.
Values:
* `Subscription_End`
* `Fixed_Period`
* `Specific_End_Date`
* `One_Time`
type: string
excludeItemBillingFromRevenueAccounting:
default: false
description: |
The flag to exclude rate plan charge related invoice items, invoice item adjustments, credit memo items, and debit memo items from revenue accounting.
**Note**: This field is only available if you have the Order to Revenue or Billing - Revenue Integration feature enabled.
type: boolean
excludeItemBookingFromRevenueAccounting:
default: false
description: |
The flag to exclude rate plan charges from revenue accounting.
**Note**: This field is only available if you have the Order to Revenue or Billing - Revenue Integration feature enabled.
type: boolean
includedUnits:
description: |
Specifies the number of units in the base set of units for this charge. Must be >=`0`.
Available for the following charge type for the Overage charge model:
* Usage-based
type: number
isAllocationEligible:
description: |
This field is used to identify if the charge segment is allocation
eligible in revenue recognition.
**Note**: The field is only available if you have the Order to Revenue feature enabled. To enable this field, submit a request at Zuora Global Support.
type: boolean
isUnbilled:
description: |
This field is used to dictate how to perform the accounting during
revenue recognition.
**Note**: The field is only available if you have the Order to Revenue feature enabled. To enable this field, submit a request at Zuora Global Support.
type: boolean
listPriceBase:
description: |
The list price base for the product rate plan charge.
Values:
* `Per_Billing_Period`
* `Per_Month`
* `Per_Week`
* `Per_Year`
* `Per_Specific_Months`
Available for the following charge type for the Flat Fee, Per Unit, Volume Pricing, and Tiered Pricing charge models:
* Recurring
type: string
number:
description: |
Unique number that identifies the charge. System-generated if not provided.
type: string
numberOfPeriods:
description: |
Specifies the number of periods to use when calculating charges in an overage smoothing charge model.
Available for the following charge type for the Overage and Tiered with Overage charge models:
* Usage-based
format: int64
type: integer
originalOrderDate:
description: |
The date when the rate plan charge is created through an order or amendment. This field is not updatable.
This field is to standardize the booking date information to increase audit ability and traceability of data between Zuora Billing and Zuora Revenue. It is mapped as the booking date for a sale order line in Zuora Revenue.
format: date
type: string
overagePrice:
description: |
Price for units over the allowed amount.
Available for the following charge type for the Overage and Tiered with Overage charge models:
* Usage-based
type: number
overageUnusedUnitsCreditOption:
description: |
Determines whether to credit the customer with unused units of usage.
Values:
* `NoCredit`
* `CreditBySpecificRate`
Available for the following charge type for the Overage and Tiered with Overage charge models:
* Usage-based
type: string
price:
description: |
Price for units in the subscription rate plan.
Supports all charge types for the Flat Fee and Per Unit charge models
type: number
priceChangeOption:
description: |
Applies an automatic price change when a termed subscription is renewed. The Zuora Billing Admin setting Enable Automatic Price Change When Subscriptions are Renewed? must be set to Yes to use this field. See Define Default Subscription Settings for more information on setting this option.
Values:
* `NoChange` (default)
* `SpecificPercentageValue`
* `UseLatestProductCatalogPricing`
Available for the following charge types:
* Recurring
* Usage-based
* Not available for the Fixed-Amount Discount charge model.
type: string
priceIncreasePercentage:
description: |
Specifies the percentage to increase or decrease the price of a termed subscription's renewal. Required if you set the `PriceChangeOption` field to `SpecificPercentageValue`.
Decimal between -100 and 100.
Available for the following charge types:
* Recurring
* Usage-based
Not available for the Fixed-Amount Discount charge model.
type: number
productRatePlanChargeId:
description: ''
type: string
productRatePlanChargeNumber:
description: 'Number of a product rate-plan charge for this subscription. '
type: string
quantity:
description: |
Number of units. Must be >=`0`.
Available for the following charge types for the Per Unit, Volume Pricing, and Tiered Pricing charge models:
* One-time
* Recurring
type: number
ratingGroup:
description: |
Specifies a rating group based on which usage records are rated.
Possible values:
- `ByBillingPeriod` (default): The rating is based on all the usages in a billing period.
- `ByUsageStartDate`: The rating is based on all the usages on the same usage start date.
- `ByUsageRecord`: The rating is based on each usage record.
- `ByUsageUpload`: The rating is based on all the usages in a uploaded usage file (`.xls` or `.csv`).
- `ByGroupId`: The rating is based on all the usages in a custom group.
**Note:**
- The `ByBillingPeriod` value can be applied for all charge models.
- The `ByUsageStartDate`, `ByUsageRecord`, and `ByUsageUpload` values can only be applied for per unit, volume pricing, and tiered pricing charge models.
- The `ByGroupId` value is only available if you have the Active Rating feature enabled.
- Use this field only for Usage charges. One-Time Charges and Recurring Charges return `NULL`.
type: string
specificBillingPeriod:
description: |
Specifies the number of month or week for the charges billing period. Required if you set the value of the `billingPeriod` field to `Specific_Months` or `Specific_Weeks`.
Available for the following charge types:
* Recurring
* Usage-based
format: int64
type: integer
specificEndDate:
description: |
Defines when the charge ends after the charge trigger date.
This field is only applicable when the `endDateCondition` field is set to `Specific_End_Date`.
If the subscription ends before the specific end date, the charge ends when the subscription ends. But if the subscription end date is subsequently changed through a Renewal, or Terms and Conditions amendment, the charge will end on the specific end date.
format: date
type: string
specificListPriceBase:
description: |
The number of months for the list price base of the charge. This field is required if you set the value of the `listPriceBase` field to `Per_Specific_Months`.
**Note**:
- This field is available only if you have the Annual List Price feature enabled.
- The value of this field is `null` if you do not set the value of the `listPriceBase` field to `Per_Specific_Months`.
format: int32
maximum: 200
minimum: 1
type: integer
tiers:
description: |
Container for Volume, Tiered or Tiered with Overage charge models. Supports the following charge types:
* One-time
* Recurring
* Usage-based
items:
$ref: '#/components/schemas/POSTTierType'
type: array
triggerDate:
description: |
Specifies when to start billing the customer for the charge. Required if the `triggerEvent` field is set to `USD`.
format: date
type: string
triggerEvent:
description: |
Specifies when to start billing the customer for the charge.
Values:
* `UCE`
* `USA`
* `UCA`
* `USD`
type: string
unusedUnitsCreditRates:
description: |
Specifies the rate to credit a customer for unused units of usage. This field applies only for overage charge models when the `OverageUnusedUnitsCreditOption` field is set to `CreditBySpecificRate`.
Available for the following charge type for the Overage and Tiered with Overage charge models:
* Usage-based
type: number
upToPeriods:
description: |
The period type used to define when the charge ends.
Values:
* `Billing_Periods`
* `Days`
* `Weeks`
* `Months`
* `Years`
You must use this field together with the `upToPeriods` field to specify the time period.
This field is applicable only when the `endDateCondition` field is set to `Fixed_Period`.
format: int64
type: integer
upToPeriodsType:
description: |
The period type used to define when the charge ends.
Values:
* `Billing_Periods`
* `Days`
* `Weeks`
* `Months`
* `Years`
You must use this field together with the `upToPeriods` field to specify the time period.
This field is applicable only when the `endDateCondition` field is set to `Fixed_Period`.
type: string
required:
- productRatePlanChargeId
type: object
- $ref: '#/components/schemas/RatePlanChargeObjectCustomFields'
title: chargeOverrides
GETSubscriptionTypeWithSuccess:
allOf:
- properties:
accountId:
description: The ID of the account associated with this subscription.
type: string
accountName:
description: The name of the account associated with this subscription.
type: string
accountNumber:
description: The number of the account associated with this subscription.
type: string
autoRenew:
description: |
If `true`, the subscription automatically renews at the end of the term. Default is `false`.
type: boolean
billToContact:
$ref: '#/components/schemas/GETAccountSummaryTypeBillToContact'
cancelReason:
description: |
The reason for a subscription cancellation copied from the `changeReason` field of a Cancel Subscription order action.
This field contains valid value only if a subscription is cancelled through the Orders UI or API. Otherwise, the value for this field will always be `null`.
type: string
contractEffectiveDate:
description: |
Effective contract date for this subscription, as yyyy-mm-dd.
format: date
type: string
contractedMrr:
description: |
Monthly recurring revenue of the subscription, does not count in the discounts.
type: number
contractedNetMrr:
description: |
Monthly recurring revenue of the subscription inclusive of all the discounts applicable, including the fixed-amount discounts and percentage discounts.
type: number
asOfDayGrossMrr:
description: |
Monthly recurring revenue of the subscription exclusive of any discounts applicable as of specified day.
type: number
asOfDayNetMrr:
description: |
Monthly recurring revenue of the subscription inclusive of all the discounts applicable, including the fixed-amount discounts and percentage discounts as of specified day.
type: number
netTotalContractedValue:
description: |
Total contracted value of the subscription inclusive of all the discounts applicable, including the fixed-amount discounts and percentage discounts.
type: number
currency:
description: |
The currency of the subscription.
**Note**: This field is available only if you have the Multiple Currencies feature enabled.
type: string
currentTerm:
description: |
The length of the period for the current subscription term.
format: int64
type: integer
currentTermPeriodType:
description: |
The period type for the current subscription term.
Values are:
* `Month` (default)
* `Year`
* `Day`
* `Week`
type: string
customerAcceptanceDate:
description: |
The date on which the services or products within a subscription have been accepted by the customer, as yyyy-mm-dd.
format: date
type: string
externallyManagedBy:
description: |
An enum field on the Subscription object to indicate the name of a third-party store. This field is used to represent subscriptions created through third-party stores.
enum:
- Amazon
- Apple
- Google
- Roku
type: string
id:
description: |
Subscription ID.
type: string
initialTerm:
description: |
The length of the period for the first subscription term.
format: int64
type: integer
initialTermPeriodType:
description: |
The period type for the first subscription term.
Values are:
* `Month` (default)
* `Year`
* `Day`
* `Week`
type: string
invoiceGroupNumber:
description: |
The number of the invoice group associated with the subscription.
The value of this field is `null` if you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled.
type: string
nullable: true
invoiceOwnerAccountId:
description: ''
type: string
invoiceOwnerAccountName:
description: ''
type: string
invoiceOwnerAccountNumber:
description: ''
type: string
invoiceScheduleId:
description: |
The ID of the invoice schedule associated with the subscription.
If multiple invoice schedules are created for different terms of a subscription, this field stores the latest invoice schedule.
**Note**: This field is available only if you have the Billing Schedule feature enabled.
type: integer
invoiceSeparately:
description: |
Separates a single subscription from other subscriptions and creates an invoice for the subscription.
If the value is `true`, the subscription is billed separately from other subscriptions. If the value is `false`, the subscription is included with other subscriptions in the account invoice.
type: boolean
invoiceTemplateId:
description: |
The ID of the invoice template associated with the subscription.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request or you select **Default Template from Account** for this field during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
invoiceTemplateName:
description: |
The name of the invoice template associated with the subscription.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify the `invoiceTemplateId` field in the request or you select **Default Template from Account** for the `invoiceTemplateId` field during subscription creation, the value of the `invoiceTemplateName` field is automatically set to `null` in the response body.
type: string
isLatestVersion:
description: If `true`, the current subscription object is the latest version.
type: boolean
lastBookingDate:
description: |-
The last booking date of the subscription object. This field is writable only when the subscription is newly created as a first version subscription. You can override the date value when creating a subscription through the Subscribe and Amend API or the subscription creation UI (non-Orders). Otherwise, the default value `today` is set per the user's timezone. The value of this field is as follows:
* For a new subscription created by the [Subscribe and Amend APIs](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Orders_Harmonization/Orders_Migration_Guidance#Subscribe_and_Amend_APIs_to_Migrate), this field has the value of the subscription creation date.
* For a subscription changed by an amendment, this field has the value of the amendment booking date.
* For a subscription created or changed by an order, this field has the value of the order date.
format: date
type: string
notes:
description: |
A string of up to 65,535 characters.
type: string
orderNumber:
description: |
The order number of the order in which the changes on the subscription are made.
**Note:** This field is only available if you have the [Order Metrics](https://knowledgecenter.zuora.com/BC_Subscription_Management/Orders/AA_Overview_of_Orders#Order_Metrics) feature enabled. If you wish to have access to the feature, submit a request at [Zuora Global Support](http://support.zuora.com/). We will investigate your use cases and data before enabling this feature for you.
type: string
organizationLabel:
description: |
The organization that this object belongs to.
Note: This field is available only when the Multi-Org feature is enabled.
type: string
paymentTerm:
description: |
The name of the payment term associated with the subscription. For example, `Net 30`. The payment term determines the due dates of invoices.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request or you select **Default Term from Account** for this field during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
scheduledCancelDate:
description: The date when the subscription is scheduled to be canceled.
format: date
type: string
scheduledSuspendDate:
description: The date when the subscription is scheduled to be suspended.
format: date
type: string
scheduledResumeDate:
description: The date when the subscription is scheduled to be resumed.
format: date
type: string
ramp:
description: |
Ramp information associated with the subscription.
$ref: '#/components/schemas/SubscriptionRampResponse'
type: object
ratePlans:
description: |
Container for rate plans.
items:
$ref: '#/components/schemas/GETSubscriptionRatePlanType'
type: array
renewalSetting:
description: |
Specifies whether a termed subscription will remain `TERMED` or change to `EVERGREEN` when it is renewed.
Values are:
* `RENEW_WITH_SPECIFIC_TERM` (default)
* `RENEW_TO_EVERGREEN`
type: string
renewalTerm:
description: |
The length of the period for the subscription renewal term.
format: int64
type: integer
renewalTermPeriodType:
description: |
The period type for the subscription renewal term.
Values are:
* `Month` (default)
* `Year`
* `Day`
* `Week`
type: string
revision:
description: |
An auto-generated decimal value uniquely tagged with a subscription. The value always contains one decimal place, for example, the revision of a new subscription is 1.0. If a further version of the subscription is created, the revision value will be increased by 1. Also, the revision value is always incremental regardless of deletion of subscription versions.
type: string
sequenceSetId:
description: |
The ID of the sequence set associated with the subscription.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request or you select **Default Set from Account** for this field during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
nullable: true
communicationProfileId:
default: false
description: |
The ID of the communication profile associated with the subscription.
**Note**: If you have the [Flexible Billing
Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes)
feature disabled, this field is unavailable in the request body and the
value of this field is `null` in the response body.
type: string
sequenceSetName:
description: |
The name of the sequence set associated with the subscription.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify the `sequenceSetId` field in the request or you select **Default Template from Account** for the `sequenceSetId` field during subscription creation, the value of the `sequenceSetName` field is automatically set to `null` in the response body.
type: string
serviceActivationDate:
description: |
The date on which the services or products within a subscription have been activated and access has been provided to the customer, as yyyy-mm-dd
format: date
type: string
shipToContact:
$ref: '#/components/schemas/GetAccountSummaryTypeShipToContact'
soldToContact:
$ref: '#/components/schemas/GETAccountSummaryTypeSoldToContact'
status:
description: |
Subscription status; possible values are:
* `Draft`
* `Pending Activation`
* `Pending Acceptance`
* `Active`
* `Cancelled`
* `Suspended`
type: string
statusHistory:
description: |
Container for status history.
items:
$ref: '#/components/schemas/GETSubscriptionStatusHistoryType'
type: array
subscriptionEndDate:
description: |
The date when the subscription term ends, where the subscription ends at midnight the day before.
For example, if the `subscriptionEndDate` is 12/31/2016, the subscriptions ends at midnight (00:00:00 hours) on 12/30/2016.
This date is the same as the term end date or the cancelation date, as appropriate.
format: date
type: string
subscriptionNumber:
description: Subscription number.
type: string
subscriptionStartDate:
description: |
Date the subscription becomes effective.
format: date
type: string
success:
description: |
Returns `true` if the request was processed successfully.
type: boolean
termEndDate:
description: |
Date the subscription term ends. If the subscription is evergreen, this is null or is the cancellation date (if one has been set).
format: date
type: string
termStartDate:
description: |
Date the subscription term begins. If this is a renewal subscription, this date is different from the subscription start date.
format: date
type: string
termType:
description: |
Possible values are: `TERMED`, `EVERGREEN`.
type: string
totalContractedValue:
description: |
Total contracted value of the subscription.
type: number
version:
description: This is the subscription version automatically generated by Zuora Billing. Each order or amendment creates a new version of the subscription, which incorporates the changes made in the order or amendment.
format: int64
type: integer
type: object
- $ref: '#/components/schemas/SubscriptionObjectQTFields'
- $ref: '#/components/schemas/SubscriptionObjectNSFields'
- $ref: '#/components/schemas/SubscriptionObjectCustomFields'
PUTRenewSubscriptionType:
example:
runBilling: true
properties:
applicationOrder:
description: |
The priority order to apply credit memos and/or unapplied payments to an invoice. Possible item values are: `CreditMemo`, `UnappliedPayment`.
**Note:**
- This field is valid only if the `applyCredit` field is set to `true`.
- If no value is specified for this field, the default priority order is used, ["CreditMemo", "UnappliedPayment"], to apply credit memos first and then apply unapplied payments.
- If only one item is specified, only the items of the spedified type are applied to invoices. For example, if the value is `["CreditMemo"]`, only credit memos are used to apply to invoices.
items:
type: string
type: array
applyCredit:
description: |
If the value is true, the credit memo or unapplied payment on the order account will be automatically applied to the invoices generated by this order. The credit memo generated by this order will not be automatically applied to any invoices.
**Note:** This field is only available if you have [Invoice Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement) 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: boolean
applyCreditBalance:
description: |
Whether to automatically apply a credit balance to an invoice.
If the value is `true`, the credit balance is applied to the invoice. If the value is `false`, no action is taken.
To view the credit balance adjustment, retrieve the details of the invoice using the Get Invoices method.
Prerequisite: `invoice` must be `true`.
**Note:**
- If you are using the field `invoiceCollect` rather than the field `invoice`, the `invoiceCollect` value must be `true`.
- This field is deprecated if you have the Invoice Settlement feature enabled.
type: boolean
collect:
default: false
description: |
Collects an automatic payment for a subscription. The collection generated in this operation is only for this subscription, not for the entire customer account.
If the value is `true`, the automatic payment is collected. If the value is `false`, no action is taken.
Prerequisite: The `invoice` or `runBilling` field must be `true`.
**Note**: This field is available only if you are on the latest Zuora API version, or you set the `Zuora-Version` request header to `196.0` or [a later available version](https://developer.zuora.com/v1-api-reference/api-versions/#minor-version).
type: boolean
creditMemoReasonCode:
description: A code identifying the reason for the credit memo transaction that is generated by the request. The value must be an existing reason code. If you do not pass the field or pass the field with empty value, Zuora uses the default reason code.
type: string
documentDate:
description: |
The date of the billing document, in `yyyy-mm-dd` format. It represents the invoice date for invoices, credit memo date for credit memos, and debit memo date for debit memos.
- If this field is specified, the specified date is used as the billing document date.
- If this field is not specified, the date specified in the `targetDate` is used as the billing document date.
format: date
type: string
orderDate:
description: |
The date when the order is signed. If no additinal contractEffectiveDate is provided, this order will use this order date as the contract effective date.
This field must be in the `yyyy-mm-dd` format.
This field is required for Orders customers only, not applicable to Orders Harmonization customers.
format: date
type: string
runBilling:
default: false
description: |
Creates an invoice for a subscription. If you have the Invoice Settlement feature enabled, a credit memo might also be created based on the [invoice and credit memo generation rule](https://knowledgecenter.zuora.com/CB_Billing/Invoice_Settlement/Credit_and_Debit_Memos/Rules_for_Generating_Invoices_and_Credit_Memos).
The billing documents generated
in this operation is only for this subscription, not for the entire
customer account.
Possible values:
- `true`: An invoice is created. If you have the Invoice Settlement feature enabled, a credit memo might also be created.
- `false`: No invoice is created.
**Note**: This field is available only if you are on the latest Zuora API version, or you set the `Zuora-Version` request header to `211.0` or [a later available version](https://developer.zuora.com/v1-api-reference/api-versions/#minor-version).
type: boolean
targetDate:
description: |
Date through which to calculate charges if an invoice or a credit memo is generated, as yyyy-mm-dd. Default is current date.
**Note**:
- This field is available only if you are on the latest Zuora API version, or you set the `Zuora-Version` request header to `211.0` or [a later available version](https://developer.zuora.com/v1-api-reference/api-versions/#minor-version).
- The credit memo is only available if you have the Invoice Settlement feature enabled.
format: date
type: string
type: object
PUTRenewSubscriptionResponseType:
properties:
creditMemoId:
description: |
The credit memo ID, if a credit memo is generated during the subscription process.
**Note:** This container is only available if you set the Zuora REST API minor version to 207.0 or later [available versions](https://developer.zuora.com/api-references/api/overview/#section/API-Versions/Minor-Version) in the request header, and you have [Invoice Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement) 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
invoiceId:
description: |
Invoice ID, if one is generated.
type: string
paidAmount:
description: |
Payment amount, if payment is collected.
type: number
paymentId:
description: |
Payment ID, if payment is collected.
type: string
success:
description: |
Returns `true` if the request was processed successfully.
type: boolean
termEndDate:
description: |
Date the new subscription term ends, as yyyy-mm-dd.
format: date
type: string
termStartDate:
description: |
Date the new subscription term begins, as yyyy-mm-dd.
format: date
type: string
totalDeltaMrr:
description: |
Change in the subscription monthly recurring revenue as a result of the update. For a renewal, this is the MRR of the subscription in the new term.
type: number
totalDeltaTcv:
description: |
Change in the total contracted value of the subscription as a result of the update. For a renewal, this is the TCV of the subscription in the new term.
type: number
type: object
POSTSubscriptionCancellationType:
example:
cancellationPolicy: EndOfCurrentTerm
properties:
applicationOrder:
description: |
The priority order to apply credit memos and/or unapplied payments to an invoice. Possible item values are: `CreditMemo`, `UnappliedPayment`.
**Note:**
- This field is valid only if the `applyCredit` field is set to `true`.
- If no value is specified for this field, the default priority order is used, ["CreditMemo", "UnappliedPayment"], to apply credit memos first and then apply unapplied payments.
- If only one item is specified, only the items of the spedified type are applied to invoices. For example, if the value is `["CreditMemo"]`, only credit memos are used to apply to invoices.
items:
type: string
type: array
applyCredit:
description: |
If the value is true, the credit memo or unapplied payment on the order account will be automatically applied to the invoices generated by this order. The credit memo generated by this order will not be automatically applied to any invoices.
**Note:** This field is only available if you have [Invoice Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement) 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: boolean
applyCreditBalance:
description: |
Whether to automatically apply a credit balance to an invoice.
If the value is `true`, the credit balance is applied to the invoice. If the value is `false`, no action is taken.
To view the credit balance adjustment, retrieve the details of the invoice using the Get Invoices method.
Prerequisite: `invoice` must be `true`.
**Note:**
- If you are using the field `invoiceCollect` rather than the field `invoice`, the `invoiceCollect` value must be `true`.
- This field is deprecated if you have the Invoice Settlement feature enabled.
type: boolean
bookingDate:
description: |
The booking date that you want to set for the amendment contract when you cancel the subscription. The default value is the current date when you make the API call.
format: date
type: string
cancellationEffectiveDate:
description: |
Date the cancellation takes effect, in the format yyyy-mm-dd. Use only if `cancellationPolicy` is `SpecificDate`. Should not be earlier than the subscription contract-effective date, later than the subscription term-end date, or within a period for which the customer has been invoiced.
format: date
type: string
cancellationPolicy:
description: |
Cancellation method. Possible values are: `EndOfCurrentTerm`, `EndOfLastInvoicePeriod`, `SpecificDate`. If using `SpecificDate`, the `cancellationEffectiveDate` field is required.
type: string
collect:
default: false
description: |
Collects an automatic payment for a subscription. The collection generated in this operation is only for this subscription, not for the entire customer account.
If the value is `true`, the automatic payment is collected. If the value is `false`, no action is taken.
Prerequisite: The `invoice` or `runBilling` field must be `true`.
**Note**: This field is available only if you are on the latest Zuora API version, or you set the `Zuora-Version` request header to `196.0` or [a later available version](https://developer.zuora.com/v1-api-reference/api-versions/#minor-version).
type: boolean
contractEffectiveDate:
description: |
The date when the customer notifies you that they want to cancel their subscription.
format: date
type: string
creditMemoReasonCode:
description: A code identifying the reason for the credit memo transaction that is generated by the request. The value must be an existing reason code. If you do not pass the field or pass the field with empty value, Zuora uses the default reason code.
type: string
documentDate:
description: |
The date of the billing document, in `yyyy-mm-dd` format. It represents the invoice date for invoices, credit memo date for credit memos, and debit memo date for debit memos.
- If this field is specified, the specified date is used as the billing document date.
- If this field is not specified, the date specified in the `targetDate` is used as the billing document date.
format: date
type: string
orderDate:
description: |
The date when the order is signed. If no additinal contractEffectiveDate is provided, this order will use this order date as the contract effective date.
This field must be in the `yyyy-mm-dd` format.
This field is required for Orders customers only, not applicable to Orders Harmonization customers.
format: date
type: string
runBilling:
default: false
description: |
Creates an invoice for a subscription. If you have the Invoice Settlement feature enabled, a credit memo might also be created based on the [invoice and credit memo generation rule](https://knowledgecenter.zuora.com/CB_Billing/Invoice_Settlement/Credit_and_Debit_Memos/Rules_for_Generating_Invoices_and_Credit_Memos).
The billing documents generated
in this operation is only for this subscription, not for the entire
customer account.
Possible values:
- `true`: An invoice is created. If you have the Invoice Settlement feature enabled, a credit memo might also be created.
- `false`: No invoice is created.
**Note**: This field is available only if you are on the latest Zuora API version, or you set the `Zuora-Version` request header to `211.0` or [a later available version](https://developer.zuora.com/v1-api-reference/api-versions/#minor-version).
type: boolean
targetDate:
description: |
Date through which to calculate charges if an invoice or a credit memo is generated, as
yyyy-mm-dd. Default is current date.
**Note**:
- This field is available only if you are on the latest Zuora
API version, or you set the `Zuora-Version` request header to `211.0` or [a later available version](https://developer.zuora.com/v1-api-reference/api-versions/#minor-version).
- The credit memo is only available if you have the Invoice
Settlement feature enabled.
format: date
type: string
required:
- cancellationPolicy
type: object
POSTSubscriptionCancellationResponseType:
properties:
cancelledDate:
description: |
The date that the subscription was canceled.
This field is available in the Orders Harmonization tenants and the Subscribe and Amend tenants. This field is not available in the Orders tenants. For more information, see Identify your tenant type for managing subscriptions.
format: date
type: string
creditMemoId:
description: |
The credit memo ID, if a credit memo is generated during the subscription process.
**Note:** This container is only available if you set the Zuora REST API minor version to 207.0 or later [available versions](https://developer.zuora.com/api-references/api/overview/#section/API-Versions/Minor-Version) in the request header, and you have [Invoice Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement) 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
invoiceId:
description: |
ID of the invoice, if one is generated.
type: string
paidAmount:
description: |
Amount paid.
type: number
paymentId:
description: |
ID of the payment, if a payment is collected.
type: string
subscriptionId:
description: |
The subscription ID.
type: string
success:
description: |
Returns `true` if the request was processed successfully.
type: boolean
totalDeltaMrr:
description: |
Change in the subscription monthly recurring revenue as a result of the update.
type: number
totalDeltaTcv:
description: |
Change in the total contracted value of the subscription as a result of the update.
type: number
type: object
PUTSubscriptionResumeType:
example:
resumePolicy: Today
properties:
applicationOrder:
description: |
The priority order to apply credit memos and/or unapplied payments to an invoice. Possible item values are: `CreditMemo`, `UnappliedPayment`.
**Note:**
- This field is valid only if the `applyCredit` field is set to `true`.
- If no value is specified for this field, the default priority order is used, ["CreditMemo", "UnappliedPayment"], to apply credit memos first and then apply unapplied payments.
- If only one item is specified, only the items of the spedified type are applied to invoices. For example, if the value is `["CreditMemo"]`, only credit memos are used to apply to invoices.
items:
type: string
type: array
applyCredit:
description: |
If the value is true, the credit memo or unapplied payment on the order account will be automatically applied to the invoices generated by this order. The credit memo generated by this order will not be automatically applied to any invoices.
**Note:** This field is only available if you have [Invoice Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement) 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: boolean
applyCreditBalance:
description: |
Whether to automatically apply a credit balance to an invoice.
If the value is `true`, the credit balance is applied to the invoice. If the value is `false`, no action is taken.
To view the credit balance adjustment, retrieve the details of the invoice using the Get Invoices method.
Prerequisite: `invoice` must be `true`.
**Note:** This field is deprecated if you have the Invoice Settlement feature enabled.
type: boolean
bookingDate:
description: |
The booking date that you want to set for the amendment contract when you resume the subscription. If `extendsTerm` is `true`, which means you also extend the term, then this field is also the booking date for the Terms and Conditions amendment contract.
This field must be in the `yyyy-mm-dd` format. The default value of this field is the current date when you make the API call.
format: date
type: string
collect:
default: false
description: |
Collects an automatic payment for a subscription. The collection generated in this operation is only for this subscription, not for the entire customer account.
If the value is `true`, the automatic payment is collected. If the value is `false`, no action is taken.
Prerequisite: The `invoice` or `runBilling` field must be `true`.
**Note**: This field is available only if you are on the latest Zuora API version, or you set the `Zuora-Version` request header to `196.0` or a later available version.
type: boolean
contractEffectiveDate:
description: |
The date when the customer notifies you that they want to resume their subscription.
format: date
type: string
creditMemoReasonCode:
description: A code identifying the reason for the credit memo transaction that is generated by the request. The value must be an existing reason code. If you do not pass the field or pass the field with empty value, Zuora uses the default reason code.
type: string
documentDate:
description: |
The date of the billing document, in `yyyy-mm-dd` format. It represents the invoice date for invoices, credit memo date for credit memos, and debit memo date for debit memos.
- If this field is specified, the specified date is used as the billing document date.
- If this field is not specified, the date specified in the `targetDate` is used as the billing document date.
format: date
type: string
extendsTerm:
description: |
Whether to extend the subscription term by the length of time the suspension is in effect.
Values: `true`, `false`.
type: boolean
orderDate:
description: |
The date when the order is signed. If no additinal contractEffectiveDate is provided, this order will use this order date as the contract effective date.
This field must be in the `yyyy-mm-dd` format.
This field is required for Orders customers only, not applicable to Orders Harmonization customers.
format: date
type: string
resumePeriods:
description: |
The length of the period used to specify when the subscription is resumed. The subscription resumption takes effect after a specified period based on the suspend date or today's date. You must use this field together with the `resumePeriodsType` field to specify the period.
**Note:** This field is only applicable when the `suspendPolicy` field is set to `FixedPeriodsFromToday` or `FixedPeriodsFromSuspendDate`.
type: string
resumePeriodsType:
description: |
The period type used to define when the subscription resumption takes effect. The subscription resumption takes effect after a specified period based on the suspend date or today's date. You must use this field together with the `resumePeriods` field to specify the period.
Values: `Day`, `Week`, `Month`, `Year`
**Note:** This field is only applicable when the `suspendPolicy` field is set to `FixedPeriodsFromToday` or `FixedPeriodsFromSuspendDate`.
type: string
resumePolicy:
description: |
Resume methods. Specify a way to resume a subscription.
Values:
* `Today`: The subscription resumption takes effect on today's date.
* `FixedPeriodsFromSuspendDate`: The subscription resumption takes effect after a specified period based on the suspend date. You must specify the `resumePeriods` and `resumePeriodsType` fields to define the period.
* `SpecificDate`: The subscription resumption takes effect on a specific date. You must define the specific date in the `resumeSpecificDate` field.
* `FixedPeriodsFromToday`: The subscription resumption takes effect after a specified period based on the today's date. You must specify the `resumePeriods` and `resumePeriodsType` fields to define the period.
* `suspendDate`: The subscription resumption takes effect on the date of suspension of the subscription.
type: string
resumeSpecificDate:
description: |
A specific date when the subscription resumption takes effect, in the format yyyy-mm-dd.
**Note:** This field is only applicable only when the `resumePolicy` field is set to `SpecificDate`.
The value should not be earlier than the subscription suspension date.
format: date
type: string
runBilling:
default: false
description: |
Creates an invoice for a subscription. If you have the Invoice Settlement feature enabled, a credit memo might also be created based on the [invoice and credit memo generation rule](https://knowledgecenter.zuora.com/CB_Billing/Invoice_Settlement/Credit_and_Debit_Memos/Rules_for_Generating_Invoices_and_Credit_Memos).
The billing documents generated
in this operation is only for this subscription, not for the entire
customer account.
Possible values:
- `true`: An invoice is created. If you have the Invoice Settlement feature enabled, a credit memo might also be created.
- `false`: No invoice is created.
**Note**: This field is available only if you are on the latest Zuora API version, or you set the `Zuora-Version` request header to `211.0` or a later available version.
type: boolean
targetDate:
description: |
Date through which to calculate charges if an invoice or a credit memo is generated, as
yyyy-mm-dd. Default is current date.
**Note:**
- This field is available only if you are on the latest Zuora API version, or you set the `Zuora-Version` request header to `211.0` or a later available version.
- The credit memo is only available if you have the Invoice Settlement feature enabled.
format: date
type: string
required:
- resumePolicy
type: object
PUTSubscriptionResumeResponseType:
properties:
creditMemoId:
description: |
The credit memo ID, if a credit memo is generated during the subscription process.
**Note:** This container is only available if you set the Zuora REST API minor version to 207.0 or later [available versions](https://developer.zuora.com/api-references/api/overview/#section/API-Versions/Minor-Version) in the request header, and you have [Invoice Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement) 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
invoiceId:
description: |
Invoice ID, if an invoice is generated during the subscription process.
type: string
paidAmount:
description: |
Payment amount, if a payment is collected.
type: number
paymentId:
description: |
Payment ID, if a payment is collected.
type: string
resumeDate:
description: |
The date when subscription resumption takes effect, as yyyy-mm-dd.
format: date
type: string
subscriptionId:
description: |
The subscription ID.
type: string
success:
description: |
Returns `true` if the request was processed successfully.
type: boolean
termEndDate:
description: |
The date when the new subscription term ends, as yyyy-mm-dd.
format: date
type: string
totalDeltaTcv:
description: |
Change in the total contracted value of the subscription as a result of the update.
type: number
type: object
PUTSubscriptionSuspendType:
example:
suspendPolicy: Today
properties:
applicationOrder:
description: |
The priority order to apply credit memos and/or unapplied payments to an invoice. Possible item values are: `CreditMemo`, `UnappliedPayment`.
**Note:**
- This field is valid only if the `applyCredit` field is set to `true`.
- If no value is specified for this field, the default priority order is used, ["CreditMemo", "UnappliedPayment"], to apply credit memos first and then apply unapplied payments.
- If only one item is specified, only the items of the spedified type are applied to invoices. For example, if the value is `["CreditMemo"]`, only credit memos are used to apply to invoices.
items:
type: string
type: array
applyCredit:
description: |
If the value is true, the credit memo or unapplied payment on the order account will be automatically applied to the invoices generated by this order. The credit memo generated by this order will not be automatically applied to any invoices.
**Note:** This field is only available if you have [Invoice Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement) 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: boolean
applyCreditBalance:
description: |
Whether to automatically apply a credit balance to an invoice.
If the value is `true`, the credit balance is applied to the invoice. If the value is `false`, no action is taken.
To view the credit balance adjustment, retrieve the details of the invoice using the Get Invoices method.
Prerequisite: `invoice` must be `true`.
**Note:**
- If you are using the field `invoiceCollect` rather than the field `invoice`, the `invoiceCollect` value must be `true`.
- This field is deprecated if you have the Invoice Settlement feature enabled.
type: boolean
bookingDate:
description: |
The booking date that you want to set for the amendment contract when you suspend the subscription. If `resume` is `true`, which means you also choose to resume the subscription at some point, then this field is also the booking date for the Resume amendment contract.
This field must be in the `yyyy-mm-dd` format. The default value of this field is the current date when you make the API call.
format: date
type: string
collect:
default: false
description: |
Collects an automatic payment for a subscription. The collection generated in this operation is only for this subscription, not for the entire customer account.
If the value is `true`, the automatic payment is collected. If the value is `false`, no action is taken.
Prerequisite: The `invoice` or `runBilling` field must be `true`.
**Note**: This field is available only if you are on the latest Zuora API version, or you set the `Zuora-Version` request header to `196.0` or a later available version.
type: boolean
contractEffectiveDate:
description: |
The date when the customer notifies you that they want to amend their subscription.
format: date
type: string
creditMemoReasonCode:
description: A code identifying the reason for the credit memo transaction that is generated by the request. The value must be an existing reason code. If you do not pass the field or pass the field with empty value, Zuora uses the default reason code.
type: string
documentDate:
description: |
The date of the billing document, in `yyyy-mm-dd` format. It represents the invoice date for invoices, credit memo date for credit memos, and debit memo date for debit memos.
- If this field is specified, the specified date is used as the billing document date.
- If this field is not specified, the date specified in the `targetDate` is used as the billing document date.
format: date
type: string
extendsTerm:
description: |
Whether to extend the subscription term by the length of time the suspension is in effect. Values: `true`, `false`.
type: boolean
orderDate:
description: |
The date when the order is signed. If no additinal contractEffectiveDate is provided, this order will use this order date as the contract effective date.
This field must be in the `yyyy-mm-dd` format.
This field is required for Orders customers only, not applicable to Orders Harmonization customers.
format: date
type: string
resume:
description: |
Whether to set when to resume a subscription when creating a suspend amendment. Values: `true`, `false`.
type: boolean
resumePeriods:
description: |
The length of the period used to specify when the subscription is resumed. The subscription resumption takes effect after a specified period based on the suspend date or today's date. You must use this field together with the `resumePeriodsType` field to specify the period.
**Note:** This field is only applicable when the `suspendPolicy` field is set to `FixedPeriodsFromToday` or `FixedPeriodsFromSuspendDate`.
type: string
resumePeriodsType:
description: |
The period type used to define when the subscription resumption takes effect. The subscription resumption takes effect after a specified period based on the suspend date or today's date. You must use this field together with the resumePeriods field to specify the period.
Values: `Day`, `Week`, `Month`, `Year`
**Note:** This field is only applicable when the `suspendPolicy` field is set to `FixedPeriodsFromToday` or `FixedPeriodsFromSuspendDate`.
type: string
resumePolicy:
description: |
Resume methods. Specify a way to resume a subscription. Values:
* `Today`: The subscription resumption takes effect on today's date.
* `FixedPeriodsFromSuspendDate`: The subscription resumption takes effect after a specified period based on the suspend date. You must specify the `resumePeriods` and `resumePeriodsType` fields to define the period.
* `SpecificDate`: The subscription resumption takes effect on a specific date. You must define the specific date in the `resumeSpecificDate` field.
* `FixedPeriodsFromToday`: The subscription resumption takes effect after a specified period based on the today's date. You must specify the `resumePeriods` and `resumePeriodsType` fields to define the period.
* `suspendDate`: The subscription resumption takes effect on the date of suspension of the subscription.
type: string
resumeSpecificDate:
description: |
A specific date when the subscription resumption takes effect, in the format yyyy-mm-dd.
**Note:** This field is only applicable only when the `resumePolicy` field is set to `SpecificDate`.
The value should not be earlier than the subscription suspension date.
format: date
type: string
runBilling:
default: false
description: |
Creates an invoice for a subscription. If you have the Invoice Settlement feature enabled, a credit memo might also be created based on the [invoice and credit memo generation rule](https://knowledgecenter.zuora.com/CB_Billing/Invoice_Settlement/Credit_and_Debit_Memos/Rules_for_Generating_Invoices_and_Credit_Memos).
The billing documents generated
in this operation is only for this subscription, not for the entire
customer account.
Possible values:
- `true`: An invoice is created. If you have the Invoice Settlement feature enabled, a credit memo might also be created.
- `false`: No invoice is created.
**Note**: This field is available only if you are on the latest Zuora API version, or you set the `Zuora-Version` request header to `211.0` or a later available version.
type: boolean
suspendPeriods:
description: |
The length of the period used to specify when the subscription suspension takes effect. The subscription suspension takes effect after a specified period based on today's date. You must use this field together with the `suspendPeriodsType` field to specify the period.
**Note:** This field is only applicable only when the suspendPolicy field is set to FixedPeriodsFromToday.
type: string
suspendPeriodsType:
description: |
The period type used to define when the subscription suspension takes effect. The subscription suspension takes effect after a specified period based on today's date. You must use this field together with the suspendPeriods field to specify the period.
Type: string (enum)
Values: `Day`, `Week`, `Month`, `Year`
**Note:** This field is only applicable only when the suspendPolicy field is set to FixedPeriodsFromToday.
type: string
suspendPolicy:
description: |
Suspend methods. Specify a way to suspend a subscription.
Value:
* `Today`: The subscription suspension takes effect on today's date.
* `EndOfLastInvoicePeriod`: The subscription suspension takes effect at the end of the last invoice period. The suspend date defaults to a date that is one day after the last invoiced period. You can choose this option to avoid any negative invoices (credits) issued back to the customer after the subscription suspension.
* `SpecificDate`: The subscription suspension takes effect on a specific date. You must define the specific date in the `suspendSpecificDate` field.
* `FixedPeriodsFromToday`: The subscription suspension takes effect after a specified period based on today's date. You must specify the `suspendPeriods` and `suspendPeriodsType` fields to define the period.
type: string
suspendSpecificDate:
description: |
A specific date when the subscription suspension takes effect, in the format yyyy-mm-dd.
**Note:** This field is only applicable only when the suspendPolicy field is set to SpecificDate.
The value should not be earlier than the subscription contract effective date, later than the subscription term end date, or within a period for which the customer has been invoiced.
format: date
type: string
targetDate:
description: |
Date through which to calculate charges if an invoice or a credit memo is generated, as
yyyy-mm-dd. Default is current date.
This field is available only if you are on the latest Zuora API version, or you set the `Zuora-Version` request header to `211.0` or a later available version.
**Note:** The credit memo is only available if you have the Invoice Settlement feature enabled.
format: date
type: string
required:
- suspendPolicy
type: object
PUTSubscriptionSuspendResponseType:
properties:
creditMemoId:
description: |
The credit memo ID, if a credit memo is generated during the subscription process.
**Note:** This container is only available if you set the Zuora REST API minor version to 207.0 or later [available versions](https://developer.zuora.com/api-references/api/overview/#section/API-Versions/Minor-Version) in the request header, and you have [Invoice Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement) 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
invoiceId:
description: |
Invoice ID, if an invoice is generated during the subscription process.
type: string
paidAmount:
description: |
Payment amount, if a payment is collected.
type: number
paymentId:
description: |
Payment ID, if a payment is collected.
type: string
resumeDate:
description: |
The date when subscription resumption takes effect, in the format yyyy-mm-dd.
format: date
type: string
nullable: true
subscriptionId:
description: |
The subscription ID.
type: string
success:
description: |
Returns `true` if the request was processed successfully.
type: boolean
suspendDate:
description: |
The date when subscription suspension takes effect, in the format yyyy-mm-dd.
format: date
type: string
termEndDate:
description: |
The date when the new subscription term ends, in the format yyyy-mm-dd.
format: date
type: string
totalDeltaTcv:
description: |
Change in the total contracted value of the subscription as a result of the update.
type: number
type: object
PUTDeleteSubscriptionResponseType:
properties:
success:
description: Returns `true` if the request is processed successfully.
type: boolean
type: object
PUTSubscriptionPatchSpecificVersionRequestType:
example:
customFields:
CustomTag__c: internal
properties:
customFields:
$ref: '#/components/schemas/SubscriptionObjectCustomFields'
ratePlans:
items:
properties:
charges:
items:
properties:
chargeId:
description: |
Use either this field or the `chargeNumber` field to specify the charge for which you will be updating the custom fields. By using this field you actually specify a specific charge segment of a charge. See [Segmented rate plan charges](https://knowledgecenter.zuora.com/Central_Platform/API/G_SOAP_API/E1_SOAP_API_Object_Reference/RatePlanCharge#Segmented_rate_plan_charges) for more information about charge segments.
type: string
chargeNumber:
description: |
Use either this field or the `chargeId` field to specify the charge for which you will be updating the custom fields. By using this field you actually specify the last charge segment of a charge. See [Segmented rate plan charges](https://knowledgecenter.zuora.com/Central_Platform/API/G_SOAP_API/E1_SOAP_API_Object_Reference/RatePlanCharge#Segmented_rate_plan_charges) for more information about charge segments.
type: string
customFields:
$ref: '#/components/schemas/RatePlanChargeObjectCustomFields'
type: object
type: array
customFields:
$ref: '#/components/schemas/RatePlanObjectCustomFields'
ratePlanId:
description: The rate plan id in any version of the subscription. This will be linked to the only one rate plan in the current version.
type: string
required:
- ratePlanId
type: object
type: array
type: object
GETMetricsBySubscriptionNumbersResponse:
allOf:
- $ref: '#/components/schemas/CommonResponse'
- properties:
subscriptionMetrics:
items:
properties:
subscriptionNumber:
description: |
The number for the subscription.
type: string
contractedMrr:
description: |
Monthly recurring revenue of the subscription.
type: number
contractedNetMrr:
description: |
Monthly recurring revenue of the subscription rate plan inclusive of all the discounts applicable, including the fixed-amount discounts and percentage discounts.
type: number
asOfDayGrossMrr:
description: |
Monthly recurring revenue of the subscription rate plan exclusive of any discounts applicable as of specified day.
type: number
asOfDayNetMrr:
description: |
Monthly recurring revenue of the subscription rate plan inclusive of all the discounts applicable, including the fixed-amount discounts and percentage discounts as of specified day.
type: number
netTotalContractedValue:
description: |
Total contracted value of the subscription inclusive of all the discounts applicable, including the fixed-amount discounts and percentage discounts.
type: number
totalContractedValue:
description: |
Total contracted value of the subscription.
type: number
type: object
type: array
type: object
GetOrderActionRatePlanResponse:
allOf:
- $ref: '#/components/schemas/CommonResponse'
- properties:
amendment:
$ref: '#/components/schemas/OrderActionRatePlanAmendment'
externallyManagedPlanId:
description: |
The unique identifier for the rate plan purchased on a third-party store. This field is used to represent a subscription rate plan created through third-party stores.
type: string
id:
description: Unique subscription rate-plan ID.
type: string
lastChangeType:
description: |
Latest change type. Possible values are:
- New
- Update
- Remove
type: string
order:
$ref: '#/components/schemas/OrderActionRatePlanOrder'
productId:
description: |
Product ID
type: string
productName:
description: |
The name of the product.
type: string
productRatePlanId:
description: |
Product rate plan ID
type: string
productSku:
description: |
The unique SKU for the product.
type: string
ratePlanName:
description: |
The name of the rate plan.
type: string
subscriptionId:
description: |
Subscription ID.
type: string
subscriptionVersion:
description: |
The version of the subscription.
type: object
OrderActionRatePlanAmendment:
description: |
The amendment that is related to the subscription rate plan.
properties:
code:
description: |
The amendment code.
type: string
contractEffectiveDate:
description: |
The date when the amendment becomes effective for billing purposes, as `yyyy-mm-dd`.
format: date
type: string
createdBy:
description: |
The ID of the user who created this amendment.
type: string
createdDate:
description: The time that the amendment gets created in the system, in the `YYYY-MM-DD HH:MM:SS` format.
format: datetime
type: string
customerAcceptanceDate:
description: |
The date when the customer accepts the amendment changes to the subscription, as `yyyy-mm-dd`.
format: date
type: string
description:
description: |
Description of the amendment.
type: string
effectiveDate:
description: |
The date when the amendment changes take effective.
format: date
type: string
id:
description: |
The amendment ID.
type: string
name:
description: |
The name of the amendment.
type: string
serviceActivationDate:
description: |
The date when service is activated, as `yyyy-mm-dd`.
format: date
type: string
type:
description: |
Type of the amendment.
Possible values are:
- NewProduct
- RemoveProduct
- UpdateProduct
type: string
updatedBy:
description: The ID of the user who updated this amendment.
type: string
updatedDate:
description: The time that the amendment gets updated in the system, in the `YYYY-MM-DD HH:MM:SS` format.
format: datetime
type: string
customFields:
additionalProperties:
description: |
Custom fields of the Amendment object. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
description: |
Container for custom fields of an Amendment object.
type: object
OrderActionRatePlanOrder:
description: |
The order that is related to the subscription rate plan.
properties:
id:
description: The order ID.
type: string
orderActions:
items:
$ref: '#/components/schemas/OrderActionRatePlanOrderAction'
type: array
orderNumber:
description: The order number of the order.
type: string
type: object
OrderActionRatePlanOrderAction:
description: Represents the processed order action.
properties:
addProduct:
$ref: '#/components/schemas/OrderActionRatePlanRatePlanOverride'
id:
description: The Id of the order action processed in the order.
type: string
removeProduct:
$ref: '#/components/schemas/OrderActionRatePlanRemoveProduct'
type:
description: Type of the order action.
enum:
- AddProduct
- UpdateProduct
- RemoveProduct
type: string
updateProduct:
$ref: '#/components/schemas/OrderActionRatePlanRatePlanUpdate'
customFields:
$ref: '#/components/schemas/OrderActionRatePlanOrderActionObjectCustomFields'
type: object
OrderActionRatePlanRatePlanOverride:
description: |
Rate plan associated with a subscription.
properties:
chargeOverrides:
description: |
List of charges associated with the rate plan.
items:
$ref: '#/components/schemas/OrderActionRatePlanChargeOverride'
type: array
customFields:
$ref: '#/components/schemas/OrderActionRatePlanRatePlanObjectCustomFields'
newRatePlanId:
description: |
Internal identifier of the rate plan.
type: string
productRatePlanId:
description: |
Internal identifier of the product rate plan that the rate plan is based on.
type: string
uniqueToken:
description: |
Unique identifier for the rate plan. This identifier enables you to refer to the rate plan before the rate plan has an internal identifier in Zuora.
For instance, suppose that you want to use a single order to add a product to a subscription and later update the same product. When you add the product, you can set a unique identifier for the rate plan. Then when you update the product, you can use the same unique identifier to specify which rate plan to modify.
maxLength: 50
type: string
required:
- productRatePlanId
title: ratePlan
type: object
OrderActionRatePlanRemoveProduct:
description: |
Information about an order action of type `RemoveProduct`.
properties:
ratePlanId:
description: |
Internal identifier of the rate plan to remove.
type: string
uniqueToken:
description: A unique string to represent the rate plan charge in the order. The unique token is used to perform multiple actions against a newly added rate plan. For example, if you want to add and update a product in the same order, you would assign a unique token to the product rate plan when added and use that token in future order actions.A unique string in the order to represent the rate plan.
type: string
title: removeProduct
type: object
OrderActionRatePlanRatePlanUpdate:
description: |
Information about an order action of type `UpdateProduct`.
properties:
chargeUpdates:
items:
$ref: '#/components/schemas/OrderActionRatePlanChargeUpdate'
type: array
customFields:
$ref: '#/components/schemas/OrderActionRatePlanRatePlanObjectCustomFields'
newRatePlanId:
description: |
Internal identifier of the updated rate plan in the new subscription version.
type: string
ratePlanId:
description: |
Internal identifier of the rate plan that was updated.
type: string
specificUpdateDate:
description: |
The specific date when the Update Product order action takes effect. This field allows you to update a charge before a future-dated Update Product order action on the subscription. The format of the date is yyyy-mm-dd.
**Note**: After you use this option, the charge's `TriggerEvent` field value will be changed to `SpecificDate`.
See [Update a Product on Subscription with Future-dated Updates](https://knowledgecenter.zuora.com/BC_Subscription_Management/Orders/AC_Orders_Tutorials/C_Update_a_Product_in_a_Subscription/Update_a_Product_on_Subscription_with_Future-dated_Updates) for more information about this feature.
format: date
type: string
uniqueToken:
description: |
A unique string to represent the rate plan charge in the order. The unique token is used to perform multiple actions against a newly added rate plan. For example, if you want to add and update a product in the same order, you would assign a unique token to the product rate plan when added and use that token in future order actions.
type: string
title: updateProduct
type: object
OrderActionRatePlanOrderActionObjectCustomFields:
additionalProperties:
description: |
Custom fields of the Order Action object. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
description: |
Container for custom fields of an Order Action object.
title: orderActionFieldsCustom
type: object
OrderActionRatePlanChargeUpdate:
description: The JSON object containing the information for a charge update in the 'UpdateProduct' type order action.
properties:
billing:
allOf:
- $ref: '#/components/schemas/OrderActionRatePlanBillingUpdate'
description: |
Billing information about the charge.
chargeNumber:
description: |
Read only. Identifies the charge to be updated.
type: string
customFields:
$ref: '#/components/schemas/OrderActionRatePlanRatePlanChargeObjectCustomFields'
description:
description: |
Description of the charge.
type: string
effectiveDate:
$ref: '#/components/schemas/OrderActionRatePlanTriggerParams'
pricing:
allOf:
- $ref: '#/components/schemas/OrderActionRatePlanPricingUpdate'
description: |
Pricing information about the charge.
uniqueToken:
description: |
A unique string to represent the rate plan charge in the order. The unique token is used to perform multiple actions against a newly added rate plan. For example, if you want to add and update a product in the same order, you would assign a unique token to the product rate plan when added and use that token in future order actions.
type: string
type: object
OrderActionRatePlanRatePlanObjectCustomFields:
additionalProperties:
description: |
Custom fields of the Rate Plan object. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
description: |
Container for custom fields of a Rate Plan object.
title: RatePlanCustomFields
type: object
OrderActionRatePlanBillingUpdate:
properties:
billingPeriodAlignment:
enum:
- AlignToCharge
- AlignToSubscriptionStart
- AlignToTermStart
type: string
type: object
OrderActionRatePlanRatePlanChargeObjectCustomFields:
additionalProperties:
description: |
Custom fields of the Rate Plan Charge object. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
description: |
Container for custom fields of a Rate Plan Charge object.
title: ratePlanChargeFieldsCustom
type: object
OrderActionRatePlanTriggerParams:
description: |
Specifies when a charge becomes active.
properties:
specificTriggerDate:
description: |
Date in YYYY-MM-DD format. Only applicable if the value of the `triggerEvent` field is `SpecificDate`.
While this field is applicable, if this field is not set, your `CreateSubscription` order action creates a `Pending` order and a `Pending Acceptance` subscription. If at the same time the service activation date is required and not set, a `Pending Activation` subscription is created.
While this field is applicable, if this field is not set, the following order actions create a `Pending` order but do not impact the subscription status. **Note**: This feature is in **Limited Availability**. If you want to have access to the feature, submit a request at [Zuora Global Support](http://support.zuora.com/).
* AddProduct
* UpdateProduct
* RemoveProduct
* RenewSubscription
* TermsAndConditions
format: date
type: string
triggerEvent:
description: |
Condition for the charge to become active.
If the value of this field is `SpecificDate`, use the `specificTriggerDate` field to specify the date when the charge becomes active.
enum:
- ContractEffective
- ServiceActivation
- CustomerAcceptance
type: string
title: startDate
type: object
OrderActionRatePlanPricingUpdate:
properties:
chargeModelData:
allOf:
- $ref: '#/components/schemas/OrderActionRatePlanChargeModelDataOverride'
description: |
Container for charge model configuration data.
discount:
allOf:
- $ref: '#/components/schemas/OrderActionRatePlanDiscountPricingUpdate'
description: |
Pricing information about a discount charge.
recurringDelivery:
allOf:
- $ref: '#/components/schemas/OrderActionRatePlanRecurringDeliveryPricingUpdate'
description: |
Pricing information about a recurring charge that uses the Delivery Pricing charge model. In this charge model, the charge has a fixed price. This field is only available if you have the Delivery Pricing charge model enabled.
recurringFlatFee:
allOf:
- $ref: '#/components/schemas/OrderActionRatePlanRecurringFlatFeePricingUpdate'
description: |
Pricing information about a recurring charge that uses the "flat fee" charge model. In this charge model, the charge has a fixed price.
recurringPerUnit:
allOf:
- $ref: '#/components/schemas/OrderActionRatePlanRecurringPerUnitPricingUpdate'
description: |
Pricing information about a recurring charge that uses the "per unit" charge model. In this charge model, the charge has a fixed price per unit purchased.
recurringTiered:
allOf:
- $ref: '#/components/schemas/OrderActionRatePlanRecurringTieredPricingUpdate'
description: |
Pricing information about a recurring charge that uses the "tiered pricing" charge model. In this charge model, the charge has cumulative pricing tiers that become effective as units are purchased.
recurringVolume:
allOf:
- $ref: '#/components/schemas/OrderActionRatePlanRecurringVolumePricingUpdate'
description: |
Pricing information about a recurring charge that uses the "volume pricing" charge model. In this charge model, the charge has a variable price per unit, depending on how many units are purchased.
usageFlatFee:
allOf:
- $ref: '#/components/schemas/OrderActionRatePlanUsageFlatFeePricingUpdate'
description: |
Pricing information about a usage charge that uses the "flat fee" charge model. In this charge model, the charge has a fixed price.
usageOverage:
allOf:
- $ref: '#/components/schemas/OrderActionRatePlanUsageOveragePricingUpdate'
description: |
Pricing information about a usage charge that uses the "overage" charge model. In this charge model, the charge has an allowance of free units and a fixed price per additional unit consumed.
usagePerUnit:
allOf:
- $ref: '#/components/schemas/OrderActionRatePlanUsagePerUnitPricingUpdate'
description: |
Pricing information about a usage charge that uses the "per unit" charge model. In this charge model, the charge has a fixed price per unit consumed.
usageTiered:
allOf:
- $ref: '#/components/schemas/OrderActionRatePlanUsageTieredPricingUpdate'
description: |
Pricing information about a usage charge that uses the "tiered pricing" charge model. In this charge model, the charge has cumulative pricing tiers that become effective as units are consumed.
usageTieredWithOverage:
allOf:
- $ref: '#/components/schemas/OrderActionRatePlanUsageTieredWithOveragePricingUpdate'
description: |
Pricing information about a usage charge that uses the "tiered with overage" charge model. In this charge model, the charge has cumulative pricing tiers that become effective as units are consumed. The charge also has a fixed price per unit consumed beyond the limit of the final tier.
usageVolume:
allOf:
- $ref: '#/components/schemas/OrderActionRatePlanUsageVolumePricingUpdate'
description: |
Pricing information about a usage charge that uses the "volume pricing" charge model. In this charge model, the charge has a variable price per unit, depending on how many units are consumed.
type: object
OrderActionRatePlanChargeModelDataOverride:
description: |
Container for charge model configuration data.
**Note**: This field is only available if you have the High Water Mark, Pre-Rated Pricing, or Multi-Attribute Pricing charge models enabled. The charge models are available for customers with Enterprise and Nine editions by default. If you are a Growth customer, see [Zuora Editions](https://docs.zuora.com/en/entitlements/current-entitlements/zuora-editions) for pricing information.
properties:
chargeModelConfiguration:
properties:
customFieldPerUnitRate:
description: |
The custom field that carries the per-unit rate for each usage record. For example, `perUnitAmount__c`.
This field is only available for the usage-based charges that use the Pre-Rated Per Unit Pricing charge model. The charge model is available for customers with Enterprise and Nine editions by default. If you are a Growth customer, see [Zuora Editions](https://docs.zuora.com/en/entitlements/current-entitlements/zuora-editions) for pricing information.
type: string
customFieldTotalAmount:
description: |
The custom field that carries the total amount to charge for a usage record. For example, `totalAmount__c`.
This field is only available for the usage-based charges that use the Pre-Rated Pricing charge model. The charge model is available for customers with Enterprise and Nine editions by default. If you are a Growth customer, see [Zuora Editions](https://docs.zuora.com/en/entitlements/current-entitlements/zuora-editions) for pricing information.
type: string
formula:
description: |
The pricing formula to calculate actual rating amount for each usage record.
This field is only available for the usage-based charges that use the Multi-Attribute Pricing charge model. The charge model is available for customers with Enterprise and Nine editions by default. If you are a Growth customer, see [Zuora Editions](https://docs.zuora.com/en/entitlements/current-entitlements/zuora-editions) for pricing information.
type: string
type: object
tiers:
description: |
List of cumulative pricing tiers in the charge.
**Note**: When you override tiers of the charge with a High Water Mark Pricing charge model, you have to provide all of the tiers, including the ones you do not want to change. The new tiers will completely override the previous ones. The High Water Mark Pricing charge models are available for customers with Enterprise and Nine editions by default. If you are a Growth customer, see [Zuora Editions](https://docs.zuora.com/en/entitlements/current-entitlements/zuora-editions) for pricing information.
items:
$ref: '#/components/schemas/OrderActionRatePlanChargeTier'
type: array
title: chargeModelData
type: object
OrderActionRatePlanDiscountPricingUpdate:
properties:
applyDiscountTo:
description: |
Specifies which type of charge the discount charge applies to.
enum:
- ONETIME
- RECURRING
- USAGE
- ONETIMERECURRING
- ONETIMEUSAGE
- RECURRINGUSAGE
- ONETIMERECURRINGUSAGE
type: string
discountLevel:
description: |
Application scope of the discount charge. For example, if the value of this field is `subscription` and the value of the `applyDiscountTo` field is `RECURRING`, the discount charge applies to all recurring charges in the same subscription as the discount charge.
enum:
- rateplan
- subscription
- account
type: string
discountPercentage:
description: |
The amount of the discount as a percentage. This field is only used for percentage discounts.
type: number
priceChangeOption:
description: |
Specifies how Zuora changes the price of the charge each time the subscription renews.
enum:
- NoChange
- UseLatestProductCatalogPricing
type: string
type: object
OrderActionRatePlanRecurringDeliveryPricingUpdate:
allOf:
- $ref: '#/components/schemas/OrderActionRatePlanPriceChangeParams'
- properties:
deliverySchedule:
$ref: '#/components/schemas/DeliveryScheduleParams'
listPrice:
type: number
type: object
OrderActionRatePlanRecurringFlatFeePricingUpdate:
allOf:
- $ref: '#/components/schemas/OrderActionRatePlanPriceChangeParams'
- properties:
listPrice:
type: number
type: object
OrderActionRatePlanRecurringPerUnitPricingUpdate:
allOf:
- $ref: '#/components/schemas/OrderActionRatePlanPriceChangeParams'
- properties:
listPrice:
type: number
quantity:
minimum: 0
type: number
type: object
OrderActionRatePlanRecurringTieredPricingUpdate:
allOf:
- $ref: '#/components/schemas/OrderActionRatePlanPriceChangeParams'
- properties:
quantity:
minimum: 0
type: number
tiers:
items:
$ref: '#/components/schemas/OrderActionRatePlanChargeTier'
type: array
type: object
OrderActionRatePlanRecurringVolumePricingUpdate:
allOf:
- $ref: '#/components/schemas/OrderActionRatePlanPriceChangeParams'
- properties:
quantity:
minimum: 0
type: number
tiers:
items:
$ref: '#/components/schemas/OrderActionRatePlanChargeTier'
type: array
type: object
OrderActionRatePlanUsageFlatFeePricingUpdate:
allOf:
- $ref: '#/components/schemas/OrderActionRatePlanPriceChangeParams'
- properties:
listPrice:
type: number
type: object
OrderActionRatePlanUsageOveragePricingUpdate:
allOf:
- $ref: '#/components/schemas/OrderActionRatePlanPriceChangeParams'
- properties:
includedUnits:
description: |
A certain quantity of units for free in the overage charge model. It cannot be negative. It must be 0 and above. Decimals are allowed.
type: number
overagePrice:
type: number
type: object
OrderActionRatePlanUsagePerUnitPricingUpdate:
allOf:
- $ref: '#/components/schemas/OrderActionRatePlanPriceChangeParams'
- properties:
listPrice:
type: number
type: object
OrderActionRatePlanUsageTieredPricingUpdate:
allOf:
- $ref: '#/components/schemas/OrderActionRatePlanPriceChangeParams'
- properties:
tiers:
items:
$ref: '#/components/schemas/OrderActionRatePlanChargeTier'
type: array
type: object
OrderActionRatePlanUsageTieredWithOveragePricingUpdate:
allOf:
- $ref: '#/components/schemas/OrderActionRatePlanPriceChangeParams'
- properties:
overagePrice:
type: number
tiers:
items:
$ref: '#/components/schemas/OrderActionRatePlanChargeTier'
type: array
type: object
OrderActionRatePlanUsageVolumePricingUpdate:
allOf:
- $ref: '#/components/schemas/OrderActionRatePlanPriceChangeParams'
- properties:
tiers:
items:
$ref: '#/components/schemas/OrderActionRatePlanChargeTier'
type: array
type: object
OrderActionRatePlanPriceChangeParams:
properties:
priceChangeOption:
description: |
Specifies how Zuora changes the price of the charge each time the subscription renews.
If the value of this field is `SpecificPercentageValue`, use the `priceIncreasePercentage` field to specify how much the price of the charge should change.
enum:
- NoChange
- SpecificPercentageValue
- UseLatestProductCatalogPricing
type: string
priceIncreasePercentage:
description: |
Specifies the percentage by which the price of the charge should change each time the subscription renews. Only applicable if the value of the `priceChangeOption` field is `SpecificPercentageValue`.
minimum: -100
type: number
type: object
OrderActionRatePlanChargeTier:
properties:
endingUnit:
description: |
Limit on the number of units for which the tier is effective.
type: number
price:
description: |
Price or per-unit price of the tier, depending on the value of the `priceFormat` field.
type: number
priceFormat:
description: |
Specifies whether the tier has a fixed price or a per-unit price.
enum:
- FlatFee
- PerUnit
type: string
startingUnit:
description: |
Number of units at which the tier becomes effective.
type: number
tier:
description: |
Index of the tier in the charge.
minimum: 1
type: integer
required:
- tier
- startingUnit
- price
- priceFormat
title: chargeTier
type: object
OrderActionRatePlanChargeOverride:
description: |
Charge associated with a rate plan.
properties:
billing:
description: |
Billing information about the charge.
properties:
billCycleDay:
description: |
Day of the month that each billing period begins on. Only applicable if the value of the `billCycleType` field is `SpecificDayofMonth`.
maximum: 31
minimum: 0
type: integer
billCycleType:
description: |
Specifies how Zuora determines the day that each billing period begins on.
* `DefaultFromCustomer` - Each billing period begins on the bill cycle day of the account that owns the subscription.
* `SpecificDayofMonth` - Use the `billCycleDay` field to specify the day of the month that each billing period begins on.
* `SubscriptionStartDay` - Each billing period begins on the same day of the month as the start date of the subscription.
* `ChargeTriggerDay` - Each billing period begins on the same day of the month as the date when the charge becomes active.
* `SpecificDayofWeek` - Use the `weeklyBillCycleDay` field to specify the day of the week that each billing period begins on.
enum:
- DefaultFromCustomer
- SpecificDayofMonth
- SubscriptionStartDay
- ChargeTriggerDay
- SpecificDayofWeek
type: string
billingPeriod:
description: |
Billing frequency of the charge. The value of this field controls the duration of each billing period.
If the value of this field is `Specific_Months` or `Specific_Weeks`, use the `specificBillingPeriod` field to specify the duration of each billing period.
enum:
- Month
- Quarter
- Semi_Annual
- Annual
- Eighteen_Months
- Two_Years
- Three_Years
- Five_Years
- Specific_Months
- Subscription_Term
- Week
- Specific_Weeks
type: string
billingPeriodAlignment:
description: |
Specifies how Zuora determines when to start new billing periods. You can use this field to align the billing periods of different charges.
* `AlignToCharge` - Zuora starts a new billing period on the first billing day that falls on or after the date when the charge becomes active.
* `AlignToSubscriptionStart` - Zuora starts a new billing period on the first billing day that falls on or after the start date of the subscription.
* `AlignToTermStart` - For each term of the subscription, Zuora starts a new billing period on the first billing day that falls on or after the start date of the term.
See the `billCycleType` field for information about how Zuora determines the billing day.
**Note**: This field is not supported in one time charges.
enum:
- AlignToCharge
- AlignToSubscriptionStart
- AlignToTermStart
type: string
billingTiming:
description: |
Specifies whether to invoice for a billing period on the first day of the billing period (billing in advance) or the first day of the next billing period (billing in arrears).
enum:
- IN_ADVANCE
- IN_ARREARS
type: string
specificBillingPeriod:
description: |
Duration of each billing period in months or weeks, depending on the value of the `billingPeriod` field. Only applicable if the value of the `billingPeriod` field is `Specific_Months` or `Specific_Weeks`.
type: integer
weeklyBillCycleDay:
description: |
Day of the week that each billing period begins on. Only applicable if the value of the `billCycleType` field is `SpecificDayofWeek`.
enum:
- Sunday
- Monday
- Tuesday
- Wednesday
- Thursday
- Friday
- Saturday
type: string
type: object
chargeNumber:
description: |
Charge number of the charge. For example, C-00000307.
If you do not set this field, Zuora will generate the charge number.
maxLength: 50
type: string
customFields:
$ref: '#/components/schemas/OrderActionRatePlanRatePlanChargeObjectCustomFields'
description:
description: |
Description of the charge.
maxLength: 500
type: string
endDate:
$ref: '#/components/schemas/OrderActionRatePlanEndConditions'
pricing:
description: |
Pricing information about the charge.
properties:
chargeModelData:
$ref: '#/components/schemas/OrderActionRatePlanChargeModelDataOverride'
discount:
$ref: '#/components/schemas/OrderActionRatePlanDiscountPricingOverride'
oneTimeFlatFee:
$ref: '#/components/schemas/OrderActionRatePlanOneTimeFlatFeePricingOverride'
oneTimePerUnit:
$ref: '#/components/schemas/OrderActionRatePlanOneTimePerUnitPricingOverride'
oneTimeTiered:
$ref: '#/components/schemas/OrderActionRatePlanOneTimeTieredPricingOverride'
oneTimeVolume:
$ref: '#/components/schemas/OrderActionRatePlanOneTimeVolumePricingOverride'
recurringDelivery:
$ref: '#/components/schemas/OrderActionRatePlanRecurringDeliveryPricingOverride'
recurringFlatFee:
$ref: '#/components/schemas/OrderActionRatePlanRecurringFlatFeePricingOverride'
recurringPerUnit:
$ref: '#/components/schemas/OrderActionRatePlanRecurringPerUnitPricingOverride'
recurringTiered:
$ref: '#/components/schemas/OrderActionRatePlanRecurringTieredPricingOverride'
recurringVolume:
$ref: '#/components/schemas/OrderActionRatePlanRecurringVolumePricingOverride'
usageFlatFee:
$ref: '#/components/schemas/OrderActionRatePlanUsageFlatFeePricingOverride'
usageOverage:
$ref: '#/components/schemas/OrderActionRatePlanUsageOveragePricingOverride'
usagePerUnit:
$ref: '#/components/schemas/OrderActionRatePlanUsagePerUnitPricingOverride'
usageTiered:
$ref: '#/components/schemas/OrderActionRatePlanUsageTieredPricingOverride'
usageTieredWithOverage:
$ref: '#/components/schemas/OrderActionRatePlanUsageTieredWithOveragePricingOverride'
usageVolume:
$ref: '#/components/schemas/OrderActionRatePlanUsageVolumePricingOverride'
type: object
productRatePlanChargeId:
description: |
Internal identifier of the product rate plan charge that the charge is based on.
type: string
revRecCode:
description: |
Revenue Recognition Code
maxLength: 70
type: string
revRecTriggerCondition:
description: |
Specifies the revenue recognition trigger condition.
* `Contract Effective Date`
* `Service Activation Date`
* `Customer Acceptance Date`
enum:
- Contract Effective Date
- Service Activation Date
- Customer Acceptance Date
type: string
revenueRecognitionRuleName:
description: |
Specifies the revenue recognition rule.
* `Recognize upon invoicing`
* `Recognize daily over time`
enum:
- Recognize upon invoicing
- Recognize daily over time
type: string
startDate:
$ref: '#/components/schemas/OrderActionRatePlanTriggerParams'
uniqueToken:
description: |
Unique identifier for the charge. This identifier enables you to refer to the charge before the charge has an internal identifier in Zuora.
For instance, suppose that you want to use a single order to add a product to a subscription and later update the same product. When you add the product, you can set a unique identifier for the charge. Then when you update the product, you can use the same unique identifier to specify which charge to modify.
maxLength: 50
type: string
required:
- productRatePlanChargeId
title: charge
type: object
OrderActionRatePlanEndConditions:
description: |
Specifies when a charge becomes inactive.
properties:
endDateCondition:
description: |
Condition for the charge to become inactive.
If the value of this field is `Fixed_Period`, the charge is active for a predefined duration based on the value of the `upToPeriodsType` and `upToPeriods` fields.
If the value of this field is `Specific_End_Date`, use the `specificEndDate` field to specify the date when then charge becomes inactive.
enum:
- Subscription_End
- Fixed_Period
- Specific_End_Date
type: string
specificEndDate:
description: |
Date in YYYY-MM-DD format. Only applicable if the value of the `endDateCondition` field is `Specific_End_Date`.
format: date
type: string
upToPeriods:
description: |
Duration of the charge in billing periods, days, weeks, months, or years, depending on the value of the `upToPeriodsType` field. Only applicable if the value of the `endDateCondition` field is `Fixed_Period`.
type: integer
upToPeriodsType:
description: |
Unit of time that the charge duration is measured in. Only applicable if the value of the `endDateCondition` field is `Fixed_Period`.
enum:
- Billing_Periods
- Days
- Weeks
- Months
- Years
type: string
title: endDate
type: object
OrderActionRatePlanDiscountPricingOverride:
description: |
Pricing information about a discount charge.
properties:
applyDiscountTo:
description: |
Specifies which type of charge the discount charge applies to.
enum:
- ONETIME
- RECURRING
- USAGE
- ONETIMERECURRING
- ONETIMEUSAGE
- RECURRINGUSAGE
- ONETIMERECURRINGUSAGE
type: string
discountAmount:
description: |
Only applicable if the discount charge is a fixed-amount discount.
type: number
discountLevel:
description: |
Application scope of the discount charge. For example, if the value of this field is `subscription` and the value of the `applyDiscountTo` field is `RECURRING`, the discount charge applies to all recurring charges in the same subscription as the discount charge.
enum:
- rateplan
- subscription
- account
type: string
discountPercentage:
description: |
Only applicable if the discount charge is a percentage discount.
type: number
priceChangeOption:
description: |
Specifies how Zuora changes the price of the charge each time the subscription renews.
enum:
- NoChange
- UseLatestProductCatalogPricing
type: string
title: discount
type: object
OrderActionRatePlanOneTimeFlatFeePricingOverride:
description: |
Pricing information about a one-time charge that uses the "flat fee" charge model. In this charge model, the charge has a fixed price.
properties:
listPrice:
description: |
Price of the charge.
type: number
required:
- listPrice
title: oneTimeFlatFee
type: object
OrderActionRatePlanOneTimePerUnitPricingOverride:
description: |
Pricing information about a one-time charge that uses the "per unit" charge model. In this charge model, the charge has a fixed price per unit purchased.
properties:
listPrice:
description: |
Per-unit price of the charge.
type: number
quantity:
description: |
Number of units purchased.
minimum: 0
type: number
title: oneTimePerUnit
type: object
OrderActionRatePlanOneTimeTieredPricingOverride:
description: |
Pricing information about a one-time charge that uses the "tiered pricing" charge model. In this charge model, the charge has cumulative pricing tiers that become effective as units are purchased.
properties:
quantity:
description: |
Number of units purchased.
minimum: 0
type: number
tiers:
description: |
List of cumulative pricing tiers in the charge.
items:
$ref: '#/components/schemas/OrderActionRatePlanChargeTier'
type: array
title: oneTimeTiered
type: object
OrderActionRatePlanOneTimeVolumePricingOverride:
description: |
Pricing information about a one-time charge that uses the "volume pricing" charge model. In this charge model, the charge has a variable price per unit, depending on how many units are purchased.
properties:
quantity:
description: |
Number of units purchased.
minimum: 0
type: number
tiers:
description: |
List of variable pricing tiers in the charge.
items:
$ref: '#/components/schemas/OrderActionRatePlanChargeTier'
type: array
title: oneTimeVolume
type: object
OrderActionRatePlanRecurringDeliveryPricingOverride:
allOf:
- $ref: '#/components/schemas/OrderActionRatePlanPriceChangeParams'
- properties:
deliverySchedule:
$ref: '#/components/schemas/DeliveryScheduleParams'
listPrice:
description: |
Price of the charge in each recurring period.
type: number
type: object
description: |
Pricing information about a recurring charge that uses the Delivery Pricing charge model. In this charge model, the charge has a fixed price. This field is only available if you have the Delivery Pricing charge model enabled.
title: recurringDelivery
OrderActionRatePlanRecurringFlatFeePricingOverride:
allOf:
- $ref: '#/components/schemas/OrderActionRatePlanPriceChangeParams'
- properties:
listPrice:
description: |
Price of the charge in each recurring period.
type: number
listPriceBase:
description: |
Specifies the duration of each recurring period.
enum:
- Per_Billing_Period
- Per_Month
- Per_Week
- Per_Year
- Per_Specific_Months
type: string
specificListPriceBase:
description: |
The number of months for the list price base of the charge. The value of this field is `null` if you do not set the value of the `listPriceBase` field to `Per_Specific_Months`.
format: int32
maximum: 200
minimum: 1
type: integer
type: object
description: |
Pricing information about a recurring charge that uses the "flat fee" charge model. In this charge model, the charge has a fixed price.
title: recurringFlatFee
OrderActionRatePlanRecurringPerUnitPricingOverride:
allOf:
- $ref: '#/components/schemas/OrderActionRatePlanPriceChangeParams'
- properties:
listPrice:
description: |
Per-unit price of the charge in each recurring period.
type: number
listPriceBase:
description: |
Specifies the duration of each recurring period.
**Note**: The `Per_Year` and `Per_Specific_Months` enum values are available only if you have the Annual List Price feature enabled.
enum:
- Per_Billing_Period
- Per_Month
- Per_Week
- Per_Year
- Per_Specific_Months
type: string
quantity:
description: |
Number of units purchased.
minimum: 0
type: number
specificListPriceBase:
description: |
The number of months for the list price base of the charge. This field is required if you set the value of the `listPriceBase` field to `Per_Specific_Months`.
format: int32
maximum: 200
minimum: 1
type: integer
type: object
description: |
Pricing information about a recurring charge that uses the "per unit" charge model. In this charge model, the charge has a fixed price per unit purchased.
title: recurringPerUnit
OrderActionRatePlanRecurringTieredPricingOverride:
allOf:
- $ref: '#/components/schemas/OrderActionRatePlanPriceChangeParams'
- properties:
listPriceBase:
description: |
Specifies the duration of each recurring period.
enum:
- Per_Billing_Period
- Per_Month
- Per_Week
- Per_Year
- Per_Specific_Months
type: string
quantity:
description: |
Number of units purchased.
minimum: 0
type: number
specificListPriceBase:
description: |
The number of months for the list price base of the charge. This field is required if you set the value of the `listPriceBase` field to `Per_Specific_Months`.
format: int32
maximum: 200
minimum: 1
type: integer
tiers:
description: |
List of cumulative pricing tiers in the charge.
items:
$ref: '#/components/schemas/OrderActionRatePlanChargeTier'
type: array
type: object
description: |
Pricing information about a recurring charge that uses the "tiered pricing" charge model. In this charge model, the charge has cumulative pricing tiers that become effective as units are purchased.
title: recurringTiered
OrderActionRatePlanRecurringVolumePricingOverride:
allOf:
- $ref: '#/components/schemas/OrderActionRatePlanPriceChangeParams'
- properties:
listPriceBase:
description: |
Specifies the duration of each recurring period.
**Note**: The `Per_Year` and `Per_Specific_Months` enum values are available only if you have the Annual List Price feature enabled.
enum:
- Per_Billing_Period
- Per_Month
- Per_Week
- Per_Year
- Per_Specific_Months
type: string
quantity:
description: |
Number of units purchased.
minimum: 0
type: number
specificListPriceBase:
description: |
The number of months for the list price base of the charge. This field is required if you set the value of the `listPriceBase` field to `Per_Specific_Months`.
format: int32
maximum: 200
minimum: 1
type: integer
tiers:
description: |
List of variable pricing tiers in the charge.
items:
$ref: '#/components/schemas/OrderActionRatePlanChargeTier'
type: array
type: object
description: |
Pricing information about a recurring charge that uses the "volume pricing" charge model. In this charge model, the charge has a variable price per unit, depending on how many units are purchased.
title: recurringVolume
OrderActionRatePlanUsageFlatFeePricingOverride:
allOf:
- $ref: '#/components/schemas/OrderActionRatePlanPriceChangeParams'
- properties:
listPrice:
description: |
Price of the charge.
type: number
type: object
description: |
Pricing information about a usage charge that uses the "flat fee" charge model. In this charge model, the charge has a fixed price.
title: usageFlatFee
OrderActionRatePlanUsageOveragePricingOverride:
allOf:
- $ref: '#/components/schemas/OrderActionRatePlanPriceChangeParams'
- properties:
includedUnits:
description: |
Number of free units that may be consumed.
minimum: 0
type: number
numberOfPeriods:
description: |
Number of periods that Zuora considers when calculating overage charges with overage smoothing.
minimum: 1
type: integer
overagePrice:
description: |
Price per overage unit consumed.
type: number
overageUnusedUnitsCreditOption:
description: |
Specifies whether to credit the customer for unused units.
If the value of this field is `CreditBySpecificRate`, use the `unusedUnitsCreditRates` field to specify the rate at which to credit the customer for unused units.
enum:
- NoCredit
- CreditBySpecificRate
type: string
unusedUnitsCreditRates:
description: |
Per-unit rate at which to credit the customer for unused units. Only applicable if the value of the `overageUnusedUnitsCreditOption` field is `CreditBySpecificRate`.
type: number
type: object
description: |
Pricing information about a usage charge that uses the "overage" charge model. In this charge model, the charge has an allowance of free units and a fixed price per additional unit consumed.
title: usageOverage
OrderActionRatePlanUsagePerUnitPricingOverride:
allOf:
- $ref: '#/components/schemas/OrderActionRatePlanPriceChangeParams'
- properties:
listPrice:
description: |
Per-unit price of the charge.
type: number
ratingGroup:
description: |
Specifies how Zuora groups usage records when rating usage. See [Usage Rating by Group](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Usage/Usage_Rating_by_Group) for more information.
* ByBillingPeriod (default): The rating is based on all the usages in a billing period.
* ByUsageStartDate: The rating is based on all the usages on the same usage start date.
* ByUsageRecord: The rating is based on each usage record.
* ByUsageUpload: The rating is based on all the usages in a uploaded usage file (.xls or .csv). If you import a mass usage in a single upload, which contains multiple usage files in .xls or .csv format, usage records are grouped for each usage file.
enum:
- ByBillingPeriod
- ByUsageStartDate
- ByUsageRecord
- ByUsageUpload
type: string
type: object
description: |
Pricing information about a usage charge that uses the "per unit" charge model. In this charge model, the charge has a fixed price per unit consumed.
title: usagePerUnit
OrderActionRatePlanUsageTieredPricingOverride:
allOf:
- $ref: '#/components/schemas/OrderActionRatePlanPriceChangeParams'
- properties:
ratingGroup:
description: |
Specifies how Zuora groups usage records when rating usage. See [Usage Rating by Group](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Usage/Usage_Rating_by_Group) for more information.
* ByBillingPeriod (default): The rating is based on all the usages in a billing period.
* ByUsageStartDate: The rating is based on all the usages on the same usage start date.
* ByUsageRecord: The rating is based on each usage record.
* ByUsageUpload: The rating is based on all the usages in a uploaded usage file (.xls or .csv). If you import a mass usage in a single upload, which contains multiple usage files in .xls or .csv format, usage records are grouped for each usage file.
enum:
- ByBillingPeriod
- ByUsageStartDate
- ByUsageRecord
- ByUsageUpload
type: string
tiers:
description: |
List of cumulative pricing tiers in the charge.
items:
$ref: '#/components/schemas/OrderActionRatePlanChargeTier'
type: array
type: object
description: |
Pricing information about a usage charge that uses the "tiered pricing" charge model. In this charge model, the charge has cumulative pricing tiers that become effective as units are consumed.
title: usageTiered
OrderActionRatePlanUsageTieredWithOveragePricingOverride:
allOf:
- $ref: '#/components/schemas/OrderActionRatePlanPriceChangeParams'
- properties:
numberOfPeriods:
description: |
Number of periods that Zuora considers when calculating overage charges with overage smoothing.
minimum: 1
type: integer
overagePrice:
description: |
Price per overage unit consumed.
type: number
overageUnusedUnitsCreditOption:
description: |
Specifies whether to credit the customer for unused units.
If the value of this field is `CreditBySpecificRate`, use the `unusedUnitsCreditRates` field to specify the rate at which to credit the customer for unused units.
enum:
- NoCredit
- CreditBySpecificRate
type: string
tiers:
description: |
List of cumulative pricing tiers in the charge.
items:
$ref: '#/components/schemas/OrderActionRatePlanChargeTier'
type: array
unusedUnitsCreditRates:
description: |
Per-unit rate at which to credit the customer for unused units. Only applicable if the value of the `overageUnusedUnitsCreditOption` field is `CreditBySpecificRate`.
type: number
type: object
description: |
Pricing information about a usage charge that uses the "tiered with overage" charge model. In this charge model, the charge has cumulative pricing tiers that become effective as units are consumed. The charge also has a fixed price per unit consumed beyond the limit of the final tier.
title: usageTieredWithOverage
OrderActionRatePlanUsageVolumePricingOverride:
allOf:
- $ref: '#/components/schemas/OrderActionRatePlanPriceChangeParams'
- properties:
ratingGroup:
description: |
Specifies how Zuora groups usage records when rating usage. See [Usage Rating by Group](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Usage/Usage_Rating_by_Group) for more information.
* ByBillingPeriod (default): The rating is based on all the usages in a billing period.
* ByUsageStartDate: The rating is based on all the usages on the same usage start date.
* ByUsageRecord: The rating is based on each usage record.
* ByUsageUpload: The rating is based on all the usages in a uploaded usage file (.xls or .csv). If you import a mass usage in a single upload, which contains multiple usage files in .xls or .csv format, usage records are grouped for each usage file.
enum:
- ByBillingPeriod
- ByUsageStartDate
- ByUsageRecord
- ByUsageUpload
type: string
tiers:
description: |
List of variable pricing tiers in the charge.
items:
$ref: '#/components/schemas/OrderActionRatePlanChargeTier'
type: array
type: object
description: |
Pricing information about a usage charge that uses the "volume pricing" charge model. In this charge model, the charge has a variable price per unit, depending on how many units are consumed.
title: usageVolume
CreateOmniChannelSubscriptionRequest:
example:
externalSubscriptionId: original-transaction-id1
accountId: 8a90b4488e602d56018e6062ff5700a3
externalSourceSystem: Apple
externalTransactionReason: Purchase
externalState: Active
state: Active
externalProductId: external-product-id-1
externalInAppOwnershipType: Purchased
externalQuantity: 1
currency: USD
autoRenew: true
externalPurchaseDate: '2024-02-01 00:01:15'
externalActivationDate: '2024-02-01 00:01:15'
externalExpirationDate: '2024-05-01 00:01:15'
externalApplicationId: 004d58fca978fec3697fec4af1d10065
externalBundleId: 43dcdc4562784ed8a59ece4ef7d98e57
externalSubscriberId: 2466082b6d1149c184a09b15bd5be694
externalPurchaseType: Purchased
externalPrice: 100
externalLastRenewalDate: '2024-10-01 00:00:00'
externalNextRenewalDate: '2025-01-01 00:00:00'
allOf:
- properties:
accountId:
description: |
The ID of the account associated with this subscription.
type: string
externalSubscriptionId:
description: |
The original transaction ID of the notification. This must be unique in the tenant.
type: string
externalTransactionReason:
description: |
The latest transaction reason.
type: string
externalSourceSystem:
description: |
The source app store from which the channel subscription originated. For example, Apple, Google, Roku, Amazon.
type: string
externalState:
description: |
The original status from client, such as active, canceled, expired, pastDue.
type: string
state:
description: |
The common external subscription state.
type: string
externalProductId:
description: |
The product ID in the external system.
type: string
externalReplaceByProductId:
description: |
The product ID is going to replace the existing product ID in the `externalProductId` field during the subscription renewal.
type: string
nullable: true
externalInAppOwnershipType:
description: |
Such as purchased, family_shared.
type: string
externalQuantity:
description: |
The quantity of the product, must be greather than 0.
default: 1
type: integer
currency:
description: |
The currency code of the transaction. If not specified, get value from the Account.
type: string
autoRenew:
description: |
If `true`, the subscription automatically renews at the end of the
term.
default: false
type: boolean
externalPurchaseDate:
description: |
When the App Store charged the user’s account for a purchase, restored product, subscription,
or subscription renewal after a lapse. UTC time, `yyyy-mm-dd hh:mm:ss`.
type: string
format: datetime
externalActivationDate:
description: |
When the external subscription was activated on the external platform.
UTC time, `yyyy-mm-dd hh:mm:ss`.
type: string
format: datetime
externalExpirationDate:
description: |
This expiration date is a static value that applies for each transaction.
UTC time, `yyyy-mm-dd hh:mm:ss`.
type: string
format: datetime
externalApplicationId:
description: |
The external application ID.
type: string
externalBundleId:
description: |
The external bundler ID.
type: string
externalSubscriberId:
description: |
The external subscriber ID.
type: string
externalPrice:
description: |
The price in external system.
type: number
externalPurchaseType:
description: The external purchase type.
type: string
externalLastRenewalDate:
description: |
This last renewal date is a static value that applies for each transaction.
UTC time, `yyyy-mm-dd hh:mm:ss`.
type: string
format: datetime
externalNextRenewalDate:
description: |
This next renewal date is a static value that applies for each transaction.
UTC time, `yyyy-mm-dd hh:mm:ss`.
type: string
format: datetime
accountIdentifierField:
description: The account field used to identify the account in acountData. It could be a custom field.
type: string
accountData:
$ref: '#/components/schemas/OmniChannelAccountData'
required:
- externalSubscriptionId
type: object
- $ref: '#/components/schemas/SubscriptionObjectCustomFields'
CreateOmniChannelSubscriptionResponse:
allOf:
- $ref: '#/components/schemas/CommonResponse'
- properties:
subscriptionId:
description: |
The system generated ID in Billing.
type: string
subscriptionNumber:
description: |
The system generated subscription number.
type: string
accountId:
description: |
The ID of the account associated with this subscription.
type: string
accountNumber:
description: |
The number of the account associated with this subscription.
type: string
OmniChannelAccountData:
description: |
The information of the account that you want to create while creating an omnichannel subscription.
properties:
accountNumber:
maxLength: 70
type: string
description: The number of the account.
name:
maxLength: 255
type: string
description: The name of the account.
currency:
description: |
Three uppercase character currency code.
type: string
notes:
maxLength: 65535
type: string
description: The note for the account.
billToContact:
$ref: '#/components/schemas/ContactInfo'
soldToContact:
$ref: '#/components/schemas/ContactInfo'
customFields:
additionalProperties: true
description: |
Container for custom fields.
title: CustomFields
type: object
required:
- billToContact
- currency
- name
type: object
GetOmniChannelSubscriptionResponse:
allOf:
- $ref: '#/components/schemas/CommonResponse'
- properties:
id:
description: |
The system generated ID in Billing.
type: string
subscriptionNumber:
description: |
The system generated subscription number.
type: string
accountId:
description: |
The ID of the account associated with this subscription.
type: string
externalSubscriptionId:
description: |
The original transaction ID of the notification.
type: string
externalTransactionReason:
description: |
The latest transaction reason.
type: string
externalSourceSystem:
description: |
The source app store from which the channel subscription originated. For example, Apple, Google, Roku, Amazon.
type: string
externalState:
description: |
The original status from client, such as active, canceled, expired, pastDue.
type: string
state:
description: |
The common external subscription state.
type: string
externalProductId:
description: |
The product ID in the external system.
type: string
externalReplaceByProductId:
description: |
The product ID is going to replace the existing product ID in the `externalProductId` field during the subscription renewal.
type: string
nullable: true
externalInAppOwnershipType:
description: |
Such as purchased, family_shared.
type: string
externalQuantity:
description: |
The quantity of the product, must be greater than 0.
default: 1
type: integer
currency:
description: |
The currency code of the transaction. If not specified, get value from the Account.
type: string
autoRenew:
description: |
If `true`, the subscription automatically renews at the end of the
term.
default: false
type: boolean
originalPurchaseDate:
description: |
The value of `externalPurchaseDate` when this external subscription firstly created.
UTC time, `yyyy-mm-dd hh:mm:ss`.
type: string
format: datetime
externalPurchaseDate:
description: |
When the App Store charged the user’s account for a purchase, restored product, subscription,
or subscription renewal after a lapse. UTC time, `yyyy-mm-dd hh:mm:ss`.
type: string
format: datetime
externalActivationDate:
description: |
When the external subscription was activated on the external platform.
UTC time, `yyyy-mm-dd hh:mm:ss`.
type: string
format: datetime
externalExpirationDate:
description: |
This expiration date is a static value that applies for each transaction.
UTC time, `yyyy-mm-dd hh:mm:ss`.
type: string
format: datetime
externalApplicationId:
description: |
The external application ID.
type: string
externalBundleId:
description: |
The external bundler ID.
type: string
externalSubscriberId:
description: |
The external subscriber ID.
type: string
externalPrice:
description: |
The price in external system.
type: number
externalPurchaseType:
description: The external purchase type.
type: string
externalLastRenewalDate:
description: |
This last renewal date is a static value that applies for each transaction.
UTC time, `yyyy-mm-dd hh:mm:ss`.
type: string
format: datetime
externalNextRenewalDate:
description: |
This next renewal date is a static value that applies for each transaction.
UTC time, `yyyy-mm-dd hh:mm:ss`.
type: string
format: datetime
type: object
- $ref: '#/components/schemas/SubscriptionObjectCustomFields'
title: OmniChannelSubscription
GetSubscriptionChangeLogsResponse:
allOf:
- $ref: '#/components/schemas/CommonResponse'
- properties:
subscriptions:
description: |
Array of Subscriptions.
items:
$ref: '#/components/schemas/SubscriptionChangeLog'
type: array
type: object
SubscriptionChangeLog:
description: Represents the order information that will be returned in the GET call.
properties:
subscriptionNumber:
description: Subscription number.
type: string
accountNumber:
description: Account number.
type: string
invoiceOwnerAccountNumber:
description: Invoice owner account number of the subscription.
type: string
currency:
description: The currency of the subscription.
type: string
orderNumber:
description: The order number of the order which created this subscription.
type: string
version:
description: The version of the subscription.
format: int64
type: integer
changedTime:
description: The create time of the subscription.
type: string
type:
description: The type of the subscription.
type: string
enum:
- Standard
- OmniChannel
externalSubscriptionId:
description: External subscription ID.
type: string
nullable: true
subscriptionStartDate:
description: Start date of the subscription.
type: string
subscriptionEndDate:
description: End date of the subscription.
type: string
termStartDate:
description: Term start date of the subscription.
type: string
termEndDate:
description: Term end date of the subscription.
type: string
ratePlans:
description: Represents the rate plans in this subscription.
items:
$ref: '#/components/schemas/RatePlanChangeLog'
type: array
fields:
description: Represents the fields whose values are changed for this subscription. If the subscription has no change, this field is empty.
items:
$ref: '#/components/schemas/ChangeLogField'
type: array
type: object
title: Subscription
RatePlanChangeLog:
description: Represents the order information that will be returned in the GET call.
properties:
ratePlanNumber:
description: Rate plan number.
type: string
ratePlanCharges:
description: Represents the charges in this rate plan.
items:
$ref: '#/components/schemas/RatePlanChargeChangeLog'
type: array
fields:
description: Represents the fields whose values are changed for the rate plan. If the rate plan has no change, this field is empty.
items:
$ref: '#/components/schemas/ChangeLogField'
type: array
type: object
title: SubscriptionRatePlan
ChangeLogField:
description: Represents the order information that will be returned in the GET call.
properties:
fieldName:
description: The field name.
type: string
oldValue:
description: The old value of this field.
type: string
nullable: true
newValue:
description: The new value of this field.
type: string
type: object
title: ChangedField
RatePlanChargeChangeLog:
description: Represents the order information that will be returned in the GET call.
properties:
chargeNumber:
description: Charge number.
type: string
ratePlanChargeId:
description: Rate plan charge ID.
type: string
effectiveStartDate:
description: Effective start date of this charge.
type: string
effectiveEndDate:
description: Effective end date of this charge.
type: string
fields:
description: Represents the fields whose values are changed for this charge. If the charge has no change, this field is empty.
items:
$ref: '#/components/schemas/ChangeLogField'
type: array
type: object
title: SubscriptionRatePlanCharge
GetSubscriptionChangeLogResponse:
allOf:
- $ref: '#/components/schemas/CommonResponse'
- properties:
subscription:
$ref: '#/components/schemas/SubscriptionChangeLog'
type: object
POSTReverseRolloverRequestType:
allOf:
- properties:
destinationValidityPeriod:
$ref: '#/components/schemas/DestinationValidityPeriodInfo'
prepaymentUom:
description: |
Specifies the units of measure for prepayment charge. Units of measure are configured in the web-based UI. Your values depend on your configuration in **Billing Settings**.
**Values**: a valid unit of measure
type: string
sourceValidityPeriod:
$ref: '#/components/schemas/SourceValidityPeriodInfo'
subscriptionNumber:
description: The unique identifier number of the subscription.
maxLength: 100
type: string
required:
- subscriptionNumber
- prepaymentUom
- sourceValidityPeriod
- destinationValidityPeriod
type: object
example:
destinationValidityPeriod:
endDate: '2024-01-01'
startDate: '2023-01-01'
prepaymentUom: Each
sourceValidityPeriod:
endDate: '2025-01-01'
startDate: '2024-01-01'
subscriptionNumber: A-S00000009
POSTReverseRolloverResponseType:
properties:
message:
description: Indicates the result.
type: string
reverseRolloverFundCount:
description: Indicates the number of funds which have been rolled back.
format: int64
type: integer
success:
description: Indicates whether the call succeeded.
type: boolean
type: object
DestinationValidityPeriodInfo:
description: Date range of the destination validity period to which the funds are transferred. It should be close to the source validity period.
properties:
endDate:
description: End date of the destination validity period.
format: date
type: string
startDate:
description: Start date of the destination validity period.
format: date
type: string
required:
- startDate
- endDate
title: destinationValidityPeriod
type: object
SourceValidityPeriodInfo:
description: Date range of the source validity period from which the funds are transferred. It should be close to the destination validity period.
properties:
endDate:
description: End date of the source validity period.
format: date
type: string
startDate:
description: Start date of the source validity period.
format: date
type: string
required:
- startDate
- endDate
title: sourceValidityPeriod
type: object
POSTTriggerRolloverRequestType:
allOf:
- properties:
destinationValidityPeriod:
$ref: '#/components/schemas/DestinationValidityPeriodInfo'
prepaymentUom:
description: |
Specifies the units of measure for prepayment charge. Units of measure are configured in the web-based UI. Your values depend on your configuration in **Billing Settings**.
**Values**: a valid unit of measure
type: string
priority:
description: |
Specifies the priority of rolled over fund in case of drawdown.
**Values**: ApplyLast / ApplyFirst
type: string
sourceValidityPeriod:
$ref: '#/components/schemas/SourceValidityPeriodInfo'
subscriptionNumber:
description: The unique identifier number of the subscription.
maxLength: 100
type: string
required:
- subscriptionNumber
- prepaymentUom
- sourceValidityPeriod
- destinationValidityPeriod
- priority
type: object
example:
destinationValidityPeriod:
endDate: '2025-01-01'
startDate: '2024-01-01'
prepaymentUom: Each
priority: ApplyFirst
sourceValidityPeriod:
endDate: '2024-01-01'
startDate: '2023-01-01'
subscriptionNumber: A-S00000009
POSTTriggerRolloverResponseType:
properties:
message:
description: Indicates the result.
type: string
rolloverFundCount:
description: Indicates the number of funds which have been rolled over.
format: int64
type: integer
success:
description: Indicates whether the call succeeded.
type: boolean
type: object
POSTDepleteFundRequestType:
properties:
fundIds:
description: |
The unique ID of the fund. A maximum of 100 fund Ids are allowed.
type: object
example:
fundIds:
- 4028818c8d0c9db5018d0cbbdecd72c1
- 4028818c8d0c9db5018d0cbbdecd72c2
POSTDepleteFundResponseType:
properties:
fundIds:
items:
properties:
fundId:
description: |
The unique ID of the fund.
type: string
status:
description: |
The status of the fund expiry.
type: string
message:
description: |
The detail information of the fund expiry response.
type: string
type: object
type: array
type: object
POSTUsageResponseType:
properties:
checkImportStatus:
description: |
The path for checking the status of the import.
The possible status values at this path are `Pending`, `Processing`, `Completed`, `Canceled`, and `Failed`. Only `Completed` indicates that the file contents were imported successfully.
type: string
size:
description: |
The size of the uploaded file in bytes.
format: int64
type: integer
success:
description: |
Indicates whether the call succeeded.
type: boolean
type: object
GETUsageRateDetailWrapper:
properties:
data:
description: |
Contains usage rate details for the invoice item as specified in the request.
properties:
amountWithoutTax:
description: |
The amount of the invoice item without tax.
format: double
type: number
chargeNumber:
description: |
The unique number of the product rate plan charge associated with the invoice item.
type: string
invoiceId:
description: |
The unique ID of the invoice.
type: string
invoiceItemId:
description: |
The unique ID of the invoice item.
type: string
invoiceNumber:
description: |
The unique number of the invoice.
type: string
listPrice:
description: |
The list price of the product rate plan charge associated with the invoice item. For example, if the product rate plan charge uses the tiered charge model, its list price could be:
Tier / From / To / List Price / Price Format\n1 / 0 / 9 / 0.00 / Per Unit\n2 / 10 / 20 / 1.00 / Per Unit\n3 / 21 / 30 / 2.00 / Flat Fee\n4 / 31 / / 3.00 / Per Unit\n
type: string
quantity:
description: |
The quantity of the invoice item.
format: double
type: number
rateDetail:
description: |
The rate detail of the invoice item. It shows how the total amount is calculated. For example, if the product rate plan charge uses the tiered charge model, the rate detail for the associated invoice item could be:
Tier 1: 0-9, 9 Each(s) x $0.00/Each = $0.00\nTier 2: 10-20, 11 Each(s) x $1.00/Each = $11.00\nTier 3: 21-30, $2.00 Flat Fee\nTier 4: >=31, 15 Each(s) x $3.00/Each = $45.00\nTotal = $58.00.
The rate detail retrieved from this REST API operation is the same as the [Rate Detail presented on PDF invoices](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/IA_Invoices/Create_a_custom_invoice_template/DD_Display_Usage_Charge_Breakdown#How_UsageSummary.RateDetail_is_displayed_on_invoices).
type: string
servicePeriod:
description: |
The service period of the invoice item.
type: string
uom:
description: |
The unit of measurement of the invoice item.
type: string
type: object
success:
description: |
Returns `true` if the request was processed successfully.
Returns `false` if the request was not processed successfully.
type: boolean
type: object
ProxyCreateUsage:
allOf:
- properties:
AccountId:
description: |2-
The ID of the account associated with the usage data. This field is only required if no value is specified for the `AccountNumber` field.
**Character limit**: 32 **Values**: a valid account ID.
type: string
AccountNumber:
description: |2-
The number of the account associated with the usage data. This field is only required if no value is specified for the `AccountId` field.
**Character limit**: 50 **Values**: a valid account number.
type: string
ChargeId:
description: ' The OrginalId of the rate plan charge related to the usage record, e.g., `2c9081a03c63c94c013c6873357a0117` **Character limit**: 32 **Values**: a valid rate plan charge OriginalID. '
type: string
ChargeNumber:
description: |
A unique number for the rate plan charge related to the usage record. For example, C-00000007.
maxLength: 50
type: string
Description:
description: |
A description of the usage record.
maxLength: 200
type: string
EndDateTime:
description: |2-
The end date and time of a range of time when usage is tracked. Use this field for reporting; this field doesn't affect usage calculation.
**Character limit**: 29 **Values**: a valid date and time value.
format: date-time
type: string
ProductRatePlanChargeNumber:
description: |
Specify a product rate plan charge number so that you can charge your customer with a dynamic usage charge for the corresponding uploaded usage record.
To use this field, you must set the `X-Zuora-WSDL-Version` request header to `146` or higher. Otherwise, an error occurs.
**Note**: This field is only available if you have the Dynamic Usage Charges feature enabled.
type: string
Quantity:
description: |
Indicates the number of units used.
**Character limit**: 16
**Values**: A valid decimal amount.
format: double
type: number
StartDateTime:
description: |2-
The start date and time of a range of time when usage is tracked. Zuora uses this field value to determine the usage date. Unlike the `EndDateTime`, the `StartDateTime` field does affect usage calculation.
**Character limit**: 29 **Values**: a valid date and time value
format: date-time
type: string
SubscriptionId:
description: |
The original ID of the subscription that contains the fees related to the usage data.
The ID of a subscription might change when you create amendments to the subscription. It is good practice to use the unique subscription number that you can specify in the `SubscriptionNumber` field.
maxLength: 32
type: string
SubscriptionNumber:
description: |
The unique identifier number of the subscription that contains the fees related to the usage data.
It is good practice to use this field when creating usage records.
maxLength: 100
type: string
UOM:
description: |
Specifies the units to measure usage. Units of measure are configured in the web-based UI. Your values depend on your configuration in **Billing Settings**. **Character limit**: **Values**: a valid unit of measure
type: string
UniqueKey:
description: |
The unique external reference of the usage record. See [Upload usage record with unique key](https://knowledgecenter.zuora.com/Zuora_Billing/Bill_your_customers/Bill_for_usage_or_prepaid_products/Advanced_Consumption_Billing/Unbilled_Usage#Upload_usage_record_with_unique_key) for information on how to use this field.
**Note**: This field is only available if you set the `X-Zuora-WSDL-Version` request header to `114` or later. This field is only available if you have the Prepaid with Drawdown feature or the Unbilled Usage feature enabled. See [Upload usage record with unique key](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Prepaid_balance_transactions#Upload_usage_record_with_unique_key) for more information.
type: string
required:
- Quantity
- StartDateTime
- UOM
type: object
- $ref: '#/components/schemas/UsageObjectCustomFields'
example:
AccountId: 8ad09378905a5af201907ca1edb524c2
UOM: Minutes
Quantity: 200
StartDateTime: '2024-06-01T02:00:00.000+01:00'
UsageObjectCustomFields:
additionalProperties:
description: |
Custom fields of the Usage object. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
description: |
Container for custom fields of a Usage object.
title: usageFieldsCustom
type: object
ProxyGetUsage:
allOf:
- properties:
AccountId:
description: |2-
The ID of the account associated with the usage data. This field is required if no value is specified for the `AccountNumber` field.
**Character limit**: 32 **Values**: a valid account ID
type: string
AccountNumber:
description: |2-
The number of the account associated with the usage data. This field is required if no value is specified for the `AccountId` field.
**Character limit**: 50 **Values**: a valid account number
type: string
ChargeId:
description: ' The OrginalId of the rate plan charge related to the usage record, e.g., `2c9081a03c63c94c013c6873357a0117` **Character limit**: 32 **Values**: a valid rate plan charge OriginalID '
type: string
CreatedById:
description: |2-
The user ID of the person who uploaded the usage records.
**Character limit**: 32 **Values**: automatically generated
type: string
CreatedDate:
description: |2-
The date when the usage was generated.
**Character limit**: 29 **Values**: automatically generated
format: date-time
type: string
Description:
description: |
A description of the usage record.
type: string
EndDateTime:
description: |2-
The end date and time of a range of time when usage is tracked. Use this field for reporting; this field doesn't affect usage calculation.
**Character limit**: 29 **Values**: a valid date and time value
format: date-time
type: string
Id:
description: Object identifier.
type: string
ProductRatePlanChargeNumber:
description: |
Specify a product rate plan charge number so that you can charge your customer with a dynamic usage charge for the corresponding uploaded usage record.
To use this field, you must set the `X-Zuora-WSDL-Version` request header to `146` or higher. Otherwise, an error occurs.
**Note**: This field is only available if you have the Dynamic Usage Charges feature enabled.
type: string
Quantity:
description: |
Indicates the number of units used.
**Character limit**: 16
**Values**: A valid decimal amount.
format: double
type: number
RbeStatus:
description: |2-
Indicates if the rating and billing engine (RBE) processed usage data for an invoice.
**Character limit**: 9 **Values**: automatically generated to be one of the following values: `Importing`, `Pending`, `Processed`
type: string
SourceType:
description: |2-
Indicates if the usage records were imported from the web-based UI or the API.
**Character limit**: 6 **Values**: automatically generated to be one of the following values: `API`, `Import`
type: string
StartDateTime:
description: |2-
The start date and time of a range of time when usage is tracked. Zuora uses this field value to determine the usage date. Unlike the `EndDateTime`, the `StartDateTime` field does affect usage calculation.
**Character limit**: 29 **Values**: a valid date and time value
format: date-time
type: string
SubscriptionId:
description: |2-
The original ID of the subscription that contains the fees related to the usage data.
**Character limit**: 32 **Values**: a valid subscription ID
type: string
SubscriptionNumber:
description: |
The unique identifier number of the subscription that contains the fees related to the usage data.
type: string
UOM:
description: |2-
Specifies the units to measure usage. Units of measure are configured in the web-based UI. Your values depend on your configuration in **Billing Settings**.
**Character limit**: **Values**: a valid unit of measure
type: string
UpdatedById:
description: |2-
The ID of the user who last updated the usage upload.
**Character limit**: 32 **Values**: automatically generated
type: string
UpdatedDate:
description: |2-
The date when the usage upload was last updated.
**Character limit**: 29 **Values**: automatically generated
format: date-time
type: string
type: object
- $ref: '#/components/schemas/UsageObjectCustomFields'
ProxyModifyUsage:
allOf:
- properties:
EndDateTime:
description: |2-
The end date and time of a range of time when usage is tracked. Use this field for reporting; this field doesn't affect usage calculation.
**Character limit**: 29 **Values**: a valid date and time value
format: date-time
type: string
Quantity:
description: |
Indicates the number of units used.
**Character limit**: 16
**Values**: A valid decimal amount.
format: double
type: number
RbeStatus:
description: |2-
Indicates if the rating and billing engine (RBE) processed usage data for an invoice.
**Character limit**: 9 **Values**: automatically generated to be one of the following values: `Importing`, `Pending`, `Processed`
type: string
StartDateTime:
description: |2-
The start date and time of a range of time when usage is tracked. Zuora uses this field value to determine the usage date. Unlike the `EndDateTime`, the `StartDateTime` field does affect usage calculation.
**Character limit**: 29 **Values**: a valid date and time value
format: date-time
type: string
UOM:
description: |2-
Specifies the units to measure usage. Units of measure are configured in the web-based UI. Your values depend on your configuration in **Billing Settings**.
**Character limit**: **Values**: a valid unit of measure
type: string
type: object
- $ref: '#/components/schemas/UsageObjectCustomFields'
example:
EndDateTime: '2024-06-30T02:00:00.000+01:00'
RunMeterVersionRequest:
type: object
description: The request payload to run a specific version of a meter.
properties:
sourceOptions:
type: array
description: Settings for meter to run with local file.
items:
type: object
properties:
processorId:
type: string
description: Source operator ID. Optional if there's only one local file source in the meter.
localFileId:
type: string
description: Internal ID of uploaded file.
eventStoreSourceOptions:
type: array
description: Settings for meter to run with event store.
items:
type: object
required:
- processorId
properties:
processorId:
type: string
description: Source operator ID.
startDate:
type: string
format: date
description: Start date of event store to query from (e.g., 2025-01-01).
endDate:
type: string
format: date
description: End date of event store to query to (e.g., 2025-02-01).
RunMeterVersionResponse:
type: object
description: Response payload after triggering a meter run.
properties:
success:
type: boolean
description: Whether the API request has succeeded.
data:
type: object
properties:
id:
type: string
description: Internal run history ID, unique within tenant.
sessionId:
type: string
description: Corresponding session ID of this run.
jobId:
type: string
description: Corresponding job ID of this run.
meterId:
type: integer
description: Internal meter ID.
version:
type: string
description: Version of the meter.
revision:
type: integer
description: Revision number of this version run.
runType:
type: integer
description: |
The run type:
- 1. NORMAL
- 2. DEBUG
minimum: 1
maximum: 2
runTypeDescription:
type: string
description: Description of the run type.
startTime:
type: string
format: date-time
description: Start time of this run.
endTime:
type: string
format: date-time
nullable: true
description: End time of this run.
status:
type: integer
description: |
The run status:
- 1. NEVER_RUN
- 2. TESTING
- 3. TESTING_FAILED
- 4. TESTING_PASSED
- 5. RUNNING
- 6. PAUSED
- 7. COMPLETED
- 8. FAILED
- 9. CANCELED
- 10. INITIALIZING
- 11. USAGE_PUSHING
- 12. PUSH_COMPLETED
- 13. CONSUME_COMPLETED
minimum: 1
maximum: 13
statusDescription:
type: string
description: Description of the run status.
canExportSummary:
type: boolean
description: Whether the summary is ready to export.
hasLineageEnabled:
type: boolean
description: Whether lineage feature is enabled on this run.
TestSpecificMeterRequest:
type: object
properties:
sourceOptions:
type: array
items:
$ref: '#/components/schemas/SourceOption'
eventStoreSourceOptions:
type: array
items:
$ref: '#/components/schemas/EventStoreSourceOption'
TestSpecificMeterResponse:
type: object
properties:
id:
type: string
description: Internal run history ID, unique within tenant.
sessionId:
type: string
description: The corresponding session ID of this run.
jobId:
type: string
description: The corresponding job ID of this run.
meterId:
type: integer
description: The meter ID.
version:
type: string
description: The version of the meter.
revision:
type: integer
description: The revision of the meter version when it runs.
runType:
type: integer
description: The run type of the meter (1 for NORMAL, 2 for DEBUG).
minimum: 1
maximum: 2
runTypeDescription:
type: string
description: Description of the run type.
startTime:
type: string
description: The start time of the run in ISO 8601 format.
endTime:
type: string
description: The end time of the run in ISO 8601 format.
runStatus:
type: string
description: The status of the run (e.g., NEVER_RUN, TESTING, FAILED).
runStatusDescription:
type: string
description: Description of the run status.
canExportSummary:
type: boolean
description: Whether the summary is ready to export.
hasLineageEnabled:
type: boolean
description: Whether lineage is enabled for this run.
MediationErrorResponse:
type: object
properties:
success:
type: boolean
description: Whether the API request has succeeded or not.
data:
type: object
description: Detailed response information for successful requests (e.g., instance info, job details).
properties:
id:
type: string
description: The instance ID.
sessionId:
type: string
description: The session ID of the meter instance.
jobId:
type: string
description: The job ID of the meter instance.
meterId:
type: integer
description: The ID of the meter.
version:
type: string
description: The meter version.
revision:
type: string
description: The meter revision.
runType:
type: integer
description: The run type of the instance.
runTypeDescription:
type: string
description: The description of the run type.
startTime:
type: string
description: The start time of the instance.
status:
type: integer
description: The job status of the instance.
statusDescription:
type: string
description: The status description of the instance.
canExportSummary:
type: boolean
description: Whether the instance can export summary information (internal usage).
hasLineageEnabled:
type: boolean
description: Whether lineage is enabled for the meter (internal usage).
error:
type: object
description: Contains error details when the request fails.
properties:
code:
type: string
description: The error reason code (e.g., "70002006" for authorization errors).
message:
type: string
description: A human-readable description of the error.
SourceOption:
type: object
properties:
processorId:
type: string
description: The source operator ID. Optional if there is only one local file source.
sampleFileId:
type: integer
description: Test meter with event definition sample file, specified by the ID.
localFileId:
type: integer
description: Test meter with uploaded file, specified by the ID.
testData:
type: array
description: Test meter with manually input data.
items:
type: object
properties:
Amount:
type: number
description: Amount
Quantity:
type: number
description: Quantity
UsageDate:
type: string
format: date
description: UsageDate
CostCenter:
type: string
description: CostCenter
CustomerId:
type: string
description: CustomerId
UsageIdentifier:
type: string
description: UsageIdentifier
saveTestData:
type: boolean
description: Whether to save the test data.
testDataName:
type: string
description: The name of the test data.
testDataId:
type: integer
description: Test meter with previously saved test data, specified by the ID.
EventStoreSourceOption:
type: object
properties:
processorId:
type: string
description: The source operator ID for event store.
startDate:
type: string
format: date
description: The start date of the event store to query from, e.g., 2025-01-01.
endDate:
type: string
format: date
description: The end date of the event store to query to, e.g., 2025-02-01.
CreateSpecificMeterSummaryRequest:
type: object
properties:
runType:
type: string
description: Specifies the type of run.
sessionIds:
type: array
description: A list of specific run IDs to export.
items:
type: string
operatorIds:
type: array
description: A list of operator IDs to filter by.
items:
type: string
groupBy:
type: array
description: Specifies the fields used to group the summary results.
items:
type: string
queryFromTime:
type: string
description: The minimum timestamp for the data to be exported.
queryToTime:
type: string
description: The maximum timestamp for the data to be exported.
example:
runType: NORMAL
queryFromTime: 2025-10-01T0000+0000
queryToTime: 2025-11-17T23:59:59+0000
operatorIds:
- 4610a876-61ee-4e5e-a634-152e7a635f75
sessionIds:
- R-00002247
- R-00002293
groupBy:
- errorCode
- processorId
- sessionId
CreateSpecificMeterSummaryResponse:
type: object
properties:
success:
type: boolean
description: Indicates whether the request was successful.
data:
$ref: '#/components/schemas/SummaryResponse'
description: |
List of audit trail entries for the specified meter. Each object represents a recorded event or operation associated with the meter.
previousPage:
type: string
description: Cursor or URL for the previous page of audit records, if available. Used for backward pagination.
nextPage:
type: string
description: Cursor or URL for the next page of audit records, if available. Used for forward pagination.
error:
$ref: '#/components/schemas/Error'
description: Container for error information returned by the API when the request fails.
SummaryResponse:
type: object
properties:
requestId:
type: string
description: Unique identifier for the API request.
requestTime:
type: string
description: Timestamp indicating when the request was made.
query:
$ref: '#/components/schemas/SummaryFilters'
description: Defines the filters or parameters applied to the summary query.
output:
type: array
description: |
Lists grouped summary results based on the specified fields.
items:
$ref: '#/components/schemas/SummaryGroupByResult'
Error:
type: object
properties:
code:
type: string
description: Machine-readable error code identifying the failure type.
message:
type: string
description: Human-readable description of the error that provides more context about what went wrong.
detail:
type: object
description: Additional structured details about the error, such as validation issues or parameter-specific information.
SummaryFilters:
type: object
properties:
runType:
type: string
description: Specifies the type of run.
sessionIds:
type: array
description: A list of specific run IDs to export.
items:
type: string
operatorIds:
type: array
description: A list of operator IDs to filter by.
items:
type: string
groupBy:
type: array
description: Specifies the fields used to group the summary results.
items:
type: string
queryFromTime:
type: string
description: The minimum timestamp for the data to be exported.
queryToTime:
type: string
description: The maximum timestamp for the data to be exported.
SummaryGroupByResult:
type: object
properties:
dimensions:
description: Stores dimension details or attributes used in grouping or filtering.
type: object
additionalProperties:
type: object
description: Stores extra or custom fields not defined in the main schema.
output:
type: integer
format: int64
description: Represents the total number of output records or items.
totalErrorCount:
type: integer
format: int64
description: Indicates the total count of errors in the response.
RunStatusResponse:
type: object
properties:
success:
type: boolean
description: Indicates whether the request was successful.
data:
type: object
properties:
runStatus:
type: integer
description: |
The run status of the current version. Possible values:
- 1: NEVER_RUN
- 2: TESTING
- 3: TESTING_FAILED
- 4: TESTING_PASSED
- 5: RUNNING
- 6: PAUSED
- 7: COMPLETED
- 8: FAILED
- 9: CANCELED
- 10: INITIALIZING
- 11: USAGE_PUSHING
- 12: PUSH_COMPLETED
- 13: CONSUME_COMPLETED
minimum: 1
maximum: 13
runStatusDescription:
type: string
description: Description of the run status.
GetAuditTrailResponse:
type: object
properties:
success:
type: boolean
description: Indicates whether the request was successful.
data:
type: array
description: |
List of audit trail entries for the specified meter. Each object represents a recorded event or operation associated with the meter.
items:
$ref: '#/components/schemas/MeterAuditRecord'
previousPage:
type: string
description: Cursor for the previous page of audit records, if available. Used for backward pagination.
nextPage:
type: string
description: Cursor for the next page of audit records, if available. Used for forward pagination.
error:
$ref: '#/components/schemas/Error'
description: Container for error information returned by the API when the request fails.
MeterAuditRecord:
type: object
properties:
errorTime:
type: string
description: Timestamp when an error occurred during the meter operation or event processing, if applicable.
timestamp:
type: string
description: Timestamp when the audit entry was created, representing the exact time the event or operation was recorded.
errorCode:
type: string
description: Unique identifier for the specific error type, used to categorize and troubleshoot issues. Present only when an error has occurred.
errorMessage:
type: string
description: Descriptive message explaining the cause or nature of the error. Useful for debugging or logging.
payload:
description: Raw event data or metadata associated with the audited action, including event content, request body, or contextual details.
type: object
additionalProperties:
type: object
eventId:
type: string
description: Unique identifier assigned to the audited event. Enables correlation of events across systems for traceability.
traceId:
type: string
description: Unique identifier used to trace the end-to-end flow of an event through the system. Useful for debugging distributed processes.
operatorType:
type: string
description: 'Type of processor used. Examples: MAP, ENRICHMENT'
enum:
- ACCUMULATOR
- AGGREGATOR
- BILLING_RATING
- CLICKHOUSE_SINK
- CLICKHOUSE_SOURCE
- DEDUPLICATE
- EVENT_STORE_SINK
- EVENT_STORE_SOURCE
- FILTER
- HTTP
- KAFKA_SINK
- KAFKA_SOURCE
- LOCAL_FS_SOURCE
- MAP
- NATS_SINK
- NATS_SOURCE
- PARTITION
- RATING
- S3_SINK
- S3_SOURCE
- SAMPLE_COMMITTABLE_SINK
- SCRIPT_ACCUMULATOR
- SCRIPT_AGGREGATOR
- SCRIPT_FILTER
- SCRIPT_MAP
- SNOWFLAKE_ERROR
- SNOWFLAKE_SINK
- SNOWFLAKE_SOURCE
- STREAMING_API_SOURCE
- SUBSCRIPTION_LOOKUP
- TSTORE_SINK
- USAGE_RECORD_SINK
- USER_INPUT_SOURCE
operatorName:
type: string
description: Name of the processor used in ther meter configuration.
operatorId:
type: string
description: ID of the processor used in the meter configuration.
GetAuditTrailExportResponse:
type: object
properties:
success:
type: boolean
description: Indicates whether the request was successful.
data:
description: |
List of audit trail entries for the specified meter. Each object represents a recorded event or operation associated with the meter.
type: object
additionalProperties:
type: object
description: Stores extra or custom fields that are not defined in the main schema.
previousPage:
type: string
description: Cursor for the previous page of audit records, if available. Used for backward pagination.
nextPage:
type: string
description: Cursor for the next page of audit records, if available. Used for forward pagination.
error:
$ref: '#/components/schemas/Error'
description: Container for error information returned by the API when the request fails.
ExportAuditTrailResponse:
type: object
properties:
success:
type: boolean
description: Indicates whether the request was successful.
data:
description: |
List of audit trail entries for the specified meter. Each object represents a recorded event or operation associated with the meter.
type: object
additionalProperties:
type: object
description: Stores extra or custom fields that are not defined in the main schema.
previousPage:
type: string
description: Cursor for the previous page of audit records, if available. Used for backward pagination.
nextPage:
type: string
description: Cursor for the next page of audit records, if available. Used for forward pagination.
error:
$ref: '#/components/schemas/Error'
description: Container for error information returned by the API when the request fails.
GetPresignedURLResponse:
type: object
properties:
success:
type: boolean
description: Indicates whether the request was successful.
data:
type: string
description: |
The pre-signed URL to download a specific export file.
previousPage:
type: string
description: Cursor for the previous page, if available. Used for backward pagination.
nextPage:
type: string
description: Cursor for the next page, if available. Used for forward pagination.
error:
$ref: '#/components/schemas/Error'
description: Container for error information returned by the API when the request fails.
ExportMeterResponse:
type: object
properties:
name:
type: string
description: Meter name
description:
type: string
description: Meter description
type:
type: string
description: Meter type (e.g., CUSTOM, STANDARD)
typeDefinition:
$ref: '#/components/schemas/MeterTypeDefinition'
description: The meter definition for non-CUSTOM meters
latestVersion:
type: string
description: The latest version of the meter
versions:
type: array
items:
$ref: '#/components/schemas/MeterVersionExportResult'
description: List of all versions for the meter
schemas:
type: array
items:
$ref: '#/components/schemas/EventSchemaExportResult'
description: List of event schemas used by this meter
MeterTypeDefinition:
type: object
properties:
sourceType:
type: string
description: Source type, e.g., ZUORA_BULK_API or LOCAL_FILE
schemaId:
type: string
description: Event definition ID
fieldMappings:
type: array
items:
$ref: '#/components/schemas/UsageFieldMapping'
description: Field mappings from event definition to Zuora usage
configs:
type: object
additionalProperties: true
description: Configurations for accumulated meters (e.g., SUM)
MeterVersionExportResult:
type: object
properties:
version:
type: string
description: The initial version of meter, default is 0.0.1
versionDetail:
type: string
description: Detail description of this version
metadata:
type: string
description: Version metadata, UI stores meter position data into this field
tasks:
type: array
items:
$ref: '#/components/schemas/MeterTask'
description: List of tasks for this version
EventSchemaExportResult:
type: object
description: Schema details of an event associated with a meter
properties:
name:
type: string
description: Event definition name
type:
type: integer
description: Schema type (1 = simple, 2 = advanced)
minimum: 1
maximum: 2
schema:
type: object
description: JSON schema
properties:
description:
type: string
description: Schema description
type:
type: string
enum:
- object
description: Schema base type
title:
type: string
description: Schema title
required:
type: array
description: Required fields in the event
items:
type: string
properties:
type: object
description: Field definitions in the schema
additionalProperties:
type: object
properties:
type:
type: string
description: Data type of the field
description:
type: string
description: Description of the field
example:
name: source(97)
type: 1
schema:
description: A description
type: object
title: source
required:
- CustomerId
- UsageIdentifier
- UsageDate
properties:
Amount:
type: number
description: Amount
Quantity:
type: number
description: Quantity
UsageDate:
type: string
description: UsageDate
CostCenter:
type: string
description: CostCenter
CustomerId:
type: string
description: CustomerId
UsageIdentifier:
type: string
description: UsageIdentifier
MeterTask:
type: object
properties:
id:
type: string
description: Operator ID
name:
type: string
description: Operator name
nodeType:
type: string
description: Operator node type (e.g., SOURCE, PROCESSOR, SINK)
operatorType:
type: string
description: Operator type (e.g., KAFKA, S3, LOCAL_FILE)
metadata:
type: object
additionalProperties: true
description: Operator metadata
predecessors:
type: array
items:
$ref: '#/components/schemas/TransitionNode'
description: Predecessor operators
extraConfig:
type: object
additionalProperties: true
description: Extra configurations for the operator
setting:
type: object
additionalProperties: true
description: Runtime settings for the operator
TransitionNode:
type: object
properties:
id:
type: string
description: Operator ID
UsageFieldMapping:
type: object
properties:
name:
type: string
description: Field name
field:
type: string
description: Mapped field name
required:
type: boolean
description: Indicates if the field is required
dateFormat:
type: string
description: Date format if applicable
ImportMeterRequest:
type: object
required:
- file
properties:
file:
type: string
format: binary
description: Meter definition file, should match format from Export Meter API
globalId:
type: string
description: If present and matches an existing meter, updates it. Else, creates a new meter with this globalId.
ImportMeterResponse:
type: object
properties:
success:
type: boolean
example: true
data:
type: object
properties:
id:
type: string
description: Internal meter ID, unique within tenant
name:
type: string
description: Meter name
description:
type: string
description: Meter description
type:
type: string
description: Meter type
typeDefinition:
$ref: '#/components/schemas/MeterTypeDefinition'
description: The meter definition for non-CUSTOM meters
latestVersion:
type: string
description: The latest version of the meter
globalId:
type: string
description: Meter global ID used for ingestion via Streaming API
uniqueUploadUrl:
type: string
description: The upload URL for usage ingestion
activeVersionRunStatus:
type: integer
description: Run status of the active version
activeVersionRunStatusDescription:
type: string
description: Description of active version run status
latestVersionRunStatus:
type: integer
description: Run status of the latest version
latestVersionRunStatusDescription:
type: string
description: Description of latest version run status
createdAt:
type: string
description: Timestamp of meter creation
updatedAt:
type: string
description: Timestamp of meter update
CreateFileResponse:
type: object
properties:
id:
type: string
description: Internal file ID
name:
type: string
description: File name
resourceId:
type: string
description: Resource ID of the file
format:
type: string
description: File format (CSV, Excel, JSON)
hasHeader:
type: boolean
description: Indicates if the file has a header
firstRow:
type: integer
description: The first row number in the CSV file
delimiter:
type: string
description: Delimiter used in the CSV file
sheet:
type: string
description: The sheet name in the Excel file
dataRange:
type: string
description: Data range in the Excel file
lines:
type: integer
description: Number of lines in the file
createdAt:
type: string
format: date-time
description: Creation timestamp
updatedAt:
type: string
format: date-time
description: Last update timestamp
StreamingEvent:
type: object
description: A usage event to be ingested into Zuora Mediation.
properties:
CustomerId:
type: string
description: Unique identifier for the customer.
UsageIdentifier:
type: string
description: Identifier for the usage type.
UsageDate:
type: string
format: date-time
description: Date and time when the usage occurred.
Quantity:
type: number
description: Quantity of usage.
required:
- CustomerId
- UsageIdentifier
- UsageDate
- Quantity
StreamingIngestionSuccessResponse:
type: object
description: Successful ingestion response.
properties:
success:
type: boolean
description: Whether the ingestion was successful.
message:
type: string
description: Response message with details.
StreamingIngestionAuthError:
type: object
description: Response for authentication, authorization, or other system-level errors.
properties:
message:
type: string
description: Error message describing the problem.
required:
- message
BulkDeleteEventRequest:
type: object
required:
- file
- storeId
properties:
file:
type: string
format: binary
description: The file that contains the event IDs to delete.
storeId:
type: integer
description: ID of the event store to delete events from.
BulkDeleteEventResponse:
type: object
properties:
success:
type: boolean
description: Indicates whether the bulk delete request was successful.
data:
type: object
properties:
queryId:
type: string
description: Query ID to track the bulk delete operation.
LatestEventStoreJobResponse:
type: object
properties:
success:
type: boolean
description: Indicates whether the request was successful.
data:
type: object
properties:
id:
type: string
description: Internal event store query history ID.
eventStoreId:
type: string
description: Related event store ID.
queryId:
type: string
description: Query ID.
status:
type: integer
description: |
Run status of the job. Possible values:
- 5: RUNNING
- 6: PAUSED
- 7: COMPLETED
- 8: FAILED
minimum: 5
maximum: 8
operationType:
type: string
description: Operation type.
inputRecordCount:
type: integer
description: Input record count of this query.
uniqueRecordCount:
type: integer
description: Unique record count of this query.
modifiedRecordCount:
type: integer
description: Modified record count of this query.
createdAt:
type: string
description: Created timestamp of the query history.
updatedAt:
type: string
description: Updated timestamp of the query history.
SubmitEventStoreQueryRequest:
type: object
required:
- query
properties:
query:
type: string
description: The query clause.
example:
query: select * from usage_event
SubmitEventStoreQueryResponse:
type: object
properties:
success:
type: boolean
description: Indicates whether the request was successful.
data:
description: Contains metadata and result details for the submitted event store query.
type: object
properties:
queryId:
type: string
description: Unique identifier of the submitted event store query. Use this ID to poll for status and fetch results.
additionalProperties:
type: object
description: Stores extra or custom fields that are not defined in the main schema.
previousPage:
type: string
description: Cursor or URL for the previous page of audit records, if available. Used for backward pagination.
nextPage:
type: string
description: Cursor or URL for the next page of audit records, if available. Used for forward pagination.
error:
$ref: '#/components/schemas/Error'
description: Container for error information returned by the API when the request fails.
GetQueryResultsResponse:
type: object
properties:
success:
type: boolean
description: Indicates whether the request was successful.
data:
description: Contains the query result object, including the query ID, execution status flags, total row count, column metadata, and the list of rows returned by the query.
$ref: '#/components/schemas/QueryResult'
previousPage:
type: string
description: Cursor for the previous page of audit records, if available. Used for backward pagination.
nextPage:
type: string
description: Cursor for the next page of audit records, if available. Used for forward pagination.
QueryResult:
type: object
properties:
isFailed:
type: boolean
description: A boolean flag indicating whether the query execution has failed.
totalCount:
type: integer
format: int32
description: The total number of rows that match the conditions defined in the executed query.
columns:
type: array
description: A list containing details of each column in the store.
items:
type: object
properties:
name:
type: string
description: The column name.
logicalType:
type: object
description: Logical type information for the column.
properties:
type:
type: string
description: The data type of the column (for example, VARCHAR, BIGINT, DECIMAL).
nullable:
type: boolean
description: Indicates whether the column can contain null values.
length:
type: integer
format: int32
description: For string types, the maximum length.
precision:
type: integer
description: For DECIMAL types, the total number of digits.
scale:
type: integer
description: For DECIMAL types, the number of digits to the right of the decimal point.
additionalProperties: false
comment:
type: string
nullable: true
description: Optional comment or description for the column.
additionalProperties: false
rows:
type: array
description: The list of rows returned by the query.
items:
type: object
properties:
kind:
type: string
description: The kind of change for the row (for example, INSERT).
fields:
type: array
description: The ordered list of field values for this row. Each position corresponds to a column in the columns array.
items: {}
additionalProperties: false
message:
type: string
description: Error message displayed for a failed query execution.
ready:
type: boolean
description: A boolean flag indicating whether the query execution has completed.
GetCommitmentsResponse:
type: object
properties:
total:
type: integer
description: Total number of commitments returned.
example: 1
page:
type: integer
description: Current page number.
example: 1
page_size:
type: integer
description: Number of commitments per page.
example: 1
commitments:
type: array
description: |
List of commitments.
items:
$ref: '#/components/schemas/GetCommitmentResponse'
GetCommitmentResponse:
type: object
properties:
id:
type: string
description: |
ID of the commitment.
status:
$ref: '#/components/schemas/CommitmentStatus'
version:
type: integer
description: |
Version of the commitment.
startDate:
type: string
format: date
description: The start date of the commitment.
endDate:
type: string
format: date
description: The end date of the commitment.
totalAmount:
type: number
format: double
description: The commitment amount.
currency:
type: string
description: |
Currency of the commitment.
orderNumber:
type: string
maxLength: 32
description: The number of the order.
orderId:
type: string
maxLength: 32
description: The ID of the order.
accountId:
type: string
maxLength: 32
description: |
The ID of the commitment owner account.
accountNumber:
type: string
maxLength: 100
description: Use this field to assign an existing account as the owner of an Commitment.
commitmentNumber:
type: string
maxLength: 100
description: |
The number of the commitment.
name:
type: string
maxLength: 255
description: |
The name of the commitment.
type:
type: string
description: |
The type of the commitment.
enum:
- MinCommitment
- MaxCommitment
description:
type: string
maxLength: 500
description: |
The description about this commitment.
priority:
type: integer
description: |
The priority of the commitment.
It defines the evaluation order of the commitment. The lower the number, the higher the priority.
When two commitments have the same priority, the one with the earlier created time will be evaluated first.
customFields:
$ref: '#/components/schemas/CommitmentCustomFields'
accountReceivableAccountingCode:
description: The accounting code on the Commitment object for customers
type: string
maxLength: 200
adjustmentLiabilityAccountingCode:
type: string
maxLength: 100
description: |
The accounting code on the commitment for customers.
**Note**: This field is only available if you have the Order to Revenue feature enabled.
adjustmentRevenueAccountingCode:
type: string
maxLength: 100
description: |
The accounting code on the commitment for customers.
**Note**: This field is only available if you have the Order to Revenue feature enabled.
contractAssetAccountingCode:
type: string
maxLength: 100
description: |
The accounting code on the commitment for customers.
**Note**: This field is only available if you have the Order to Revenue feature enabled.
contractLiabilityAccountingCode:
type: string
maxLength: 100
description: |
The accounting code on the commitment for customers.
**Note**: This field is only available if you have the Order to Revenue feature enabled.
contractRecognizedRevenueAccountingCode:
type: string
maxLength: 100
description: |
The accounting code on the commitment for customers.
**Note**: This field is only available if you have the Order to Revenue feature enabled.
deferredRevenueAccountingCode:
type: string
maxLength: 100
description: The deferred revenue accounting code for the commitment.
excludeItemBookingFromRevenueAccounting:
type: boolean
default: true
description: |
The flag to exclude commitment related booking items from revenue accounting.
excludeItemBillingFromRevenueAccounting:
type: boolean
description: |
The flag to exclude commitment related invoice items, invoice item adjustments, credit memo items, and debit memo items from revenue accounting.
**Note**: This field is only available if you have the Order to Revenue feature enabled.
eligibleAccountConditions:
$ref: '#/components/schemas/EligibleAccountCondition'
eligibleChargeConditions:
$ref: '#/components/schemas/EligibleChargeCondition'
periodAlignmentOption:
$ref: '#/components/schemas/PeriodAlignmentOptionEnum'
specificPeriodAlignmentDate:
type: string
format: date
description: The specific date for period alignment, required if `periodAlignmentOption` is `SpecificDate`.
isAllocationEligible:
type: boolean
description: |
This field is used to identify if the commitment is allocation eligible in revenue recognition.
**Note**: This field is only available if you have the Order to Revenue feature enabled.
isUnbilled:
type: boolean
description: |
This field is used to dictate how to perform the accounting during revenue recognition.
**Note**: This field is only available if you have the Order to Revenue feature enabled.
recognizedRevenueAccountingCode:
type: string
maxLength: 100
description: The recognized revenue accounting code for the commitment.
revenueAmortizationMethod:
description: |
This field is used to dictate the type of revenue amortization method.
type: string
maxLength: 200
revenueRecognitionRule:
type: string
description: The revenue recognition rule for the commitment.
revenueRecognitionTiming:
description: |
This field is used to dictate the type of revenue recognition timing.
type: string
maxLength: 200
unbilledReceivablesAccountingCode:
type: string
maxLength: 100
description: |
The accounting code on the commitment for customers.
**Note**: This field is only available if you have the Order to Revenue feature enabled.
taxable:
type: boolean
description: |
Determines whether the true-up invoice of a commitment is taxable. If the value is `true`, the tax code and tax mode are required.
taxCode:
type: string
description: |
Identifies which tax rules and tax rates to apply to the corresponding billing document.
taxMode:
type: string
description: |
The tax mode that determines whether tax is included or exclueded from the billing document.
enum:
- TaxInclusive
- TaxExclusive
CommitmentStatus:
type: string
enum:
- Active
- Canceled
description: |
Status of the commitment.
CommitmentCustomFields:
type: object
description: Container for custom fields of a Commitment object.
additionalProperties:
description: A custom field on the Commitment object.
type: string
ListCommitmentPeriodsResponse:
title: ListCommitmentPeriodsResponse
properties:
total:
type: integer
description: Total number of periods available for the given commitment/Total commitments for given account.
page:
type: integer
description: The current page number.
pageSize:
type: integer
description: The number of results returned per page.
periods:
description: A list of commitment period objects.
type: array
items:
$ref: '#/components/schemas/CommitmentPeriod'
CommitmentPeriod:
type: object
title: CommitmentPeriod
properties:
id:
type: string
description: ID of the commitment period.
commitmentId:
type: string
description: ID of the commitment.
commitmentNumber:
type: string
description: The number of the commitment.
version:
type: integer
description: Version of the commitment period.
type:
$ref: '#/components/schemas/CommitmentTypeEnum'
priority:
type: integer
description: Priority of the commitment.
currency:
type: string
description: Currency of the commitment.
isProrated:
type: boolean
description: Indicates if the period is prorated.
amount:
description: The total amount of the commitment within the current period.
type: number
format: double
status:
$ref: '#/components/schemas/PeriodStatusResponse'
startDate:
description: Ths start date of the commitment period.
type: string
format: date
endDate:
description: The end date of the commitment period.
type: string
format: date
PeriodStatusResponse:
type: string
enum:
- Active
- Canceled
- Evaluated
- ActiveWithDrawdown
description: |
Status of the commitment period.
GetCommitmentBalanceResponse:
title: GetCommitmentBalanceResponse
properties:
total:
type: integer
description: Total commitments for the given account.
page:
type: integer
description: The current page number.
pageSize:
type: integer
description: The number of results returned per page.
periods:
description: A list of commitment period objects.
type: array
items:
$ref: '#/components/schemas/PeriodBalance'
PeriodBalance:
type: object
title: PeriodBalance
properties:
id:
type: string
description: ID of the commitment period.
committedAmount:
description: The total amount of the commitment within the current period.
type: number
format: double
balance:
description: The balance amount to be spent within the current period.
type: number
format: double
totalSpend:
description: The total amount spent within the current period.
type: number
format: double
status:
$ref: '#/components/schemas/PeriodBalanceStatus'
startDate:
description: Ths start date of the commitment period.
type: string
format: date
endDate:
description: The end date of the commitment period.
type: string
format: date
PeriodBalanceStatus:
type: string
enum:
- ACTIVE
- EVALUATED
- ACTIVE_WITH_DRAWDOWN
description: |
A subset of the Period status. Periods in the 'Cancelled' status will not be included.
GetCommitmentScheduleResponse:
title: GetCommitmentScheduleResponse
properties:
schedules:
description: A list of commitment schedule objects.
type: array
items:
$ref: '#/components/schemas/ListCommitmentScheduleOutput'
total:
type: integer
description: Total number of schedules available for the given commitment.
page:
type: integer
description: The current page number.
pageSize:
type: integer
description: The number of results returned per page.
ListCommitmentScheduleOutput:
type: object
title: ListCommitmentScheduleOutput
properties:
id:
type: string
description: ID of the commitment schedule.
commitmentId:
type: string
description: ID of the commitment.
commitmentNumber:
type: string
description: The number of the commitment.
version:
description: Version of the commitment schedule.
type: integer
startDate:
description: Ths start date of the commitment schedule.
type: string
format: date
endDate:
description: The end date of the commitment schedule.
type: string
format: date
totalAmount:
description: The total amount of the commitment schedule.
type: number
format: double
amount:
description: The non-prorated actual amount of the commitment schedule.
type: number
format: double
amountBase:
$ref: '#/components/schemas/AmountBaseEnum'
periodType:
$ref: '#/components/schemas/PeriodTypeEnum'
specificPeriodLength:
description: The specific length of the period, required if `periodType` is `SpecificMonths`.
type: integer
status:
$ref: '#/components/schemas/CommitmentScheduleStatus'
CommitmentScheduleStatus:
type: string
enum:
- Active
- Canceled
- Evaluated
description: |
Status of the commitment schedule.
GETAdjustmentsBySubscriptionNumberResponseType:
allOf:
- $ref: '#/components/schemas/CommonResponse'
- properties:
adjustments:
description: |
Container for all the delivery adjustments of a subscription.
items:
$ref: '#/components/schemas/GETAdjustmentByIdResponseType'
type: array
type: object
GETAdjustmentByIdResponseType:
allOf:
- properties:
adjustmentId:
description: |
The system generated delivery adjustment ID.
format: UUID
type: string
adjustmentNumber:
description: |
The system generated delivery adjustment Number.
type: string
amount:
description: |
The amount of the delivery adjustment.
type: number
billingDate:
description: |
The billing date is same as the delivery date of the delivery adjustment, in `yyyy-mm-dd` format.
format: date
type: string
chargeNumber:
description: |
The charge number in the subscription for which the delivery adjustment is created.
type: string
creditMemoNumber:
description: |
The Credit Memo generated for the delivery adjustment.
type: string
debitMemoNumber:
description: |
The Debit Memo generated to write off the Credit Memo for the delivery adjustment.
**Note**: This field is only available when the delivery adjustment is in `Cancelled` status.
type: string
deferredRevenueAccountingCode:
description: |
The accounting code for the deferred revenue, such as Monthly Recurring Liability.
**Note**: For the credit memo generated by the delivery adjustment, if this field is not specified, the value inherits from the subscription rate plan charge.
type: string
deliveryDate:
description: |
The delivery adjustment date, in `yyyy-mm-dd` format.
format: date
type: string
deliveryDay:
description: |
The delivery adjustment day of the week.
format: string
type: string
reason:
description: |
The reason for the delivery adjustment.
type: string
recognizedRevenueAccountingCode:
description: |
The accounting code for the recognized revenue, such as Monthly Recurring Charges or Overage Charges.
**Note**: For the credit memo generated by the delivery adjustment, if this field is not specified, the value inherits from the subscription rate plan charge.
type: string
revenueRecognitionRuleName:
description: |
The name of the revenue recognition rule governing the revenue schedule.
**Note**: For the credit memo generated by the delivery adjustment, if this field is not specified, the value inherits from the subscription rate plan charge.
type: string
status:
description: |
The status of the delivery adjustment will be `Billed` or `Cancelled`.
type: string
subscriptionNumber:
description: |
The subscription number for which the delivery adjustment is created.
type: string
type: object
POSTCreateBillingAdjustmentRequestType:
example:
chargeNumbers:
- string
- string
deferredRevenueAccountingCode: string
endDate: '2023-02-27'
exclusion:
- chargeNumbers:
- string
- string
deliveryDate: '2023-02-26'
- chargeNumbers:
- string
- string
deliveryDate: '2023-05-27'
reason: string
recognizedRevenueAccountingCode: string
revenueRecognitionRuleName: string
startDate: '2023-02-26'
subscriptionNumber: string
type: DeliveryCredit
properties:
accountNumber:
description: |
The account number for which the delivery adjustment is created.
**Note**:
- The account number should be of the subscription owner.
- Only one of accountNumber or subscriptionNumber should be provided.
type: string
chargeNumbers:
description: |
An optional container to specify charge numbers in the subscription for which the delivery adjustment needs to be created.
items:
type: string
type: array
deferredRevenueAccountingCode:
description: |
The accounting code for the deferred revenue, such as Monthly Recurring Liability.
**Note**: For the credit memo generated by the delivery adjustment, if this field is not specified, the value inherits from the subscription rate plan charge.
type: string
endDate:
description: |
The end date of the delivery adjustment, in `yyyy-mm-dd` format. This is inclusive.
format: date
type: string
exclusion:
description: |
The charge numbers and the corresponding dates for exclusion of delivery adjustment.
items:
properties:
chargeNumbers:
description: |
The charge numbers to be excluded from delivery adjustment on the specified delivery date.
items:
type: string
type: array
deliveryDate:
description: |
The date on which the delivery adjustment has to be excluded, in `yyyy-mm-dd` format.
format: date
type: string
type: object
type: array
reason:
description: |
The reason for the delivery adjustment.
type: string
recognizedRevenueAccountingCode:
description: |
The accounting code for the recognized revenue, such as Monthly Recurring Charges or Overage Charges.
**Note**: For the credit memo generated by the delivery adjustment, if this field is not specified, the value inherits from the subscription rate plan charge.
type: string
revenueRecognitionRuleName:
description: |
The name of the revenue recognition rule governing the revenue schedule.
**Note**: For the credit memo generated by the delivery adjustment, if this field is not specified, the value inherits from the subscription rate plan charge.
type: string
startDate:
description: |
The start date of the delivery adjustment, in `yyyy-mm-dd` format. This is inclusive.
format: date
type: string
subscriptionNumber:
description: |
The subscription number for which the delivery adjustment is created.
**Note**: Only one of accountNumber or subscriptionNumber should be provided.
type: string
type:
description: |
The type of delivery adjustment.
enum:
- DeliveryCredit
type: string
creditMemoCustomFields:
additionalProperties:
description: |
Custom fields of the Credit Memo object. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Manage Custom Fields for more information.
type: object
description: |
Container for custom fields of the Credit Memo object. When creating a delivery adjustment, Zuora generates a credit memo automatically. You can use this field to specify the custom fields of the credit memo associated with this adjustment.
title: creditMemoCustomFields
type: object
required:
- startDate
- endDate
type: object
GETAdjustmentsResponseType:
allOf:
- $ref: '#/components/schemas/CommonResponse'
- properties:
adjustments:
description: |
Container for delivery adjustments of a subscription.
items:
$ref: '#/components/schemas/POSTAdjustmentResponseType'
type: array
ineligibleAdjustments:
description: |
Container for ineligible delivery adjustments of a subscription.
items:
$ref: '#/components/schemas/POSTIneligibleAdjustmentResponseType'
type: array
totalAmount:
description: |
The total amount of all the delivery adjustments.
type: number
totalNumberOfDeliveries:
description: |
The total number of all delivery adjustments.
type: number
type: object
POSTAdjustmentResponseType:
allOf:
- properties:
adjustmentId:
description: |
The system generated delivery adjustment ID.
format: UUID
type: string
adjustmentNumber:
description: |
The system generated delivery adjustment number.
format: string
type: string
amount:
description: |
The amount of the delivery adjustment.
type: number
billingDate:
description: |
The billing date is same as the delivery date of the delivery adjustment, in `yyyy-mm-dd` format.
format: date
type: string
chargeNumber:
description: |
The charge number in the subscription for which the delivery adjustment is created.
type: string
creditMemoNumber:
description: |
The Credit Memo generated for the delivery adjustment.
type: string
deferredRevenueAccountingCode:
description: |
The accounting code for the deferred revenue, such as Monthly Recurring Liability.
**Note**: For the credit memo generated by the delivery adjustment, if this field is not specified, the value inherits from the subscription rate plan charge.
type: string
deliveryDate:
description: |
The delivery adjustment date, in `yyyy-mm-dd` format.
format: date
type: string
deliveryDay:
description: |
The delivery adjustment day of the week.
type: string
eligible:
description: |
The eligible flag is set as true for a successfully created delivery adjustment.
type: boolean
reason:
description: |
The reason for the delivery adjustment.
type: string
recognizedRevenueAccountingCode:
description: |
The accounting code for the recognized revenue, such as Monthly Recurring Charges or Overage Charges.
**Note**: For the credit memo generated by the delivery adjustment, if this field is not specified, the value inherits from the subscription rate plan charge.
type: string
revenueRecognitionRuleName:
description: |
The name of the revenue recognition rule governing the revenue schedule.
**Note**: For the credit memo generated by the delivery adjustment, if this field is not specified, the value inherits from the subscription rate plan charge.
type: string
status:
description: |
The status of the delivery adjustment will be `Billed` or `Cancelled`.
type: string
subscriptionNumber:
description: |
The subscription number for which the delivery adjustment is created.
type: string
type: object
POSTIneligibleAdjustmentResponseType:
allOf:
- properties:
adjustmentId:
description: |
The system generated delivery adjustment ID.
format: UUID
type: string
adjustmentNumber:
description: |
The system generated delivery adjustment number.
format: string
type: string
amount:
description: |
The amount of the delivery adjustment.
type: number
billingDate:
description: |
The billing date of the delivery adjustment.
format: date
type: string
chargeNumber:
description: |
The charge number in the subscription for which the delivery adjustment is created.
type: string
deferredRevenueAccountingCode:
description: |
The accounting code for the deferred revenue, such as Monthly Recurring Liability.
**Note**: For the credit memo generated by the delivery adjustment, if this field is not specified, the value inherits from the subscription rate plan charge.
type: string
deliveryDate:
description: |
The delivery adjustment date, in `yyyy-mm-dd` format.
format: date
type: string
deliveryDay:
description: |
The delivery adjustment day of the week.
format: string
type: string
eligible:
description: |
The eligible flag is set as false for an unsuccessful delivery adjustment.
type: boolean
errorMessage:
description: |
The reason due to which a delivery adjustment is not eligible on the given date.
type: string
reason:
description: |
The reason for the delivery adjustment.
type: string
recognizedRevenueAccountingCode:
description: |
The accounting code for the recognized revenue, such as Monthly Recurring Charges or Overage Charges.
**Note**: For the credit memo generated by the delivery adjustment, if this field is not specified, the value inherits from the subscription rate plan charge.
type: string
revenueRecognitionRuleName:
description: |
The name of the revenue recognition rule governing the revenue schedule.
**Note**: For the credit memo generated by the delivery adjustment, if this field is not specified, the value inherits from the subscription rate plan charge.
type: string
status:
description: |
The status of the delivery adjustment.
type: string
subscriptionNumber:
description: |
The subscription number for which the delivery adjustment is created.
type: string
type: object
POSTPreviewBillingAdjustmentRequestType:
example:
chargeNumbers:
- string
- string
deferredRevenueAccountingCode: string
endDate: '2023-02-27'
exclusion:
- chargeNumbers:
- string
- string
deliveryDate: '2023-02-26'
- chargeNumbers:
- string
- string
deliveryDate: '2023-05-27'
reason: string
recognizedRevenueAccountingCode: string
revenueRecognitionRuleName: string
startDate: '2023-02-26'
subscriptionNumber: string
type: DeliveryCredit
properties:
accountNumber:
description: |
The account number for which the delivery adjustment is created.
**Note**:
- The account number should be of the subscription owner.
- Only one of accountNumber or subscriptionNumber should be provided.
type: string
chargeNumbers:
description: |
An optional container to specify charge numbers in the subscription for which the delivery adjustment needs to be created.
items:
type: string
type: array
deferredRevenueAccountingCode:
description: |
The accounting code for the deferred revenue, such as Monthly Recurring Liability.
**Note**: For the credit memo generated by the delivery adjustment, if this field is not specified, the value inherits from the subscription rate plan charge.
type: string
endDate:
description: |
The end date of the delivery adjustment, in `yyyy-mm-dd` format. This is inclusive.
format: date
type: string
reason:
description: |
The reason for the delivery adjustment.
type: string
recognizedRevenueAccountingCode:
description: |
The accounting code for the recognized revenue, such as Monthly Recurring Charges or Overage Charges.
**Note**: For the credit memo generated by the delivery adjustment, if this field is not specified, the value inherits from the subscription rate plan charge.
type: string
revenueRecognitionRuleName:
description: |
The name of the revenue recognition rule governing the revenue schedule.
**Note**: For the credit memo generated by the delivery adjustment, if this field is not specified, the value inherits from the subscription rate plan charge.
type: string
startDate:
description: |
The start date of the delivery adjustment, in `yyyy-mm-dd` format. This is inclusive.
format: date
type: string
subscriptionNumber:
description: |
The subscription number for which the delivery adjustment is created.
**Note**: Only one of accountNumber or subscriptionNumber should be provided.
type: string
type:
description: |
The type of delivery adjustment.
enum:
- DeliveryCredit
type: string
required:
- startDate
- endDate
type: object
CancelBillingAdjustmentRequest:
example:
debitMemoCustomFields:
trackingNumber__c: '001'
description: |
Information about `CancelBillingAdjustment`.
properties:
debitMemoCustomFields:
additionalProperties:
description: |
Custom fields of the Debit Memo object. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Manage Custom Fields for more information.
type: object
description: |
Container for custom fields of the Debit Memo object. When cancelling a delivery adjustment, Zuora generates a debit memo automatically. You can use this field to specify the custom fields of the debit memo associated with the cancellation of adjustment.
title: debitMemoCustomFields
type: object
GETCancelAdjustmentResponseType:
allOf:
- $ref: '#/components/schemas/CommonResponse'
- properties:
debitMemoNumber:
description: |
The Debit Memo generated to write off the Credit Memo for the delivery adjustment.
type: string
type: object
BillingDocumentQueryResponseElementType:
properties:
documents:
description: |
Container for billing documents.
items:
$ref: '#/components/schemas/GETBillingDocumentsResponseType'
type: array
nextPage:
description: |
URL to retrieve the next page of the response if it exists; otherwise absent.
format: URL
type: string
success:
description: Returns `true` if the request was processed successfully.
type: boolean
type: object
GETBillingDocumentsResponseType:
properties:
accountId:
description: The ID of the customer account associated with the billing document.
format: uuid
type: string
amount:
description: |
The total amount of the billing document.
format: double
type: number
balance:
description: |
The balance of the billing document.
format: double
type: number
documentDate:
description: |
The date of the billing document. The date can be the invoice date for invoices, credit memo date for credit memos, or debit memo date for debit memos.
format: date
type: string
documentNumber:
description: |
The number of the billing document.
type: string
documentType:
description: |
The type of the billing document.
enum:
- Invoice
- CreditMemo
- DebitMemo
type: string
id:
description: |
The ID of the billing document.
type: string
status:
description: |
The current status of the billing document.
enum:
- Draft
- Posted
- Canceled
- Error
type: string
currency:
description: |
The currency of the billing document.
**Note:** By default, the currency on a billing document matches the default currency set on the associated account.
However, Zuora now offers a Multiple Currencies feature to support different currencies for billing documents, allowing flexibility beyond the account-level currency.
For more information, see Multiple Currency.
type: string
nullable: true
title: documents
type: object
POSTBillingDocumentFilesDeletionJobRequest:
example:
accountIds:
- 4028905558b483220158b48983dd0015
- 6028905558b483220158b68983dd0016
properties:
accountIds:
description: |
Container for the IDs of the accounts that you want to create the billing document files deletion job for.
**Note**: When creating jobs to delete billing document PDF files, you must specify either set of `accountIds` or `accountKeys` in the request body.
items:
type: string
type: array
accountKeys:
description: |
Container for the IDs and/or numbers of the accounts that you want to create the billing document files deletion job for.
**Note**: When creating jobs to delete billing document PDF files, you must specify either set of `accountIds` or `accountKeys` in the request body.
items:
type: string
type: array
type: object
POSTBillingDocumentFilesDeletionJobResponse:
properties:
id:
description: |
The unique ID of the billing document file deletion job.
type: string
status:
description: |
The status of the billing document file deletion job.
enum:
- Pending
type: string
success:
description: Returns `true` if the request was processed successfully.
type: boolean
type: object
GETBillingDocumentFilesDeletionJobResponse:
properties:
id:
description: |
The unique ID of the billing document file deletion job.
type: string
status:
description: |
The status of the billing document file deletion job.
enum:
- Pending
- Processing
- Completed
- Error
type: string
success:
description: Returns `true` if the request was processed successfully.
type: boolean
type: object
PostGenerateBillingDocumentType:
example:
subscriptionIds:
- 8ad09be490a1ec6a0190a56eb69d4cd3
effectiveDate: '2024-07-01'
targetDate: '2024-08-31'
properties:
autoPost:
default: false
description: |
Whether to automatically post the billing documents after the draft billing documents are generated.
If an error occurs during posting billing documents, the draft billing documents are not generated too.
enum:
- true
- false
type: boolean
autoRenew:
default: false
description: |
Whether to automatically renew the subscriptions with **Auto Renew** set to **Yes**.
enum:
- true
- false
type: boolean
chargeTypeToExclude:
description: |
The types of the charges to be excluded from the generation of billing documents. The field values are case insensitive. Supported values include `onetime`, `recurring`, and `usage`.
items:
type: string
type: array
creditMemoReasonCode:
description: A code identifying the reason for the credit memo transaction that is generated by the request. The value must be an existing reason code. If you do not pass the field or pass the field with empty value, Zuora uses the default reason code.
type: string
effectiveDate:
description: |
The date on which to generate the billing documents, in `yyyy-mm-dd` format.
format: date
type: string
includeSubscriptions:
default: true
description: |
Indicates whether to bill subscriptions in the bill run.
type: boolean
includeOrderLineItems:
default: true
description: |
Indicates whether to bill order line items in the bill run.
type: boolean
subscriptionIds:
description: |
The IDs of the subscriptions that you want to create the billing documents for. Each value must be the ID of the latest version of an active subscription.
items:
type: string
type: array
targetDate:
description: |
The date used to determine which charges are to be billed, in `yyyy-mm-dd` format.
format: date
type: string
type: object
GenerateBillingDocumentResponseType:
properties:
creditMemos:
description: |
Container for generated credit memos.
**Note:** This container is only available if you have [Invoice Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement) 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.
items:
$ref: '#/components/schemas/CreditMemoResponseType'
type: array
invoices:
description: |
Container for generated invoics.
items:
$ref: '#/components/schemas/InvoiceResponseType'
type: array
success:
description: Returns `true` if the request was processed successfully.
type: boolean
type: object
CreditMemoResponseType:
properties:
id:
description: |
The ID of the generated credit memo.
type: string
title: creditMemos
type: object
InvoiceResponseType:
properties:
id:
description: |
The ID of the generated invoice.
type: string
title: invoices
type: object
PostInvoiceType:
allOf:
- properties:
accountId:
description: |
The ID of the account associated with the invoice.
You must specify either `accountNumber` or `accountId` for a customer account. If both of them are specified, they must refer to the same customer account.
type: string
accountNumber:
description: |
The Number of the account associated with the invoice.
You must specify either `accountNumber` or `accountId` for a customer account. If both of them are specified, they must refer to the same customer account.
type: string
autoPay:
default: false
description: |
Whether invoices are automatically picked up for processing in the corresponding payment run.
type: boolean
billToContact:
$ref: '#/components/schemas/PostCreateInvoiceContactType'
billToContactId:
description: |
The ID of the bill-to contact associated with the invoice. This field is mutually exclusive with the `billToContact` field.
**Note**: If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body.
type: string
comments:
description: |
Comments about the invoice.
type: string
currency:
description: |
The code of a currency as defined in Billing Settings through the Zuora UI.
If you do not specify a currency during standalone invoice creation, the default account currency is applied. The currency that you specify in the request must be configured and activated in Billing Settings.
**Note**: This field is available only if you have the Multiple Currencies feature enabled.
type: string
customRates:
description: |
It contains Home currency and Reporting currency custom rates currencies. The maximum number of items is 2 (you can pass the Home currency item or Reporting currency item or both).
**Note**:
- This field is available only if you are on the latest Zuora API minor version, or you set the `Zuora-Version` request header to `224.0` or [a later available version](https://developer.zuora.com/v1-api-reference/api-versions/#minor-version).
- You cannot set the custom rates, if both the **Automatically include additional Currency Conversion information in data source exports** option and **Fx data** feature are enabled.
- Invoice, InvoiceItem, and TaxationItem will utilize the provided custom Fx rate to convert amounts from the transactional currency to the home currency.
items:
$ref: '#/components/schemas/InvoiceWithCustomRatesType'
maxItems: 2
type: array
dueDate:
description: |
The date by which the payment for this invoice is due, in `yyyy-mm-dd` format.
format: date
type: string
invoiceDate:
description: |
The date that appears on the invoice being created, in `yyyy-mm-dd` format. The value cannot fall in a closed accounting period.
format: date
type: string
invoiceItems:
description: |
Container for invoice items. The maximum number of invoice items is 1,000.
You must have corresponding billing permissions to create invoice items from existing product rate plan charges or new charges. For more information about billing permissions, see Billing Roles.
- To create an invoice item from an existing charge, you must have the **Create Standalone Invoice With Product Catalog** permission and specify the charge ID in the `productRatePlanChargeId` field.
- To create an invoice item from a new charge, you must have the **Create Standalone Invoice Without Product Catalog** permission without specifying the `productRatePlanChargeId` field.
**Note**: For the "Create a standalone invoice" and "Create standalone invoices" operations, note the following:
- If tax has been calculated by an external tax engine, you need to create a standalone invoice with both `invoiceItems` and `taxItems`. The `taxItems` corresponds to the tax information processed by this external tax engine. In this case, you should not specify the `taxMode` and `taxCode` nested fields of the `invoiceItems` field. Instead, you need to specify the `taxMode` and `taxCode` nested fields of the `taxItems` field. You need to specify the `taxMode` field as `TaxExclusive`.
- If tax has not been calculated by an external tax engine, you can create a standalone invoice only with `invoiceItems`, and decide whether Zuora includes the tax in the quoted charge price and invoice item by specifying the `taxMode` nested field of the `invoiceItems` field as either `TaxExclusive` or `TaxInclusive`. Meanwhile, you need to specify the `taxCode` field, indicating the charge price and invoice item are taxable.
items:
$ref: '#/components/schemas/PostInvoiceItemType'
type: array
invoiceNumber:
description: |
A customized invoice number with the following format requirements:
- Max length: 32 characters
- Acceptable characters: a-z,A-Z,0-9,-,_,
Purely numerical prefixes or prefixes ending with a number are supported for standalone invoices. For example, you can use `202310000300`, `2003`, `INV202310000300`, or `2023-09-100009785` as invoice numbers.
The value must be unique in the system, otherwise it may cause issues with bill runs and subscribe/amend. Check out [things to note and troubleshooting steps](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/IA_Invoices/Unified_Invoicing/Import_external_invoices_as_standalone_invoices?#Customizing_invoice_number).
type: string
paymentTerm:
description: |
The ID or name of the payment term associated with the invoice. For example, `Net 30`. The payment term determines the due dates of invoices.
**Note**: If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body.
type: string
sequenceSet:
description: |
The ID or name of the sequence set associated with the invoice.
**Note**: If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body.
type: string
shipToContact:
$ref: '#/components/schemas/PostCreateInvoiceContactType'
shipToContactId:
description: |
The ID of the ship-to contact associated with the invoice. This field is mutually exclusive with the `shipToContact` field.
**Note**: If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body.
type: string
shipToSameAsBillTo:
default: false
description: |
Whether the ship-to contact and bill-to contact are the same entity. This field is mutually exclusive with the `shipToContact` and `shipToContactId` fields.
The created invoice has the same bill-to contact and ship-to contact entity only when all the following conditions are met in the request body:
- This field is set to `true`.
- A bill-to contact or bill-to contact ID is specified.
- Neither ship-to contact nor ship-to contact ID is specified.
**Note**: If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body.
type: boolean
soldToContact:
$ref: '#/components/schemas/PostCreateInvoiceContactType'
soldToContactId:
description: |
The ID of the sold-to contact associated with the invoice. This field is mutually exclusive with the `soldToContact` field.
**Note**: If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body.
type: string
soldToSameAsBillTo:
default: false
description: |
Whether the sold-to contact and bill-to contact are the same entity. This field is mutually exclusive with the `soldToContact` and `soldToContactId` fields.
The created invoice has the same bill-to contact and sold-to contact entity only when all the following conditions are met in the request body:
- This field is set to `true`.
- A bill-to contact or bill-to contact ID is specified.
- Neither sold-to contact nor sold-to contact ID is specified.
**Note**: If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body.
type: boolean
status:
default: Draft
description: |
The status of invoice. By default, the invoice status is Draft.
When creating an invoice, if you set this field to `Posted`, the invoice is created and posted directly.
enum:
- Draft
- Posted
type: string
templateId:
description: |
The ID of the invoice template associated with the invoice.
**Note**: If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body.
type: string
transferredToAccounting:
enum:
- Processing
- Error
- Ignore
- 'Yes'
- 'No'
type: string
required:
- invoiceDate
title: invoices
type: object
- $ref: '#/components/schemas/InvoiceObjectNSFields'
- $ref: '#/components/schemas/InvoiceObjectCustomFields'
example:
accountId: 8ad09be48db5aba7018db604776d4854
invoiceDate: '2024-07-30'
invoiceItems:
- amount: 100
serviceStartDate: '2024-07-11'
productRatePlanChargeId: 8ad097b4909708e001909b41bb085d38
PostInvoiceResponse:
allOf:
- properties:
accountId:
description: |
The ID of the customer account associated with the invoice.
type: string
adjustmentAmount:
description: |
The amount of the invoice adjustments associated with the invoice.
type: number
amount:
description: |
The total amount of the invoice.
type: number
amountWithoutTax:
description: |
The invoice amount excluding tax.
type: number
autoPay:
description: |
Whether invoices are automatically picked up for processing in the corresponding payment run.
type: boolean
balance:
description: |
The remaining balance of the invoice after all payments, adjustments, and refunds are applied.
type: number
billRunId:
description: |
The id of bill run if the invoice is generated by a bill run.
type: string
billToContactId:
description: |
The ID of the bill-to contact associated with the invoice.
type: string
nullable: true
billToContactSnapshotId:
description: |
The ID of the bill-to contact snapshot associated with the invoice.
type: string
comments:
description: |
Comments about the invoice.
type: string
createdById:
description: |
The user ID of the person who created the invoice. If a bill run generated the invoice, then the value is the user ID of person who created the bill run.
type: string
createdDate:
description: |
The date and time when the invoice was created, in `yyyy-mm-dd hh:mm:ss` format. For example, 2017-03-01 15:31:10.
format: date-time
type: string
creditBalanceAdjustmentAmount:
description: |
The currency amount of the adjustment applied to the customer's credit balance.
**Note:** This field is only available if you have the Credit Balance feature enabled and the Invoice Settlement feature disabled.
type: number
creditMemoAmount:
description: |
The currency amount of all credit memos applied to this invoice.
**Note:** This field is only available if you have [Invoice Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement) 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: number
currency:
description: |
The currency of the invoice.
**Note:** By default, the currency on a billing document matches the default currency set on the associated account.
However, Zuora now offers a Multiple Currencies feature to support different currencies for billing documents, allowing flexibility beyond the account-level currency.
For more information, see Multiple Currency.
nullable: true
type: string
discount:
description: |
the invoice discount amount.
type: number
dueDate:
description: |
The date by which the payment for this invoice is due, in `yyyy-mm-dd` format.
format: date
type: string
einvoiceErrorCode:
description: |
The error code when status is "Failed". This code can either be a Zuora-generated error code or one returned by a third-party e-invoice vendor.
type: string
einvoiceErrorMessage:
description: |
The error message when status is "Failed". This message can either be a Zuora-generated error code or one returned by a third-party e-invoice vendor.
type: string
einvoiceFileId:
description: |
The ID of the e-invoice file.
type: string
einvoiceStatus:
description: |
The status of the e-invoice file generation for the invoice.
- If e-invoicing file generation succeeds, this field is either `Generated` or `Success`, and both the error code and message are empty, and the `eInvoiceField` fieldstores the ID of the generated e-inoice file.
- If the responses from tax vendors such as Sovos or Avalara are taking too long, this field becomes `RetrieveTimeOut`. Once the vendor responds successfully, you can use the 'Resync E-Invoice Status' action to update the status automatically. You can view these updates in System Health telemetry.
- If a failure occurs during e-invoice file generation, this field is `Failed` and error code and an error message are returned respectively in the `einvoiceErrorCode` and `einvoiceErrorMessage` fields.
- If e-invoice file generation conditionally succeeds, this field is `ConditionalSuccess` and an error code and an error message are returned respectively in the `einvoiceErrorCode` and `einvoiceErrorMessage` fields.
- If the e-invoice file has been approved by the tax authority, this field is `ApprovedByAuthority`. The next status will be either `Success` or `Rejected`.
- If the e-invoice file has been rejected by the government, this field is `Rejected`. You cannot resend this e-invoice; you must create a new invoice instead.
**Note**: This field is available only if you have the E-Invoicing feature in **Early Adopter** phase enabled.
enum:
- Processing
- RetrieveTimeOut
- Generated
- Success
- Failed
- ConditionalSuccess
- ApprovedByAuthority
- Rejected
type: string
id:
description: |
The unique ID of the invoice.
type: string
includesOneTime:
description: |
Specifies whether the invoice includes one-time charges.
type: boolean
includesRecurring:
description: |
Specifies whether the invoice includes recurring charges.
type: boolean
includesUsage:
description: |
Specifies whether the invoice includes usage charges.
type: boolean
invoiceDate:
description: |
The date that appears on the invoice being created.
format: date
type: string
invoiceGroupNumber:
description: |
The number of the invoice group associated with the invoice.
The value of this field is `null` if you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled.
type: string
nullable: true
invoiceNumber:
description: |
The unique identification number of the invoice.
type: string
lastEmailSentDate:
description: |
The date when the invoice was last emailed.
type: string
organizationLabel:
description: |
The organization that this object belongs to.
Note: This field is available only when the Multi-Org feature is enabled.
type: string
paymentAmount:
description: |
The amount of payments applied to the invoice.
type: number
paymentTerm:
description: |
The name of payment term associated with the invoice.
type: string
nullable: true
postedBy:
description: |
The user ID of the person who moved the invoice to Posted status.
type: string
postedDate:
description: |
The date when the invoice was posted.
format: date
type: string
refundAmount:
description: |
Specifies the amount of a refund that was applied against an earlier payment on the invoice.
type: number
sequenceSetId:
description: |
The ID of the sequence set associated with the invoice.
type: string
nullable: true
communicationProfileId:
description: |
The ID of the communication profile associated with the invoice.
type: string
nullable: true
shipToContactId:
description: |
The ID of the ship-to contact associated with the invoice.
type: string
nullable: true
shipToContactSnapshotId:
description: |
The ID of the ship-to contact snapshot associated with the invoice.
type: string
soldToContactId:
description: |
The ID of the sold-to contact associated with the invoice.
type: string
nullable: true
soldToContactSnapshotId:
description: |
The ID of the sold-to contact snapshot associated with the invoice.
type: string
source:
description: |
The source of the invoice.
enum:
- BillRun
- API
- ApiSubscribe
- ApiAmend
type: string
sourceId:
description: |
The ID of the invoice source.
If an invoice is generated from a bill run, the value is the number of the corresponding bill run.Otherwise, the value is `null`.
type: string
sourceType:
description: |
The type of the invoice source.
enum:
- Subscription
- Standalone
- Order
- Consolidation
type: string
status:
description: |
The status of the invoice.
enum:
- Draft
- Posted
type: string
success:
description: Returns `true` if the request was processed successfully.
type: boolean
targetDate:
description: |
This date is used to determine which charges are to be billed. All charges that are to be billed on this date or prior will be included in this bill run.
format: date
type: string
taxAmount:
description: |
The amount of taxation.
type: number
taxExemptAmount:
description: |
The calculated tax amount excluded due to the exemption.
type: number
taxMessage:
description: |
The message that the tax engine return if it calculates the taxes of this invoice fails.
type: string
nullable: true
taxStatus:
description: |
The status that the tax engine return after it calculates the taxes of this invoice.
**Note:** This field is only applicable to tax calculation by third-party tax engines. The `Voided` status indicates that the tax transaction is successfully canceled on the tax vendor's side. If a tax transaction was successfully committed to the third-party tax engine but the invoice failed to post, Zuora automatically detects the issue and voids the tax transaction on the vendor's side.
enum:
- Complete
- Error
- UnknownError
- DuplicateDoc
- InvalidRequest
- InvalidResponse
- TaxEngineError
- ConcurrentModify
- InternalServerError
- TaxCodeTemplateError
- Voided
type: string
templateId:
description: |
The ID of the invoice template.
- If you have the Flexible Billing Attributes feature enabled, the value of this field depends on the configuration of the invoice template.
- If you specify an invoice template at the subscription level, the value of this field is automatically populated from the corresponding subscription.
- If you do not specify any invoice template at the subscription level, the value of this field is automatically populated from the corresponding account.
- If you have the Flexible Billing Attributes feature disabled, the value of this field is `null`.
type: string
nullable: true
transferredToAccounting:
description: |
Whether the invoice was transferred to an external accounting system.
enum:
- Processing
- Error
- Ignore
- 'Yes'
- 'No'
type: string
updatedById:
description: |
The ID of the Zuora user who last updated the invoice.
type: string
updatedDate:
description: |
The date when the invoice was last updated.
format: date-time
type: string
type: object
- $ref: '#/components/schemas/InvoiceObjectNSFields'
- $ref: '#/components/schemas/InvoiceObjectCustomFields'
InvoiceObjectNSFields:
description: |
Container for Invoice fields provided by the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
properties:
IntegrationId__NS:
description: |
ID of the corresponding object in NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
maxLength: 255
type: string
IntegrationStatus__NS:
description: |
Status of the invoice's synchronization with NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
maxLength: 255
type: string
SyncDate__NS:
description: |
Date when the invoice was synchronized with NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
maxLength: 255
type: string
title: invoiceFieldsNS
type: object
InvoiceObjectCustomFields:
additionalProperties:
description: |
Custom fields of the Invoice object. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
description: |
Container for custom fields of an Invoice object.
title: invoiceFieldsCustom
type: object
PostCreateInvoiceContactType:
allOf:
- properties:
address1:
description: |
First address line, 255 characters or less.
maxLength: 255
type: string
address2:
description: |
Second address line, 255 characters or less.
type: string
city:
description: |
City, 40 characters or less.
maxLength: 40
type: string
country:
description: |
Country; must be a valid country name or abbreviation. If using Zuora Tax, you must specify a country in the ship-to or sold-to contact to calculate tax. A bill-to contact may be used if no ship-to or sold-to contact is provided.
type: string
county:
description: |
County; 32 characters or less. May optionally be used by Zuora Tax to calculate county tax.
maxLength: 32
type: string
fax:
description: |
Fax phone number, 40 characters or less.
maxLength: 40
type: string
firstName:
description: |
First name, 100 characters or less.
maxLength: 100
type: string
homePhone:
description: |
Home phone number, 40 characters or less.
maxLength: 40
type: string
lastName:
description: |
Last name, 100 characters or less.
maxLength: 100
type: string
mobilePhone:
description: |
Mobile phone number, 40 characters or less.
maxLength: 40
type: string
nickname:
description: |
Nickname for this contact
type: string
otherPhone:
description: |
Other phone number, 40 characters or less.
maxLength: 40
type: string
otherPhoneType:
description: |
Possible values are: `Work`, `Mobile`, `Home`, `Other`.
type: string
personalEmail:
description: |
Personal email address.
maxLength: 80
type: string
format: email
state:
description: |
State; must be a valid subregion (state or province) name or code.
For more information, see View subregions of a specific country or region.
If using Zuora Tax, be aware that Zuora Tax requires a
state (in the US) or province (in Canada) in this field for the
ship-to or sold-to contact to calculate tax, and that a bill-to contact may be
used if no ship-to or sold-to contact is provided.
type: string
taxRegion:
description: |
If using Zuora Tax, a region string as optionally defined in your tax rules. Not required.
type: string
workEmail:
description: |
Work email address, 80 characters or less.
maxLength: 80
type: string
workPhone:
description: |
Work phone number, 40 characters or less.
maxLength: 40
type: string
zipCode:
description: |
Zip code, 20 characters or less.
maxLength: 20
type: string
required:
- firstName
- lastName
type: object
- $ref: '#/components/schemas/ContactCustomFields'
description: |
Container for bill-to, sold-to, or ship-to contact information. A new Contact will be created under the invoice owner account.
**Note**: If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body.
title: Contact
InvoiceWithCustomRatesType:
allOf:
- properties:
currency:
description: |
The currency code for either Reporting or Home currency.
**Note**: This field is available only if you are on the latest Zuora API minor version, or you set the `Zuora-Version` request header to `224.0` or later.
type: string
customFxRate:
description: |
The Custom FX conversion rate between Home/Reporting and Transactional currency items.
**Note**: This field is available only if you are on the latest Zuora API minor version, or you set the `Zuora-Version` request header to `224.0` or later.
format: decimal
type: number
rateDate:
description: |
The date on which a particular currency rate is fixed or obtained on.
**Note**: This field is available only if you are on the latest Zuora API minor version, or you set the `Zuora-Version` request header to `224.0` or later.
format: date
type: string
required:
- currency
- customFxRate
type: object
title: customRates
PostInvoiceItemType:
allOf:
- properties:
accountingCode:
description: |
The accounting code associated with the invoice item.
type: string
adjustmentLiabilityAccountingCode:
description: |
The accounting code for adjustment liability.
**Note**: This field is only available if you have the Billing - Revenue Integration feature enabled.
type: string
adjustmentRevenueAccountingCode:
description: |
The accounting code for adjustment revenue.
**Note**: This field is only available if you have the Billing - Revenue Integration feature enabled.
type: string
amount:
description: |
The amount of the invoice item.
- For tax-inclusive invoice items, the amount indicates the invoice item amount including tax.
- For tax-exclusive invoice items, the amount indicates the invoice item amount excluding tax.
type: number
bookingReference:
description: |
The booking reference of the invoice item.
type: string
chargeDate:
description: |
The date when the invoice item is charged, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
chargeName:
description: |
The name of the charge associated with the invoice item.
This field is required if the `productRatePlanChargeId` field is not specified in the request.
type: string
contractAssetAccountingCode:
description: |
The accounting code for contract asset.
**Note**: This field is only available if you have the Billing - Revenue Integration feature enabled.
type: string
contractLiabilityAccountingCode:
description: |
The accounting code for contract liability.
**Note**: This field is only available if you have the Billing - Revenue Integration feature enabled.
type: string
contractRecognizedRevenueAccountingCode:
description: |
The accounting code for contract recognized revenue.
**Note**: This field is only available if you have the Billing - Revenue Integration feature enabled.
type: string
deferredRevenueAccountingCode:
description: |
The accounting code for the deferred revenue, such as Monthly Recurring Liability.
**Note:** This field is only available if you have Zuora Finance enabled.
type: string
description:
description: |
The description of the invoice item.
type: string
discountItems:
description: |
Container for discount items. The maximum number of discount items is 10.
items:
$ref: '#/components/schemas/PostDiscountItemType'
type: array
excludeItemBillingFromRevenueAccounting:
description: |
The flag to exclude the invoice item from revenue accounting.
**Note**: This field is only available if you have the Billing - Revenue Integration feature enabled.
type: boolean
itemType:
description: |
The type of the invoice item.
type: string
productRatePlanChargeId:
description: |
The ID of the product rate plan charge that the invoice item is created from.
You must have the **Create Standalone Invoice With Product Catalog** permission to create an invoice item from an existing charge.
If you specify a value for the `productRatePlanChargeId` field in the request, Zuora directly copies the values of the following fields from the corresponding product rate plan charge, regardless of the values specified in the request body:
- `chargeName`
- `sku`
- `uom`
- `taxCode`
- `taxMode`
- `accountingCode`
- `deferredRevenueAccountingCode`
- `recognizedRevenueAccountingCode`
type: string
purchaseOrderNumber:
description: |
The purchase order number associated with the invoice item.
type: string
quantity:
default: 1
description: |
The number of units for the invoice item.
type: number
recognizedRevenueAccountingCode:
description: |
The accounting code for the recognized revenue, such as Monthly Recurring Charges or Overage Charges.
**Note:** This field is only available if you have Zuora Finance enabled.
type: string
revRecCode:
description: |
The revenue recognition code.
type: string
revRecTriggerCondition:
description: |
The date when revenue recognition is triggered.
enum:
- ContractEffectiveDate
- ServiceActivationDate
- CustomerAcceptanceDate
type: string
revenueRecognitionRuleName:
description: |
The name of the revenue recognition rule governing the revenue schedule.
**Note:** This field is only available if you have Zuora Finance enabled.
type: string
serviceEndDate:
description: |
The service end date of the invoice item.
format: date
type: string
serviceStartDate:
description: |
The service start date of the invoice item.
format: date
type: string
sku:
description: |
The SKU of the invoice item. The SKU of the invoice item must be different from the SKU of any existing product.
type: string
taxCode:
description: |
The tax code identifies which tax rules and tax rates to apply to the invoice item.
**Note**: This field is only available only if you have Taxation enabled.
type: string
taxItems:
description: |
Container for taxation items. The maximum number of taxation items is 5.
**Note**: This field is only available only if you have Taxation enabled.
items:
$ref: '#/components/schemas/PostTaxationItemType'
type: array
taxMode:
description: |
The tax mode of the invoice item, indicating whether the amount of the invoice item includes tax.
**Note**: This field is only available only if you have Taxation enabled.
enum:
- TaxInclusive
- TaxExclusive
type: string
unbilledReceivablesAccountingCode:
description: |
The accounting code for unbilled receivables.
**Note**: This field is only available if you have the Billing - Revenue Integration feature enabled.
type: string
unitPrice:
description: |
The per-unit price of the invoice item. To pass Level 3 data to the gateway, this field is required and must be greater than zero.
type: number
uom:
description: |
The unit of measure.
type: string
required:
- amount
- serviceStartDate
title: invoiceItems
type: object
- $ref: '#/components/schemas/InvoiceItemObjectNSFields'
- $ref: '#/components/schemas/InvoiceItemObjectCustomFields'
PostDiscountItemType:
allOf:
- properties:
accountingCode:
description: |
The accounting code associated with the discount item.
type: string
accountsReceivableAccountingCode:
description: |
The accounting code for accounts receivable.
type: string
adjustmentLiabilityAccountingCode:
description: |
The accounting code for adjustment liability.
**Note**: This field is only available if you have the Billing - Revenue Integration feature enabled.
type: string
adjustmentRevenueAccountingCode:
description: |
The accounting code for adjustment revenue.
**Note**: This field is only available if you have the Billing - Revenue Integration feature enabled.
type: string
amount:
description: |
The amount of the discount item.
- Should be a negative number. For example, `-10`.
- Always a fixed amount no matter whether the discount charge associated with the discount item uses the [fixed-amount model or percentage model](https://knowledgecenter.zuora.com/Billing/Subscriptions/Product_Catalog/B_Charge_Models/B_Discount_Charge_Models#Fixed_amount_model_and_percentage_model).
- For tax-exclusive discount items, this amount indicates the discount item amount excluding tax.
- For tax-inclusive discount items, this amount indicates the discount item amount including tax.
type: number
bookingReference:
description: |
The booking reference of the discount item.
type: string
chargeDate:
description: |
The date when the discount item is charged, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
chargeName:
description: |
The name of the charge associated with the discount item.
This field is required if the `productRatePlanChargeId` field is not specified in the request body.
type: string
contractAssetAccountingCode:
description: |
The accounting code for contract asset.
**Note**: This field is only available if you have the Billing - Revenue Integration feature enabled.
type: string
contractLiabilityAccountingCode:
description: |
The accounting code for contract liability.
**Note**: This field is only available if you have the Billing - Revenue Integration feature enabled.
type: string
contractRecognizedRevenueAccountingCode:
description: |
The accounting code for contract recognized revenue.
**Note**: This field is only available if you have the Billing - Revenue Integration feature enabled.
type: string
deferredRevenueAccountingCode:
description: |
The accounting code for the deferred revenue, such as Monthly Recurring Liability.
**Note:** This field is only available if you have Zuora Finance enabled.
type: string
description:
description: |
The description of the discount item.
type: string
itemType:
description: |
The type of the discount item.
type: string
productRatePlanChargeId:
description: |
The ID of the product rate plan charge that the discount item is created from.
If you specify a value for the `productRatePlanChargeId` field in the request, Zuora directly copies the values of the following fields from the corresponding product rate plan charge, regardless of the values specified in the request body:
- `chargeName`
- `sku`
If you specify a value for the `productRatePlanChargeId` field in the request, Zuora directly copies the values of the following fields from the corresponding discount charge that [uses discount specific accounting codes, rule and segment to manage revenue](https://knowledgecenter.zuora.com/Billing/Subscriptions/Product_Catalog/B_Charge_Models/Manage_Discount_Charges#Use_discount_specific_accounting_codes.2C_rule_and_segment_to_manage_revenue), regardless of the values specified in the request body:
- `accountingCode`
- `deferredRevenueAccountingCode`
- `recognizedRevenueAccountingCode`
If you specify a value for the `productRatePlanChargeId` field in the request, Zuora directly copies the values of the following fields from the corresponding invoice item charge if the discount charge DOES NOT [use discount specific accounting codes, rule and segment to manage revenue](https://knowledgecenter.zuora.com/Billing/Subscriptions/Product_Catalog/B_Charge_Models/Manage_Discount_Charges#Use_discount_specific_accounting_codes.2C_rule_and_segment_to_manage_revenue), regardless of the values specified in the request body:
- `accountingCode`
- `deferredRevenueAccountingCode`
- `recognizedRevenueAccountingCode`
type: string
purchaseOrderNumber:
description: |
The purchase order number associated with the discount item.
type: string
recognizedRevenueAccountingCode:
description: |
The accounting code for the recognized revenue, such as Monthly Recurring Charges or Overage Charges.
**Note:** This field is only available if you have Zuora Finance enabled.
type: string
revRecCode:
description: |
The revenue recognition code.
type: string
revRecTriggerCondition:
description: |
The date when revenue recognition is triggered.
enum:
- ContractEffectiveDate
- ServiceActivationDate
- CustomerAcceptanceDate
type: string
revenueRecognitionRuleName:
description: |
The name of the revenue recognition rule governing the revenue schedule.
**Note:** This field is only available if you have Zuora Finance enabled.
type: string
sku:
description: |
The SKU of the invoice item. The SKU of the discount item must be different from the SKU of any existing product.
type: string
taxItems:
description: |
Container for taxation items. The maximum number of taxation items is 5.
**Note**: This field is only available only if you have Taxation enabled.
items:
$ref: '#/components/schemas/PostTaxationItemType'
type: array
unbilledReceivablesAccountingCode:
description: |
The accounting code for unbilled receivables.
**Note**: This field is only available if you have the Billing - Revenue Integration feature enabled.
type: string
unitPrice:
description: |
The per-unit price of the discount item.
If the discount charge associated with the discount item uses the percentage model, the unit price will display as a percentage amount in PDF. For example: if unit price is 5.00, it will display as 5.00% in PDF.
type: number
required:
- amount
title: invoiceItems
type: object
- $ref: '#/components/schemas/DiscountItemObjectNSFields'
- $ref: '#/components/schemas/DiscountItemObjectCustomFields'
PostTaxationItemType:
allOf:
- properties:
exemptAmount:
description: |
The calculated tax amount excluded due to the exemption.
format: number
type: string
jurisdiction:
description: |
The jurisdiction that applies the tax or VAT. This value is typically a state, province, county, or city.
type: string
locationCode:
description: |
The identifier for the location based on the value of the `taxCode` field.
type: string
name:
description: |
The name of taxation.
type: string
taxAmount:
description: |
The amount of the taxation item in the invoice item.
format: number
type: string
taxCode:
description: |
The tax code identifies which tax rules and tax rates to apply to a specific invoice item.
type: string
taxCodeDescription:
description: |
The description of the tax code.
type: string
taxDate:
description: |
The date that the tax is applied to the invoice item, in `yyyy-mm-dd` format.
format: date
type: string
taxMode:
description: |
The tax mode of the invoice item, indicating whether the amount of the invoice item includes tax.
enum:
- TaxInclusive
- TaxExclusive
type: string
taxRate:
description: |
The tax rate applied to the invoice item.
format: number
type: string
taxRateDescription:
description: |
The description of the tax rate.
type: string
taxRateType:
description: |
The type of the tax rate applied to the invoice item.
enum:
- Percentage
- FlatFee
type: string
required:
- name
- taxAmount
- taxDate
- taxMode
- taxRate
- taxRateType
title: taxItems
type: object
- $ref: '#/components/schemas/TaxationItemObjectCustomFields'
InvoiceItemObjectNSFields:
description: |
Container for Invoice Item fields provided by the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
properties:
IntegrationId__NS:
description: |
ID of the corresponding object in NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
maxLength: 255
type: string
IntegrationStatus__NS:
description: |
Status of the invoice item's synchronization with NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
maxLength: 255
type: string
SyncDate__NS:
description: |
Date when the invoice item was synchronized with NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
maxLength: 255
type: string
title: invoiceItemFieldsNS
type: object
InvoiceItemObjectCustomFields:
additionalProperties:
description: |
Custom fields of the Invoice Item object. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
description: |
Container for custom fields of an Invoice Item object.
title: invoiceItemFieldsCustom
type: object
TaxationItemObjectCustomFields:
additionalProperties:
description: |
Custom fields of the Taxation Item object. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
description: |
Container for custom fields of a Taxation Item object.
title: taxationItemFieldsCustom
type: object
DiscountItemObjectNSFields:
description: |
Container for discount Item fields provided by the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
properties:
IntegrationId__NS:
description: |
ID of the corresponding object in NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
maxLength: 255
type: string
IntegrationStatus__NS:
description: |
Status of the invoice item's synchronization with NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
maxLength: 255
type: string
SyncDate__NS:
description: |
Date when the invoice item was synchronized with NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
maxLength: 255
type: string
title: discountItemFieldsNS
type: object
DiscountItemObjectCustomFields:
additionalProperties:
description: |
Custom fields of the Discount Item object. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
description: |
Container for custom fields of an Discount Item object.
title: discountItemFieldsCustom
type: object
ContactCustomFields:
additionalProperties:
description: |
Custom fields of the Contact object. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
PutBatchInvoiceType:
example:
invoices:
- id: 2c93808457d787030157e031d86c4c57
invoiceDate: '2017-12-16'
- id: 2c92c8955bd63cc1015bd7c151af02ab
invoiceDate: '2017-12-16'
properties:
invoices:
description: |
Container for invoice update details.
items:
$ref: '#/components/schemas/BatchInvoiceType'
type: array
type: object
BatchInvoiceType:
allOf:
- properties:
autoPay:
description: |
Whether invoices are automatically picked up for processing in the corresponding payment run.
By default, invoices are automatically picked up for processing in the corresponding payment run.
type: boolean
comments:
description: |
Additional information related to the invoice that a Zuora user added to the invoice.
maxLength: 255
type: string
dueDate:
description: |
The date by which the payment for this invoice is due.
format: date
type: string
id:
description: |
The ID of the invoice to be updated.
type: string
invoiceDate:
description: |
The new invoice date of the invoice. The new invoice date cannot fall in a closed accounting period.
You can only specify `invoiceDate` or `dueDate` in one request. Otherwise, an error occurs.
format: date
type: string
invoiceItems:
description: |
Container for invoice items. The maximum number of items is 1,000.
items:
$ref: '#/components/schemas/PutInvoiceItemType'
type: array
transferredToAccounting:
description: |
Whether the invoice was transferred to an external accounting system.
enum:
- Processing
- 'Yes'
- Error
- Ignore
type: string
templateId:
description: |
The ID of the invoice template associated with the invoice.
**Note**: This field is only available if you have the Flexible Billing Attributes feature enabled.
type: string
type: object
- $ref: '#/components/schemas/InvoiceObjectNSFields'
- $ref: '#/components/schemas/InvoiceObjectCustomFields'
title: invoices
PutInvoiceItemType:
allOf:
- properties:
accountingCode:
description: |
The accounting code associated with the invoice item.
type: string
adjustmentLiabilityAccountingCode:
description: |
The accounting code for adjustment liability.
**Note**: This field is only available if you have the Billing - Revenue Integration feature enabled.
type: string
adjustmentRevenueAccountingCode:
description: |
The accounting code for adjustment revenue.
**Note**: This field is only available if you have the Billing - Revenue Integration feature enabled.
type: string
amount:
description: |
The amount of the invoice item.
- For tax-inclusive invoice items, the amount indicates the invoice item amount including tax.
- For tax-exclusive invoice items, the amount indicates the invoice item amount excluding tax.
type: number
bookingReference:
description: |
The booking reference of the invoice item.
**Note**: This field is only available if `id` is null.
type: string
chargeDate:
description: |
The date when the invoice item is charged, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
chargeName:
description: |
The name of the charge associated with the invoice item.
This field is required if the `productRatePlanChargeId` field is not specified in the request.
type: string
contractAssetAccountingCode:
description: |
The accounting code for contract asset.
**Note**: This field is only available if you have the Billing - Revenue Integration feature enabled.
type: string
contractLiabilityAccountingCode:
description: |
The accounting code for contract liability.
**Note**: This field is only available if you have the Billing - Revenue Integration feature enabled.
type: string
contractRecognizedRevenueAccountingCode:
description: |
The accounting code for contract recognized revenue.
**Note**: This field is only available if you have the Billing - Revenue Integration feature enabled.
type: string
deferredRevenueAccountingCode:
description: |
The accounting code for the deferred revenue, such as Monthly Recurring Liability.
**Note:** This field is only available if you have Zuora Finance enabled.
type: string
delete:
description: |
Indicates whether to delete the existing invoice item.
**Note**: Set this field to `true` and specify an item `id` to delete an item.
type: boolean
description:
description: |
The description of the invoice item.
type: string
discountItems:
description: |
Container for discount items. The maximum number of discount items is 10.
items:
$ref: '#/components/schemas/PutDiscountItemType'
type: array
excludeItemBillingFromRevenueAccounting:
default: false
description: |
The flag to exclude the invoice item from revenue accounting.
**Note**: This field is only available if you have the Billing - Revenue Integration feature enabled.
type: boolean
id:
description: |
The unique ID of the invoice item.
- Specify this field when updating or deleting an existing memo item.
- Do not specify this field when creating a memo item.
type: string
itemType:
description: |
The type of the invoice item.
type: string
productRatePlanChargeId:
description: |
The ID of the product rate plan charge that the invoice item is created from.
If you specify the ID of a product rate plan charge in this field, no matter whether the following fields are specified with values, the following fields use the values from the corresponding product rate plan charge instead of the specified values:
- `chargeName`
- `sku`
- `uom`
- `taxCode`
- `taxMode`
- `accountingCode`
- `deferredRevenueAccountingCode`
- `recognizedRevenueAccountingCode`
**Note**: Do not specify the invoice item `id` when specifying this field.
type: string
purchaseOrderNumber:
description: |
The purchase order number associated the invoice item.
type: string
quantity:
description: |
The number of units for the invoice item.
format: number
type: string
recognizedRevenueAccountingCode:
description: |
The accounting code for the recognized revenue, such as Monthly Recurring Charges or Overage Charges.
**Note:** This field is only available if you have Zuora Finance enabled.
type: string
revRecCode:
description: |
The revenue recognition code.
type: string
revRecTriggerCondition:
description: |
The date when revenue recognition is triggered.
enum:
- ContractEffectiveDate
- ServiceActivationDate
- CustomerAcceptanceDate
type: string
revenueRecognitionRuleName:
description: |
The name of the revenue recognition rule governing the revenue schedule.
**Note:** This field is only available if you have Zuora Finance enabled.
type: string
serviceEndDate:
description: |
The service end date of the invoice item.
format: date
type: string
serviceStartDate:
description: |
The service start date of the invoice item.
format: date
type: string
sku:
description: |
The SKU of the invoice item. The SKU of the invoice item must be different from the SKU of any existing product.
type: string
taxCode:
description: |
The tax code identifies which tax rules and tax rates to apply to the invoice item.
**Note:**
- This field is only available if you have Taxation enabled.
- If the values of both `taxCode` and `taxMode` fields are changed to `null` when updating a standalone invoice, the corresponding `invoiceItems` > `taxItems` field and its nested fields specified in the creation request will be removed.
type: string
taxMode:
description: |
The tax mode of the invoice item, indicating whether the amount of the invoice item includes tax.
**Note:**
- This field is only available if you have Taxation enabled.
- If the values of both `taxCode` and `taxMode` fields are changed to `null` when updating a standalone invoice, the corresponding `invoiceItems` > `taxItems` field and its nested fields specified in the creation request will be removed.
enum:
- TaxInclusive
- TaxExclusive
type: string
unbilledReceivablesAccountingCode:
description: |
The accounting code for unbilled receivables.
**Note**: This field is only available if you have the Billing - Revenue Integration feature enabled.
type: string
unitPrice:
description: |
The per-unit price of the invoice item.
format: number
type: string
uom:
description: |
The unit of measure.
type: string
type: object
- $ref: '#/components/schemas/InvoiceItemObjectNSFields'
- $ref: '#/components/schemas/InvoiceItemObjectCustomFields'
PutDiscountItemType:
allOf:
- properties:
accountingCode:
description: |
The accounting code associated with the discount item.
type: string
adjustmentLiabilityAccountingCode:
description: |
The accounting code for adjustment liability.
**Note**: This field is only available if you have the Billing - Revenue Integration feature enabled.
type: string
adjustmentRevenueAccountingCode:
description: |
The accounting code for adjustment revenue.
**Note**: This field is only available if you have the Billing - Revenue Integration feature enabled.
type: string
amount:
description: |
The amount of the discount item.
- Should be a negative number. For example, `-10`.
- Always a fixed amount no matter whether the discount charge associated with the discount item uses the [fixed-amount model or percentage model](https://knowledgecenter.zuora.com/Billing/Subscriptions/Product_Catalog/B_Charge_Models/B_Discount_Charge_Models#Fixed_amount_model_and_percentage_model).
- For tax-exclusive discount items, this amount indicates the discount item amount excluding tax.
- For tax-inclusive discount items, this amount indicates the discount item amount including tax.
format: number
type: string
bookingReference:
description: |
The booking reference of the discount item.
type: string
chargeDate:
description: |
The date when the discount item is charged, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
chargeName:
description: |
The name of the charge associated with the discount item.
This field is required if the `productRatePlanChargeId` field is not specified in the request.
type: string
contractAssetAccountingCode:
description: |
The accounting code for contract asset.
**Note**: This field is only available if you have the Billing - Revenue Integration feature enabled.
type: string
contractLiabilityAccountingCode:
description: |
The accounting code for contract liability.
**Note**: This field is only available if you have the Billing - Revenue Integration feature enabled.
type: string
contractRecognizedRevenueAccountingCode:
description: |
The accounting code for contract recognized revenue.
**Note**: This field is only available if you have the Billing - Revenue Integration feature enabled.
type: string
deferredRevenueAccountingCode:
description: |
The accounting code for the deferred revenue, such as Monthly Recurring Liability.
**Note:** This field is only available if you have Zuora Finance enabled.
type: string
description:
description: |
The description of the discount item.
type: string
id:
description: |
The unique ID of the discount item.
type: string
itemType:
description: |
The type of the discount item.
type: string
purchaseOrderNumber:
description: |
The purchase order number associated with the discount item.
type: string
recognizedRevenueAccountingCode:
description: |
The accounting code for the recognized revenue, such as Monthly Recurring Charges or Overage Charges.
**Note:** This field is only available if you have Zuora Finance enabled.
type: string
revRecCode:
description: |
The revenue recognition code.
type: string
revRecTriggerCondition:
description: |
The date when revenue recognition is triggered.
enum:
- ContractEffectiveDate
- ServiceActivationDate
- CustomerAcceptanceDate
type: string
revenueRecognitionRuleName:
description: |
The name of the revenue recognition rule governing the revenue schedule.
**Note:** This field is only available if you have Zuora Finance enabled.
type: string
sku:
description: |
The SKU of the invoice item. The SKU of the discount item must be different from the SKU of any existing product.
type: string
unbilledReceivablesAccountingCode:
description: |
The accounting code for unbilled receivables.
**Note**: This field is only available if you have the Billing - Revenue Integration feature enabled.
type: string
unitPrice:
description: |
The per-unit price of the discount item.
If the discount charge associated with the discount item uses the percentage model, the unit price will display as a percentage amount in PDF. For example: if unit price is 5.00, it will display as 5.00% in PDF.
format: number
type: string
required:
- amount
title: invoiceItems
type: object
- $ref: '#/components/schemas/DiscountItemObjectNSFields'
- $ref: '#/components/schemas/DiscountItemObjectCustomFields'
PostBatchInvoicesType:
example:
invoices:
- accountId: ff8080817cda56fa017cda87aaa2071e
autoPay: false
comments: comments
currency: EUR
invoiceDate: '2020-02-01'
invoiceItems:
- amount: 100
bookingReference: bookingReference
chargeDate: '2020-02-01 00:00:00'
description: description
discountItems:
- amount: -10
bookingReference: discountBookingReference
chargeDate: '2020-02-01 11:00:00'
chargeName: discount
description: description
sku: SKU-0002
taxItems:
- exemptAmount: 0
jurisdiction: jurisdiction
locationCode: locationCode
name: country tax
taxAmount: -1
taxCode: country tax code
taxCodeDescription: country tax code, tax rate 10%
taxDate: '2021-02-08'
taxMode: TaxExclusive
taxRate: 0.1
taxRateDescription: country tax
taxRateType: Percentage
productRatePlanChargeId: ff8080817cda56fa017cda87999d071b
purchaseOrderNumber: PO-000303
quantity: 1
serviceEndDate: '2020-02-10'
serviceStartDate: '2020-02-01'
taxItems:
- exemptAmount: 0
jurisdiction: juristiction
locationCode: locationCode
name: country tax
taxAmount: 10
taxCode: tax code
taxCodeDescription: tax code description
taxDate: '2020-02-01'
taxMode: TaxExclusive
taxRate: 0.01
taxRateDescription: tax rate description
taxRateType: Percentage
- amount: 100
bookingReference: bookingReference
chargeDate: '2020-02-01 00:00:00'
chargeName: charge name
description: description
purchaseOrderNumber: PO-000303
quantity: 1
serviceEndDate: '2020-02-10'
serviceStartDate: '2020-02-01'
sku: sku-001
uom: each
- accountId: ff8080817cda56fa017cda87aaa2071e
autoPay: false
comments: comments
currency: EUR
invoiceDate: '2020-02-01'
invoiceItems:
- amount: 100
bookingReference: bookingReference
chargeDate: '2020-02-01 00:00:00'
description: description
productRatePlanChargeId: ff8080817cda56fa017cda87999d071b
purchaseOrderNumber: PO-000303
quantity: 1
serviceEndDate: '2020-02-10'
serviceStartDate: '2020-02-01'
taxItems:
- exemptAmount: 0
jurisdiction: juristiction
locationCode: locationCode
name: country tax
taxAmount: 10
taxCode: tax code
taxCodeDescription: tax code description
taxDate: '2020-02-01'
taxMode: TaxExclusive
taxRate: 0.01
taxRateDescription: tax rate description
taxRateType: Percentage
- amount: 100
bookingReference: bookingReference
chargeDate: '2020-02-01 00:00:00'
chargeName: charge name
description: description
purchaseOrderNumber: PO-000303
quantity: 1
serviceEndDate: '2020-02-10'
serviceStartDate: '2020-02-01'
sku: sku-001
uom: each
useSingleTransaction: false
properties:
invoices:
description: |
Container for standalone invoices.
items:
$ref: '#/components/schemas/PostInvoiceType'
type: array
useSingleTransaction:
description: |
Whether a batch request is handled with a single transaction.
- `true` indicates that a batch request will be handled with a single transaction.
- `false` indicates that the standalone invoices to be created in a batch request will be handled with separated transactions.
If the field is set to `false`, a failure in the batch request will not cause the whole request to fail, so you have to retry the whole batch request.
type: boolean
type: object
PostBatchInvoiceResponse:
properties:
invoices:
items:
$ref: '#/components/schemas/PostBatchInvoiceItemResponse'
type: array
success:
description: |
Indicates whether the call succeeded.
type: boolean
type: object
PostBatchInvoiceItemResponse:
allOf:
- properties:
success:
description: |
Indicates whether the invoice is created successfully.
type: boolean
type: object
- $ref: '#/components/schemas/PostInvoiceResponse'
POSTInvoicesBatchPostType:
allOf:
- properties:
invoices:
description: |
The container for invoices to be posted. The maximum number of invoices to be posted is 50 in one request.
items:
$ref: '#/components/schemas/InvoicePostType'
title: invoices
type: array
type: object
example:
invoices:
- complexity__c: Middle
description__c: description
id: 402890555a7e9791015a7f15fe440123
invoiceDate: '2022-10-12'
- complexity__c: Middle
description__c: description
id: 402890555a7e9791015a7f15fe44013a
invoiceDate: '2022-10-12'
- complexity__c: Middle
description__c: description
id: 402890555a7e9791015a7f15fe44012b
invoiceDate: '2022-10-12'
InvoicesBatchPostResponseType:
allOf:
- properties:
invoices:
description: |
The container for a list of posted invoices.
items:
$ref: '#/components/schemas/InvoicePostResponseType'
title: invoices
type: array
success:
description: |
Returns `true` if the request has one of invoices was posted successfully.
type: boolean
type: object
InvoicePostResponseType:
allOf:
- properties:
id:
description: |
The ID of the invoice that was posted.
type: string
success:
description: |
Returns `true` if the invoice was posted successfully.
type: boolean
type: object
InvoicePostType:
allOf:
- properties:
id:
description: |
The ID of the invoice to be posted.
type: string
invoiceDate:
description: |
The date that appears on the invoice being created, in `yyyy-mm-dd` format. The value cannot fall in a closed accounting period.
format: date
type: string
type: object
- $ref: '#/components/schemas/InvoiceObjectCustomFields'
GetInvoicePdfStatusBatchResponse:
description: ''
example:
invoiceFiles:
- invoiceId: 402824aa8cc894d5018cc8a120576881
invoiceNumber: INV00000003
pdfGenerationStatus: Generated
createdOn: '2024-01-01 11:35:56'
updatedOn: '2024-01-01 11:35:56'
pdfFileUrl: /v1/files/2c98901f62d7d83d0162d7facea6262d
- invoiceId: 2c98908a904dfc2601904e6e14090241
invoiceNumber: INV00000004
pdfGenerationStatus: Error
createdOn: '2024-01-02 10:14:13'
updatedOn: '2024-01-02 10:14:13'
errorCode: INVALID_TEMPLATE
errorMessage: Unknown merge filed chargeNumber__c
- invoiceId: 402824aa8cc894d5018cc8a120576881
invoiceNumber: INV00000005
pdfGenerationStatus: Pending
createdOn: '2024-01-01 11:35:56'
updatedOn: '2024-01-01 11:35:56'
success: true
properties:
invoiceFiles:
description: |
Array of invoice PDF statuses requested.
items:
$ref: '#/components/schemas/GetInvoicePdfStatusResponse'
type: array
success:
description: |
Indicates whether the call succeeded.
type: boolean
type: object
title: invoiceFiles
GetInvoicePdfStatusResponse:
allOf:
- properties:
invoiceId:
description: |
The ID of the invoice whose pdf status is requested.
type: string
invoiceNumber:
description: |
The invoice number of the invoice whose pdf status is requested.
type: string
pdfGenerationStatus:
description: |
The generation status of the invoice PDF.
- **Obsolete**: The status changes to `Obsolete` when additional updates are applied to the document, for example, payment applied or custom fields updated.
- **Archived**: The status changes to `Archived` from `Generated` when the PDF file is archived. The file cannot be used directly until it is restored. For restoring, refer to the Restore a file operation.
enum:
- None
- Pending
- Processing
- Generated
- Error
- Obsolete
- Archived
type: string
createdOn:
description: |
The time at which the request to generate the PDF was created.
type: string
updatedOn:
description: |
The time at which the request to generate the PDF was updated.
type: string
pdfFileURL:
description: |
The file path or the URL of the PDF when the status is `Generated`.
type: string
errorCategory:
description: |
The error category when the status is `Error`.
type: string
errorMessage:
description: |
The error message when the status is `Error`.
type: string
type: object
DeleteInvoiceResponseType:
properties:
id:
description: |
The ID of the deleted invoice.
type: string
jobId:
description: |
The ID of the job that handles the invoice deletion operation.
You can specify the value of this field as the value of the `jobId` path parameter in the [Retrieve an operation job](https://developer.zuora.com/api-references/api/operation/GET_OperationJob/) API operation to query job information.
type: string
jobStatus:
description: |
The status of the invoice deletion operation.
enum:
- Pending
- Completed
type: string
reasons:
items:
properties:
code:
description: |
The error code of the response.
type: string
message:
description: |
The detail information of the error response.
type: string
type: object
type: array
success:
description: |
Whether the call succeeded.
type: boolean
type: object
PutInvoiceType:
allOf:
- properties:
autoPay:
description: |
Whether invoices are automatically picked up for processing in the corresponding payment run.
By default, invoices are automatically picked up for processing in the corresponding payment run.
type: boolean
comments:
description: |
Additional information related to the invoice that a Zuora user added to the invoice.
maxLength: 255
type: string
dueDate:
description: |
The date by which the payment for this invoice is due.
format: date
type: string
invoiceDate:
description: |
The new invoice date of the invoice. The new invoice date cannot fall in a closed accounting period.
You can only specify `invoiceDate` or `dueDate` in one request. Otherwise, an error occurs.
format: date
type: string
invoiceItems:
description: |
Container for invoice items, The maximum number of items is 1,000.
items:
$ref: '#/components/schemas/PutInvoiceItemType'
type: array
transferredToAccounting:
description: |
Whether the invoice was transferred to an external accounting system.
enum:
- Processing
- 'Yes'
- Error
- Ignore
type: string
templateId:
description: |
The ID of the invoice template associated with the invoice.
**Note**: This field is only available if you have the Flexible Billing Attributes feature enabled.
type: string
type: object
- $ref: '#/components/schemas/InvoiceObjectNSFields'
- $ref: '#/components/schemas/InvoiceObjectCustomFields'
example:
invoiceItems:
- id: 8ad084db909fae930190a121c87f5800
amount: 105
PutInvoiceResponseType:
allOf:
- properties:
accountId:
description: |
The ID of the customer account associated with the invoice.
type: string
amount:
description: |
The total amount of the invoice.
format: BigDecimal
type: number
autoPay:
description: |
Whether invoices are automatically picked up for processing in the corresponding payment run.
type: boolean
balance:
description: |
The balance of the invoice.
format: BigDecimal
type: number
cancelledById:
description: |
The ID of the Zuora user who cancelled the invoice.
type: string
nullable: true
cancelledOn:
description: |
The date and time when the invoice was cancelled, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
nullable: true
comment:
description: |
Comments about the invoice.
type: string
createdById:
description: |
The ID of the Zuora user who created the invoice.
type: string
createdDate:
description: |
The date and time when the invoice was created, in `yyyy-mm-dd hh:mm:ss` format. For example, 2017-03-01 15:31:10.
format: date-time
type: string
creditBalanceAdjustmentAmount:
description: |
**Note:** This filed is only available if you have the Credit Balance feature enabled and the Invoice Settlement feature disabled.
The currency amount of the adjustment applied to the customer's credit balance.
format: BigDecimal
type: number
currency:
description: |
A currency defined in the web-based UI administrative settings.
type: string
discount:
description: |
The discount of the invoice.
format: BigDecimal
type: number
dueDate:
description: |
The date by which the payment for this invoice is due.
format: date
type: string
id:
description: |
The unique ID of the invoice.
type: string
invoiceDate:
description: |
The date on which to generate the invoice.
format: date
type: string
number:
description: |
The unique identification number of the invoice.
type: string
postedById:
description: |
The ID of the Zuora user who posted the invoice.
type: string
postedOn:
description: |
The date and time when the invoice was posted, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
status:
description: |
The status of the invoice.
enum:
- Draft
- Posted
- Canceled
- Error
type: string
success:
description: |
Returns `true` if the request was processed successfully.
type: boolean
targetDate:
description: |
The target date for the invoice, in `yyyy-mm-dd` format. For example, 2017-07-20.
format: date
type: string
taxAmount:
description: |
The amount of taxation.
format: BigDecimal
type: number
templateId:
description: |
The ID of the invoice template associated with the invoice.
type: string
totalTaxExemptAmount:
description: |
The calculated tax amount excluded due to the exemption.
format: BigDecimal
type: number
transferredToAccounting:
description: |
Whether the invoice was transferred to an external accounting system.
enum:
- Processing
- 'Yes'
- Error
- Ignore
type: string
updatedById:
description: |
The ID of the Zuora user who last updated the invoice.
type: string
updatedDate:
description: |
The date and time when the invoice was last updated, in `yyyy-mm-dd hh:mm:ss` format. For example, 2017-03-02 15:36:10.
format: date-time
type: string
type: object
- $ref: '#/components/schemas/InvoiceObjectNSFields'
- $ref: '#/components/schemas/InvoiceObjectCustomFields'
GetInvoiceApplicationPartCollectionType:
properties:
applicationParts:
description: |
Container for application parts.
items:
$ref: '#/components/schemas/GetInvoiceApplicationPartType'
type: array
nextPage:
description: |
URL to retrieve the next page of the response if it exists; otherwise absent.
format: URL
type: string
success:
description: Returns `true` if the request was processed successfully.
type: boolean
type: object
GetInvoiceApplicationPartType:
properties:
appliedAmount:
description: |
The amount that is applied to the invoice.
format: double
type: number
createdById:
description: |
The ID of the Zuora user who created the payment or credit memo.
format: uuid
type: string
createdDate:
description: |
The date and time when the payment or credit memo was created, in `yyyy-mm-dd hh:mm:ss` format. For example, 2017-12-01 15:31:10.
format: date-time
type: string
creditMemoId:
description: |
The ID of credit memo that is applied to the specified invoice.
format: uuid
type: string
paymentId:
description: |
The ID of the payment that is applied to the specified invoice.
format: uuid
type: string
updatedById:
description: |
The ID of the Zuora user who last updated the payment or credit memo.
format: uuid
type: string
updatedDate:
description: |
The date and time when the payment or credit memo was last updated, in `yyyy-mm-dd hh:mm:ss` format. For example, 2018-01-02 11:42:16.
format: date-time
type: string
title: applicationParts
type: object
PostInvoiceEmailRequestType:
example:
useEmailTemplateSetting: true
properties:
emailAddresses:
description: |
The valid email addresses you want to email an invoice to. Use commas to separate email addresses.
**Note:** This field is only applicable if you set the `useEmailTemplateSetting` field to `false`.
type: string
includeAdditionalEmailAddresses:
default: false
description: |
Whether to send an invoice to the additional email addresses of the invoice account.
You can set the additional email addresses in the **Additional Email Addresses** field on the account detail page from the Zuora UI. See [Create a Customer Account](https://knowledgecenter.zuora.com/BC_Subscription_Management/Customer_Accounts/B_Create_a_Customer_Account#section_2) for more information.
enum:
- true
- false
type: boolean
useEmailTemplateSetting:
default: false
description: |
Indicates whether to email an invoice based on the email template setting.
If you set this field to `true`, the invoice is sent to the email addresses specified in the **To Email** field of the email template. The email template is the one you set in the **Delivery Options** panel of the **Edit notification** dialog from the Zuora UI. See [Edit Email Templates](https://knowledgecenter.zuora.com/CF_Users_and_Administrators/Notifications/Create_Email_Templates) for more information about how to edit the **To Email** field in the email template.
enum:
- true
- false
type: boolean
type: object
GETInvoiceFilesResponse:
properties:
invoiceFiles:
description: |
Container for invoice PDF files.
items:
$ref: '#/components/schemas/InvoiceFile'
type: array
nextPage:
description: |
URL to retrieve the next page of the response if it exists; otherwise absent.
format: URL
type: string
success:
description: Returns `true` if the request was processed successfully.
type: boolean
type: object
InvoiceFile:
properties:
id:
description: |
The ID of the invoice PDF file. This is the ID for the file object and different from the file handle ID in the `pdfFileUrl` field. To open a file, you have to use the file handle ID.
type: string
pdfFileUrl:
description: |
The relative URL of the invoice PDF file.
You can obtain the absolute URL for downloading the file by adding a prefix in the following format: `{environment_base_url}/apps`
For example, `https://apisandbox.zuora.com/apps/v1/files/2c98901f62d7d83d0162d7facea6262d`.
type: string
versionNumber:
description: |
The version number of the invoice PDF file.
format: int64
type: integer
title: invoiceFiles
type: object
POSTUploadFileResponse:
properties:
fileId:
description: |
The unique ID of the uploaded PDF file.
type: string
success:
description: |
Indicates whether the call succeeded.
type: boolean
type: object
GETInvoiceItemsResponse:
properties:
invoiceItems:
description: |
Container for invoice items.
items:
$ref: '#/components/schemas/InvoiceItem'
type: array
nextPage:
description: |
URL to retrieve the next page of the response if it exists; otherwise absent.
format: URL
type: string
success:
description: Returns `true` if the request was processed successfully.
type: boolean
type: object
InvoiceItem:
allOf:
- properties:
accountingCode:
description: The accounting code associated with the invoice item.
type: string
adjustmentLiabilityAccountingCode:
description: |
The accounting code for adjustment liability.
**Note**: This field is only available if you have the Billing - Revenue Integration feature enabled.
type: string
adjustmentRevenueAccountingCode:
description: |
The accounting code for adjustment revenue.
**Note**: This field is only available if you have the Billing - Revenue Integration feature enabled.
type: string
appliedToItemId:
description: The unique ID of the invoice item that the discount charge is applied to.
type: string
availableToCreditAmount:
description: |
The amount of the invoice item that is available to credit.
format: decimal
type: number
balance:
description: |
The balance of the invoice item.
**Note**: This field is only available if you have the Invoice Settlement feature enabled.
format: decimal
type: string
bookingReference:
description: |
The booking reference of the invoice item.
type: string
chargeAmount:
description: |
The amount of the charge.
**Note**: This amount does not include taxes regardless if the charge's tax mode is inclusive or exclusive. This is the discount amount actually applied when the invoice item is a discount charge.
format: decimal
type: string
chargeDate:
description: |
The date when the invoice item is charged, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
chargeDescription:
description: The description of the charge.
type: string
chargeId:
description: The unique ID of the charge.
type: string
chargeName:
description: The name of the charge.
type: string
chargeType:
description: |
The type of the charge.
enum:
- OneTime
- Recurring
- Usage
type: string
commitmentId:
description: |
The ID of the commitment.
type: string
commitmentPeriodId:
description: |
The ID of the commitment period.
type: string
contractAssetAccountingCode:
description: |
The accounting code for contract asset.
**Note**: This field is only available if you have the Billing - Revenue Integration feature enabled.
type: string
contractLiabilityAccountingCode:
description: |
The accounting code for contract liability.
**Note**: This field is only available if you have the Billing - Revenue Integration feature enabled.
type: string
contractRecognizedRevenueAccountingCode:
description: |
The accounting code for contract recognized revenue.
**Note**: This field is only available if you have the Billing - Revenue Integration feature enabled.
type: string
deferredRevenueAccountingCode:
description: |
The deferred revenue accounting code associated with the invoice item.
**Note:** This field is only available if you have Zuora Finance enabled.
type: string
description:
description: The description of the invoice item.
type: string
excludeItemBillingFromRevenueAccounting:
description: |
The flag to exclude the invoice item from revenue accounting.
**Note**: This field is only available if you have the Billing - Revenue Integration feature enabled.
type: boolean
fulfillmentId:
description: |
The reference ID of the fulfillment associated with the invoice item.
type: string
id:
description: Item ID.
type: string
invoiceScheduleId:
description: |
The ID of the invoice schedule item by which Invoice Schedule Item the invoice item is generated by when the Invoice Schedule Item is executed.
**Note**: This field is available only if you have the Billing Schedule feature enabled.
type: string
invoiceScheduleItemId:
description: |
The ID of the invoice schedule item associated with the invoice item.
**Note**: This field is available only if you have the Billing Schedule feature enabled.
type: string
itemType:
description: |
The type of the invoice item.
type: string
numberOfDeliveries:
description: |
The number of deliveries dedicated to the Delivery Pricing charges.
**Note**: This field is available only if you have the Delivery Pricing feature enabled.
type: number
orderLineItemId:
description: |
The reference ID of the oder line item associated with the invoice item.
type: string
processingType:
description: |
The kind of the charge for the invoice item.
enum:
- Charge
- Discount
- Prepayment
- Tax
- Rounding
type: string
productName:
description: Name of the product associated with this item.
type: string
productRatePlanChargeId:
description: |
The ID of the product rate plan charge that the invoice item is created from.
type: string
purchaseOrderNumber:
description: |
The purchase order number associated with the invoice item.
type: string
quantity:
description: The quantity of this item, in the configured unit of measure for the charge.
format: decimal
type: string
reflectDiscountInNetAmount:
type: boolean
default: false
description: |
When you apply percentage discounts to either of the following charges, you need to set the `reflectDiscountInNetAmount` field on your discount charge to `true`, to enable calculating and displaying the net amount of the following charges in Zuora Revenue.
* delivery pricing charge
* prepayment charge
* drawdown charge
Note the following:
* If you are an Order to Revenue customer, when you set the `reflectDiscountInNetAmount` field to `true`, you must also set both the `excludeItemBookingFromRevenueAccounting` and `ExcludeItemBillingFromRevenueAccounting` fields to `true`.
* If you are a Billing - Revenue Integration customer, you must set the `reflectDiscountInNetAmount` field to `false`, otherwise an error will be returned. Billing - Revenue Integration does not support discounts on the preceding charges.
* If you are a Zuora Billing customer who does not enable the Order to Revenue or Billing - Revenue Integration feature, when you apply percentage discounts to the preceding charges, you also need to set the `reflectDiscountInNetAmount` field to `true`.
recognizedRevenueAccountingCode:
description: |
The recognized revenue accounting code associated with the invoice item.
**Note:** This field is only available if you have Zuora Finance enabled.
type: string
revRecCode:
description: |
The revenue recognition code.
type: string
revRecTriggerCondition:
description: |
The date when revenue recognition is triggered.
enum:
- ContractEffectiveDate
- ServiceActivationDate
- CustomerAcceptanceDate
type: string
revenueRecognitionRuleName:
description: |
The revenue recognition rule of the invoice item.
**Note:** This field is only available if you have Zuora Finance enabled.
type: string
serviceEndDate:
description: The end date of the service period for this item, i.e., the last day of the service period, as _yyyy-mm-dd_.
format: date
type: string
serviceStartDate:
description: The start date of the service period for this item, as _yyyy-mm-dd_. For a one-time fee item, the date of the charge.
format: date
type: string
sku:
description: |
The SKU of the invoice item.
type: string
shipToContactId:
description: |
The ID of the ship-to contact associated with the invoice item.
type: string
soldToContactId:
description: |
The ID of the sold-to contact associated with the invoice item.
**Note**: If you have the Flexible Billing Attributes feature disabled, the value of this field is `null`.
type: string
soldToContactSnapshotId:
description: |
The ID of the sold-to contact snapshot associated with the invoice item.
**Note**: If you have the Flexible Billing Attributes feature disabled, the value of this field is `null`.
type: string
sourceItemType:
description: |
The type of the source item.
enum:
- SubscriptionComponent
- Rounding
- ProductRatePlanCharge
- None
- OrderLineItem
type: string
subscriptionId:
description: The ID of the subscription for this item.
type: string
subscriptionName:
description: The name of the subscription for this item.
type: string
taxAmount:
description: Tax applied to the charge.
format: decimal
type: string
taxCode:
description: |
The tax code of the invoice item.
**Note** Only when taxation feature is enabled, this field can be presented.
type: string
taxMode:
description: |
The tax mode of the invoice item.
**Note** Only when taxation feature is enabled, this field can be presented.
type: string
taxationItems:
description: |
Container for the taxation items of the invoice item.
properties:
data:
description: |
List of taxation items.
items:
$ref: '#/components/schemas/GETInvoiceTaxItemType'
type: array
nextPage:
description: |
URL to retrieve the next page of the response if it exists; otherwise absent.
format: URL
type: string
type: object
unbilledReceivablesAccountingCode:
description: |
The accounting code for unbilled receivables.
**Note**: This field is only available if you have the Billing - Revenue Integration feature enabled.
type: string
unitOfMeasure:
description: Unit used to measure consumption.
type: string
unitPrice:
description: |
The per-unit price of the invoice item.
**Note**: For discount charges, this represents the discount percentage (for percentage-based discounts) or the discount amount (for fixed-amount discounts).
format: double
type: number
type: object
- $ref: '#/components/schemas/InvoiceItemObjectNSFields'
- $ref: '#/components/schemas/InvoiceItemObjectCustomFields'
title: invoiceItems
GETInvoiceTaxItemType:
allOf:
- $ref: '#/components/schemas/TaxationItemObjectCustomFields'
- properties:
availableToCreditAmount:
description: |
The amount of the invoice taxation item that is available to credit.
format: decimal
type: number
applicableTaxUnRounded:
description: |
The unrounded amount of the tax.
type: number
country:
description: |
The field which contains country code.
type: string
balance:
description: |
The balance of the taxation item.
format: double
type: number
creditAmount:
description: |
The amount of credit memos applied to the taxation item.
format: double
type: number
exemptAmount:
description: |
The calculated tax amount excluded due to the exemption.
format: double
type: number
id:
description: |
The ID of the taxation item.
type: string
jurisdiction:
description: |
The jurisdiction that applies the tax or VAT. This value is typically a state, province, county, or city.
type: string
locationCode:
description: |
The identifier for the location based on the value of the `taxCode` field.
type: string
name:
description: |
The name of the taxation item.
type: string
paymentAmount:
description: |
The amount of payments applied to the taxation item.
format: double
type: number
taxAmount:
description: |
The amount of taxation.
format: double
type: number
taxCode:
description: |
The tax code identifies which tax rules and tax rates to apply to a specific invoice.
type: string
taxCodeDescription:
description: |
The description of the tax code.
type: string
taxDate:
description: |
The date that the tax is applied to the invoice, in `yyyy-mm-dd` format.
format: date
type: string
taxRate:
description: |
The tax rate applied to the invoice.
format: double
type: number
taxRateDescription:
description: |
The description of the tax rate.
type: string
taxRateType:
description: |
The type of the tax rate.
enum:
- Percentage
- FlatFee
type: string
title: data
type: object
title: data
GETInvoiceTaxationItemsResponse:
properties:
data:
description: |
Container for the taxation items of the invoice item.
items:
$ref: '#/components/schemas/GETInvoiceTaxItemType'
type: array
nextPage:
description: |
URL to retrieve the next page of the response if it exists; otherwise absent.
format: URL
type: string
success:
description: Returns `true` if the request was processed successfully.
type: boolean
type: object
PutReverseInvoiceType:
example:
applyEffectiveDate: '2017-02-20'
memoDate: '2017-02-20'
properties:
applyEffectiveDate:
description: |
The date when the credit memo is applied to the invoice that will be reversed, in `yyyy-mm-dd` format. The effective date must be later than or equal to the memo date.
The default value is the date when you reverse the invoice and create the credit memo.
format: date
type: string
comment:
description: |
Comments about the reversal. The comment is used as the comment of the credit memo generated by reversing the specified invoice.
maxLength: 255
minLength: 0
type: string
memoDate:
description: |
The date when the credit memo was created, in `yyyy-mm-dd` format. The memo date must be later than or equal to the invoice date.
The default value is the date when you reverse the invoice and create the credit memo.
format: date
type: string
reasonCode:
description: |
A code identifying the reason for the reversal. The value must be an existing reason code or empty. The code is used as the reason code of the credit memo generated by reversing the specified invoice.
If you do not specify a value, Zuora uses the default reason code `Invoice reversal` for the credit memo.
type: string
type: object
PutReverseInvoiceResponseType:
properties:
creditMemo:
description: |
Container for the credit memo that is automatically generated when during the invoice reversal.
properties:
id:
description: The ID of the credit memo.
type: string
type: object
debitMemo:
description: |
Container for the debit memo that is automatically generated during the reversal of the credit memo related to this invoice. If no related credit memo is reversed, this field is not retruned in the response body.
properties:
id:
description: The ID of the debit memo.
type: string
type: object
id:
type: string
nullable: true
description: |
The ID of the invoice to be reserved.
This field is available only when the reversal operation is performed asynchronously.
jobId:
type: string
nullable: true
description: |
The ID of the job that handles the invoice reversal operation.
You can specify the value of this field as the value of the `jobId` path parameter in the [Retrieve an operation job](https://developer.zuora.com/v1-api-reference/api/operation/GET_OperationJob/) API operation to query job information.
This field is available only when the reversal operation is performed asynchronously.
jobStatus:
type: string
nullable: true
enum:
- Pending
- Processing
- Failed
- Completed
description: |
The status of the invoice reversal operation.
This field is available only when the reversal operation is performed asynchronously.
success:
description: |
Returns `true` if the request was processed successfully.
type: boolean
type: object
POSTTaxationItemList:
example:
taxationItems:
- exemptAmount: 0
financeInformation:
accountsReceivableAccountingCode: Check
salesTaxPayableAccountingCode: Check
invoiceItemId: 402890555a7e9791015a879f064d0055
jurisdiction: CALIFORNIA
locationCode: '06'
name: STATE TAX
taxAmount: 0.1
taxCode: ServiceTaxCode
taxCodeDescription: This is tax code description!
taxDate: '2016-09-30'
taxMode: TaxExclusive
taxRate: 0.0625
taxRateDescription: This is tax rate description!
taxRateType: Percentage
properties:
taxationItems:
description: |
Container for taxation items.
items:
$ref: '#/components/schemas/POSTTaxationItemTypeForInvoice'
type: array
type: object
GETTaxationItemListType:
properties:
success:
description: Returns `true` if the request was processed successfully.
type: boolean
taxationItems:
description: |
Container for taxation items.
items:
$ref: '#/components/schemas/GETTaxationItemTypewithSuccess'
type: array
type: object
GETTaxationItemTypewithSuccess:
allOf:
- properties:
createdById:
description: |
The ID of the Zuora user who created the taxation item.
type: string
createdDate:
description: |
The date and time when the taxation item was created in the Zuora system, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
exemptAmount:
description: |
The calculated tax amount excluded due to the exemption.
format: double
type: number
financeInformation:
description: |
Container for the finance information related to the taxation item.
properties:
accountsReceivableAccountingCode:
description: |
The accounting code for accounts receivable.
type: string
accountsReceivableAccountingCodeType:
description: |
The type of the accounting code for accounts receivable.
type: string
salesTaxPayableAccountingCode:
description: |
The accounting code for the sales taxes payable.
type: string
salesTaxPayableAccountingCodeType:
description: |
The type of the accounting code for the sales taxes payable.
type: string
type: object
id:
description: |
The ID of the taxation item.
type: string
invoiceItemId:
description: |
The ID of the invoice associated with the taxation item.
type: string
jurisdiction:
description: |
The jurisdiction that applies the tax or VAT. This value is typically a state, province, county, or city.
type: string
locationCode:
description: |
The identifier for the location based on the value of the `taxCode` field.
type: string
nullable: true
name:
description: |
The name of the taxation item.
type: string
taxAmount:
description: |
The amount of the tax applied to the invoice.
format: double
type: number
taxCode:
description: |
The tax code identifies which tax rules and tax rates to apply to a specific invoice.
type: string
taxCodeDescription:
description: |
The description of the tax code.
type: string
nullable: true
taxDate:
description: |
The date when the tax is applied to the invoice.
format: date
type: string
taxMode:
description: |
The tax mode of the invoice item, indicating whether the amount of the invoice item includes tax.
enum:
- TaxInclusive
- TaxExclusive
type: string
taxRate:
description: |
The tax rate applied to the invoice.
format: double
type: number
taxRateDescription:
description: |
The description of the tax rate.
type: string
nullable: true
taxRateType:
description: |
The type of the tax rate applied to the invoice.
enum:
- Percentage
- FlatFee
type: string
updatedById:
description: |
The ID of the Zuora user who last updated the taxation item.
type: string
updatedDate:
description: |
The date and time when the taxation item was last updated, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
type: object
- $ref: '#/components/schemas/TaxationItemObjectCustomFields'
title: taxationItems
POSTTaxationItemTypeForInvoice:
allOf:
- properties:
exemptAmount:
description: |
The calculated tax amount excluded due to the exemption.
format: number
type: string
financeInformation:
description: |
Container for the finance information related to the taxation item.
properties:
accountsReceivableAccountingCode:
description: |
The accounting code for accounts receivable.
maxLength: 100
minLength: 0
type: string
salesTaxPayableAccountingCode:
description: |
The accounting code for the sales taxes payable.
maxLength: 100
minLength: 0
type: string
type: object
invoiceItemId:
description: |
The ID of the invoice associated with the taxation item.
type: string
jurisdiction:
description: |
The jurisdiction that applies the tax or VAT. This value is typically a state, province, county, or city.
type: string
locationCode:
description: |
The identifier for the location based on the value of the `taxCode` field.
type: string
name:
description: |
The name of taxation.
type: string
taxAmount:
description: |
The amount of the taxation item in the invoice item.
format: number
type: string
taxCode:
description: |
The tax code identifies which tax rules and tax rates to apply to a specific invoice item.
type: string
taxCodeDescription:
description: |
The description of the tax code.
type: string
taxDate:
description: |
The date that the tax is applied to the invoice item, in `yyyy-mm-dd` format.
format: date
type: string
taxMode:
description: |
The tax mode of the invoice item, indicating whether the amount of the invoice item includes tax.
enum:
- TaxInclusive
- TaxExclusive
type: string
taxRate:
description: |
The tax rate applied to the invoice item.
format: number
type: string
taxRateDescription:
description: |
The description of the tax rate.
type: string
taxRateType:
description: |
The type of the tax rate applied to the invoice item.
enum:
- Percentage
- FlatFee
type: string
required:
- invoiceItemId
- jurisdiction
- name
- taxAmount
- taxDate
- taxRate
- taxRateType
title: taxItems
type: object
- $ref: '#/components/schemas/TaxationItemObjectCustomFields'
PUTWriteOffInvoiceRequest:
allOf:
- properties:
comment:
description: |
Comments about the write-off. The comment is used as the comment of the credit memo generated by writing off the specified invoice.
maxLength: 255
minLength: 0
type: string
items:
description: |
Container for items. This field is optional.
**Note:**
* If specified, you must specify ALL the items of the invoice. The entire balance of the invoice will be written off, you cannot just write off some items of the invoice.
* This field is available only if you have enabled the enhanced write-off permission for your tenant. Contact Zuora Global Support to enable this permission.
items:
$ref: '#/components/schemas/CreditMemoItemFromWriteOffInvoice'
type: array
memoDate:
description: |
The date when the credit memo was created, in `yyyy-mm-dd` format. The memo date must be later than or equal to the invoice date.
The default value is the date when you write off the invoice.
format: date
type: string
revenueImpacting:
description: |
Indicates whether this write off operation impacts the revenue. If `revenueImpacting` = `Yes`, the deferred revenue accounting code will be automatically selected from the associated invoice
The **Exclude Billing Item From Revenue** field will be automatically set to **Yes** by default for such non-revenue impacting write off credit memos, and this setting cannot be changed. This enhancement helps ensure that only revenue-impacting items are synchronized with Zuora Revenue, reducing unnecessary data processing.
If `revenueImpacting` = `No`, users can select an accounting code such as bad-debt expense accounting code for the write off operation.
**Note**: This field is available only if you have enabled the enhanced write-off permission for your tenant. Contact Zuora Global Support to enable this permission.
enum:
- 'Yes'
- 'No'
default: 'Yes'
type: string
amount:
description: |
The write off amount of the invoice.
**Note**: This field is available only if you have enabled the enhanced write-off permission for your tenant. Contact Zuora Global Support to enable this permission.
type: number
taxAutoCalculation:
description: |
Specifies whether taxes are automatically recalculated for the credit memo generated during the write-off process.
When set to `true`, the system fetches the latest tax rates from the tax vendor instead of copying the tax amounts from the original invoice.
The default value is `false`.
**Note**: This feature is in the **Early Availability** phase. Contact Zuora Global Support to enable this feature before using it.
type: boolean
nonRevenueWriteOffAccountingCode:
description: |
Specify the accounting code for the non revenue write off. Available only if `revenueImpacting` = `no`.
**Note**: This field is available only if you have enabled the enhanced write-off permission for your tenant. Contact Zuora Global Support to enable this permission.
type: string
reasonCode:
description: |
A code identifying the reason for the transaction. The value must be an existing reason code or empty. If you do not specify a value, Zuora uses the default reason code `Write-off`.
type: string
type: object
- $ref: '#/components/schemas/CreditMemoObjectCustomFields'
- $ref: '#/components/schemas/CreditMemoObjectNSFields'
example:
memoDate: '2019-01-02'
type: object
PUTWriteOffInvoiceResponse:
properties:
creditMemo:
description: |
Container for the credit memo that is automatically generated when writing off invoices.
properties:
id:
description: |
The ID of the credit memo that is created when the invoice is written off.
type: string
type: object
success:
description: |
Returns `true` if the request was processed successfully.
type: boolean
type: object
CreditMemoItemFromWriteOffInvoice:
allOf:
- properties:
comment:
description: |
Comments about the credit memo item.
type: string
financeInformation:
description: |
Container for the finance information related to the credit memo item.
properties:
deferredRevenueAccountingCode:
description: |
The accounting code for the deferred revenue, such as Monthly Recurring Liability.
maxLength: 100
minLength: 0
type: string
onAccountAccountingCode:
description: |
The accounting code that maps to an on account in your accounting system.
maxLength: 100
minLength: 0
type: string
recognizedRevenueAccountingCode:
description: |
The accounting code for the recognized revenue, such as Monthly Recurring Charges or Overage Charges.
maxLength: 100
minLength: 0
type: string
revenueRecognitionRuleName:
description: |
The name of the revenue recognition rule governing the revenue schedule.
maxLength: 100
minLength: 0
type: string
type: object
invoiceItemId:
description: |
The ID of the invoice item.
type: string
serviceEndDate:
description: |
The service end date of the credit memo item.
format: date
type: string
amountWithoutTax:
description: |
The write off amount of the invoice item excluding tax.
type: number
serviceStartDate:
description: |
The service start date of the credit memo item.
format: date
type: string
skuName:
description: |
The name of the charge associated with the invoice.
type: string
unitOfMeasure:
description: |
The definable unit that you measure when determining charges.
type: string
taxationItems:
description: |
Container for the taxation items of the credit memo item.
**Note**:
* This field is available only if you are on the latest Zuora API version, or you set the `Zuora-Version` request header to `239.0` or [a later available version](https://developer.zuora.com/v1-api-reference/api-versions/#minor-version).
items:
properties:
amount:
description: |
The credit memo taxation amount.
type: number
taxationItemId:
description: |
The Id of the debit memo item.
type: string
type: object
type: array
type: object
- $ref: '#/components/schemas/CreditMemoItemObjectCustomFields'
title: items
CreditMemoObjectCustomFields:
additionalProperties:
description: |
Custom fields of the Credit Memo object. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
description: |
Container for custom fields of a Credit Memo object.
title: creditMemoFieldsCustom
type: object
CreditMemoObjectNSFields:
description: |
Container for Credit Memo fields provided by the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
properties:
IntegrationId__NS:
description: |
ID of the corresponding object in NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
maxLength: 255
type: string
IntegrationStatus__NS:
description: |
Status of the credit memo's synchronization with NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
maxLength: 255
type: string
Origin__NS:
description: |
Origin of the corresponding object in NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
maxLength: 255
type: string
SyncDate__NS:
description: |
Date when the credit memo was synchronized with NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
maxLength: 255
type: string
Transaction__NS:
description: |
Related transaction in NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
maxLength: 255
type: string
title: creditMemoFieldsNS
type: object
CreditMemoItemObjectCustomFields:
additionalProperties:
description: |
Custom fields of the Credit Memo Item object. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
description: |
Container for custom fields of a Credit Memo Item object.
title: creditMemoItemFieldsCustom
type: object
GETCreditMemoCollectionType:
properties:
creditmemos:
description: |
Container for credit memos.
items:
$ref: '#/components/schemas/GETCreditMemoTypewithSuccess'
type: array
nextPage:
description: |
URL to retrieve the next page of the response if it exists; otherwise absent.
format: URL
type: string
success:
description: Returns `true` if the request was processed successfully.
type: boolean
type: object
GETCreditMemoTypewithSuccess:
allOf:
- properties:
accountId:
description: |
The ID of the customer account associated with the credit memo.
type: string
accountNumber:
description: |
The number of the account associated with the credit memo.
type: string
amount:
description: |
The total amount of the credit memo.
format: double
type: number
appliedAmount:
description: |
The applied amount of the credit memo.
format: double
type: number
autoApplyUponPosting:
description: |
Whether the credit memo automatically applies to the invoice upon posting.
type: boolean
billToContactId:
description: |
The ID of the bill-to contact associated with the credit memo.
The value of this field is `null` if you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled.
type: string
nullable: true
cancelledById:
description: |
The ID of the Zuora user who cancelled the credit memo.
type: string
nullable: true
cancelledOn:
description: |
The date and time when the credit memo was cancelled, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
nullable: true
comment:
description: |
Comments about the credit memo.
type: string
nullable: true
createdById:
description: |
The ID of the Zuora user who created the credit memo.
type: string
createdDate:
description: |
The date and time when the credit memo was created, in `yyyy-mm-dd hh:mm:ss` format. For example, 2017-03-01 15:31:10.
format: date-time
type: string
creditMemoDate:
description: |
The date when the credit memo takes effect, in `yyyy-mm-dd` format. For example, 2017-05-20.
format: date
type: string
currency:
description: |
The currency of the credit memo.
**Note:** By default, the currency on a billing document matches the default currency set on the associated account.
However, Zuora now offers a Multiple Currencies feature to support different currencies for billing documents, allowing flexibility beyond the account-level currency.
For more information, see Multiple Currency.
type: string
nullable: true
einvoiceErrorCode:
description: |
The error code returned when the e-invoice file status is `Failed`. This code can either be a Zuora-generated error code or one returned by a third-party e-invoicing service provider.
**Note**: This field is available only if you have the E-Invoicing feature in **Early Adopter** phase enabled.
type: string
nullable: true
einvoiceErrorMessage:
description: |
The error message returned when the e-invoice file status is `Failed`. This message can either be a Zuora-generated error message or one returned by a third-party e-invoicing service provider.
**Note**: This field is available only if you have the E-Invoicing feature in **Early Adopter** phase enabled.
type: string
nullable: true
einvoiceFileId:
description: |
The ID of the e-invoice file generated for the credit memo.
**Note**: This field is available only if you have the E-Invoicing feature in **Early Adopter** phase enabled.
type: string
nullable: true
einvoiceStatus:
description: |
The status of the e-invoice file generation for the credit memo.
- If e-invoice file generation succeeds, this field is either `Generated` or `Success`, and both the error code and message are empty, and the `eInvoiceFileId` field stores the ID of the generated e-invoice file.
- If the responses from tax vendors such as Sovos or Avalara are
taking too long, this field becomes `RetrieveTimeOut`. Once the
vendor responds successfully, you can use the 'Resync E-Invoice Status'
action to update the status automatically. You can view these updates
in System Health telemetry.
- If a failure occurs during e-invoice file generation, this field is `Failed` and an error code and an error message are returned respectively in the `einvoiceErrorCode` and `einvoiceErrorMessage` fields.
- If e-invoice file generation conditionally succeeds, this field is `ConditionalSuccess` and an error code and an error message are returned respectively in the `einvoiceErrorCode` and `einvoiceErrorMessage` fields.
- If the e-invoice file has been approved by the tax authority, this field is `ApprovedByAuthority`. The next status will be either `Success` or `Rejected`.
- If the e-invoice file has been rejected by the government, this field is `Rejected`. You cannot resend this e-invoice; you must create a new invoice instead.
**Note**: This field is available only if you have the E-Invoicing feature in **Early Adopter** phase
enabled.
enum:
- Processing
- RetrieveTimeOut
- Generated
- Success
- Failed
- ConditionalSuccess
- ApprovedByAuthority
- Rejected
type: string
nullable: true
excludeFromAutoApplyRules:
description: |
Whether the credit memo is excluded from the rule of automatically applying unapplied credit memos to invoices and debit memos during payment runs.
type: boolean
id:
description: |
The unique ID of the credit memo.
type: string
invoiceGroupNumber:
description: |
The number of the invoice group associated with the credit memo.
The value of this field is `null` if you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled.
type: string
nullable: true
latestPDFFileId:
description: |
The ID of the latest PDF file generated for the credit memo.
type: string
number:
description: |
The unique identification number of the credit memo.
type: string
organizationLabel:
description: |
The organization that this object belongs to.
Note: This field is available only when the Multi-Org feature is enabled.
type: string
postedById:
description: |
The ID of the Zuora user who posted the credit memo.
type: string
nullable: true
postedOn:
description: |
The date and time when the credit memo was posted, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
nullable: true
reasonCode:
description: |
A code identifying the reason for the transaction. The value must be an existing reason code or empty.
type: string
referredInvoiceId:
description: |
The ID of a referred invoice.
type: string
nullable: true
refundAmount:
description: |
The amount of the refund on the credit memo.
format: double
type: number
revenueImpacting:
description: |
Indicates whether this write off operation impacts the revenue. If `revenueImpacting` = `Yes`, the deferred revenue accounting code will be automatically selected from the associated invoice
If `revenueImpacting` = `No`, users can select an accounting code such as bad-debt expense accounting code for the write off operation.
enum:
- 'Yes'
- 'No'
default: 'Yes'
type: string
reversed:
description: |
Whether the credit memo is reversed.
type: boolean
sequenceSetId:
description: |
The ID of the sequence set associated with the credit memo.
The value of this field is `null` if you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled.
type: string
nullable: true
communicationProfileId:
description: |
The ID of the communication profile associated with the credit memo.
**Note**: This field is available in the request body only if you have the Flexible Billing Attributes
feature turned on. The value is `null` in the response body without this feature turned on.
type: string
nullable: true
source:
description: |
The source of the credit memo.
Possible values:
- `BillRun`: The credit memo is generated by a bill run.
- `API`: The credit memo is created by calling the [Invoice and collect](https://developer.zuora.com/api-references/api/operation/POST_TransactionInvoicePayment) operation, or by calling the Orders, Order Line Items, or Fulfillments API operations.
- `ApiSubscribe`: The credit memo is created by calling the [Create subscription](https://developer.zuora.com/api-references/api/operation/POST_Subscription) and [Create account](https://developer.zuora.com/api-references/api/operation/POST_Account) operation.
- `ApiAmend`: The credit memo is created by calling the [Update subscription](https://developer.zuora.com/api-references/api/operation/PUT_Subscription) operation.
- `AdhocFromPrpc`: The credit memo is created from a product rate plan charge through the Zuora UI or by calling the [Create a credit memo from a charge](https://developer.zuora.com/api-references/api/operation/POST_CreditMemoFromPrpc) operation.
- `AdhocFromInvoice`: The credit memo is created from an invoice or created by reversing an invoice. You can create a credit memo from an invoice through the Zuora UI or by calling the [Create credit memo from invoice](https://developer.zuora.com/api-references/api/operation/POST_CreditMemoFromInvoice) operation. You can create a credit memo by reversing an invoice through the Zuora UI or by calling the [Reverse invoice](https://developer.zuora.com/api-references/api/operation/PUT_ReverseInvoice) operation.
type: string
sourceId:
description: |
The ID of the credit memo source.
If a credit memo is generated from a bill run, the value is the number of the corresponding bill run. Otherwise, the value is `null`.
type: string
sourceType:
description: |
The type of the credit memo source.
enum:
- Subscription
- Standalone
- Invoice
- Order
- CreditMemo
- Consolidation
type: string
status:
description: |
The status of the credit memo.
enum:
- Draft
- Posted
- Canceled
- Error
- PendingForTax
- Generating
- CancelInProgress
type: string
targetDate:
description: |
The target date for the credit memo, in `yyyy-mm-dd` format. For example, 2017-07-20.
format: date
type: string
nullable: true
taxAmount:
description: |
The amount of taxation.
format: double
type: number
taxMessage:
description: |
The message about the status of tax calculation related to the credit memo. If tax calculation fails in one credit memo, this field displays the reason for the failure.
type: string
nullable: true
taxStatus:
description: |
The status of tax calculation related to the credit memo.
**Note**: This field is only applicable to tax calculation by third-party tax engines. Also, the `Voided` status indicates that the tax transaction is successfully canceled on the tax vendor's side. If a tax transaction was successfully committed to the third-party tax engine but the invoice failed to post, Zuora automatically detects the issue and voids the tax transaction on the vendor's side.
enum:
- Complete
- Error
- UnknownError
- DuplicateDoc
- InvalidRequest
- InvalidResponse
- TaxEngineError
- ConcurrentModify
- InternalServerError
- TaxCodeTemplateError
- Voided
type: string
nullable: true
totalTaxExemptAmount:
description: |
The calculated tax amount excluded due to the exemption.
format: double
type: number
transferredToAccounting:
description: |
Whether the credit memo was transferred to an external accounting system. Use this field for integration with accounting systems, such as NetSuite.
enum:
- Processing
- 'Yes'
- 'No'
- Error
- Ignore
type: string
unappliedAmount:
description: |
The unapplied amount of the credit memo.
format: double
type: number
updatedById:
description: |
The ID of the Zuora user who last updated the credit memo.
type: string
updatedDate:
description: |
The date and time when the credit memo was last updated, in `yyyy-mm-dd hh:mm:ss` format. For example, 2017-03-02 15:36:10.
format: date-time
type: string
type: object
- $ref: '#/components/schemas/CreditMemoObjectNSFields'
- $ref: '#/components/schemas/CreditMemoObjectCustomFields'
title: creditmemos
CreditMemoFromChargeRequest:
allOf:
- properties:
accountId:
description: |
The ID of the account associated with the credit memo.
**Note**: When creating credit memos from product rate plan charges, you must specify `accountNumber`, `accountId`, or both in the request body. If both fields are specified, they must correspond to the same account.
type: string
accountNumber:
description: |
The number of the customer account associated with the credit memo.
**Note**: When creating credit memos from product rate plan charges, you must specify `accountNumber`, `accountId`, or both in the request body. If both fields are specified, they must correspond to the same account.
type: string
autoPost:
default: false
description: |
Whether to automatically post the credit memo after it is created.
Setting this field to `true`, you do not need to separately call the [Post a credit memo](https://developer.zuora.com/api-references/api/operation/PUT_PostCreditMemo) operation to post the credit memo.
type: boolean
charges:
description: |
Container for product rate plan charges. The maximum number of items is 1,000.
items:
$ref: '#/components/schemas/CreditMemoFromChargeDetailType'
maxItems: 1000
type: array
comment:
description: |
Comments about the credit memo.
type: string
currency:
description: |
The code of a currency as defined in Billing Settings through the Zuora UI.
If you do not specify a currency during credit memo creation, the default account currency is applied. The currency that you specify in the request must be configured and activated in Billing Settings.
**Note**: This field is available only if you have the Multiple Currencies feature enabled.
type: string
customRates:
description: |
It contains Home currency and Reporting currency custom rates currencies. The maximum number of items is 2 (you can pass the Home currency item or Reporting currency item or both).
**Note**:
- The API custom rate feature is permission controlled.
- You cannot set the custom rates, if both the **Automatically include additional Currency Conversion information in data source exports** option and **Fx data** feature are enabled.
- CreditMemo, CreditMemoItem, and CreditMemoItemTax will utilize the provided custom Fx rate to convert amounts from the transactional currency to the home currency.
items:
$ref: '#/components/schemas/CreditMemoFromChargeCustomRatesType'
maxItems: 2
type: array
effectiveDate:
description: |
The date when the credit memo takes effect.
format: date
type: string
excludeFromAutoApplyRules:
default: false
description: |
Whether the credit memo is excluded from the rule of automatically applying unapplied credit memos to invoices and debit memos during payment runs. If you set this field to `true`, a payment run does not pick up this credit memo or apply it to other invoices or debit memos.
type: boolean
number:
type: string
maxLength: 32
description: |
A customized credit memo number with the following format requirements:
- Max length: 32 characters
- Acceptable characters: a-z,A-Z,0-9,-,_
The value must be unique in the system, otherwise it may cause issues with bill runs and subscriptions.
If not provided, Zuora will generate a unique number per the sequence set on the account level. If the account-level sequence set is not specified, the system default sequence set is used. For more information, see Configure prefix and numbering for billing documents.
reasonCode:
description: |
A code identifying the reason for the transaction. The value must be an existing reason code or empty. If you do not specify a value, Zuora uses the default reason code.
type: string
type: object
- $ref: '#/components/schemas/CreditMemoObjectNSFields'
- $ref: '#/components/schemas/CreditMemoObjectCustomFields'
example:
accountId: 8ad09be48db5aba7018db604776d4854
charges:
- amount: 10
productRatePlanChargeId: 8ad097b4909708e001909b41bb085d38
title: memos
GETCreditMemoType:
allOf:
- properties:
accountId:
description: |
The ID of the customer account associated with the credit memo.
type: string
accountNumber:
description: |
The number of the customer account associated with the credit memo.
type: string
amount:
description: |
The total amount of the credit memo.
format: double
type: number
appliedAmount:
description: |
The applied amount of the credit memo.
format: double
type: number
autoApplyUponPosting:
description: |
Whether the credit memo automatically applies to the invoice upon posting.
type: boolean
billToContactId:
description: |
The ID of the bill-to contact associated with the credit memo.
The value of this field is `null` if you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled.
type: string
nullable: true
billToContactSnapshotId:
description: |
The ID of the bill-to contact snapshot associated with the credit memo.
The value of this field is `null` if the bill rule [Preserve snapshot of bill-to and sold-to contacts when billing documents are posted](https://knowledgecenter.zuora.com/Zuora_Billing/Billing_and_Invoicing/Billing_Settings/Define_Billing_Rules#Preserve_snapshot_of_bill-to_and_sold-to_contacts_when_billing_documents_are_posted) is disabled.
type: string
nullable: true
cancelledById:
description: |
The ID of the Zuora user who cancelled the credit memo.
type: string
nullable: true
cancelledOn:
description: |
The date and time when the credit memo was cancelled, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
nullable: true
comment:
description: |
Comments about the credit memo.
type: string
nullable: true
createdById:
description: |
The ID of the Zuora user who created the credit memo.
type: string
createdDate:
description: |
The date and time when the credit memo was created, in `yyyy-mm-dd hh:mm:ss` format. For example, 2017-03-01 15:31:10.
format: date-time
type: string
creditMemoDate:
description: |
The date when the credit memo takes effect, in `yyyy-mm-dd` format. For example, 2017-05-20.
format: date
type: string
currency:
description: |
The currency of the credit memo.
**Note:** By default, the currency on a billing document matches the default currency set on the associated account.
However, Zuora now offers a Multiple Currencies feature to support different currencies for billing documents, allowing flexibility beyond the account-level currency.
For more information, see Multiple Currency.
type: string
nullable: true
einvoiceErrorCode:
description: |
The error code returned when the e-invoice file status is `Failed`. This code can either be a Zuora-generated error code or one returned by a third-party e-invoicing service provider.
**Note**: This field is available only if you have the E-Invoicing feature in **Early Adopter** phase enabled.
type: string
nullable: true
einvoiceErrorMessage:
description: |
The error message returned when the e-invoice file status is `Failed`. This message can either be a Zuora-generated error message or one returned by a third-party e-invoicing service provider.
**Note**: This field is available only if you have the E-Invoicing feature in **Early Adopter** phase enabled.
type: string
nullable: true
einvoiceFileId:
description: |
The ID of the e-invoice file generated for the credit memo.
**Note**: This field is available only if you have the E-Invoicing feature in **Early Adopter** phase enabled.
type: string
nullable: true
einvoiceStatus:
description: |
The status of the e-invoice file generation for the credit memo.
- If e-invoice file generation succeeds, this field is either `Generated` or `Success`, and both the error code and message are empty, and the `eInvoiceFileId` field stores the ID of the generated e-invoice file.
- If the responses from tax vendors such as Sovos or Avalara are
taking too long, this field becomes `RetrieveTimeOut`. Once the
vendor responds successfully, you can use the 'Resync E-Invoice Status'
action to update the status automatically. You can view these updates
in System Health telemetry.
- If a failure occurs during e-invoice file generation, this field is `Failed` and an error code and an error message are returned respectively in the `einvoiceErrorCode` and `einvoiceErrorMessage` fields.
- If e-invoice file generation conditionally succeeds, this field is `ConditionalSuccess` and an error code and an error message are returned respectively in the `einvoiceErrorCode` and `einvoiceErrorMessage` fields.
- If the e-invoice file has been approved by the tax authority, this field is `ApprovedByAuthority`. The next status will be either `Success` or `Rejected`.
- If the e-invoice file has been rejected by the government, this field is `Rejected`. You cannot resend this e-invoice; you must create a new invoice instead.
**Note**: This field is available only if you have the E-Invoicing feature in **Early Adopter** phase
enabled.
enum:
- Processing
- RetrieveTimeOut
- Generated
- Success
- Failed
- ConditionalSuccess
- ApprovedByAuthority
- Rejected
type: string
nullable: true
excludeFromAutoApplyRules:
description: |
Whether the credit memo is excluded from the rule of automatically
applying credit memos to invoices.
type: boolean
excludeItemBillingFromRevenueAccounting:
description: |
The flag to exclude the credit memo item from revenue accounting.
**Note**: This field is only available if you have the Billing -
Revenue Integration feature enabled.
type: boolean
id:
description: |
The unique ID of the credit memo.
type: string
invoiceGroupNumber:
description: |
The number of the invoice group associated with the credit memo.
The value of this field is `null` if you have the [Flexible Billing
Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes)
feature disabled.
type: string
nullable: true
latestPDFFileId:
description: |
The ID of the latest PDF file generated for the credit memo.
type: string
nullable: true
number:
description: |
The unique identification number of the credit memo.
type: string
organizationLabel:
description: |
The organization that this object belongs to.
Note: This field is available only when the Multi-Org feature is enabled.
type: string
postedById:
description: |
The ID of the Zuora user who posted the credit memo.
type: string
nullable: true
postedOn:
description: |
The date and time when the credit memo was posted, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
nullable: true
reasonCode:
description: |
A code identifying the reason for the transaction. The value must be an existing reason code or empty.
type: string
referredInvoiceId:
description: |
The ID of a referred invoice.
type: string
nullable: true
refundAmount:
description: |
The amount of the refund on the credit memo.
format: double
type: number
revenueImpacting:
description: |
Indicates whether this write off operation impacts the revenue. If `revenueImpacting` = `Yes`, the deferred revenue accounting code will be automatically selected from the associated invoice
If `revenueImpacting` = `No`, users can select an accounting code such as bad-debt expense accounting code for the write off operation.
enum:
- 'Yes'
- 'No'
default: 'Yes'
type: string
reversed:
description: |
Whether the credit memo is reversed.
type: boolean
sequenceSetId:
description: |
The ID of the sequence set associated with the credit memo.
The value of this field is `null` if you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled.
type: string
nullable: true
communicationProfileId:
description: |
The ID of the communication profile associated with the credit memo.
**Note**: This field is available in the request body only if you have the Flexible Billing Attributes
feature turned on. The value is `null` in the response body without this feature turned on.
type: string
nullable: true
source:
description: |
The source of the credit memo.
Possible values:
- `BillRun`: The credit memo is generated by a bill run.
- `API`: The credit memo is created by calling the [Invoice and collect](https://developer.zuora.com/api-references/api/operation/POST_TransactionInvoicePayment) operation, or by calling the Orders, Order Line Items, or Fulfillments API operations.
- `ApiSubscribe`: The credit memo is created by calling the [Create subscription](https://developer.zuora.com/api-references/api/operation/POST_Subscription) and [Create account](https://developer.zuora.com/api-references/api/operation/POST_Account) operation.
- `ApiAmend`: The credit memo is created by calling the [Update subscription](https://developer.zuora.com/api-references/api/operation/PUT_Subscription) operation.
- `AdhocFromPrpc`: The credit memo is created from a product rate plan charge through the Zuora UI or by calling the [Create a credit memo from a charge](https://developer.zuora.com/api-references/api/operation/POST_CreditMemoFromPrpc) operation.
- `AdhocFromInvoice`: The credit memo is created from an invoice or created by reversing an invoice. You can create a credit memo from an invoice through the Zuora UI or by calling the [Create credit memo from invoice](https://developer.zuora.com/api-references/api/operation/POST_CreditMemoFromInvoice) operation. You can create a credit memo by reversing an invoice through the Zuora UI or by calling the [Reverse invoice](https://developer.zuora.com/api-references/api/operation/PUT_ReverseInvoice) operation.
type: string
sourceId:
description: |
The ID of the credit memo source.
If a credit memo is generated from a bill run, the value is the number of the corresponding bill run. Otherwise, the value is `null`.
type: string
nullable: true
sourceType:
description: |
The type of the credit memo source.
enum:
- Subscription
- Standalone
- Invoice
- Order
- CreditMemo
- Consolidation
type: string
status:
description: |
The status of the credit memo.
enum:
- Draft
- Posted
- Canceled
- Error
- PendingForTax
- Generating
- CancelInProgress
type: string
success:
description: Returns `true` if the request was processed successfully.
type: boolean
targetDate:
description: |
The target date for the credit memo, in `yyyy-mm-dd` format. For example, 2017-07-20.
format: date
type: string
nullable: true
taxAmount:
description: |
The amount of taxation.
format: double
type: number
taxMessage:
description: |
The message about the status of tax calculation related to the credit memo. If tax calculation fails in one credit memo, this field displays the reason for the failure.
type: string
nullable: true
taxStatus:
description: |
The status of tax calculation related to the credit memo.
**Note**: This field is only applicable to tax calculation by third-party tax engines. Also, the `Voided` status indicates that the tax transaction is successfully canceled on the tax vendor's side. If a tax transaction was successfully committed to the third-party tax engine but the invoice failed to post, Zuora automatically detects the issue and voids the tax transaction on the vendor's side.
enum:
- Complete
- Error
- UnknownError
- DuplicateDoc
- InvalidRequest
- InvalidResponse
- TaxEngineError
- ConcurrentModify
- InternalServerError
- TaxCodeTemplateError
- Voided
type: string
nullable: true
totalTaxExemptAmount:
description: |
The calculated tax amount excluded due to the exemption.
format: double
type: number
transferredToAccounting:
description: |
Whether the credit memo was transferred to an external accounting system. Use this field for integration with accounting systems, such as NetSuite.
enum:
- Processing
- 'Yes'
- 'No'
- Error
- Ignore
type: string
unappliedAmount:
description: |
The unapplied amount of the credit memo.
format: double
type: number
updatedById:
description: |
The ID of the Zuora user who last updated the credit memo.
type: string
updatedDate:
description: |
The date and time when the credit memo was last updated, in `yyyy-mm-dd hh:mm:ss` format. For example, 2017-03-01 15:36:10.
format: date-time
type: string
type: object
- $ref: '#/components/schemas/CreditMemoObjectNSFields'
- $ref: '#/components/schemas/CreditMemoObjectCustomFields'
CreditMemoFromChargeDetailType:
allOf:
- properties:
amount:
description: |
The amount of the credit memo item.
**Note**: This field is available only if you are on the latest Zuora API version, or you set the `Zuora-Version` request header to `224.0` or [a later available version](https://developer.zuora.com/v1-api-reference/api-versions/#minor-version).
format: double
type: number
excludeItemBillingFromRevenueAccounting:
default: false
description: |
The flag to exclude the credit memo item from revenue accounting.
**Note**: This field is only available if you have the Billing - Revenue Integration feature enabled.
type: boolean
description:
description: |
The description of the product rate plan charge.
**Note**: This field is available only if you are on the latest Zuora API version, or you set the `Zuora-Version` request header to `257.0` or [a later available version](https://developer.zuora.com/v1-api-reference/api-versions/#minor-version).
maxLength: 255
minLength: 0
type: string
financeInformation:
description: |
Container for the finance information related to the product rate plan charge associated with the credit memo.
properties:
deferredRevenueAccountingCode:
description: |
The accounting code for the deferred revenue, such as Monthly Recurring Liability.
maxLength: 100
minLength: 0
type: string
onAccountAccountingCode:
description: |
The accounting code that maps to an on account in your accounting system.
maxLength: 100
minLength: 0
type: string
recognizedRevenueAccountingCode:
description: |
The accounting code for the recognized revenue, such as Monthly Recurring Charges or Overage Charges.
maxLength: 100
minLength: 0
type: string
revenueRecognitionRuleName:
description: |
The name of the revenue recognition rule governing the revenue schedule.
maxLength: 100
minLength: 0
type: string
type: object
productRatePlanChargeId:
description: |
The ID of the product rate plan charge that the credit memo is created from.
**Note**: This field is available only if you are on the latest Zuora API version, or you set the `Zuora-Version` request header to `257.0` or [a later available version](https://developer.zuora.com/v1-api-reference/api-versions/#minor-version).
type: string
quantity:
description: |
The number of units for the credit memo item.
format: double
type: number
serviceEndDate:
description: |
The service end date of the credit memo item. If not specified, the effective end date of the corresponding product rate plan will be used.
format: date
type: string
serviceStartDate:
description: |
The service start date of the credit memo item. If not specified, the effective start date of the corresponding product rate plan will be used.
format: date
type: string
required:
- productRatePlanChargeId
type: object
- $ref: '#/components/schemas/CreditMemoItemObjectCustomFields'
title: charges
CreditMemoFromChargeCustomRatesType:
allOf:
- properties:
currency:
description: |
The currency code for either Reporting or Home currency.
**Note**: This field is available only if you are on the latest Zuora API version, or you set the `Zuora-Version` request header to `224.0` or [a later available version](https://developer.zuora.com/v1-api-reference/api-versions/#minor-version).
type: string
customFxRate:
description: |
The Custom FX conversion rate between Home/Reporting and Transactional currency items.
**Note**: This field is available only if you are on the latest Zuora API version, or you set the `Zuora-Version` request header to `224.0` or [a later available version](https://developer.zuora.com/v1-api-reference/api-versions/#minor-version).
format: decimal
type: number
rateDate:
description: |
The date on which a particular currency rate is fixed or obtained on.
**Note**: This field is available only if you are on the latest Zuora API version, or you set the `Zuora-Version` request header to `224.0` or [a later available version](https://developer.zuora.com/v1-api-reference/api-versions/#minor-version).
format: date
type: string
required:
- currency
- customFxRate
type: object
- $ref: '#/components/schemas/CreditMemoItemObjectCustomFields'
title: customRates
POSTBulkCreditMemosRequestType:
discriminator:
propertyName: sourceType
mapping:
Invoice: '#/components/schemas/BulkCreateCreditMemosFromInvoiceRequest'
Standalone: '#/components/schemas/BulkCreateCreditMemosFromChargeRequest'
oneOf:
- $ref: '#/components/schemas/BulkCreateCreditMemosFromInvoiceRequest'
- $ref: '#/components/schemas/BulkCreateCreditMemosFromChargeRequest'
BulkCreditMemosResponseType:
allOf:
- properties:
memos:
description: |
The container for a list of credit memos.
items:
$ref: '#/components/schemas/GETCreditMemoType'
maxItems: 50
title: memos
type: array
success:
description: |
Returns `true` if the request was processed successfully.
type: boolean
type: object
BulkCreateCreditMemosFromInvoiceRequest:
properties:
sourceType:
type: string
enum:
- Invoice
description: |
The type of the source where credit memos are created.
This enum field has the following values:
- `Invoice`: By setting this field to `Invoice`, you can create multiple credit memos from invoices.
- `Standalone`: By setting this field to `Standalone`, you can create multiple credit memos from product rate plan charges.
The specific schema of the `memos` object field in the request body depends on the value of the `sourceType` field.
- To view the `memos` schema applicable to credit memo creation from invoices, select `Invoice` from the following drop-down list.
- To view the `memos` schema applicable to credit memo creation from product rate plan charges, select `Standalone` from the following drop-down list.
memos:
description: |
The container for a list of credit memos. The maximum number of credit memos is 50.
items:
$ref: '#/components/schemas/CreditMemoFromInvoiceRequest'
maxItems: 50
type: array
required:
- sourceType
type: object
BulkCreateCreditMemosFromChargeRequest:
properties:
sourceType:
type: string
enum:
- Standalone
- Invoice
description: |
The type of the source where credit memos are created.
This enum field has the following values:
- `Invoice`: By setting this field to `Invoice`, you can create multiple credit memos from invoices.
- `Standalone`: By setting this field to `Standalone`, you can create multiple credit memos from product rate plan charges.
The specific schema of the `memos` object field in the request body depends on the value of the `sourceType` field.
- To view the `memos` schema applicable to credit memo creation from invoices, select `Invoice` from the following drop-down list.
- To view the `memos` schema applicable to credit memo creation from product rate plan charges, select `Standalone` from the following drop-down list.
memos:
description: |
The container for a list of credit memos. The maximum number of credit memos is 50.
items:
$ref: '#/components/schemas/CreditMemoFromChargeRequest'
maxItems: 50
type: array
required:
- sourceType
type: object
CreditMemoFromInvoiceRequest:
allOf:
- properties:
autoApplyToInvoiceUponPosting:
description: |
Whether the credit memo automatically applies to the invoice upon posting.
type: boolean
autoPost:
default: false
description: |
Whether to automatically post the credit memo after it is created.
Setting this field to `true`, you do not need to separately call the [Post credit memo](https://developer.zuora.com/api-references/api/operation/PUT_PostCreditMemo) operation to post the credit memo.
type: boolean
comment:
description: |
Comments about the credit memo.
maxLength: 255
minLength: 0
type: string
effectiveDate:
description: |
The date when the credit memo takes effect.
format: date
type: string
excludeFromAutoApplyRules:
description: |
Whether the credit memo is excluded from the rule of automatically applying credit memos to invoices.
type: boolean
invoiceId:
description: |
The ID of the invoice that the credit memo is created from.
type: string
items:
description: |
Container for items. The maximum number of items is 1,000.
items:
$ref: '#/components/schemas/CreditMemoItemFromInvoiceItemType'
maxItems: 1000
type: array
reasonCode:
description: |
A code identifying the reason for the transaction. The value must be an existing reason code or empty. If you do not specify a value, Zuora uses the default reason code.
type: string
taxAutoCalculation:
default: true
description: |
Whether to automatically calculate taxes in the credit memo.
type: boolean
type: object
required:
- invoiceId
- $ref: '#/components/schemas/CreditMemoObjectNSFields'
- $ref: '#/components/schemas/CreditMemoObjectCustomFields'
example:
invoiceId: 8a90d7a892d82d920192dbcb314501c7
items:
- amount: 10
invoiceItemId: 8a90d7a892d82d920192dbcb31f401c8
skuName: SKU-00000707
title: memos
CreditMemoItemFromInvoiceItemType:
allOf:
- properties:
amount:
description: |
The amount of the credit memo item.
format: double
type: number
description:
description: |
The description of the credit memo item.
**Note**: This field is available only if you are on the latest Zuora API version, or you set the `Zuora-Version` request header to `257.0` or [a later available version](https://developer.zuora.com/v1-api-reference/api-versions/#minor-version).
type: string
financeInformation:
description: |
Container for the finance information related to the credit memo item.
properties:
deferredRevenueAccountingCode:
description: |
The accounting code for the deferred revenue, such as Monthly Recurring Liability.
maxLength: 100
minLength: 0
type: string
onAccountAccountingCode:
description: |
The accounting code that maps to an on account in your accounting system.
maxLength: 100
minLength: 0
type: string
recognizedRevenueAccountingCode:
description: |
The accounting code for the recognized revenue, such as Monthly Recurring Charges or Overage Charges.
maxLength: 100
minLength: 0
type: string
revenueRecognitionRuleName:
description: |
The name of the revenue recognition rule governing the revenue schedule.
maxLength: 100
minLength: 0
type: string
type: object
invoiceItemId:
description: |
The ID of the invoice item.
type: string
quantity:
description: |
The number of units for the credit memo item.
format: double
type: number
serviceEndDate:
description: |
The service end date of the credit memo item.
format: date
type: string
serviceStartDate:
description: |
The service start date of the credit memo item.
format: date
type: string
skuName:
description: |
The name of the charge associated with the invoice.
type: string
taxItems:
description: |
Container for taxation items.
items:
$ref: '#/components/schemas/CreditMemoTaxItemFromInvoiceTaxItemType'
type: array
taxMode:
default: TaxExclusive
description: |
The tax mode of the credit memo item, indicating whether the amount of the credit memo item includes tax.
**Note**:
- Only includes the `taxMode` field if the credit memo needs to be processed with a different tax mode than what was processed during invoice generation or the product rate plan charge was defined with. Otherwise, do not specify a tax mode.
- You can set this field to `TaxInclusive` only if the `taxAutoCalculation` field is set to `true`.
- If you set `taxMode` to `TaxInclusive`, you cannot input tax amounts for credit memo items. The corresponding invoice item must use the same tax engine as the credit memo item to calculate tax amounts.
enum:
- TaxExclusive
- TaxInclusive
type: string
unitOfMeasure:
description: |
The definable unit that you measure when determining charges.
type: string
required:
- skuName
- amount
- invoiceItemId
type: object
- $ref: '#/components/schemas/CreditMemoItemObjectCustomFields'
title: items
CreditMemoTaxItemFromInvoiceTaxItemType:
properties:
amount:
description: |
The amount of the credit memo taxation item.
format: double
type: number
financeInformation:
description: |
Container for the finance information related to the source taxation item.
properties:
onAccountAccountingCode:
description: |
The accounting code that maps to an on account in your accounting system.
maxLength: 100
minLength: 0
type: string
salesTaxPayableAccountingCode:
description: |
The accounting code for the sales taxes payable.
maxLength: 100
minLength: 0
type: string
type: object
jurisdiction:
description: |
The jurisdiction that applies the tax or VAT. This value is typically a state, province, county, or city.
type: string
locationCode:
description: |
The identifier for the location based on the value of the `taxCode` field.
type: string
sourceTaxItemId:
description: |
The ID of the source taxation item.
type: string
taxCode:
description: |
The tax code identifies which tax rules and tax rates to apply to a specific credit memo.
type: string
taxCodeDescription:
description: |
The description of the tax code.
type: string
taxDate:
description: |
The date that the tax is applied to the credit memo, in `yyyy-mm-dd` format.
format: date
type: string
taxExemptAmount:
description: |
The calculated tax amount excluded due to the exemption.
format: double
type: number
taxName:
description: |
The name of taxation.
type: string
taxRate:
description: |
The tax rate applied to the credit memo.
format: double
type: number
taxRateDescription:
description: |
The description of the tax rate.
type: string
taxRateType:
description: |
The type of the tax rate applied to the credit memo.
enum:
- Percentage
- FlatFee
type: string
title: taxItems
type: object
PUTBulkCreditMemosRequestType:
allOf:
- properties:
memos:
description: |
The container for a list of credit memos. The maximum number of credit memos is 50.
items:
$ref: '#/components/schemas/PUTCreditMemosWithIdType'
maxItems: 50
type: array
type: object
example:
memos:
- autoApplyUponPosting: false
comment: new comment
effectiveDate: '2017-04-17'
excludeFromAutoApplyRules: false
id: 402890555b797b57015b7986fc1a001f
items:
- amount: 1
comment: This is comment!
id: 402890555b797b57015b7986fc1a001c
quantity: 1
serviceEndDate: '2016-11-30'
serviceStartDate: '2016-11-01'
skuName: SKU-1
taxItems:
- amount: 0.03
id: 402890555b797b57015b7986fc3c001d
jurisdiction: CALIFORNIA
locationCode: '06'
taxCode: null
taxCodeDescription: This is tax code description!
taxDate: '2016-11-30'
taxExemptAmount: 0
taxName: STATE TAX1
taxRate: 0.0625
taxRateDescription: This is tax rate description!
taxRateType: Percentage
unitOfMeasure: Test_UOM
- amount: 2
comment: This is comment!
id: 402890555b797b57015b7986fc41001e
serviceEndDate: '2016-11-30'
serviceStartDate: '2016-11-01'
skuName: SKU-2
taxItems: []
unitOfMeasure: Test_UOM
reasonCode: Correcting invoice error
PUTCreditMemosWithIdType:
allOf:
- properties:
id:
description: |
The ID of the credit memo.
type: string
type: object
- $ref: '#/components/schemas/PUTCreditMemoType'
title: memos
PUTCreditMemoType:
allOf:
- properties:
autoApplyUponPosting:
description: |
Whether the credit memo automatically applies to the invoice upon posting.
type: boolean
comment:
description: |
Comments about the credit memo.
maxLength: 255
minLength: 0
type: string
effectiveDate:
description: |
The date when the credit memo takes effect.
format: date
type: string
excludeFromAutoApplyRules:
description: |
Whether the credit memo is excluded from the rule of automatically applying unapplied credit memos to invoices and debit memos during payment runs. If you set this field to `true`, a payment run does not pick up this credit memo or apply it to other invoices or debit memos.
type: boolean
items:
description: |
Container for credit memo items.
items:
$ref: '#/components/schemas/PUTCreditMemoItemType'
type: array
reasonCode:
description: |
A code identifying the reason for the transaction. The value must be an existing reason code or empty. If you do not specify a value, Zuora uses the default reason code.
type: string
transferredToAccounting:
description: |
Whether the credit memo is transferred to an external accounting system. Use this field for integration with accounting systems, such as NetSuite.
enum:
- Processing
- 'Yes'
- 'No'
- Error
- Ignore
type: string
type: object
- $ref: '#/components/schemas/CreditMemoObjectNSFields'
- $ref: '#/components/schemas/CreditMemoObjectCustomFields'
example:
comment: Details about this Credit Memo
PUTCreditMemoItemType:
allOf:
- properties:
amount:
description: |
The amount of the credit memo item. For tax-inclusive credit memo items, the amount indicates the credit memo item amount including tax. For tax-exclusive credit memo items, the amount indicates the credit memo item amount excluding tax
format: double
type: number
comment:
description: |
Comments about the credit memo item.
type: string
delete:
description: |
Whether to delete the existing credit memo item.
**Note**: To delete a credit memo item, set this field to `true` and specify a credit memo item ID in the `id` field.
type: boolean
excludeItemBillingFromRevenueAccounting:
default: false
description: |
The flag to exclude the credit memo item from revenue accounting.
**Note**: This field is only available if you have the Billing - Revenue Integration feature enabled.
type: boolean
financeInformation:
description: |
Container for the finance information related to the credit memo item.
properties:
deferredRevenueAccountingCode:
description: |
The accounting code for the deferred revenue, such as Monthly Recurring Liability.
maxLength: 100
minLength: 0
type: string
onAccountAccountingCode:
description: |
The accounting code that maps to an on account in your accounting system.
maxLength: 100
minLength: 0
type: string
recognizedRevenueAccountingCode:
description: |
The accounting code for the recognized revenue, such as Monthly Recurring Charges or Overage Charges.
maxLength: 100
minLength: 0
type: string
revenueRecognitionRuleName:
description: |
The name of the revenue recognition rule governing the revenue schedule.
maxLength: 100
minLength: 0
type: string
type: object
id:
description: |
The ID of the credit memo item.
- Specify this field when updating or deleting an existing memo item.
- Do not specify this field when creating a memo item.
maxLength: 32
minLength: 32
type: string
quantity:
description: |
The number of units for the credit memo item.
format: double
type: number
productRatePlanChargeId:
description: |
The ID of the product rate plan charge that the credit memo is created from.
**Note**: Do not specify the credit memo item `id` when specifying this field.
type: string
serviceEndDate:
description: |
The service end date of the credit memo item.
format: date
type: string
serviceStartDate:
description: |
The service start date of the credit memo item.
format: date
type: string
skuName:
description: |
The name of the SKU.
type: string
taxItems:
description: |
Container for credit memo taxation items.
items:
$ref: '#/components/schemas/PutCreditMemoTaxItemType'
type: array
unitOfMeasure:
description: |
The definable unit that you measure when determining charges.
type: string
type: object
- $ref: '#/components/schemas/CreditMemoItemObjectCustomFields'
title: items
PutCreditMemoTaxItemType:
allOf:
- properties:
amount:
description: |
The amount of the taxation item in the credit memo item.
format: double
type: number
financeInformation:
description: |
Container for the finance information related to the taxation item in the credit memo item.
properties:
onAccountAccountingCode:
description: |
The accounting code that maps to an on account in your accounting system.
maxLength: 100
minLength: 0
type: string
salesTaxPayableAccountingCode:
description: |
The accounting code for the sales taxes payable.
maxLength: 100
minLength: 0
type: string
type: object
id:
description: |
The ID of the taxation item in the credit memo item.
type: string
jurisdiction:
description: |
The jurisdiction that applies the tax or VAT. This value is typically a state, province, county, or city.
type: string
locationCode:
description: |
The identifier for the location based on the value of the `taxCode` field.
type: string
taxCode:
description: |
The tax code identifies which tax rules and tax rates to apply to a specific credit memo.
type: string
taxCodeDescription:
description: |
The description of the tax code.
type: string
taxDate:
description: |
The date that the tax is applied to the credit memo, in `yyyy-mm-dd` format.
format: date
type: string
taxExemptAmount:
description: |
The calculated tax amount excluded due to the exemption.
format: double
type: number
taxName:
description: |
The name of taxation.
type: string
taxRate:
description: |
The tax rate applied to the credit memo.
format: double
type: number
taxRateDescription:
description: |
The description of the tax rate.
type: string
taxRateType:
description: |
The type of the tax rate applied to the credit memo.
enum:
- Percentage
- FlatFee
type: string
required:
- id
type: object
- $ref: '#/components/schemas/CreditTaxationItemObjectCustomFields'
title: taxItems
CreditTaxationItemObjectCustomFields:
additionalProperties:
description: |
Custom fields of the Credit Taxation Item object. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
description: |
Container for custom fields of a Credit Taxation Item object.
title: creditTaxationItemFieldsCustom
type: object
GetCreditMemoPdfStatusBatchResponse:
description: ''
example:
creditMemoFiles:
- creditMemoId: 402824aa8cc894d5018cc8a120576881
creditMemoNumber: CM00000003
pdfGenerationStatus: Generated
createdOn: '2024-01-01 11:35:56'
updatedOn: '2024-01-01 11:35:56'
pdfFileUrl: /v1/files/2c98901f62d7d83d0162d7facea6262d
- creditMemoId: 2c98908a904dfc2601904e6e14090241
creditMemoNumber: CM00000004
pdfGenerationStatus: Error
createdOn: '2024-01-02 10:14:13'
updatedOn: '2024-01-02 10:14:13'
errorCode: INVALID_TEMPLATE
errorMessage: Unknown merge filed chargeNumber__c
- creditMemoId: 402824aa8cc894d5018cc8a120576881
creditMemoNumber: CM00000005
pdfGenerationStatus: Pending
createdOn: '2024-01-01 11:35:56'
updatedOn: '2024-01-01 11:35:56'
success: true
properties:
creditMemoFiles:
description: |
Array of credit memo PDF statuses requested.
items:
$ref: '#/components/schemas/GetCreditMemoPdfStatusResponse'
type: array
success:
description: |
Indicates whether the call succeeded.
type: boolean
type: object
title: creditMemoFiles
GetCreditMemoPdfStatusResponse:
allOf:
- properties:
creditMemoId:
description: |
The ID of the credit memo whose pdf status is requested.
type: string
creditMemoNumber:
description: |
The credit memo number of the credit memo whose pdf status is requested.
type: string
pdfGenerationStatus:
description: |
The generation status of the credit memo PDF.
type: string
enum:
- None
- Pending
- Processing
- Generated
- Error
- Obsolete
createdOn:
description: |
The time at which the request to generate the PDF was created.
type: string
updatedOn:
description: |
The time at which the request to generate the PDF was updated.
type: string
pdfFileURL:
description: |
The file path or the URL of the PDF when the status is `Generated`.
type: string
errorCategory:
description: |
The error category when the status is `Error`.
type: string
errorMessage:
description: |
The error message when the status is `Error`.
type: string
type: object
GETTaxationItemsOfCreditMemoItemType:
allOf:
- properties:
data:
description: |
Container for the taxation items of the credit memo item.
items:
$ref: '#/components/schemas/GETCMTaxItemTypeNew'
type: array
nextPage:
description: |
URL to retrieve the next page of the response if it exists; otherwise absent.
format: URL
type: string
success:
description: Returns `true` if the request was processed successfully.
type: boolean
type: object
GETCMTaxItemTypeNew:
allOf:
- properties:
appliedAmount:
description: |
The applied amount of the taxation item.
format: double
type: number
exemptAmount:
description: |
The calculated tax amount excluded due to the exemption.
format: double
type: number
financeInformation:
description: |
Container for the finance information related to the taxation item.
properties:
onAccountAccountingCode:
description: |
The accounting code that maps to an on account in your accounting system.
type: string
nullable: true
onAccountAccountingCodeType:
description: |
The type of the accounting code that maps to an on account in your accounting system.
type: string
nullable: true
salesTaxPayableAccountingCode:
description: |
The accounting code for the sales taxes payable.
type: string
nullable: true
salesTaxPayableAccountingCodeType:
description: |
The type of the accounting code for the sales taxes payable.
type: string
nullable: true
type: object
id:
description: |
The ID of the taxation item.
type: string
jurisdiction:
description: |
The jurisdiction that applies the tax or VAT. This value is typically a state, province, county, or city.
type: string
locationCode:
description: |
The identifier for the location based on the value of the `taxCode` field.
type: string
name:
description: |
The name of the taxation item.
type: string
refundAmount:
description: |
The amount of the refund on the taxation item.
format: double
type: number
sourceTaxItemId:
description: |
The ID of the source taxation item.
type: string
nullable: true
taxAmount:
description: |
The amount of taxation.
format: double
type: number
taxCode:
description: |
The tax code identifies which tax rules and tax rates to apply to a specific credit memo.
type: string
taxCodeDescription:
description: |
The description of the tax code.
type: string
taxDate:
description: |
The date that the tax is applied to the credit memo, in `yyyy-mm-dd` format.
format: date
type: string
taxRate:
description: |
The tax rate applied to the credit memo.
format: double
type: number
taxRateDescription:
description: |
The description of the tax rate.
type: string
taxRateType:
description: |
The type of the tax rate.
enum:
- Percentage
- FlatFee
type: string
unappliedAmount:
description: |
The unapplied amount of the taxation item.
format: double
type: number
type: object
- $ref: '#/components/schemas/CreditTaxationItemObjectCustomFields'
title: data
PUTCreditMemoWriteOff:
allOf:
- properties:
comment:
description: |
Comments about the debit memo.
type: string
memoDate:
description: |
The creation date of the debit memo and the effective date of the credit memo. Credit memos are applied to the corresponding debit memos on `memoDate`. By default, `memoDate` is set to the current date.
format: date
type: string
reasonCode:
description: |
A code identifying the reason for the transaction. The value must be an existing reason code or empty. The default value is `Write-off`.
type: string
type: object
- $ref: '#/components/schemas/DebitMemoObjectCustomFieldsCMWriteOff'
example:
memoDate: '2022-05-05'
PUTCreditMemoWriteOffResponseType:
properties:
debitMemo:
description: |
Container for the credit memo that is automatically created.
properties:
id:
description: |
The unique ID of the created debit memo.
type: string
type: object
success:
description: |
Returns `true` if the request was processed successfully.
type: boolean
type: object
DebitMemoObjectCustomFieldsCMWriteOff:
additionalProperties:
description: |
Custom fields of the Debit Memo object. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
description: |
Container for custom fields of a Debit Memo object.
title: debitMemoFieldsCustom
type: object
ApplyCreditMemoType:
example:
effectiveDate: '2024-08-19'
invoices:
- invoiceId: 8ad097b490a1ec740190a5aaece25734
amount: 11
properties:
debitMemos:
description: |
Container for debit memos that the credit memo is applied to. The maximum number of debit memos is 1,000.
items:
$ref: '#/components/schemas/CreditMemoApplyDebitMemoRequestType'
type: array
effectiveDate:
description: |
The date when the credit memo is applied.
format: date
type: string
invoices:
description: |
Container for invoices that the credit memo is applied to. The maximum number of invoices is 1,000.
items:
$ref: '#/components/schemas/CreditMemoApplyInvoiceRequestType'
type: array
type: object
CreditMemoApplyDebitMemoRequestType:
properties:
amount:
description: |
The credit memo amount to be applied to the debit memo.
format: double
type: number
debitMemoId:
description: |
The unique ID of the debit memo that the credit memo is applied to.
type: string
items:
description: |
Container for items. The maximum number of items is 1,000.
If `creditMemoItemId` is the source, then it should be accompanied by a target `debitMemoItemId`.
If `creditTaxItemId` is the source, then it should be accompanied by a target `taxItemId`.
items:
$ref: '#/components/schemas/CreditMemoApplyDebitMemoItemRequestType'
type: array
required:
- amount
- debitMemoId
title: debitMemos
type: object
CreditMemoApplyInvoiceRequestType:
properties:
amount:
description: |
The credit memo amount to be applied to the invoice.
format: double
type: number
invoiceId:
description: |
The unique ID of the invoice that the credit memo is applied to.
type: string
items:
description: |
Container for items. The maximum number of items is 1,000.
If `creditMemoItemId` is the source, then it should be accompanied by a target `invoiceItemId`.
If `creditTaxItemId` is the source, then it should be accompanied by a target `taxItemId`.
items:
$ref: '#/components/schemas/CreditMemoApplyInvoiceItemRequestType'
type: array
required:
- amount
- invoiceId
title: invoices
type: object
CreditMemoApplyInvoiceItemRequestType:
properties:
amount:
description: |
The amount that is applied to the specific item.
format: double
type: number
creditMemoItemId:
description: |
The ID of the credit memo item.
type: string
creditTaxItemId:
description: |
The ID of the credit memo taxation item.
type: string
invoiceItemId:
description: |
The ID of the invoice item that the credit memo item is applied to.
type: string
taxItemId:
description: |
The ID of the invoice taxation item that the credit memo taxation item is applied to.
type: string
required:
- amount
title: items
type: object
CreditMemoApplyDebitMemoItemRequestType:
properties:
amount:
description: |
The amount that is applied to the specific item.
format: double
type: number
creditMemoItemId:
description: |
The ID of the credit memo item.
type: string
creditTaxItemId:
description: |
The ID of the credit memo taxation item.
type: string
debitMemoItemId:
description: |
The ID of the debit memo item that the credit memo item is applied to.
type: string
taxItemId:
description: |
The ID of the debit memo taxation item that the credit memo taxation item is applied to.
type: string
required:
- amount
title: items
type: object
PostCreditMemoEmailRequestType:
example:
useEmailTemplateSetting: true
properties:
emailAddresses:
description: |
The valid email addresses you want to email a credit memo to. Use commas to separate email addresses.
**Note:** This field is only applicable if you set the `useEmailTemplateSetting` field to `false`.
type: string
includeAdditionalEmailAddresses:
default: false
description: |
Indicates whether to send a credit memo to the additional email addresses of the memo account.
You can set the additional email addresses in the **Additional Email Addresses** field on the account detail page from the Zuora UI. See [Create a Customer Account](https://knowledgecenter.zuora.com/BC_Subscription_Management/Customer_Accounts/B_Create_a_Customer_Account#section_2) for more information.
enum:
- true
- false
type: boolean
pdfFileId:
description: |
The ID of the PDF file that you want to send in the email.
If you do not specify any PDF file ID, the latest PDF file generated for the credit memo is sent in the email.
type: string
useEmailTemplateSetting:
default: false
description: |
Indicates whether to email a credit memo based on the email template setting.
If you set this field to `true`, the credit memo is sent to the email addresses specified in the **To Email** field of the email template. The email template is the one you set in the **Delivery Options** panel of the **Edit notification** dialog from the Zuora UI. See [Edit Email Templates](https://knowledgecenter.zuora.com/CF_Users_and_Administrators/Notifications/Create_Email_Templates) for more information about how to edit the **To Email** field in the email template.
enum:
- true
- false
type: boolean
type: object
GETCreditMemoFilesResponse:
properties:
creditMemoFiles:
description: |
Container for credit memo PDF files.
items:
$ref: '#/components/schemas/CreditMemoFile'
type: array
nextPage:
description: |
URL to retrieve the next page of the response if it exists; otherwise absent.
format: URL
type: string
success:
description: Returns `true` if the request was processed successfully.
type: boolean
type: object
CreditMemoFile:
properties:
id:
description: |
The ID of the credit memo PDF file. This is the ID for the file object and different from the file handle ID in the `pdfFileUrl` field. To open a file, you have to use the file handle ID.
type: string
pdfFileUrl:
description: |
The relative URL of the credit memo PDF file.
You can obtain the absolute URL for downloading the file by adding a prefix in the following format: `{environment_base_url}/apps`
For example, `https://apisandbox.zuora.com/apps/v1/files/8a90a24f8e128020018e12cf610903f8`.
type: string
versionNumber:
description: |
The version number of the credit memo PDF file.
format: int64
type: integer
title: creditMemoFile
type: object
GETCreditMemoItemsListType:
properties:
items:
description: |
Container for credit memo items.
items:
$ref: '#/components/schemas/GETCreditMemoItemTypewithSuccess'
type: array
nextPage:
description: |
URL to retrieve the next page of the response if it exists; otherwise absent.
format: URL
type: string
success:
description: Returns `true` if the request was processed successfully.
type: boolean
type: object
GETCreditMemoItemTypewithSuccess:
allOf:
- properties:
amount:
description: |
The amount of the credit memo item. For tax-inclusive credit memo items, the amount indicates the credit memo item amount including tax. For tax-exclusive credit memo items, the amount indicates the credit memo item amount excluding tax.
format: double
type: number
amountWithoutTax:
description: |
The credit memo item amount excluding tax.
format: double
type: number
appliedAmount:
description: |
The applied amount of the credit memo item.
format: double
type: number
appliedToItemId:
description: |
The unique ID of the credit memo item that the discount charge is applied to.
type: string
commitmentId:
description: |
The ID of the commitment.
type: string
commitmentPeriodId:
description: |
The ID of the commitment period.
type: string
createdById:
description: |
The ID of the Zuora user who created the credit memo item.
type: string
createdDate:
description: |
The date and time when the credit memo item was created, in `yyyy-mm-dd hh:mm:ss` format. For example, 2017-03-01 15:31:10.
format: date-time
type: string
creditFromItemId:
description: |
The ID of the credit from item.
type: string
creditFromItemSource:
description: |
The type of the credit from item.
enum:
- InvoiceItem
- CreditMemoItem
type: string
description:
description: |
The description of the credit memo item.
**Note**: This field is available only if you are on the latest Zuora API version, or you set the `Zuora-Version` request header to `257.0` or [a later available version](https://developer.zuora.com/v1-api-reference/api-versions/#minor-version).
type: string
excludeItemBillingFromRevenueAccounting:
description: |
The flag to exclude the credit memo item from revenue accounting.
**Note**: This field is only available if you have the Order to Revenue or Billing - Revenue Integration feature enabled.
type: boolean
financeInformation:
description: |
Container for the finance information related to the credit memo item.
properties:
deferredRevenueAccountingCode:
description: |
The accounting code for the deferred revenue, such as Monthly Recurring Liability.
type: string
deferredRevenueAccountingCodeType:
description: |
The type of the deferred revenue accounting code, such as Deferred Revenue.
type: string
nonRevenueWriteOffAccountingCode:
description: |
Specify the accounting code for the non revenue write off. Available only if `revenueImpacting` = `no`.
type: string
nonRevenueWriteOffAccountingCodeType:
description: |
Specify the accounting code type for the non revenue write off.
type: string
onAccountAccountingCode:
description: |
The accounting code that maps to an on account in your accounting system.
type: string
onAccountAccountingCodeType:
description: |
The type of the accounting code that maps to an on account in your accounting system.
type: string
recognizedRevenueAccountingCode:
description: |
The accounting code for the recognized revenue, such as Monthly Recurring Charges or Overage Charges.
type: string
recognizedRevenueAccountingCodeType:
description: |
The type of the recognized revenue accounting code, such as Sales Revenue or Sales Discount.
type: string
revenueRecognitionRuleName:
description: |
The name of the revenue recognition rule governing the revenue schedule.
type: string
revenueScheduleNumber:
description: |
Revenue schedule number. The revenue schedule number is always prefixed with "RS", for example, RS-00000001.
type: string
type: object
id:
description: |
The ID of the credit memo item.
type: string
invoiceScheduleId:
description: |
The ID of the invoice schedule associated with the credit memo item.
**Note**: This field is available only if you have the Billing Schedule feature enabled.
type: string
invoiceScheduleItemId:
description: |
The ID of the invoice schedule item associated with the credit memo item. The credit memo item is generated during the processing of the invoice schedule item.
**Note**: This field is available only if you have the Billing Schedule feature enabled.
type: string
numberOfDeliveries:
description: |
The number of deliveries dedicated to the Delivery Pricing charges. The value might be different, as follows:
- For the credit memo generated by a bill run, this field has a value.
- For the credit memo generated from an invoice, this field is blank.
**Note**: This field is available only if you have the Delivery Pricing feature enabled.
type: number
processingType:
description: |
The kind of the charge for the credit memo item. Its possible values are `Charge` and `Discount`.
type: string
quantity:
description: |
The number of units for the credit memo item.
format: double
type: number
reflectDiscountInNetAmount:
type: boolean
default: false
description: |
When you apply percentage discounts to either of the following charges, you need to set the `reflectDiscountInNetAmount` field on your discount charge to `true`, to enable calculating and displaying the net amount of the following charges in Zuora Revenue.
* delivery pricing charge
* prepayment charge
* drawdown charge
Note the following:
* If you are an Order to Revenue customer, when you set the `reflectDiscountInNetAmount` field to `true`, you must also set the `excludeItemBillingFromRevenueAccounting` field to `true`.
* If you are a Billing - Revenue Integration customer, you must set the `reflectDiscountInNetAmount` field to `false`, otherwise an error will be returned. Billing - Revenue Integration does not support discounts on the preceding charges.
* If you are a Zuora Billing customer who does not enable the Order to Revenue or Billing - Revenue Integration feature, when you apply percentage discounts to the preceding charges, you also need to set the `reflectDiscountInNetAmount` field to `true`.
refundAmount:
description: |
The amount of the refund on the credit memo item.
format: double
type: number
revenueImpacting:
description: |
Indicates whether this write off operation impacts the revenue. If `revenueImpacting` = `Yes`, the deferred revenue accounting code will be automatically selected from the associated invoice
If `revenueImpacting` = `No`, users can select an accounting code such as bad-debt expense accounting code for the write off operation.
enum:
- 'Yes'
- 'No'
default: 'Yes'
type: string
serviceEndDate:
description: |
The service end date of the credit memo item.
format: date
type: string
serviceStartDate:
description: |
The service start date of the credit memo item.
format: date
type: string
sku:
description: |
The SKU for the product associated with the credit memo item.
type: string
skuName:
description: |
The name of the SKU.
type: string
shipToContactId:
description: |
The ID of the ship-to contact associated with the credit memo item.
**Note**: If you have the Flexible Billing Attributes feature disabled, the value of this field is `null`.
type: string
soldToContactId:
description: |
The ID of the sold-to contact associated with the credit memo item.
**Note**: If you have the Flexible Billing Attributes feature disabled, the value of this field is `null`.
type: string
soldToContactSnapshotId:
description: |
The ID of the sold-to contact snapshot associated with the credit memo item.
**Note**: If you have the Flexible Billing Attributes feature disabled, the value of this field is `null`.
type: string
sourceItemId:
description: |
The ID of the source item.
- If the value of the `sourceItemType` field is `SubscriptionComponent` , the value of this field is the ID of the corresponding rate plan charge.
- If the value of the `sourceItemType` field is `InvoiceDetail`, the value of this field is the ID of the corresponding invoice item.
- If the value of the `sourceItemType` field is `ProductRatePlanCharge` , the value of this field is the ID of the corresponding product rate plan charge.
- If the value of the `sourceItemType` field is `OrderLineItem` , the value of this field is the ID of the corresponding return order line item.
type: string
sourceItemType:
description: |
The type of the source item.
- If a credit memo is not created from an invoice or a product rate plan charge or a return order line item, the value of this field is `SubscriptionComponent`.
- If a credit memo is created from an invoice, the value of this field is `InvoiceDetail`.
- If a credit memo is created from a product rate plan charge, the value of this field is `ProductRatePlanCharge`.
- If a credit memo is created from a return order line item, the value of this field is `OrderLineItem`.
enum:
- SubscriptionComponent
- InvoiceDetail
- ProductRatePlanCharge
- OrderLineItem
type: string
subscriptionId:
description: |
The ID of the subscription associated with the credit memo item.
type: string
taxMode:
description: |
The tax mode of the credit memo item, indicating whether the amount of the credit memo item includes tax.
enum:
- TaxExclusive
- TaxInclusive
type: string
taxationItems:
description: |
Container for the taxation items of the credit memo item.
**Note**: This field is available only if you are on the latest Zuora API version, or you set the `Zuora-Version` request header to `239.0` or [a later available version](https://developer.zuora.com/v1-api-reference/api-versions/#minor-version).
properties:
data:
description: |
List of taxation items.
items:
$ref: '#/components/schemas/GETCMTaxItemTypeNew'
type: array
nextPage:
description: |
URL to retrieve the next page of the response if it exists; otherwise absent.
format: URL
type: string
type: object
unappliedAmount:
description: |
The unapplied amount of the credit memo item.
format: double
type: number
unitOfMeasure:
description: |
The units to measure usage.
type: string
unitPrice:
description: |
The per-unit price of the credit memo item.
format: double
type: number
updatedById:
description: |
The ID of the Zuora user who last updated the credit memo item.
type: string
updatedDate:
description: |
The date and time when the credit memo item was last updated, in `yyyy-mm-dd hh:mm:ss` format. For example, 2017-03-02 15:36:10.
format: date-time
type: string
type: object
- $ref: '#/components/schemas/CreditMemoItemObjectCustomFields'
title: items
GETCreditMemoItemType:
allOf:
- properties:
amount:
description: |
The amount of the credit memo item. For tax-inclusive credit memo items, the amount indicates the credit memo item amount including tax. For tax-exclusive credit memo items, the amount indicates the credit memo item amount excluding tax.
format: double
type: number
amountWithoutTax:
description: |
The credit memo item amount excluding tax.
format: double
type: number
appliedAmount:
description: |
The applied amount of the credit memo item.
format: double
type: number
appliedToItemId:
description: |
The unique ID of the credit memo item that the discount charge is applied to.
type: string
nullable: true
commitmentId:
description: |
The ID of the commitment.
type: string
commitmentPeriodId:
description: |
The ID of the commitment period.
type: string
createdById:
description: |
The ID of the Zuora user who created the credit memo item.
type: string
createdDate:
description: |
The date and time when the credit memo item was created, in `yyyy-mm-dd hh:mm:ss` format. For example, 2017-03-01 15:31:10.
format: date-time
type: string
creditFromItemId:
description: |
The ID of the credit from item.
type: string
creditFromItemSource:
description: |
The type of the credit from item.
enum:
- InvoiceItem
- CreditMemoItem
type: string
description:
description: |
The description of the credit memo item.
**Note**: This field is available only if you are on the latest Zuora API version, or you set the `Zuora-Version` request header to `257.0` or [a later available version](https://developer.zuora.com/v1-api-reference/api-versions/#minor-version).
type: string
excludeItemBillingFromRevenueAccounting:
description: |
The flag to exclude the credit memo item from revenue accounting.
**Note**: This field is only available if you have the Order to Revenue or Billing - Revenue Integration feature enabled.
type: boolean
financeInformation:
description: |
Container for the finance information related to the credit memo item.
properties:
deferredRevenueAccountingCode:
description: |
The accounting code for the deferred revenue, such as Monthly Recurring Liability.
type: string
nullable: true
deferredRevenueAccountingCodeType:
description: |
The type of the deferred revenue accounting code, such as Deferred Revenue.'
type: string
nullable: true
nonRevenueWriteOffAccountingCode:
description: |
Specify the accounting code for the non revenue write off. Available only if `revenueImpacting` = `no`.
type: string
nullable: true
nonRevenueWriteOffAccountingCodeType:
description: |
Specify the accounting code type for the non revenue write off.
type: string
nullable: true
onAccountAccountingCode:
description: |
The accounting code that maps to an on account in your accounting system.
type: string
nullable: true
onAccountAccountingCodeType:
description: |
The type of the accounting code that maps to an on account in your accounting system.
type: string
nullable: true
recognizedRevenueAccountingCode:
description: |
The accounting code for the recognized revenue, such as Monthly Recurring Charges or Overage Charges.
type: string
nullable: true
recognizedRevenueAccountingCodeType:
description: |
The type of the recognized revenue accounting code, such as Sales Revenue or Sales Discount.
type: string
nullable: true
revenueRecognitionRuleName:
description: |
The name of the revenue recognition rule governing the revenue schedule.
type: string
revenueScheduleNumber:
description: |
Revenue schedule number. The revenue schedule number is always prefixed with "RS", for example, RS-00000001.
type: string
type: object
id:
description: |
The ID of the credit memo item.
type: string
invoiceScheduleId:
description: |
The ID of the invoice schedule associated with the credit memo item.
**Note**: This field is available only if you have the Billing Schedule feature enabled.
type: string
invoiceScheduleItemId:
description: |
The ID of the invoice schedule item associated with the credit memo item. The credit memo item is generated during the processing of the invoice schedule item.
**Note**: This field is available only if you have the Billing Schedule feature enabled.
type: string
numberOfDeliveries:
description: |
The number of deliveries dedicated to the Delivery Pricing charges. The value might be different, as follows:
- For the credit memo generated by a bill run, this field has a value.
- For the credit memo generated from an invoice, this field is blank.
**Note**: This field is available only if you have the Delivery Pricing feature enabled.
type: number
organizationLabel:
description: |
The organization that this object belongs to.
Note: This field is available only when the Multi-Org feature is enabled.
type: string
processingType:
description: |
The kind of the charge for the credit memo item. Its possible values are `Charge` and `Discount`.
type: string
quantity:
description: |
The number of units for the credit memo item.
format: double
type: number
refundAmount:
description: |
The amount of the refund on the credit memo item.
format: double
type: number
reflectDiscountInNetAmount:
type: boolean
default: false
description: |
When you apply percentage discounts to either of the following charges, you need to set the `reflectDiscountInNetAmount` field on your discount charge to `true`, to enable calculating and displaying the net amount of the following charges in Zuora Revenue.
* delivery pricing charge
* prepayment charge
* drawdown charge
Note the following:
* If you are an Order to Revenue customer, when you set the `reflectDiscountInNetAmount` field to `true`, you must also set the `excludeItemBillingFromRevenueAccounting` field to `true`.
* If you are a Billing - Revenue Integration customer, you must set the `reflectDiscountInNetAmount` field to `false`, otherwise an error will be returned. Billing - Revenue Integration does not support discounts on the preceding charges.
* If you are a Zuora Billing customer who does not enable the Order to Revenue or Billing - Revenue Integration feature, when you apply percentage discounts to the preceding charges, you also need to set the `reflectDiscountInNetAmount` field to `true`.
revenueImpacting:
description: |
Indicates whether this write off operation impacts the revenue. If `revenueImpacting` = `Yes`, the deferred revenue accounting code will be automatically selected from the associated invoice
If `revenueImpacting` = `No`, users can select an accounting code such as bad-debt expense accounting code for the write off operation.
enum:
- 'Yes'
- 'No'
default: 'Yes'
type: string
serviceEndDate:
description: |
The service end date of the credit memo item.
format: date
type: string
serviceStartDate:
description: |
The service start date of the credit memo item. If the associated charge is a one-time fee, this date is the date of that charge.
format: date
type: string
sku:
description: |
The SKU for the product associated with the credit memo item.
type: string
skuName:
description: |
The name of the SKU.
type: string
shipToContactId:
description: |
The ID of the ship-to contact associated with the credit memo item.
**Note**: If you have the Flexible Billing Attributes feature disabled, the value of this field is `null`.
type: string
soldToContactId:
description: |
The ID of the sold-to contact associated with the credit memo item.
**Note**: If you have the Flexible Billing Attributes feature disabled, the value of this field is `null`.
type: string
soldToContactSnapshotId:
description: |
The ID of the sold-to contact snapshot associated with the credit memo item.
**Note**: If you have the Flexible Billing Attributes feature disabled, the value of this field is `null`.
type: string
sourceItemId:
description: |
The ID of the source item.
- If the value of the `sourceItemType` field is `SubscriptionComponent` , the value of this field is the ID of the corresponding rate plan charge.
- If the value of the `sourceItemType` field is `InvoiceDetail`, the value of this field is the ID of the corresponding invoice item.
- If the value of the `sourceItemType` field is `ProductRatePlanCharge` , the value of this field is the ID of the corresponding product rate plan charge.
- If the value of the `sourceItemType` field is `OrderLineItem` , the value of this field is the ID of the corresponding return order line item.
type: string
sourceItemType:
description: |
The type of the source item.
- If a credit memo is not created from an invoice or a product rate plan charge or a return order line item,, the value of this field is `SubscriptionComponent`.
- If a credit memo is created from an invoice, the value of this field is `InvoiceDetail`.
- If a credit memo is created from a product rate plan charge, the value of this field is `ProductRatePlanCharge`.
- If a credit memo is created from a return order line item, the value of this field is `OrderLineItem`.
enum:
- SubscriptionComponent
- InvoiceDetail
- ProductRatePlanCharge
- OrderLineItem
type: string
subscriptionId:
description: |
The ID of the subscription associated with the credit memo item.
type: string
success:
description: Returns `true` if the request was processed successfully.
type: boolean
taxMode:
description: |
The tax mode of the credit memo item, indicating whether the amount of the credit memo item includes tax.
enum:
- TaxExclusive
- TaxInclusive
type: string
taxationItems:
description: |
Container for the taxation items of the credit memo item.
**Note**: This field is available only if you are on the latest Zuora API version, or you set the `Zuora-Version` request header to `239.0` or [a later available version](https://developer.zuora.com/v1-api-reference/api-versions/#minor-version).
properties:
data:
description: |
List of taxation items.
items:
$ref: '#/components/schemas/GETCMTaxItemTypeNew'
type: array
nextPage:
description: |
URL to retrieve the next page of the response if it exists; otherwise absent.
format: URL
type: string
type: object
unappliedAmount:
description: |
The unapplied amount of the credit memo item.
format: double
type: number
unitOfMeasure:
description: |
The units to measure usage.
type: string
unitPrice:
description: |
The per-unit price of the credit memo item.
format: double
type: number
updatedById:
description: |
The ID of the Zuora user who last updated the credit memo item.
type: string
updatedDate:
description: |
The date and time when the credit memo item was last updated, in `yyyy-mm-dd hh:mm:ss` format. For example, 2017-03-02 15:36:10.
format: date-time
type: string
type: object
- $ref: '#/components/schemas/CreditMemoItemObjectCustomFields'
GETCreditMemoPartsCollectionType:
properties:
nextPage:
description: |
URL to retrieve the next page of the response if it exists; otherwise absent.
format: URL
type: string
parts:
description: |
Container for credit memo parts.
items:
$ref: '#/components/schemas/GETCreditMemoPartTypewithSuccess'
type: array
success:
description: Returns `true` if the request was processed successfully.
type: boolean
type: object
GETCreditMemoPartTypewithSuccess:
properties:
amount:
description: |
The amount of the credit memo part.
format: double
type: number
createdById:
description: |
The ID of the Zuora user who created the credit memo part.
type: string
createdDate:
description: |
The date and time when the credit memo part was created, in `yyyy-mm-dd hh:mm:ss` format. For example, 2017-03-01 15:31:10.
format: date-time
type: string
debitMemoId:
description: |
The ID of the debit memo associated with the credit memo part.
type: string
id:
description: |
The ID of the credit memo part.
type: string
invoiceId:
description: |
The ID of the invoice associated with the credit memo part.
type: string
updatedById:
description: |
The ID of the Zuora user who last updated the credit memo part.
type: string
updatedDate:
description: |
The date and time when the credit memo part was last upated, in `yyyy-mm-dd hh:mm:ss` format. For example, 2017-03-02 15:36:10.
format: date-time
type: string
title: parts
type: object
GETCreditMemoPartType:
properties:
amount:
description: |
The amount of the credit memo part.
format: double
type: number
createdById:
description: |
The ID of the Zuora user who created the credit memo part.
type: string
createdDate:
description: |
The date and time when the credit memo part was created, in `yyyy-mm-dd hh:mm:ss` format. For example, 2017-03-01 15:31:10.
format: date-time
type: string
debitMemoId:
description: |
The ID of the debit memo associated with the credit memo part.
type: string
id:
description: |
The ID of the credit memo part.
type: string
invoiceId:
description: |
The ID of the invoice associated with the credit memo part.
type: string
organizationLabel:
description: |
The organization that this object belongs to.
Note: This field is available only when the Multi-Org feature is enabled.
type: string
success:
description: Returns `true` if the request was processed successfully.
type: boolean
updatedById:
description: |
The ID of the Zuora user who last updated the credit memo part.
type: string
updatedDate:
description: |
The date and time when the credit memo part was last upated, in `yyyy-mm-dd hh:mm:ss` format. For example, 2017-03-02 15:36:10.
format: date-time
type: string
type: object
POSTMemoPdfResponse:
properties:
success:
description: |
Returns `true` if the request was processed successfully.
type: boolean
type: object
PostNonRefRefundType:
allOf:
- properties:
comment:
description: |
Comments about the refund.
maxLength: 255
minLength: 0
type: string
customRates:
description: |
It contains Home currency and Reporting currency custom rates currencies. The maximum number of items is 2 (you can pass the Home currency item, Reporting currency item, or both).
**Note**:
- This field is available only if you are on the latest Zuora API version, or you set the `Zuora-Version` request header to `224.0` or a later version.
- You cannot set the custom rates, if both the **Automatically include additional Currency Conversion information in data source exports** option and **Fx data** feature are enabled.
items:
$ref: '#/components/schemas/CreditMemoFromChargeCustomRatesType'
maxItems: 2
type: array
financeInformation:
description: |
Container for the finance information related to the refund.
properties:
bankAccountAccountingCode:
description: |
The accounting code that maps to a bank account in your accounting system.
maxLength: 100
minLength: 0
type: string
onAccountAccountingCode:
description: |
The accounting code that maps to an on account in your accounting system.
maxLength: 100
minLength: 0
type: string
transferredToAccounting:
description: |
Whether the refund was transferred to an external accounting system. Use this field for integration with accounting systems, such as NetSuite.
enum:
- Processing
- 'Yes'
- 'No'
- Error
- Ignore
type: string
unappliedPaymentAccountingCode:
description: |
The accounting code for the unapplied payment.
maxLength: 100
minLength: 0
type: string
type: object
gatewayId:
description: |
The ID of the gateway instance that processes the refund. This field can be specified only for electronic refunds. The ID must be a valid gateway instance ID, and this gateway must support the specific payment method.
If no gateway ID is specified, the default gateway in the billing account configuration will be used. If no gateway is specified in the billing account, the default gateway of the corresponding tenant will be used.
type: string
gatewayOptions:
description: |
The field used to pass gateway-specific parameters and parameter values.
properties:
key:
description: |
The name of a gateway-specific parameter.
type: string
value:
description: |
The value of the gateway-specific parameter.
type: string
type: object
items:
description: |
Container for credit memo items. The maximum number of items is 1,000.
**Note:** This field is only available if you have the [Invoice Item Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement/C_Invoice_Item_Settlement) feature enabled. Invoice Item Settlement must be used together with other Invoice Settlement features (Unapplied Payments, and Credit and Debit memos). If you wish 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.
items:
$ref: '#/components/schemas/RefundCreditMemoItemType'
type: array
methodType:
description: |
How an external refund was issued to a customer. This field is required for an external refund and must be left empty for an electronic refund. You can issue an external refund on a credit memo.
enum:
- ACH
- Cash
- Check
- CreditCard
- PayPal
- WireTransfer
- DebitCard
- CreditCardReferenceTransaction
- BankTransfer
- Other
type: string
paymentMethodId:
description: |
The ID of the payment method used for the refund. This field is required for an electronic refund, and the value must be an electronic payment method ID. This field must be left empty for an external refund.
type: string
reasonCode:
description: |
A code identifying the reason for the transaction. The value must be an existing reason code or empty. If you do not specify a value, Zuora uses the default reason code.
type: string
referenceId:
description: |
The transaction ID returned by the payment gateway for an electronic refund. Use this field to reconcile refunds between your gateway and Zuora Payments.
maxLength: 100
minLength: 0
type: string
refundDate:
description: |
The date when the refund takes effect, in `yyyy-mm-dd` format. The date of the refund cannot be before the credit memo date. Specify this field only for external refunds. Zuora automatically generates this field for electronic refunds.
format: date
type: string
secondRefundReferenceId:
description: |
The transaction ID returned by the payment gateway if there is an additional transaction for the refund. Use this field to reconcile payments between your gateway and Zuora Payments.
maxLength: 100
minLength: 0
type: string
softDescriptor:
description: A payment gateway-specific field that maps to Zuora for the gateways, Orbital, Vantiv and Verifi.
maxLength: 35
type: string
softDescriptorPhone:
description: A payment gateway-specific field that maps to Zuora for the gateways, Orbital, Vantiv and Verifi.
maxLength: 20
type: string
totalAmount:
description: |
The total amount of the refund. The amount cannot exceed the unapplied amount of the associated credit memo. If the original credit memo was applied to one or more invoices or debit memos, you have to unapply a full or partial credit memo from the invoices or debit memos, and then refund the full or partial unapplied credit memo to your customers.
format: double
type: number
type:
description: |
The type of the refund.
enum:
- External
- Electronic
type: string
required:
- totalAmount
- type
type: object
- $ref: '#/components/schemas/RefundObjectNSFields'
- $ref: '#/components/schemas/RefundObjectCustomFields'
example:
type: Electronic
totalAmount: 10
paymentMethodId: 8ad084db90a5e73b0190c02783f552fa
GETRefundCreditMemoType:
allOf:
- properties:
accountId:
description: |
The ID of the account associated with this refund. Zuora associates the refund automatically with the account from the associated payment.
type: string
amount:
description: |
The total amount of the refund.
format: double
type: number
cancelledOn:
description: |
The date and time when the refund was cancelled, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
nullable: true
comment:
description: |
Comments about the refund.
type: string
nullable: true
createdById:
description: |
The ID of the Zuora user who created the refund.
type: string
createdDate:
description: |
The date and time when the refund was created, in `yyyy-mm-dd hh:mm:ss` format. For example, 2017-03-06 15:31:10.
format: date-time
type: string
creditMemoId:
description: |
The ID of the credit memo that is refunded.
type: string
financeInformation:
description: |
Container for the finance information related to the refund.
properties:
bankAccountAccountingCode:
description: |
The accounting code that maps to a bank account in your accounting system.
type: string
nullable: true
bankAccountAccountingCodeType:
description: |
The type of the accounting code that maps to a bank account in your accounting system.
type: string
nullable: true
transferredToAccounting:
description: |
Whether the refund was transferred to an external accounting system. Use this field for integration with accounting systems, such as NetSuite.
enum:
- Processing
- 'Yes'
- 'No'
- Error
- Ignore
type: string
nullable: true
unappliedPaymentAccountingCode:
description: |
The accounting code for the unapplied payment.
type: string
nullable: true
unappliedPaymentAccountingCodeType:
description: |
The type of the accounting code for the unapplied payment.
type: string
nullable: true
type: object
gatewayId:
description: |
The ID of the gateway instance that processes the refund.
type: string
gatewayResponse:
description: |
The message returned from the payment gateway for the refund. This message is gateway-dependent.
type: string
gatewayResponseCode:
description: |
The response code returned from the payment gateway for the refund. This code is gateway-dependent.
type: string
gatewayState:
description: |
The status of the refund in the gateway.
enum:
- MarkedForSubmission
- Submitted
- Settled
- NotSubmitted
- FailedToSettle
type: string
id:
description: |
The ID of the created refund.
type: string
markedForSubmissionOn:
description: |
The date and time when a refund was marked and waiting for batch submission to the payment process, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
nullable: true
methodType:
description: |
How an external refund was issued to a customer.
enum:
- ACH
- Cash
- Check
- CreditCard
- PayPal
- WireTransfer
- DebitCard
- CreditCardReferenceTransaction
- BankTransfer
- Other
type: string
number:
description: |
The unique identification number of the refund.
type: string
organizationLabel:
description: |
The organization that this object belongs to.
Note: This field is available only when the Multi-Org feature is enabled.
type: string
paymentId:
description: |
The ID of the payment associated with the refund.
type: string
nullable: true
paymentMethodId:
description: |
The unique ID of the payment method that the customer used to make the refund.
type: string
paymentMethodSnapshotId:
description: |
The unique ID of the payment method snapshot, which is a copy of the particular payment method used in a transaction.
type: string
reasonCode:
description: |
A code identifying the reason for the transaction.
type: string
nullable: true
referenceId:
description: |
The transaction ID returned by the payment gateway for an electronic refund. Use this field to reconcile refunds between your gateway and Zuora Payments.
type: string
refundDate:
description: |
The date when the refund takes effect, in yyyy-mm-dd format.
format: date
type: string
refundTransactionTime:
description: |
The date and time when the refund was issued, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
secondRefundReferenceId:
description: |
The transaction ID returned by the payment gateway if there is an additional transaction for the refund. Use this field to reconcile payments between your gateway and Zuora Payments.
type: string
nullable: true
settledOn:
description: |
The date and time when the refund was settled in the payment processor, in `yyyy-mm-dd hh:mm:ss` format. This field is used by the Spectrum gateway only and not applicable to other gateways.
format: date-time
type: string
nullable: true
softDescriptor:
description: |
A payment gateway-specific field that maps to Zuora for the gateways, Orbital, Vantiv and Verifi.
type: string
nullable: true
softDescriptorPhone:
description: |
A payment gateway-specific field that maps to Zuora for the gateways, Orbital, Vantiv and Verifi.
type: string
nullable: true
status:
description: |
The status of the refund.
enum:
- Processed
- Canceled
- Error
- Processing
type: string
submittedOn:
description: |
The date and time when the refund was submitted, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
success:
description: Returns `true` if the request was processed successfully.
type: boolean
type:
description: |
The type of the refund.
enum:
- External
- Electronic
type: string
updatedById:
description: |
The ID of the Zuora user who last updated the refund.
type: string
updatedDate:
description: |
The date and time when the refund was last updated, in `yyyy-mm-dd hh:mm:ss` format. For example, 2017-03-07 15:36:10.
format: date-time
type: string
type: object
- $ref: '#/components/schemas/RefundObjectNSFields'
- $ref: '#/components/schemas/RefundObjectCustomFields'
RefundObjectNSFields:
description: |
Container for Refund fields provided by the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
properties:
IntegrationId__NS:
description: |
ID of the corresponding object in NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
maxLength: 255
type: string
IntegrationStatus__NS:
description: |
Status of the refund's synchronization with NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
maxLength: 255
type: string
Origin__NS:
description: |
Origin of the corresponding object in NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
maxLength: 255
type: string
SyncDate__NS:
description: |
Date when the refund was synchronized with NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
maxLength: 255
type: string
SynctoNetSuite__NS:
description: |
Specifies whether the refund should be synchronized with NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
maxLength: 255
type: string
title: refundFieldsNS
type: object
RefundObjectCustomFields:
additionalProperties:
description: |
Custom fields of the Refund object. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
description: |
Container for custom fields of a Refund object.
title: refundFieldsCustom
type: object
RefundCreditMemoItemType:
properties:
amount:
description: |
The amount of the refund on the specific item.
format: double
type: number
creditMemoItemId:
description: |
The ID of the credit memo item that is refunded.
type: string
creditTaxItemId:
description: |
The ID of the credit memo taxation item that is refunded.
type: string
required:
- amount
title: items
type: object
PutReverseCreditMemoType:
example:
applyEffectiveDate: '2017-02-20'
memoDate: '2017-02-20'
properties:
applyEffectiveDate:
description: |
The date when the to-be-reversed credit memo is applied to the newly generated debit memo, in `yyyy-mm-dd` format. The effective date must be later than or equal to the memo date.
The default value is the date when you reverse the credit memo and create the debit memo.
format: date
type: string
comment:
description: |
Comments about the reversal. The comment is used as the comment of the debit memo generated by reversing the specified credit memo.
maxLength: 255
minLength: 0
type: string
memoDate:
description: |
The date when the debit memo is created, in `yyyy-mm-dd` format. The memo date must be later than or equal to the credit memo's memo date.
The default value is the date when you reverse the credit memo and create the debit memo.
format: date
type: string
reasonCode:
description: |
A code identifying the reason for the reversal. The value must be an existing reason code or empty. The code is used as the reason code of the debit memo generated by reversing the specified credit memo.
If you do not specify a value, Zuora uses the default reason code `Credit memo reversal` for the debit memo.
type: string
type: object
PutReverseCreditMemoResponseType:
properties:
creditMemo:
description: |
Container for the credit memo that is automatically generated during the reversal of the invoice that is related to the credit memo. If no related invoice is reversed, the value is null.
properties:
id:
description: The ID of the credit memo.
type: string
type: object
debitMemo:
description: |
Container for the debit memo that is automatically generated during the credit memo reversal.
properties:
id:
description: The ID of the debit memo.
type: string
type: object
success:
description: |
Returns `true` if the request was processed successfully.
type: boolean
type: object
POSTTaxationItemListForCMType:
example:
taxationItems:
- name: STATE TAX
memoItemId: 8ad086fa932a0b5401932e82ab1f1fb3
jurisdiction: CALIFORNIA
taxAmount: 0.5
taxCode: ServiceTaxCode
taxDate: '2024-11-15'
taxRate: 0.05
taxRateType: Percentage
properties:
taxationItems:
description: |
Container for taxation items.
items:
$ref: '#/components/schemas/POSTTaxationItemForCMType'
type: array
type: object
POSTTaxationItemForCMType:
allOf:
- properties:
exemptAmount:
description: |
The calculated tax amount excluded due to the exemption.
format: double
type: number
financeInformation:
description: |
Container for the finance information related to the taxation item.
properties:
onAccountAccountingCode:
description: |
The accounting code that maps to an on account in your accounting system.
maxLength: 100
minLength: 0
type: string
salesTaxPayableAccountingCode:
description: |
The accounting code for the sales taxes payable.
maxLength: 100
minLength: 0
type: string
type: object
jurisdiction:
description: |
The jurisdiction that applies the tax or VAT. This value is typically a state, province, county, or city.
type: string
locationCode:
description: |
The identifier for the location based on the value of the `taxCode` field.
type: string
memoItemId:
description: |
The ID of the credit memo that the taxation item is created for.
type: string
name:
description: |
The name of the taxation item.
type: string
sourceTaxItemId:
description: |
The ID of the taxation item of the invoice, which the credit memo is created from.
If you want to use this REST API to create taxation items for a credit memo created from an invoice, the taxation items of the invoice must be created or imported through the SOAP API call.
**Note:**
- This field is only used if the credit memo is created from an invoice.
- If you do not contain this field in the request body, Zuora will automatically set a value for the `sourceTaxItemId` field based on the tax location code, tax jurisdiction, and tax rate.
type: string
taxAmount:
description: |
The amount of the tax applied to the credit memo.
format: double
type: number
taxCode:
description: |
The tax code identifies which tax rules and tax rates to apply to a specific credit memo.
type: string
taxCodeDescription:
description: |
The description of the tax code.
type: string
taxDate:
description: |
The date when the tax is applied to the credit memo.
format: date
type: string
taxRate:
description: |
The tax rate applied to the credit memo.
format: double
type: number
taxRateDescription:
description: |
The description of the tax rate.
type: string
taxRateType:
description: |
The type of the tax rate applied to the credit memo.
enum:
- Percentage
- FlatFee
type: string
required:
- taxRate
- jurisdiction
- name
- taxRateType
- taxAmount
type: object
- $ref: '#/components/schemas/TaxationItemObjectCustomFields'
title: taxationItems
UnapplyCreditMemoType:
example:
effectiveDate: '2024-10-30'
invoices:
- invoiceId: 8a90acec910816f601910bcf57a62363
amount: 1
properties:
debitMemos:
description: |
Container for debit memos that the credit memo is unapplied from. The maximum number of debit memos is 1,000.
items:
$ref: '#/components/schemas/CreditMemoUnapplyDebitMemoRequestType'
type: array
effectiveDate:
description: |
The date when the credit memo is unapplied.
format: date
type: string
invoices:
description: |
Container for invoices that the credit memo is unapplied from. The maximum number of invoices is 1,000.
items:
$ref: '#/components/schemas/CreditMemoUnapplyInvoiceRequestType'
type: array
type: object
CreditMemoUnapplyDebitMemoRequestType:
properties:
amount:
description: |
The credit memo amount to be unapplied from the debit memo.
format: double
type: number
debitMemoId:
description: |
The unique ID of the debit memo that the credit memo is unapplied from.
type: string
items:
description: |
Container for items. The maximum number of items is 1,000.
items:
$ref: '#/components/schemas/CreditMemoUnapplyDebitMemoItemRequestType'
type: array
required:
- amount
- debitMemoId
title: debitMemos
type: object
CreditMemoUnapplyInvoiceRequestType:
properties:
amount:
description: |
The credit memo amount to be unapplied from the invoice.
format: double
type: number
invoiceId:
description: |
The unique ID of the invoice that the credit memo is unapplied from.
type: string
items:
description: |
Container for items. The maximum number of items is 1,000.
items:
$ref: '#/components/schemas/CreditMemoUnapplyInvoiceItemRequestType'
type: array
required:
- amount
- invoiceId
title: invoices
type: object
CreditMemoUnapplyInvoiceItemRequestType:
properties:
amount:
description: |
The amount that is unapplied from the specific item.
format: double
type: number
creditMemoItemId:
description: |
The ID of the credit memo item.
type: string
creditTaxItemId:
description: |
The ID of the credit memo taxation item.
type: string
invoiceItemId:
description: |
The ID of the invoice item that the credit memo item is unapplied from.
type: string
taxItemId:
description: |
The ID of the invoice taxation item that the credit memo taxation item is unapplied from.
type: string
required:
- amount
title: items
type: object
CreditMemoUnapplyDebitMemoItemRequestType:
properties:
amount:
description: |
The amount that is unapplied from the specific item.
format: double
type: number
creditMemoItemId:
description: |
The ID of the credit memo item.
type: string
creditTaxItemId:
description: |
The ID of the credit memo taxation item.
type: string
debitMemoItemId:
description: |
The ID of the debit memo item that the credit memo item is unapplied from.
type: string
taxItemId:
description: |
The ID of the debit memo taxation item that the credit memo taxation item is unapplied from.
type: string
required:
- amount
title: items
type: object
InvoiceSettlementAsyncJobResponse:
allOf:
- $ref: '#/components/schemas/CommonResponse'
- properties:
id:
description: The ID of the operation job.
type: string
status:
$ref: '#/components/schemas/InvoiceSettlementAsyncJobStatus'
operationType:
$ref: '#/components/schemas/InvoiceSettlementAsyncJobOperationType'
referenceId:
description: The ID of the business object which is being operated.
type: string
referenceType:
$ref: '#/components/schemas/InvoiceSettlementAsyncJobReferenceType'
error:
description: The error message if the operation error out.
type: string
nullable: true
type: object
InvoiceSettlementAsyncJobStatus:
enum:
- Pending
- Processing
- Processed
- Error
type: string
description: |
Job status of the Invoice Settlement async job.
InvoiceSettlementAsyncJobOperationType:
enum:
- AsyncCreditMemoApply
- AsyncCreditMemoUnapply
type: string
description: |
Operation type of the Invoice Settlement async job.
InvoiceSettlementAsyncJobReferenceType:
enum:
- CreditMemo
type: string
description: |
Reference type of the Invoice Settlement async job.
AsyncApplyCreditMemoRequest:
example:
effectiveDate: '2017-03-02'
invoices:
- amount: 1
invoiceId: 4028905f5a87c0ff015a87d3f8f10043
properties:
effectiveDate:
description: |
The date when the credit memo is applied.
format: date
type: string
invoices:
description: |
Container for invoices that the credit memo is applied to. The maximum number of invoices is 1,000.
items:
$ref: '#/components/schemas/AsyncApplyCreditMemoToInvoice'
type: array
type: object
AsyncApplyCreditMemoToInvoice:
properties:
amount:
description: |
The credit memo amount to be applied to the invoice.
type: number
invoiceId:
description: |
The unique ID of the invoice that the credit memo is applied to.
type: string
required:
- amount
- invoiceId
title: AppliedInvoice
type: object
AsyncUnapplyCreditMemoRequest:
example:
effectiveDate: '2017-03-02'
invoices:
- amount: 1
invoiceId: 4028905f5a87c0ff015a87d3f8f10043
properties:
effectiveDate:
description: |
The date when the credit memo is unapplied.
format: date
type: string
invoices:
description: |
Container for invoices that the credit memo is unapplied. The maximum number of invoices is 1,000.
items:
$ref: '#/components/schemas/AsyncUnapplyCreditMemoToInvoice'
type: array
type: object
AsyncUnapplyCreditMemoToInvoice:
properties:
amount:
description: |
The credit memo amount to be unapplied from the invoice.
type: number
invoiceId:
description: |
The unique ID of the invoice that the credit memo is unapplied from.
type: string
required:
- amount
- invoiceId
title: UnappliedInvoice
GETDebitMemoCollectionType:
properties:
debitmemos:
description: |
Container for debit memos.
items:
$ref: '#/components/schemas/GETDebitMemoTypewithSuccess'
type: array
nextPage:
description: |
URL to retrieve the next page of the response if it exists; otherwise absent.
format: URL
type: string
success:
description: Returns `true` if the request was processed successfully.
type: boolean
type: object
GETDebitMemoTypewithSuccess:
allOf:
- properties:
accountId:
description: |
The ID of the customer account associated with the debit memo.
type: string
accountNumber:
description: |
The number of the customer account associated with the debit memo.
type: string
amount:
description: |
The total amount of the debit memo.
format: double
type: number
autoPay:
description: |
Whether debit memos are automatically picked up for processing in the corresponding payment run.
By default, debit memos are automatically picked up for processing in the corresponding payment run.
type: boolean
balance:
description: |
The balance of the debit memo.
format: double
type: number
beAppliedAmount:
description: |
The applied amount of the debit memo.
format: double
type: number
billToContactId:
description: |
The ID of the bill-to contact associated with the debit memo.
The value of this field is `null` if you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled.
type: string
cancelledById:
description: |
The ID of the Zuora user who cancelled the debit memo.
type: string
nullable: true
cancelledOn:
description: |
The date and time when the debit memo was cancelled, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
nullable: true
comment:
description: |
Comments about the debit memo.
type: string
nullable: true
createdById:
description: |
The ID of the Zuora user who created the debit memo.
type: string
createdDate:
description: |
The date and time when the debit memo was created, in `yyyy-mm-dd hh:mm:ss` format. For example, 2017-03-01 15:31:10.
format: date-time
type: string
currency:
type: string
description: |
The currency of the debit memo.
**Note:** By default, the currency on a billing document matches the default currency set on the associated account.
However, Zuora now offers a Multiple Currencies feature to support different currencies for billing documents, allowing flexibility beyond the account-level currency.
For more information, see Multiple Currency.
nullable: true
debitMemoDate:
description: |
The date when the debit memo takes effect, in `yyyy-mm-dd` format. For example, 2017-05-20.
format: date
type: string
dueDate:
description: |
The date by which the payment for the debit memo is due, in `yyyy-mm-dd` format.
format: date
type: string
einvoiceErrorCode:
description: |
The error code returned when the e-invoice file status is `Failed`. This code can either be a Zuora-generated error code or one returned by a third-party e-invoicing service provider.
**Note**: This field is available only if you have the E-Invoicing feature in **Early Adopter** phase enabled.
type: string
nullable: true
einvoiceErrorMessage:
description: |
The error message returned when the e-invoice file status is `Failed`. This message can either be a Zuora-generated error message or one returned by a third-party e-invoicing service provider.
**Note**: This field is available only if you have the E-Invoicing feature in **Early Adopter** phase enabled.
type: string
nullable: true
einvoiceFileId:
description: |
The ID of the e-invoice file generated for the debit memo.
**Note**: This field is available only if you have the E-Invoicing feature in **Early Adopter** phase enabled.
type: string
nullable: true
einvoiceStatus:
description: |
The status of the e-invoice file generation for the debit memo.
- If e-invoice file generation succeeds, this field is either `Generated` or `Success`, and both the error code and message are empty, and the `eInvoiceFileId` field stores the ID of the generated e-invoice file.
- If the responses from tax vendors such as Sovos or Avalara are
taking too long, this field becomes `RetrieveTimeOut`. Once the
vendor responds successfully, you can use the 'Resync E-Invoice Status'
action to update the status automatically. You can view these updates
in System Health telemetry.
- If a failure occurs during e-invoice file generation, this field is `Failed` and an error code and an error message are returned respectively in the `einvoiceErrorCode` and `einvoiceErrorMessage` fields.
- If e-invoice file generation conditionally succeeds, this field is `ConditionalSuccess` and an error code and an error message are returned respectively in the `einvoiceErrorCode` and `einvoiceErrorMessage` fields.
- If the e-invoice file has been approved by the tax authority, this field is `ApprovedByAuthority`. The next status will be either `Success` or `Rejected`.
- If the e-invoice file has been rejected by the government, this field is `Rejected`. You cannot resend this e-invoice; you must create a new invoice instead.
**Note**: This field is available only if you have the E-Invoicing feature in **Early Adopter** phase
enabled.
enum:
- Processing
- RetrieveTimeOut
- Generated
- Success
- Failed
- ConditionalSuccess
- ApprovedByAuthority
- Rejected
type: string
nullable: true
id:
description: |
The unique ID of the debit memo.
type: string
invoiceGroupNumber:
description: |
The number of the invoice group associated with the debit memo.
The value of this field is `null` if you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled.
type: string
nullable: true
latestPDFFileId:
description: |
The ID of the latest PDF file generated for the debit memo.
type: string
number:
description: |
The unique identification number of the debit memo.
type: string
paymentTerm:
description: |
The name of the payment term associated with the debit memo.
The value of this field is `null` if you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled.
type: string
nullable: true
postedById:
description: |
The ID of the Zuora user who posted the debit memo.
type: string
nullable: true
postedOn:
description: |
The date and time when the debit memo was posted, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
nullable: true
reasonCode:
description: |
A code identifying the reason for the transaction. The value must be an existing reason code or empty.
type: string
referredCreditMemoId:
description: |
The ID of the credit memo from which the debit memo was created.
type: string
nullable: true
referredInvoiceId:
description: |
The ID of a referred invoice.
type: string
nullable: true
sequenceSetId:
description: |
The ID of the sequence set associated with the debit memo.
The value of this field is `null` if you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled.
type: string
nullable: true
communicationProfileId:
description: |
The ID of the communication profile associated with the debit memo.
**Note**: This field is available in the request body only if you have the Flexible Billing Attributes
feature turned on. The value is `null` in the response body without this feature turned on.
type: string
nullable: true
sourceType:
description: |
The type of the debit memo source.
enum:
- Subscription
- Standalone
- Order
- Consolidation
- Invoice
- CreditMemo
type: string
status:
description: |
The status of the debit memo.
enum:
- Draft
- Posted
- Canceled
- Error
- PendingForTax
- Generating
- CancelInProgress
type: string
targetDate:
description: |
The target date for the debit memo, in `yyyy-mm-dd` format. For example, 2017-07-20.
format: date
type: string
nullable: true
taxAmount:
description: |
The amount of taxation.
format: double
type: number
taxMessage:
description: |
The message about the status of tax calculation related to the debit memo. If tax calculation fails in one debit memo, this field displays the reason for the failure.
type: string
nullable: true
taxStatus:
description: |
The status of tax calculation related to the debit memo.
**Note**: This field is only applicable to tax calculation by third-party tax engines. Also, the `Voided` status indicates that the tax transaction is successfully canceled on the tax vendor's side. If a tax transaction was successfully committed to the third-party tax engine but the invoice failed to post, Zuora automatically detects the issue and voids the tax transaction on the vendor's side.
enum:
- Complete
- Error
- UnknownError
- DuplicateDoc
- InvalidRequest
- InvalidResponse
- TaxEngineError
- ConcurrentModify
- InternalServerError
- TaxCodeTemplateError
- Voided
type: string
nullable: true
totalTaxExemptAmount:
description: |
The calculated tax amount excluded due to the exemption.
format: double
type: number
transferredToAccounting:
description: |
Whether the debit memo was transferred to an external accounting system. Use this field for integration with accounting systems, such as NetSuite.
enum:
- Processing
- 'Yes'
- 'No'
- Error
- Ignore
type: string
updatedById:
description: |
The ID of the Zuora user who last updated the debit memo.
type: string
updatedDate:
description: |
The date and time when the debit memo was last updated, in `yyyy-mm-dd hh:mm:ss` format. For example, 2017-03-02 15:31:10.
format: date-time
type: string
type: object
- $ref: '#/components/schemas/DebitMemoObjectNSFields'
- $ref: '#/components/schemas/DebitMemoObjectCustomFields'
title: debitmemos
DebitMemoObjectNSFields:
description: |
Container for Debit Memo fields provided by the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
properties:
IntegrationId__NS:
description: |
ID of the corresponding object in NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
maxLength: 255
type: string
IntegrationStatus__NS:
description: |
Status of the debit memo's synchronization with NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
maxLength: 255
type: string
SyncDate__NS:
description: |
Date when the debit memo was synchronized with NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).
maxLength: 255
type: string
title: debitMemoFieldsNS
type: object
DebitMemoObjectCustomFields:
additionalProperties:
description: |
Custom fields of the Debit Memo object. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
description: |
Container for custom fields of a Debit Memo object.
title: debitMemoFieldsCustom
type: object
DebitMemoFromChargeRequest:
allOf:
- properties:
accountId:
description: |
The ID of the account associated with the debit memo.
**Note**: When creating debit memos from product rate plan charges, you must specify `accountNumber`, `accountId`, or both in the request body. If both fields are specified, they must correspond to the same account.
type: string
accountNumber:
description: |
The number of the account associated with the debit memo.
**Note**: When creating debit memos from product rate plan charges, you must specify `accountNumber`, `accountId`, or both in the request body. If both fields are specified, they must correspond to the same account.
type: string
autoPay:
description: |
Whether debit memos are automatically picked up for processing in the corresponding payment run.
By default, debit memos are automatically picked up for processing in the corresponding payment run.
type: boolean
autoPost:
default: false
description: |
Whether to automatically post the debit memo after it is created.
Setting this field to `true`, you do not need to separately call the [Post a debit memo](https://developer.zuora.com/api-references/api/operation/PUT_PostDebitMemo) operation to post the debit memo.
type: boolean
charges:
description: |
Container for product rate plan charges. The maximum number of items is 1,000.
items:
$ref: '#/components/schemas/DebitMemoFromChargeDetailType'
maxItems: 1000
type: array
comment:
description: |
Comments about the debit memo.
maxLength: 255
minLength: 0
type: string
currency:
description: |
The code of a currency as defined in Billing Settings through the Zuora UI.
If you do not specify a currency during debit memo creation, the default account currency is applied. The currency that you specify in the request must be configured and activated in Billing Settings.
**Note**: This field is available only if you have the Multiple Currencies feature enabled.
type: string
customRates:
description: |
It contains Home currency and Reporting currency custom rates currencies. The maximum number of items is 2 (you can pass the Home currency item or Reporting currency item or both).
**Note**:
- The API custom rate feature is permission controlled.
- You cannot set the custom rates, if both the **Automatically include additional Currency Conversion information in data source exports** option and **Fx data** feature are enabled.
- DebitMemo, DebitMemoItem, and DebitMemoItemTax will utilize the provided custom Fx rate to convert amounts from the transactional currency to the home currency.
items:
$ref: '#/components/schemas/DebitMemoFromChargeCustomRatesType'
maxItems: 2
type: array
dueDate:
description: |
The date by which the payment for the debit memo is due, in `yyyy-mm-dd` format.
format: date
type: string
effectiveDate:
description: |
The date when the debit memo takes effect.
format: date
type: string
number:
type: string
maxLength: 32
description: |
A customized debit memo number with the following format requirements:
- Max length: 32 characters
- Acceptable characters: a-z,A-Z,0-9,-,_
The value must be unique in the system, otherwise it may cause issues with bill runs and subscriptions.
If not provided, Zuora will generate a unique number per the sequence set on the account level. If the account-level sequence set is not specified, the system default sequence set is used. For more information, see Configure prefix and numbering for billing documents.
reasonCode:
description: |
A code identifying the reason for the transaction. The value must be an existing reason code or empty. If you do not specify a value, Zuora uses the default reason code.
type: string
type: object
- $ref: '#/components/schemas/DebitMemoObjectNSFields'
- $ref: '#/components/schemas/DebitMemoObjectCustomFields'
example:
accountId: 8ad09be48db5aba7018db604776d4854
charges:
- amount: 10
productRatePlanChargeId: 8ad097b4909708e001909b41bb085d38
title: memos
GETDebitMemoType:
allOf:
- properties:
accountId:
description: |
The ID of the customer account associated with the debit memo.
type: string
accountNumber:
description: |
The number of the customer account associated with the debit memo.
type: string
amount:
description: |
The total amount of the debit memo.
format: double
type: number
autoPay:
description: |
Whether debit memos are automatically picked up for processing in the corresponding payment run.
By default, debit memos are automatically picked up for processing in the corresponding payment run.
type: boolean
balance:
description: |
The balance of the debit memo.
format: double
type: number
beAppliedAmount:
description: |
The amount that is applied to the debit memo.
format: double
type: number
billToContactId:
description: |
The ID of the bill-to contact associated with the debit memo.
The value of this field is `null` if you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled.
type: string
billToContactSnapshotId:
description: |
The ID of the bill-to contact snapshot associated with the debit memo.
The value of this field is `null` if the bill rule [Preserve snapshot of bill-to and sold-to contacts when billing documents are posted](https://knowledgecenter.zuora.com/Zuora_Billing/Billing_and_Invoicing/Billing_Settings/Define_Billing_Rules#Preserve_snapshot_of_bill-to_and_sold-to_contacts_when_billing_documents_are_posted) is disabled.
type: string
cancelledById:
description: |
The ID of the Zuora user who cancelled the debit memo.
type: string
nullable: true
cancelledOn:
description: |
The date and time when the debit memo was cancelled, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
nullable: true
currency:
description: |
The currency of the debit memo.
**Note:** By default, the currency on a billing document matches the default currency set on the associated account.
However, Zuora now offers a Multiple Currencies feature to support different currencies for billing documents, allowing flexibility beyond the account-level currency.
For more information, see Multiple Currency.
type: string
nullable: true
comment:
description: |
Comments about the debit memo.
type: string
nullable: true
createdById:
description: |
The ID of the Zuora user who created the debit memo.
type: string
createdDate:
description: |
The date and time when the debit memo was created, in `yyyy-mm-dd hh:mm:ss` format. For example, 2017-03-01 15:31:10.
format: date-time
type: string
debitMemoDate:
description: |
The date when the debit memo takes effect, in `yyyy-mm-dd` format. For example, 2017-05-20.
format: date
type: string
dueDate:
description: |
The date by which the payment for the debit memo is due, in `yyyy-mm-dd` format.
format: date
type: string
einvoiceErrorCode:
description: |
The error code returned when the e-invoice file status is `Failed`. This code can either be a Zuora-generated error code or one returned by a third-party e-invoicing service provider.
**Note**: This field is available only if you have the E-Invoicing feature in **Early Adopter** phase enabled.
type: string
nullable: true
einvoiceErrorMessage:
description: |
The error message returned when the e-invoice file status is `Failed`. This message can either be a Zuora-generated error message or one returned by a third-party e-invoicing service provider.
**Note**: This field is available only if you have the E-Invoicing feature in **Early Adopter** phase enabled.
type: string
nullable: true
einvoiceFileId:
description: |
The ID of the e-invoice file generated for the debit memo.
**Note**: This field is available only if you have the E-Invoicing feature in **Early Adopter** phase enabled.
type: string
nullable: true
einvoiceStatus:
description: |
The status of the e-invoice file generation for the debit memo.
- If e-invoice file generation succeeds, this field is either `Generated` or `Success`, and both the error code and message are empty, and the `eInvoiceFileId` field stores the ID of the generated e-invoice file.
- If the responses from tax vendors such as Sovos or Avalara are
taking too long, this field becomes `RetrieveTimeOut`. Once the
vendor responds successfully, you can use the 'Resync E-Invoice Status'
action to update the status automatically. You can view these updates
in System Health telemetry.
- If a failure occurs during e-invoice file generation, this field is `Failed` and an error code and an error message are returned respectively in the `einvoiceErrorCode` and `einvoiceErrorMessage` fields.
- If e-invoice file generation conditionally succeeds, this field is `ConditionalSuccess` and an error code and an error message are returned respectively in the `einvoiceErrorCode` and `einvoiceErrorMessage` fields.
- If the e-invoice file has been approved by the tax authority, this field is `ApprovedByAuthority`. The next status will be either `Success` or `Rejected`.
- If the e-invoice file has been rejected by the government, this field is `Rejected`. You cannot resend this e-invoice; you must create a new invoice instead.
**Note**: This field is available only if you have the E-Invoicing feature in **Early Adopter** phase
enabled.
enum:
- Processing
- RetrieveTimeOut
- Generated
- Success
- Failed
- ConditionalSuccess
- ApprovedByAuthority
- Rejected
type: string
nullable: true
excludeItemBillingFromRevenueAccounting:
description: |
The flag to exclude the debit memo item from revenue accounting.
**Note**: This field is only available if you have the Billing - Revenue Integration feature enabled.
type: boolean
id:
description: |
The unique ID of the debit memo.
type: string
invoiceGroupNumber:
description: |
The number of the invoice group associated with the debit memo.
The value of this field is `null` if you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled.
type: string
nullable: true
latestPDFFileId:
description: |
The ID of the latest PDF file generated for the debit memo.
type: string
number:
description: |
The unique identification number of the debit memo.
type: string
organizationLabel:
description: |
The organization that this object belongs to.
Note: This field is available only when the Multi-Org feature is enabled.
type: string
paymentTerm:
description: |
The name of the payment term assoicated with the debit memo.
The value of this field is `null` if you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled.
type: string
postedById:
description: |
The ID of the Zuora user who posted the debit memo.
type: string
nullable: true
postedOn:
description: |
The date and time when the debit memo was posted, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
nullable: true
reasonCode:
description: |
A code identifying the reason for the transaction. The value must be an existing reason code or empty.
type: string
referredCreditMemoId:
description: |
The ID of the credit memo from which the debit memo was created.
type: string
referredInvoiceId:
description: |
The ID of a referred invoice.
type: string
nullable: true
sequenceSetId:
description: |
The ID of the sequence set associated with the debit memo.
The value of this field is `null` if you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled.
type: string
nullable: true
communicationProfileId:
description: |
The ID of the communication profile associated with the debit memo.
**Note**: This field is available in the request body only if you have the Flexible Billing Attributes
feature turned on. The value is `null` in the response body without this feature turned on.
type: string
nullable: true
soldToContactId:
description: |
The ID of the sold-to contact associated with the debit memo.
The value of this field is `null` if you have the Flexible Billing Attributes feature disabled.
type: string
nullable: true
soldToContactSnapshotId:
description: |
The ID of the sold-to contact snapshot associated with the debit memo.
The value of this field is `null` if you have the Flexible Billing Attributes feature disabled.
type: string
nullable: true
sourceType:
description: |
The type of the debit memo source.
enum:
- Subscription
- Standalone
- Order
- Consolidation
- Invoice
- CreditMemo
type: string
status:
description: |
The status of the debit memo.
enum:
- Draft
- Posted
- Canceled
- Error
- PendingForTax
- Generating
- CancelInProgress
type: string
success:
description: Returns `true` if the request was processed successfully.
type: boolean
targetDate:
description: |
The target date for the debit memo, in `yyyy-mm-dd` format. For example, 2017-07-20.
format: date
type: string
nullable: true
taxAmount:
description: |
The amount of taxation.
format: double
type: number
taxMessage:
description: |
The message about the status of tax calculation related to the debit memo. If tax calculation fails in one debit memo, this field displays the reason for the failure.
type: string
nullable: true
taxStatus:
description: |
The status of tax calculation related to the debit memo.
**Note**: This field is only applicable to tax calculation by third-party tax engines. Also, the `Voided` status indicates that the tax transaction is successfully canceled on the tax vendor's side. If a tax transaction was successfully committed to the third-party tax engine but the invoice failed to post, Zuora automatically detects the issue and voids the tax transaction on the vendor's side.
enum:
- Complete
- Error
- UnknownError
- DuplicateDoc
- InvalidRequest
- InvalidResponse
- TaxEngineError
- ConcurrentModify
- InternalServerError
- TaxCodeTemplateError
- Voided
type: string
nullable: true
totalTaxExemptAmount:
description: |
The calculated tax amount excluded due to the exemption.
format: double
type: number
transferredToAccounting:
description: |
Whether the debit memo was transferred to an external accounting system. Use this field for integration with accounting systems, such as NetSuite.
enum:
- Processing
- 'Yes'
- 'No'
- Error
- Ignore
type: string
updatedById:
description: |
The ID of the Zuora user who last updated the debit memo.
type: string
updatedDate:
description: |
The date and time when the debit memo was last updated, in `yyyy-mm-dd hh:mm:ss` format. For example, 2017-03-02 15:36:10.
format: date-time
type: string
type: object
- $ref: '#/components/schemas/DebitMemoObjectNSFields'
- $ref: '#/components/schemas/DebitMemoObjectCustomFields'
title: memos
DebitMemoFromChargeDetailType:
allOf:
- properties:
amount:
description: |
The amount of the debit memo item.
**Note**: This field is available only if you are on the latest Zuora API minor version, or you set the `Zuora-Version` request header to `224.0` or [a later available version](https://developer.zuora.com/v1-api-reference/api-versions/#minor-version).
format: double
type: number
excludeItemBillingFromRevenueAccounting:
default: false
description: |
The flag to exclude the debit memo item from revenue accounting.
**Note**: This field is only available if you have the Billing - Revenue Integration feature enabled.
type: boolean
description:
description: |
The description of the product rate plan charge.
**Note**: This field is available only if you are on the latest Zuora API minor version, or you set the `Zuora-Version` request header to `257.0` or [a later available version](https://developer.zuora.com/v1-api-reference/api-versions/#minor-version).
maxLength: 255
minLength: 0
type: string
financeInformation:
description: |
Container for the finance information related to the product rate plan charge associated with the debit memo.
properties:
deferredRevenueAccountingCode:
description: |
The accounting code for the deferred revenue, such as Monthly Recurring Liability.
maxLength: 100
minLength: 0
type: string
nullable: true
recognizedRevenueAccountingCode:
description: |
The accounting code for the recognized revenue, such as Monthly Recurring Charges or Overage Charges.
maxLength: 100
minLength: 0
type: string
nullable: true
revenueRecognitionRuleName:
description: |
The name of the revenue recognition rule governing the revenue schedule.
maxLength: 100
minLength: 0
type: string
nullable: true
type: object
productRatePlanChargeId:
description: |
The ID of the product rate plan charge that the debit memo is created from.
**Note**: This field is available only if you are on the latest Zuora API minor version, or you set the `Zuora-Version` request header to `257.0` or [a later available version](https://developer.zuora.com/v1-api-reference/api-versions/#minor-version).
type: string
quantity:
description: |
The number of units for the debit memo item.
format: double
type: number
serviceEndDate:
description: |
The service end date of the debit memo item. If not specified, the effective end date of the corresponding product rate plan will be used.
format: date
type: string
serviceStartDate:
description: |
The service start date of the debit memo item. If not specified, the effective start date of the corresponding product rate plan will be used.
format: date
type: string
required:
- productRatePlanChargeId
type: object
- $ref: '#/components/schemas/DebitMemoItemObjectCustomFields'
title: charges
DebitMemoFromChargeCustomRatesType:
allOf:
- properties:
currency:
description: |
The currency code for either Reporting or Home currency.
**Note**: This field is available only if you are on the latest Zuora API minor version, or you set the `Zuora-Version` request header to `224.0` or [a later available version](https://developer.zuora.com/v1-api-reference/api-versions/#minor-version).
type: string
customFxRate:
description: |
The Custom FX conversion rate between home currency and transactional currency items.
**Note**: This field is available only if you are on the latest Zuora API minor version, or you set the `Zuora-Version` request header to `224.0` or [a later available version](https://developer.zuora.com/v1-api-reference/api-versions/#minor-version).
format: decimal
type: number
rateDate:
description: |
The date on which a particular currency rate is fixed or obtained on.
**Note**: This field is available only if you are on the latest Zuora API minor version, or you set the `Zuora-Version` request header to `224.0` or [a later available version](https://developer.zuora.com/v1-api-reference/api-versions/#minor-version).
format: date
type: string
required:
- currency
- customFxRate
type: object
- $ref: '#/components/schemas/DebitMemoItemObjectCustomFields'
title: customRates
DebitMemoItemObjectCustomFields:
additionalProperties:
description: |
Custom fields of the Debit Memo Item object. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
description: |
Container for custom fields of a Debit Memo Item object.
title: debitMemoItemFieldsCustom
type: object
PUTBatchDebitMemosRequest:
example:
debitMemos:
- dueDate: '2017-12-28'
id: 402890d25f9f083f015f9f28041d0008
- dueDate: '2017-12-20'
id: 402890555a87d7f5015a892f2ba10057
properties:
debitMemos:
description: |
Container for debit memo update details.
items:
$ref: '#/components/schemas/BatchDebitMemoType'
type: array
type: object
BatchDebitMemoType:
properties:
dueDate:
description: |
The date by which the payment for the debit memo is due, in `yyyy-mm-dd` format.
format: date
type: string
id:
description: |
The unique ID or number of the debit memo to be updated. For example, 402890555a87d7f5015a892f2ba10057 or or DM00000001.
type: string
title: debitMemos
type: object
POSTBulkDebitMemosRequestType:
discriminator:
propertyName: sourceType
mapping:
Invoice: '#/components/schemas/BulkCreateDebitMemosFromInvoiceRequest'
Standalone: '#/components/schemas/BulkCreateDebitMemosFromChargeRequest'
oneOf:
- $ref: '#/components/schemas/BulkCreateDebitMemosFromInvoiceRequest'
- $ref: '#/components/schemas/BulkCreateDebitMemosFromChargeRequest'
BulkDebitMemosResponseType:
allOf:
- properties:
memos:
description: |
The container for a list of debit memos.
items:
$ref: '#/components/schemas/GETDebitMemoType'
maxItems: 50
type: array
success:
description: Returns `true` if the request was processed successfully.
type: boolean
type: object
BulkCreateDebitMemosFromInvoiceRequest:
properties:
sourceType:
type: string
enum:
- Invoice
description: |
The type of the source where debit memos are created.
This enum field has the following values:
- `Invoice`: By setting this field to `Invoice`, you can create multiple debit memos from invoices.
- `Standalone`: By setting this field to `Standalone`, you can create multiple debit memos from product rate plan charges.
The specific schema of the `memos` object field in the request body depends on the value of the `sourceType` field.
- To view the `memos` schema applicable to debit memo creation from invoices, select `Invoice` from the following drop-down list.
- To view the `memos` schema applicable to debit memo creation from product rate plan charges, select `Standalone` from the following drop-down list.
memos:
description: |
The container for a list of debit memos. The maximum number of debit memos is 50.
items:
$ref: '#/components/schemas/DebitMemoFromInvoiceRequest'
maxItems: 50
type: array
required:
- sourceType
type: object
BulkCreateDebitMemosFromChargeRequest:
properties:
sourceType:
type: string
enum:
- Standalone
description: |
The type of the source where debit memos are created.
This enum field has the following values:
- `Invoice`: By setting this field to `Invoice`, you can create multiple debit memos from invoices.
- `Standalone`: By setting this field to `Standalone`, you can create multiple debit memos from product rate plan charges.
The specific schema of the `memos` object field in the request body depends on the value of the `sourceType` field.
- To view the `memos` schema applicable to debit memo creation from invoices, select `Invoice` from the following drop-down list.
- To view the `memos` schema applicable to debit memo creation from product rate plan charges, select `Standalone` from the following drop-down list.
memos:
description: |
The container for a list of debit memos. The maximum number of debit memos is 50.
items:
$ref: '#/components/schemas/DebitMemoFromChargeRequest'
maxItems: 50
type: array
required:
- sourceType
type: object
DebitMemoFromInvoiceRequest:
allOf:
- properties:
autoPay:
description: |
Whether debit memos are automatically picked up for processing in the corresponding payment run.
By default, debit memos are automatically picked up for processing in the corresponding payment run.
type: boolean
autoPost:
default: false
description: |
Whether to automatically post the debit memo after it is created.
Setting this field to `true`, you do not need to separately call the [Post debit memo](https://developer.zuora.com/api-references/api/operation/PUT_PostDebitMemo) operation to post the debit memo.
type: boolean
billToContactId:
description: |
The ID of the bill-to contact associated with the debit memo.
**Note**: This field is available only if you have Flexible Billing Attributes enabled for your tenant.
type: string
comment:
description: |
Comments about the debit memo.
maxLength: 255
minLength: 0
type: string
effectiveDate:
description: |
The date when the debit memo takes effect.
format: date
type: string
invoiceId:
description: |
The ID of the invoice that the debit memo is created from.
type: string
items:
description: |
Container for items. The maximum number of items is 1,000.
items:
$ref: '#/components/schemas/DebitMemoItemFromInvoiceItemType'
maxItems: 1000
type: array
reasonCode:
description: |
A code identifying the reason for the transaction. The value must be an existing reason code or empty. If you do not specify a value, Zuora uses the default reason code.
type: string
soldToContactId:
description: |
The ID of the sold-to contact associated with the debit memo.
**Note**: This field is available only if you have Flexible Billing Attributes enabled for your tenant.
type: string
soldToSameAsBillTo:
description: |
Whether the sold-to contact and bill-to contact are the same entity.
The created debit memo has the same bill-to contact and sold-to contact entity only when all the following conditions are met in the request body:
- This field is set to `true`.
- The `billToContactId` field is specified.
- The `soldToContactId` field is not specified.
type: boolean
taxAutoCalculation:
default: true
description: |
Whether to automatically calculate taxes in the debit memo.
type: boolean
type: object
required:
- invoiceId
- $ref: '#/components/schemas/DebitMemoObjectNSFields'
- $ref: '#/components/schemas/DebitMemoObjectCustomFields'
example:
invoiceId: 8a90cc5c9301541f01930186636b1400
effectiveDate: '2024-11-11'
items:
- amount: 10
invoiceItemId: 8a90cc5c9301541f0193018663aa1413
skuName: SKU-00000591
reasonCode: Correcting invoice error
title: memos
DebitMemoItemFromInvoiceItemType:
allOf:
- properties:
amount:
description: |
The amount of the debit memo item.
format: double
type: number
description:
description: |
The description of the debit memo item.
**Note**: This field is available only if you are on the latest Zuora API version, or you set the `Zuora-Version` request header to `257.0` or a later available version.
type: string
financeInformation:
description: |
Container for the finance information related to the debit memo item.
properties:
deferredRevenueAccountingCode:
description: |
The accounting code for the deferred revenue, such as Monthly Recurring Liability.
maxLength: 100
minLength: 0
type: string
recognizedRevenueAccountingCode:
description: |
The accounting code for the recognized revenue, such as Monthly Recurring Charges or Overage Charges.
maxLength: 100
minLength: 0
type: string
revenueRecognitionRuleName:
description: |
The name of the revenue recognition rule governing the revenue schedule.
maxLength: 100
minLength: 0
type: string
type: object
invoiceItemId:
description: |
The ID of the invoice item.
type: string
quantity:
description: |
The number of units for the debit memo item.
format: double
type: number
serviceEndDate:
description: |
The service end date of the debit memo item.
format: date
type: string
serviceStartDate:
description: |
The service start date of the debit memo item.
format: date
type: string
skuName:
description: |
The name of the charge associated with the invoice.
type: string
taxItems:
description: |
Container for taxation items.
items:
$ref: '#/components/schemas/DebitMemoTaxItemFromInvoiceTaxItemType'
type: array
taxMode:
default: TaxExclusive
description: |
The tax mode of the debit memo item, indicating whether the amount of the debit memo item includes tax.
**Note**: You can set this field to `TaxInclusive` only if the `taxAutoCalculation` field is set to `true`.
If you set `taxMode` to `TaxInclusive`, you cannot input tax amounts for debit memo items. The corresponding invoice item must use the same tax engine as the debit memo item to calculate tax amounts.
enum:
- TaxExclusive
- TaxInclusive
type: string
unitOfMeasure:
description: |
The definable unit that you measure when determining charges.
type: string
required:
- skuName
- amount
type: object
- $ref: '#/components/schemas/DebitMemoItemObjectCustomFields'
title: items
DebitMemoTaxItemFromInvoiceTaxItemType:
properties:
amount:
description: |
The amount of the debit memo taxation item.
format: double
type: number
financeInformation:
description: |
Container for the finance information related to the source taxation item.
properties:
salesTaxPayableAccountingCode:
description: |
The accounting code for the sales taxes payable.
maxLength: 100
minLength: 0
type: string
type: object
jurisdiction:
description: |
The jurisdiction that applies the tax or VAT. This value is typically a state, province, county, or city.
type: string
locationCode:
description: |
The identifier for the location based on the value of the `taxCode` field.
type: string
sourceTaxItemId:
description: |
The ID of the source taxation item.
type: string
taxCode:
description: |
The tax code identifies which tax rules and tax rates to apply to a specific debit memo.
type: string
taxCodeDescription:
description: |
The description of the tax code.
type: string
taxDate:
description: |
The date that the tax is applied to the debit memo, in `yyyy-mm-dd` format.
format: date
type: string
taxExemptAmount:
description: |
The calculated tax amount excluded due to the exemption.
format: double
type: number
taxName:
description: |
The name of taxation.
type: string
taxRate:
description: |
The tax rate applied to the debit memo.
format: double
type: number
taxRateDescription:
description: |
The description of the tax rate.
type: string
taxRateType:
description: |
The type of the tax rate applied to the debit memo.
enum:
- Percentage
- FlatFee
type: string
required:
- amount
title: taxItems
type: object
PUTBulkDebitMemosRequestType:
allOf:
- properties:
memos:
description: |
The container for a list of debit memos. The maximum number of debit memos is 50.
items:
$ref: '#/components/schemas/PUTDebitMemoWithIdType'
maxItems: 50
title: memos
type: array
type: object
example:
memos:
- autoPay: true
comment: new comment
dueDate: '2017-05-20'
effectiveDate: '2017-04-17'
id: 4028905f5a890526015a8db30954007a
items:
- amount: 1
comment: This is comment!
id: 402890555b797b57015b7986fc1a001c
quantity: 1
serviceEndDate: '2016-11-30'
serviceStartDate: '2016-11-01'
skuName: SKU-1
taxItems:
- amount: 0.03
id: 402890555b797b57015b7986fc3c001d
jurisdiction: CALIFORNIA
locationCode: '06'
taxCode: null
taxCodeDescription: This is tax code description!
taxDate: '2016-11-30'
taxExemptAmount: 0
taxName: STATE TAX1
taxRate: 0.0625
taxRateDescription: This is tax rate description!
taxRateType: Percentage
unitOfMeasure: Test_UOM
- amount: 2
comment: This is comment!
id: 402890555b797b57015b7986fc41001e
serviceEndDate: '2016-11-30'
serviceStartDate: '2016-11-01'
skuName: SKU-2
taxItems:
- amount: 0.06
id: 402890555b797b57015b7986fc4c001f
jurisdiction: CALIFORNIA
locationCode: '06'
taxCode: null
taxCodeDescription: This is tax code description!
taxDate: '2016-11-30'
taxExemptAmount: 0
taxName: STATE TAX2
taxRate: 0.0625
taxRateDescription: This is tax rate description!
taxRateType: Percentage
unitOfMeasure: Test_UOM
reasonCode: Correcting invoice error
PUTDebitMemoWithIdType:
allOf:
- properties:
id:
description: |
The ID of the debit memo.
type: string
type: object
- $ref: '#/components/schemas/PUTDebitMemoType'
PUTDebitMemoType:
allOf:
- properties:
autoPay:
description: |
Whether debit memos are automatically picked up for processing in the corresponding payment run.
By default, debit memos are automatically picked up for processing in the corresponding payment run.
type: boolean
comment:
description: |
Comments about the debit memo.
maxLength: 255
minLength: 0
type: string
dueDate:
description: |
The date by which the payment for the debit memo is due, in `yyyy-mm-dd` format.
format: date
type: string
effectiveDate:
description: |
The date when the debit memo takes effect.
format: date
type: string
items:
description: |
Container for debit memo items.
items:
$ref: '#/components/schemas/PUTDebitMemoItemType'
type: array
reasonCode:
description: |
A code identifying the reason for the transaction. The value must be an existing reason code or empty. If you do not specify a value, Zuora uses the default reason code
type: string
transferredToAccounting:
description: |
Whether the debit memo is transferred to an external accounting system. Use this field for integration with accounting systems, such as NetSuite.
enum:
- Processing
- 'Yes'
- 'No'
- Error
- Ignore
type: string
type: object
- $ref: '#/components/schemas/DebitMemoObjectNSFields'
- $ref: '#/components/schemas/DebitMemoObjectCustomFields'
example:
comment: Details about this Debit Memo
PUTDebitMemoItemType:
allOf:
- properties:
amount:
description: |
The amount of the debit memo item. For tax-inclusive debit memo items, the amount indicates the debit memo item amount including tax. For tax-exclusive debit memo items, the amount indicates the debit memo item amount excluding tax.
format: double
type: number
comment:
description: |
Comments about the debit memo item.
type: string
delete:
description: |
Whether to delete the existing debit memo item.
**Note**: To delete a debit memo item, set this field to `true` and specify a debit memo item ID in the `id` field.
type: boolean
excludeItemBillingFromRevenueAccounting:
default: false
description: |
The flag to exclude the debit memo item from revenue accounting.
**Note**: This field is only available if you have the Billing - Revenue Integration feature enabled.
type: boolean
financeInformation:
description: |
Container for the finance information related to the debit memo item.
properties:
deferredRevenueAccountingCode:
description: |
The accounting code for the deferred revenue, such as Monthly Recurring Liability.
maxLength: 100
minLength: 0
type: string
recognizedRevenueAccountingCode:
description: |
The accounting code for the recognized revenue, such as Monthly Recurring Charges or Overage Charges.
maxLength: 100
minLength: 0
type: string
revenueRecognitionRuleName:
description: |
The name of the revenue recognition rule governing the revenue schedule.
maxLength: 100
minLength: 0
type: string
type: object
id:
description: |
The ID of the debit memo item.
- Specify this field when updating or deleting an existing memo item.
- Do not specify this field when creating a memo item.
maxLength: 32
minLength: 32
type: string
productRatePlanChargeId:
description: |
The ID of the product rate plan charge that the debit memo is created from.
**Note**: Do not specify the debit memo item `id` when specifying this field.
type: string
quantity:
description: |
The number of units for the debit memo item.
format: double
type: number
serviceEndDate:
description: |
The service end date of the debit memo item.
format: date
type: string
serviceStartDate:
description: |
The service start date of the debit memo item.
format: date
type: string
skuName:
description: |
The name of the SKU.
type: string
taxItems:
description: |
Container for debit memo taxation items.
items:
$ref: '#/components/schemas/PutDebitMemoTaxItemType'
type: array
unitOfMeasure:
description: |
The definable unit that you measure when determining charges.
type: string
type: object
- $ref: '#/components/schemas/DebitMemoItemObjectCustomFields'
title: items
PutDebitMemoTaxItemType:
allOf:
- properties:
amount:
description: |
The amount of the taxation item in the debit memo item.
format: double
type: number
financeInformation:
description: |
Container for the finance information related to the taxation item in the debit memo item.
properties:
salesTaxPayableAccountingCode:
description: |
The accounting code for the sales taxes payable.
maxLength: 100
minLength: 0
type: string
type: object
id:
description: |
The ID of the taxation item in the debit memo item.
type: string
jurisdiction:
description: |
The jurisdiction that applies the tax or VAT. This value is typically a state, province, county, or city.
type: string
locationCode:
description: |
The identifier for the location based on the value of the `taxCode` field.
type: string
taxCode:
description: |
The tax code identifies which tax rules and tax rates to apply to a specific debit memo.
type: string
taxCodeDescription:
description: |
The description of the tax code.
type: string
taxDate:
description: |
The date that the tax is applied to the debit memo, in `yyyy-mm-dd` format.
format: date
type: string
taxExemptAmount:
description: |
The calculated tax amount excluded due to the exemption.
format: double
type: number
taxName:
description: |
The name of taxation.
type: string
taxRate:
description: |
The tax rate applied to the debit memo.
format: double
type: number
taxRateDescription:
description: |
The description of the tax rate.
type: string
taxRateType:
description: |
The type of the tax rate applied to the debit memo.
enum:
- Percentage
- FlatFee
type: string
required:
- id
type: object
- $ref: '#/components/schemas/DebitTaxationItemObjectCustomFields'
title: taxItems
DebitTaxationItemObjectCustomFields:
additionalProperties:
description: |
Custom fields of the Debit Taxation Item object. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
description: |
Container for custom fields of a Debit Taxation Item object.
title: debitTaxationItemFieldsCustom
type: object
GetDebitMemoPdfStatusBatchResponse:
description: ''
example:
debitMemoFiles:
- debitMemoId: 402824aa8cc894d5018cc8a120576881
debitMemoNumber: DM00000003
pdfGenerationStatus: Generated
createdOn: '2024-01-01 11:32:19'
updatedOn: '2024-01-01 11:32:19'
pdfFileUrl: /v1/files/2c98901f62d7d83d0162d7facea6262d
- debitMemoId: 2c98908a904dfc2601904e6e14090241
debitMemoNumber: DM00000004
pdfGenerationStatus: Error
createdOn: '2024-01-02 10:14:13'
updatedOn: '2024-01-02 10:14:13'
errorCode: INVALID_TEMPLATE
errorMessage: Unknown merge filed chargeNumber__c
- debitMemoId: 402824aa8cc894d5018cc8a120576881
debitMemoNumber: DM00000005
pdfGenerationStatus: Pending
createdOn: '2024-01-01 11:35:56'
updatedOn: '2024-01-01 11:35:56'
success: true
properties:
debitMemoFiles:
description: |
Array of debit memo PDF statuses requested.
items:
$ref: '#/components/schemas/GetDebitMemoPdfStatusResponse'
type: array
success:
description: |
Indicates whether the call succeeded.
type: boolean
type: object
title: debitMemoFiles
GetDebitMemoPdfStatusResponse:
allOf:
- properties:
debitMemoId:
description: |
The ID of the debit memo whose pdf status is requested.
type: string
debitMemoNumber:
description: |
The debit memo number of the debit memo whose pdf status is requested.
type: string
pdfGenerationStatus:
description: |
The generation status of the debit memo PDF.
type: string
enum:
- None
- Pending
- Processing
- Generated
- Error
- Obsolete
createdOn:
description: |
The time at which the request to generate the PDF was created.
type: string
updatedOn:
description: |
The time at which the request to generate the PDF was updated.
type: string
pdfFileURL:
description: |
The file path or the URL of the PDF when the status is `Generated`.
type: string
errorCategory:
description: |
The error category when the status is `Error`.
type: string
errorMessage:
description: |
The error message when the status is `Error`.
type: string
type: object
GetDebitMemoApplicationPartCollectionType:
properties:
applicationParts:
description: |
Container for application parts.
items:
$ref: '#/components/schemas/GetDebitMemoApplicationPartType'
type: array
nextPage:
description: |
URL to retrieve the next page of the response if it exists; otherwise absent.
format: URL
type: string
success:
description: Returns `true` if the request was processed successfully.
type: boolean
type: object
GetDebitMemoApplicationPartType:
properties:
appliedAmount:
description: |
The amount that is applied to the debit memo.
format: double
type: number
createdById:
description: |
The ID of the Zuora user who created the payment or credit memo.
format: uuid
type: string
createdDate:
description: |
The date and time when the payment or credit memo was created, in `yyyy-mm-dd hh:mm:ss` format. For example, 2017-12-01 15:31:10.
format: date-time
type: string
creditMemoId:
description: |
The ID of credit memo that is applied to the specified debit memo.
format: uuid
type: string
paymentId:
description: |
The ID of the payment that is applied to the specified debit memo.
format: uuid
type: string
updatedById:
description: |
The ID of the Zuora user who last updated the payment or credit memo.
format: uuid
type: string
updatedDate:
description: |
The date and time when the payment or credit memo was last updated, in `yyyy-mm-dd hh:mm:ss` format. For example, 2018-01-02 11:42:16.
format: date-time
type: string
title: applicationParts
type: object
GETTaxationItemsOfDebitMemoItemType:
allOf:
- properties:
data:
description: |
Container for the taxation items of the debit memo item.
items:
$ref: '#/components/schemas/GETDMTaxItemTypeNew'
type: array
nextPage:
description: |
URL to retrieve the next page of the response if it exists; otherwise absent.
format: URL
type: string
success:
description: Returns `true` if the request was processed successfully.
type: boolean
type: object
GETDMTaxItemTypeNew:
allOf:
- properties:
balance:
description: |
The balance of the taxation item.
format: double
type: number
creditAmount:
description: |
The amount of credit memos applied to the debit memo.
format: double
type: number
exemptAmount:
description: |
The calculated tax amount excluded due to the exemption.
format: double
type: number
financeInformation:
description: |
Container for the finance information related to the taxation item.
properties:
salesTaxPayableAccountingCode:
description: |
The accounting code for the sales taxes payable.
type: string
salesTaxPayableAccountingCodeType:
description: |
The type of the accounting code for the sales taxes payable.
type: string
type: object
id:
description: |
The ID of the taxation item.
type: string
jurisdiction:
description: |
The jurisdiction that applies the tax or VAT. This value is typically a state, province, county, or city.
type: string
locationCode:
description: |
The identifier for the location based on the value of the `taxCode` field.
type: string
name:
description: |
The name of the taxation item.
type: string
paymentAmount:
description: |
The amount of payments applied to the debit memo.
format: double
type: number
sourceTaxItemId:
description: |
The ID of the source taxation item.
type: string
taxAmount:
description: |
The amount of taxation.
format: double
type: number
taxCode:
description: |
The tax code identifies which tax rules and tax rates to apply to a specific debit memo.
type: string
taxCodeDescription:
description: |
The description of the tax code.
type: string
taxDate:
description: |
The date that the tax is applied to the debit memo, in `yyyy-mm-dd` format.
format: date
type: string
taxRate:
description: |
The tax rate applied to the debit memo.
format: double
type: number
taxRateDescription:
description: |
The description of the tax rate.
type: string
taxRateType:
description: |
The type of the tax rate.
enum:
- Percentage
- FlatFee
type: string
type: object
- $ref: '#/components/schemas/DebitTaxationItemObjectCustomFields'
title: data
DebitMemoCollectRequest:
example:
collect: true
applyCredit: true
properties:
applicationOrder:
description: |
The priority order to apply credit memos and/or unapplied payments to the debit memo. Possible item values are: `CreditMemo`, `UnappliedPayment`.
**Note:**
- This field is valid only if the `applyCredit` field is set to `true`.
- If no value is specified for this field, the default priority order is used, ["CreditMemo", "UnappliedPayment"], to apply credit memos first and then apply unapplied payments.
- If only one item is specified, only the items of the spedified type are applied to invoices. For example, if the value is `["CreditMemo"]`, only credit memos are used to apply the debit memo.
items:
type: string
type: array
applyCredit:
default: false
description: |
Whether to automatically apply credit memos or unapplied payments, or both to the debit memo.
If the value is `true`, the credit memo or unapplied payment, or both will be automatically applied to the debit memo. If no value is specified or the value is `false`, no action is taken.
type: boolean
collect:
default: false
description: |
Indicates if the current request needs to collect payment or not.
type: boolean
payment:
description: |
Some detail info that would be used to processed an electronic payment.
The info would only effect when `collect` set to `true`.
properties:
gatewayId:
description: |
The ID of the gateway instance that processes the payment. The ID must be a valid gateway instance ID and this gateway must support the specific payment method.
If no gateway ID is specified in the request body, the default gateway for the customer account is used automatically, if this default one is not configured, the default gateway of the tenant would be used.
type: string
paymentMethodId:
description: |
The unique ID of the payment method that the customer used to make the payment.
If no payment method ID is specified in the request body, the default payment method for the customer account is used automatically. If the default payment method is different from the type of payments that you want to create, an error occurs.
type: string
type: object
type: object
DebitMemoCollectResponse:
allOf:
- properties:
appliedCreditMemos:
description: |
The information about which credit memo applied to the specific debit memo.
items:
$ref: '#/components/schemas/DebitMemoCollectResponseAppliedCreditMemos'
type: array
appliedPayments:
description: |
The information about which payment applied to the specific debit memo.
items:
$ref: '#/components/schemas/DebitMemoCollectResponseAppliedPayments'
type: array
debitMemo:
description: |
The information about the debit memo that just collected.
properties:
id:
description: |
The unique ID of the debit memo.
type: string
number:
description: |
The unique identification number of the debit memo.
type: string
type: object
organizationLabel:
description: |
The organization that this object belongs to.
Note: This field is available only when the Multi-Org feature is enabled.
type: string
processedPayment:
description: |
The information about the payment that newly processed to the debit memo.
properties:
amount:
description: |
The total amount of the payment.
format: double
type: number
gatewayId:
description: |
The ID of the gateway instance that processes the payment.
type: string
gatewayResponse:
description: |
The message returned from the payment gateway for the payment. This message is gateway-dependent.
type: string
gatewayResponseCode:
description: |
The code returned from the payment gateway for the payment. This code is gateway-dependent.
type: string
id:
description: |
The unique ID of the created payment. For example, 4028905f5a87c0ff015a87eb6b75007f.
type: string
number:
description: |
The unique identification number of the payment. For example, P-00000001.
type: string
paymentMethodId:
description: |
The unique ID of the payment method that the customer used to make the payment.
type: string
status:
description: |
The status of the payment.
enum:
- Processing
- Processed
- Error
- Canceled
type: string
type: object
success:
description: Returns `true` if the request was processed successfully.
type: boolean
type: object
DebitMemoCollectResponseAppliedCreditMemos:
allOf:
- properties:
appliedAmount:
description: |
The applied amount of the credit memo to the debit memo.
format: double
type: number
id:
description: |
The unique ID of the credit memo.
type: string
number:
description: |
The unique identification number of the credit memo.
type: string
unappliedAmount:
description: |
The unapplied amount of the credit memo after applied to the debit memo.
format: double
type: number
type: object
DebitMemoCollectResponseAppliedPayments:
allOf:
- properties:
appliedAmount:
description: |
The applied amount of the payment to the debit memo.
format: double
type: number
id:
description: |
The unique ID of the payment.
type: string
number:
description: |
The unique identification number of the payment.
type: string
unappliedAmount:
description: |
The unapplied amount of the payment after applied to the debit memo.
format: double
type: number
type: object
PostDebitMemoEmailType:
example:
useEmailTemplateSetting: true
properties:
emailAddresses:
description: |
The valid email addresses you want to email a debit memo to. Use commas to separate email addresses.
**Note:** This field is only applicable if you set the `useEmailTemplateSetting` field to `false`.
type: string
includeAdditionalEmailAddresses:
default: false
description: |
Indicates whether to send a debit memo to the additional email addresses of the memo account.
You can set the additional email addresses in the **Additional Email Addresses** field on the account detail page from the Zuora UI. See [Create a Customer Account](https://knowledgecenter.zuora.com/BC_Subscription_Management/Customer_Accounts/B_Create_a_Customer_Account#section_2) for more information.
enum:
- true
- false
type: boolean
pdfFileId:
description: |
The ID of the PDF file that you want to send in the email.
If you do not specify any PDF file ID, the latest PDF file generated for the debit memo is sent in the email.
type: string
useEmailTemplateSetting:
default: false
description: |
Indicates whether to email a debit memo based on the email template setting.
If you set this field to `true`, the debit memo is sent to the email addresses specified in the **To Email** field of the email template. The email template is the one you set in the **Delivery Options** panel of the **Edit notification** dialog from the Zuora UI. See [Edit Email Templates](https://knowledgecenter.zuora.com/CF_Users_and_Administrators/Notifications/Create_Email_Templates) for more information about how to edit the **To Email** field in the email template.
enum:
- true
- false
type: boolean
type: object
GETDebitMemoFilesResponse:
properties:
debitMemoFiles:
description: |
Container for debit memo PDF files.
items:
$ref: '#/components/schemas/DebitMemoFile'
type: array
nextPage:
description: |
URL to retrieve the next page of the response if it exists; otherwise absent.
format: URL
type: string
success:
description: Returns `true` if the request was processed successfully.
type: boolean
type: object
DebitMemoFile:
properties:
id:
description: |
The ID of the debit memo PDF file. This is the ID for the file object and different from the file handle ID in the `pdfFileUrl` field. To open a file, you have to use the file handle ID.
type: string
pdfFileUrl:
description: |
The relative URL of the debit memo PDF file.
You can obtain the absolute URL for downloading the file by adding a prefix in the following format: `{environment_base_url}/apps`
For example, `https://apisandbox.zuora.com/apps/v1/files/2c98901f62d7d83d0162d7facea6262d`.
type: string
versionNumber:
description: |
The version number of the debit memo PDF file.
format: int64
type: integer
title: debitMemoFile
type: object
GETDebitMemoItemCollectionType:
properties:
items:
description: |
Container for debit memo items.
items:
$ref: '#/components/schemas/GETDebitMemoItemTypewithSuccess'
type: array
nextPage:
description: |
URL to retrieve the next page of the response if it exists; otherwise absent.
format: URL
type: string
success:
description: Returns `true` if the request was processed successfully.
type: boolean
type: object
GETDebitMemoItemTypewithSuccess:
allOf:
- properties:
amount:
description: |
The amount of the debit memo item. For tax-inclusive debit memo items, the amount indicates the debit memo item amount including tax. For tax-exclusive debit memo items, the amount indicates the debit memo item amount excluding tax.
format: double
type: number
amountWithoutTax:
description: |
The debit memo item amount excluding tax.
format: double
type: number
appliedToItemId:
description: |
The parent debit memo item that this debit memo items is applied to if this item is discount.
type: string
balance:
description: |
The balance of the debit memo item.
format: double
type: number
beAppliedAmount:
description: |
The applied amount of the debit memo item.
format: double
type: number
createdById:
description: |
The ID of the Zuora user who created the debit memo item.
type: string
createdDate:
description: |
The date and time when the debit memo item was created, in `yyyy-mm-dd hh:mm:ss` format. For example, 2017-03-01 15:31:10.
format: date-time
type: string
description:
description: |
The description of the debit memo item.
**Note**: This field is available only if you are on the latest Zuora API version, or you set the `Zuora-Version` request header to `257.0` or [a later available version](https://developer.zuora.com/v1-api-reference/api-versions/#minor-version).
type: string
excludeItemBillingFromRevenueAccounting:
description: |
The flag to exclude the debit memo item from revenue accounting.
**Note**: This field is only available if you have the Order to Revenue or Billing - Revenue Integration feature enabled.
type: boolean
financeInformation:
description: |
Container for the finance information related to the debit memo item.
properties:
deferredRevenueAccountingCode:
description: |
The accounting code for the deferred revenue, such as Monthly Recurring Liability.
type: string
deferredRevenueAccountingCodeType:
description: |
The type of the deferred revenue accounting code, such as Deferred Revenue.
type: string
recognizedRevenueAccountingCode:
description: |
The accounting code for the recognized revenue, such as Monthly Recurring Charges or Overage Charges.
type: string
recognizedRevenueAccountingCodeType:
description: |
The type of the recognized revenue accounting code, such as Sales Revenue or Sales Discount.
type: string
revenueRecognitionRuleName:
description: |
The name of the revenue recognition rule governing the revenue schedule.
type: string
revenueScheduleNumber:
description: |
The revenue schedule number. The revenue schedule number is always prefixed with "RS", for example, RS-00000001.
type: string
type: object
id:
description: |
The ID of the debit memo item.
type: string
processingType:
description: |
The kind of the charge for the debit memo item. Its possible values are `Charge` and `Discount`.
type: string
quantity:
description: |
The number of units for the debit memo item.
format: double
type: number
reflectDiscountInNetAmount:
type: boolean
default: false
description: |
When you apply percentage discounts to either of the following charges, you need to set the `reflectDiscountInNetAmount` field on your discount charge to `true`, to enable calculating and displaying the net amount of the following charges in Zuora Revenue.
* delivery pricing charge
* prepayment charge
* drawdown charge
Note the following:
* If you are an Order to Revenue customer, when you set the `reflectDiscountInNetAmount` field to `true`, you must also set the `excludeItemBillingFromRevenueAccounting` field to `true`.
* If you are a Billing - Revenue Integration customer, you must set the `reflectDiscountInNetAmount` field to `false`, otherwise an error will be returned. Billing - Revenue Integration does not support discounts on the preceding charges.
* If you are a Zuora Billing customer who does not enable the Order to Revenue or Billing - Revenue Integration feature, when you apply percentage discounts to the preceding charges, you also need to set the `reflectDiscountInNetAmount` field to `true`.
serviceEndDate:
description: |
The end date of the service period associated with this debit memo item. Service ends one second before the date specified in this field.
format: date
type: string
serviceStartDate:
description: |
The start date of the service period associated with this debit memo item. If the associated charge is a one-time fee, this date is the date of that charge.
format: date
type: string
sku:
description: |
The SKU for the product associated with the debit memo item.
type: string
skuName:
description: |
The name of the SKU.
type: string
shipToContactId:
description: |
The ID of the ship-to contact associated with the invoice item.
The value of this field is `null` if you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled.
type: string
soldToContactId:
description: |
The ID of the sold-to contact associated with the invoice item.
The value of this field is `null` if you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled.
type: string
soldToContactSnapshotId:
description: |
The ID of the sold-to contact snapshot associated with the invoice item.
The value of this field is `null` if you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled.
type: string
sourceItemId:
description: |
The ID of the source item.
type: string
sourceItemType:
description: |
The type of the source item.
enum:
- CreditMemoItem
- SubscriptionComponent
- InvoiceDetail
- ProductRatePlanCharge
type: string
subscriptionId:
description: |
The ID of the subscription associated with the debit memo item.
type: string
taxMode:
description: |
The tax mode of the debit memo item, indicating whether the amount of the debit memo item includes tax.
enum:
- TaxExclusive
- TaxInclusive
type: string
taxationItems:
description: |
Container for the taxation items of the debit memo item.
**Note**: This field is available only if you are on the latest Zuora API version, or you set the `Zuora-Version` request header to `239.0` or [a later available version](https://developer.zuora.com/v1-api-reference/api-versions/#minor-version).
properties:
data:
description: |
List of taxation items.
items:
$ref: '#/components/schemas/GETDMTaxItemTypeNew'
type: array
nextPage:
description: |
URL to retrieve the next page of the response if it exists; otherwise absent.
format: URL
type: string
type: object
unitOfMeasure:
description: |
The units to measure usage.
type: string
unitPrice:
description: |
The per-unit price of the debit memo item.
format: double
type: number
updatedById:
description: |
The ID of the Zuora user who last updated the debit memo item.
type: string
updatedDate:
description: |
The date and time when the debit memo item was last updated, in `yyyy-mm-dd hh:mm:ss` format. For example, 2017-03-02 15:36:10.
format: date-time
type: string
type: object
- $ref: '#/components/schemas/DebitMemoItemObjectCustomFields'
title: items
GETDebitMemoItemType:
allOf:
- properties:
amount:
description: |
The amount of the debit memo item. For tax-inclusive debit memo items, the amount indicates the debit memo item amount including tax. For tax-exclusive debit memo items, the amount indicates the debit memo item amount excluding tax.
format: double
type: number
amountWithoutTax:
description: |
The debit memo item amount excluding tax.
format: double
type: number
appliedToItemId:
description: |
The parent debit memo item that this debit memo items is applied to if this item is discount.
type: string
balance:
description: |
The balance of the debit memo item.
format: double
type: number
beAppliedAmount:
description: |
The applied amount of the debit memo item.
format: double
type: number
createdById:
description: |
The ID of the Zuora user who created the debit memo item.
type: string
createdDate:
description: |
The date and time when the debit memo item was created, in `yyyy-mm-dd hh:mm:ss` format. For example, 2017-03-01 15:31:10.
format: date-time
type: string
description:
description: |
Description about the debit memo item.
**Note**: This field is available only if you are on the latest Zuora API minor version, or you set the `Zuora-Version` request header to `257.0` or [a later available version](https://developer.zuora.com/v1-api-reference/api-versions/#minor-version).
type: string
excludeItemBillingFromRevenueAccounting:
description: |
The flag to exclude the debit memo item from revenue accounting.
**Note**: This field is only available if you have the Order to Revenue or Billing - Revenue Integration feature enabled.
type: boolean
financeInformation:
description: |
Container for the finance information related to the debit memo item.
properties:
deferredRevenueAccountingCode:
description: |
The accounting code for the deferred revenue, such as Monthly Recurring Liability.
type: string
deferredRevenueAccountingCodeType:
description: |
The type of the deferred revenue accounting code, such as Deferred Revenue.
type: string
recognizedRevenueAccountingCode:
description: |
The accounting code for the recognized revenue, such as Monthly Recurring Charges or Overage Charges.
type: string
recognizedRevenueAccountingCodeType:
description: |
The type of the recognized revenue accounting code, such as Sales Revenue or Sales Discount.
type: string
revenueRecognitionRuleName:
description: |
The name of the revenue recognition rule governing the revenue schedule.
type: string
revenueScheduleNumber:
description: |
The revenue schedule number. The revenue schedule number is always prefixed with "RS", for example, RS-00000001.
type: string
type: object
id:
description: |
The ID of the debit memo item.
type: string
processingType:
description: |
The kind of the charge for the debit memo item. Its possible values are `Charge` and `Discount`.
type: string
quantity:
description: |
The number of units for the debit memo item.
format: double
type: number
reflectDiscountInNetAmount:
type: boolean
default: false
description: |
When you apply percentage discounts to either of the following charges, you need to set the `reflectDiscountInNetAmount` field on your discount charge to `true`, to enable calculating and displaying the net amount of the following charges in Zuora Revenue.
* delivery pricing charge
* prepayment charge
* drawdown charge
Note the following:
* If you are an Order to Revenue customer, when you set the `reflectDiscountInNetAmount` field to `true`, you must also set the `excludeItemBillingFromRevenueAccounting` field to `true`.
* If you are a Billing - Revenue Integration customer, you must set the `reflectDiscountInNetAmount` field to `false`, otherwise an error will be returned. Billing - Revenue Integration does not support discounts on the preceding charges.
* If you are a Zuora Billing customer who does not enable the Order to Revenue or Billing - Revenue Integration feature, when you apply percentage discounts to the preceding charges, you also need to set the `reflectDiscountInNetAmount` field to `true`.
serviceEndDate:
description: |
The end date of the service period associated with this debit memo item. Service ends one second before the date specified in this field.
format: date
type: string
serviceStartDate:
description: |
The start date of the service period associated with this debit memo item. If the associated charge is a one-time fee, this date is the date of that charge.
format: date
type: string
sku:
description: |
The SKU for the product associated with the debit memo item.
type: string
skuName:
description: |
The name of the SKU.
type: string
shipToContactId:
description: |
The ID of the ship-to contact associated with the invoice item.
The value of this field is `null` if you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled.
type: string
soldToContactId:
description: |
The ID of the sold-to contact associated with the invoice item.
The value of this field is `null` if you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled.
type: string
soldToContactSnapshotId:
description: |
The ID of the sold-to contact snapshot associated with the invoice item.
The value of this field is `null` if you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled.
type: string
sourceItemId:
description: |
The ID of the source item.
type: string
sourceItemType:
description: |
The type of the source item.
enum:
- CreditMemoItem
- SubscriptionComponent
- InvoiceDetail
- ProductRatePlanCharge
type: string
subscriptionId:
description: |
The ID of the subscription associated with the debit memo item.
type: string
success:
description: Returns `true` if the request was processed successfully.
type: boolean
taxMode:
description: |
The tax mode of the debit memo item, indicating whether the amount of the debit memo item includes tax.
enum:
- TaxExclusive
- TaxInclusive
type: string
taxationItems:
description: |
Container for the taxation items of the debit memo item.
**Note**: This field is available only if you are on the latest Zuora API minor version, or you set the `Zuora-Version` request header to `239.0` or [a later available version](https://developer.zuora.com/v1-api-reference/api-versions/#minor-version).
properties:
data:
description: |
List of taxation items.
items:
$ref: '#/components/schemas/GETDMTaxItemTypeNew'
type: array
nextPage:
description: |
URL to retrieve the next page of the response if it exists; otherwise absent.
format: URL
type: string
type: object
unitOfMeasure:
description: |
The units to measure usage.
type: string
unitPrice:
description: |
The per-unit price of the debit memo item.
format: double
type: number
updatedById:
description: |
The ID of the Zuora user who last updated the debit memo item.
type: string
updatedDate:
description: |
The date and time when the debit memo item was last updated, in `yyyy-mm-dd hh:mm:ss` format. For example, 2017-03-02 15:36:10.
format: date-time
type: string
type: object
- $ref: '#/components/schemas/DebitMemoItemObjectCustomFields'
POSTTaxationItemListForDMType:
example:
taxationItems:
- name: STATE TAX
memoItemId: 8ad093f793300daf01933d50a548781f
jurisdiction: CALIFORNIA
taxAmount: 0.5
taxCode: ServiceTaxCode
taxDate: '2024-11-18'
taxRate: 0.05
taxRateType: Percentage
properties:
taxationItems:
description: |
Container for taxation items.
items:
$ref: '#/components/schemas/POSTTaxationItemForDMType'
type: array
type: object
POSTTaxationItemForDMType:
allOf:
- properties:
exemptAmount:
description: |
The calculated tax amount excluded due to the exemption.
format: double
type: number
financeInformation:
description: |
Container for the finance information related to the taxation item.
properties:
salesTaxPayableAccountingCode:
description: |
The accounting code for the sales taxes payable.
maxLength: 100
minLength: 0
type: string
type: object
jurisdiction:
description: |
The jurisdiction that applies the tax or VAT. This value is typically a state, province, county, or city.
type: string
locationCode:
description: |
The identifier for the location based on the value of the `taxCode` field.
type: string
memoItemId:
description: |
The ID of the debit memo that the taxation item is created for.
type: string
name:
description: |
The name of the taxation item.
type: string
sourceTaxItemId:
description: |
The ID of the taxation item of the invoice, which the debit memo is created from.
If you want to use this REST API to create taxation items for a debit memo created from an invoice, the taxation items of the invoice must be created or imported through the SOAP API call.
**Note:**
- This field is only used if the debit memo is created from an invoice.
- If you do not contain this field in the request body, Zuora will automatically set a value for the `sourceTaxItemId` field based on the tax location code, tax jurisdiction, and tax rate.
type: string
taxAmount:
description: |
The amount of the tax applied to the debit memo.
format: double
type: number
taxCode:
description: |
The tax code identifies which tax rules and tax rates to apply to a specific debit memo.
type: string
taxCodeDescription:
description: |
The description of the tax code.
type: string
taxDate:
description: |
The date when the tax is applied to the debit memo.
format: date
type: string
taxRate:
description: |
The tax rate applied to the debit memo.
format: double
type: number
taxRateDescription:
description: |
The description of the tax rate.
type: string
taxRateType:
description: |
The type of the tax rate applied to the debit memo.
enum:
- Percentage
- FlatFee
type: string
required:
- taxRate
- jurisdiction
- name
- taxRateType
- taxAmount
type: object
- $ref: '#/components/schemas/TaxationItemObjectCustomFields'
title: taxationItems
PUTWriteOffDebitMemoRequest:
allOf:
- properties:
comment:
description: |
Comments about the write-off. The comment is used as the comment of the credit memo generated by writing off the specified invoice.
maxLength: 255
minLength: 0
type: string
amount:
description: |
The write off amount of the invoice.
type: number
taxAutoCalculation:
description: |
Indicates whether to automatically calculate taxes in the credit memo.
type: boolean
revenueImpacting:
description: |
Indicates whether this write off operation impacts the revenue. If `revenueImpacting` = `Yes`, the deferred revenue accounting code will be automatically selected from the associated invoice.
The **Exclude Billing Item From Revenue** field will be automatically set to **Yes** by default for such non-revenue impacting write off credit memos, and this setting cannot be changed. This enhancement helps ensure that only revenue-impacting items are synchronized with Zuora Revenue, reducing unnecessary data processing.
If `revenueImpacting` = `No`, users can select an accounting code such as bad-debt expense accounting code for the write off operation.
enum:
- 'Yes'
- 'No'
default: 'Yes'
type: string
nonRevenueWriteOffAccountingCode:
description: |
Specify the accounting code for the non revenue write off. Available only if `revenueImpacting` = `no`.
**Note**: This field is available only if you have enabled the enhanced write-off permission for your tenant. Contact Zuora Global Support to enable this permission.
type: string
items:
description: |
Container for items. This field is optional.
**Note:** If specified, you must specify ALL the items of the invoice. The entire balance of the invoice will be written off, you cannot just write off some items of the invoice.
items:
$ref: '#/components/schemas/DebitMemoItemFromWriteOffInvoice'
type: array
memoDate:
description: |
The date when the credit memo was created, in `yyyy-mm-dd` format. The memo date must be later than or equal to the invoice date.
The default value is the date when you write off the invoice.
format: date
type: string
reasonCode:
description: |
A code identifying the reason for the transaction. The value must be an existing reason code or empty. If you do not specify a value, Zuora uses the default reason code `Write-off`.
type: string
type: object
- $ref: '#/components/schemas/CreditMemoObjectCustomFields'
- $ref: '#/components/schemas/CreditMemoObjectNSFields'
example:
memoDate: '2019-01-02'
type: object
PUTWriteOffDebitMemoResponse:
properties:
creditMemo:
description: |
Container for the credit memo that is automatically generated when writing off invoices.
properties:
id:
description: |
The ID of the credit memo that is created when the invoice is written off.
type: string
type: object
success:
description: |
Returns `true` if the request was processed successfully.
type: boolean
type: object
DebitMemoItemFromWriteOffInvoice:
allOf:
- properties:
comment:
description: |
Comments about the credit memo item.
type: string
amountWithoutTax:
description: |
The credit memo item amount excluding tax.
format: double
type: number
debitMemoItemId:
description: |
The ID of the debit memo item.
type: string
serviceEndDate:
description: |
The service end date of the credit memo item.
format: date
type: string
serviceStartDate:
description: |
The service start date of the credit memo item.
format: date
type: string
skuName:
description: |
The name of the charge associated with the invoice.
type: string
unitOfMeasure:
description: |
The definable unit that you measure when determining charges.
type: string
excludeItemBillingFromRevenueAccounting:
description: |
The flag to exclude the credit memo item from revenue accounting.
**Note**: This field is only available if you have the Billing - Revenue Integration feature enabled.
type: boolean
taxationItems:
description: |
Container for the taxation items of the credit memo item.
**Note**: This field is available only if you are on the latest Zuora API version, or you set the `Zuora-Version` request header to `239.0` or [a later available version](https://developer.zuora.com/v1-api-reference/api-versions/#minor-version).
items:
properties:
amount:
description: |
The credit memo taxation amount.
type: number
taxationItemId:
description: |
The Id of the debit memo item.
type: string
type: object
type: array
type: object
- $ref: '#/components/schemas/CreditMemoItemObjectCustomFields'
title: items
ListEInvoicingServiceProvidersResponse:
properties:
serviceProviders:
description: |
Container for e-invoicing service providers.
items:
$ref: '#/components/schemas/GetEInvoicingServiceProviderResponse'
type: array
success:
description: |
Returns `true` if the request was processed successfully.
type: boolean
type: object
GetEInvoicingServiceProviderResponse:
allOf:
- properties:
companyIdentifier:
description: |
The identifier of the company used to create a sender system ID, which serves to identify the system where the transactions are sent.
type: string
id:
description: |
The ID of the e-invoicing service provider.
type: string
name:
description: |
The name of the e-invoicing service provider.
maxLength: 100
type: string
provider:
description: |
The name of the e-invoicing service provider that can help you generate e-invoice files for billing documents.
enum:
- Sovos
- PEPPOL
- Avalara
type: string
serviceProviderNumber:
description: |
The unique number of the e-invoicing service provider.
type: string
test:
description: |
Whether the e-invoicing service provider's configuration is intended for testing.
- If you set this field to `true`, requests are directed to the testing integration endpoints.
- If you set this field to `false`, requests are directed to the production integration endpoints.
type: boolean
apiKey:
description: |
The API key is used to authenticate the e-invoicing service provider's requests. This field only applies to the Sovos or Avalara service provider.
type: string
use_certificate:
description: |
This field is used to indicate whether the `clientCertificate`, `clientCertificateType`, and `clientCertificatePassord` fields need to be supplied in the request.
**Note:** If the flag is `true`, the TLS endpoint config is enabled. If the flag is `false`, the Non-TLS config endpoint is enabled.
A TLS certificate and password are no longer required for integration with Sovos. Zuora now uses token-based authentication for all supported countries, including India.
type: boolean
default: true
clientCertificate:
description: |
The client certificate is used to authenticate the e-invoicing service provider's requests, which should be in base64 encoded format. This field only applies to the Sovos service provider.
type: string
format: byte
clientCertificateType:
description: |
The client certificate type is used to authenticate the e-invoicing service provider's requests. This field only applies to the Sovos service provider.
type: string
default: PKCS12
title: serviceProviders
type: object
CreateEInvoicingServiceProviderRequest:
allOf:
- properties:
companyIdentifier:
description: |
The identifier of the company used to create a sender system ID, which serves to identify the system where the transactions are sent.
type: string
name:
description: |
The name of the e-invoicing service provider.
maxLength: 100
type: string
provider:
description: |
The name of the e-invoicing service provider that can help you generate e-invoice files for billing documents.
enum:
- Sovos
- PEPPOL
- Avalara
type: string
test:
description: |
Whether the e-invoicing service provider's configuration is intended for testing.
- If you set this field to `true`, requests are directed to the testing integration endpoints.
- If you set this field to `false`, requests are directed to the production integration endpoints.
type: boolean
apiKey:
description: |
The API key is used to authenticate the e-invoicing service provider's requests. This field is required for configuring Sovos or Avalara as the service provider.
type: string
secretKey:
description: |
The secret key is used to authenticate the e-invoicing service provider's requests. This field is required for configuring Sovos or Avalara as the service provider.
type: string
use_certificate:
description: |
This field is used to indicate whether the `clientCertificate`, `clientCertificateType`, and `clientCertificatePassord` fields need to be supplied in the request.
**Note:** If the flag is `true`, the TLS endpoint config is enabled. If the flag is `false`, the Non-TLS config endpoint is enabled.
A TLS certificate and password are no longer required for integration with Sovos. Zuora now uses token-based authentication for all supported countries, including India.
type: boolean
default: true
clientCertificate:
description: |
The client certificate is used to authenticate the e-invoicing service provider's requests, which should be in base64 encoded format. This field is required for configuring Sovos as the service provider.
type: string
format: byte
clientCertificateType:
description: |
The client certificate type is used to specify the type of the client certificate. This field is required for configuring Sovos as the service provider.
type: string
default: PKCS12
clientCertificatePassword:
description: |
The client certificate password is the password to protect the client certificate. This field is required for configuring Sovos as the service provider.
type: string
format: password
required:
- name
- provider
type: object
example:
name: Sovos e-invoice service
provider: Sovos
test: false
companyIdentifier: CompanySample1
apiKey: ApiKeySample
secretKey: SecretKey
use_certificate: false
clientCertificate: U3dhZ2dlciByb2Nrcw==
clientCertificateType: PKCS12
clientCertificatePassword: ClientCertificatePassword
UpdateEInvoicingServiceProviderRequest:
allOf:
- properties:
companyIdentifier:
description: |
The identifier of the company used to create a sender system ID, which serves to identify the system where the transactions are sent.
type: string
name:
description: |
The name of the e-invoicing service provider.
maxLength: 100
type: string
test:
description: |
Whether the e-invoicing service provider's configuration is intended for testing.
- If you set this field to `true`, requests are directed to the testing integration endpoints.
- If you set this field to `false`, requests are directed to the production integration endpoints.
type: boolean
apiKey:
description: |
The API key is used to authenticate the e-invoicing service provider's requests. This field only applies to the Sovos or Avalara service provider.
type: string
secretKey:
description: |
The secret key is used to authenticate the e-invoicing service provider's requests. This field only applies to the Sovos or Avalara service provider.
type: string
use_certificate:
description: |
This field is used to indicate whether the *clientCertificate*, `clientCertificateType`, and `clientCertificatePassord` fields need to be supplied in the request.
**Note:** If the flag is `true`, the TLS endpoint config is enabled. If the flag is `false`, the Non-TLS config endpoint is enabled.
A TLS certificate and password are no longer required for integration with Sovos. Zuora now uses token-based authentication for all supported countries, including India.
type: boolean
default: true
clientCertificate:
description: |
The client certificate is used to authenticate the e-invoicing service provider's requests, which should be in base64 encoded format. This field only applies to the Sovos service provider.
type: string
format: byte
clientCertificateType:
description: |
The client certificate type is used to specify the type of the client certificate. This field only applies to the Sovos service provider.
type: string
default: PKCS12
clientCertificatePassword:
description: |
The client certificate password is the password to protect the client certificate. This field only applies to the Sovos service provider.
type: string
format: password
type: object
example:
name: Sovos e-invoice service
test: false
companyIdentifier: CompanySample1
apiKey: ApiKeySample
secretKey: SecretKey
use_certificate: false
clientCertificate: U3dhZ2dlciByb2Nrcw==
clientCertificateType: PKCS12
clientCertificatePassword: ClientCertificatePassword
ListEInvoicingBusinessRegionsResponse:
properties:
regions:
description: |
Container for e-invoicing business regions.
items:
$ref: '#/components/schemas/GetEInvoicingBusinessRegionResponse'
type: array
success:
description: |
Returns `true` if the request was processed successfully.
type: boolean
type: object
GetEInvoicingBusinessRegionResponse:
allOf:
- properties:
id:
description: |
The unique ID of the e-invoicing business region.
type: string
country:
description: |
The short name of a country or region where you must comply with e-invoicing requirements. For example, `IN` for India. For the full list of country names and codes, see View countries or regions.
type: string
businessName:
description: |
The full official name that the Seller is registered with the relevant legal authority.
maxLength: 255
type: string
businessNumber:
description: |
The specify the unique identifier number of the legal entity or person that you do business with.
For example, you must use a GSTIN for India and Tax Identification Number (TIN) for Saudi Arabia.
type: string
businessNumberSchemaId:
description: |
The identification scheme identifier that an official registrar issues to identify the Seller as a legal entity or person.
type: string
tradeName:
description: |
The name that the Seller is known as, other than the legal business name.
maxLength: 100
type: string
nullable: true
endpointId:
description: |
The Seller's electronic address, to which the application-level response to the e-invoice file might be delivered.
type: string
endpointSchemeId:
description: |
The identification scheme identifier of the Seller’s electronic address.
type: string
taxRegisterNumber:
description: |
The Seller's VAT identifier (also known as Seller VAT identification number) or the local identification (defined by the Seller’s address) of the Seller for tax purposes, or a reference that enables the Seller to state the registered tax status.
type: string
nullable: true
state:
description: |
The name of the state or province where the business is located.
type: string
nullable: true
city:
description: |
The the name of the city where the business is located.
type: string
postalCode:
description: |
The short code that can identify the business address.
type: string
addressLine1:
description: |
The first line of the Seller’s address, which is often a street address or business name.
type: string
nullable: true
addressLine2:
description: |
The second line of the Seller’s address, which is often the name of a building.
type: string
nullable: true
contactName:
description: |
The name of the Seller contact to receive e-invoicing data.
maxLength: 255
type: string
nullable: true
phoneNumber:
description: |
The business phone number of the Seller contact to receive e-invoicing data.
type: string
nullable: true
email:
description: |
The email address of the Seller contact to receive e-invoicing data.
type: string
nullable: true
serviceProviderId:
description: |
The unique ID of the e-invoicing service provider that is associated to the business region.
type: string
businessRegionNumber:
description: |
The unique number of the e-invoicing business region.
type: string
digitalSignatureEnable:
description: |
Whether the e-invoicing service provider signs PDF files for billing documents.
default: false
type: boolean
digitalSignatureBoxEnable:
description: |
Whether the digital signature box is displayed on PDF files for billing documents.
default: false
type: boolean
digitalSignatureBoxPosX:
description: |
The X-coordinate to determine where the digital signature box is displayed on PDF files for billing documents.
type: number
minimum: 0
digitalSignatureBoxPosY:
description: |
The Y-coordinate to determine where the digital signature box is displayed on PDF files for billing documents.
type: number
minimum: 0
responseMapping:
description: |
Container for e-invoicing response field mappings that map values from the e-invoicing service provider’s response data to fields on the EInvoiceData object in Zuora. Each response field mapping consists of a field name and a field path.
**Note**: This field is applicable only to the Sovos or Avalara service provider.
For more information, see Configure e-invoicing response field mappings.
type: object
title: responseMapping
additionalProperties:
type: string
description: |
The response field mapping consists of a key-value pair:
* Field name: the name of the field on the EInvoiceData object (except for the `EInvoiceFile` field, which applies only to Sovos). *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
description: |
Container for custom fields of an Invoice Schedule object.
title: invoiceScheduleCustomFields
type: object
InvoiceScheduleItemCustomFields:
additionalProperties:
description: |
Custom fields of the Invoice Schedule Item object. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
description: |
Container for custom fields of an Invoice Schedule Item object.
title: invoiceScheduleItemCustomFields
type: object
POSTScheduleItemType:
allOf:
- properties:
amount:
description: |
The amount of the invoice to be generated during the processing of the invoice schedule item.
You can only specify either the `amount` field or `percentage` field in one request.
- If you choose to specify the `amount` field in the request, `null` is returned as the value of the `percentage` field in the corresponding response.
- If you choose to specify the `percentage` field in the request, the value of the `amount` field returned in the corresponding response is calculated based on the percentage of the total amount.
type: number
name:
description: |
The name of the invoice schedule item.
maxLength: 100
type: string
percentage:
description: |
The percentage of the total amount to be billed during the processing of the invoice schedule item.
You can only specify either the `amount` field or `percentage` field in one request.
- If you choose to specify the `amount` field in the request, `null` is returned as the value of the `percentage` field in the corresponding response.
- If you choose to specify the `percentage` field in the request, the value of the `amount` field returned in the corresponding response is calculated based on the percentage of the total amount.
type: number
maximum: 100
runDate:
description: |
The date in the tenant’s time zone when the invoice schedule item is planned to be processed to generate an invoice.
When specifying run dates for invoice schedule items, consider that:
- An invoice schedule item with a blank run date will not be executed.
- You can only update the run date for an invoice schedule item in Pending status.
- If the run date of an invoice schedule item is left empty, the dates of all subsequent invoice schedule items must also be blank.
- You must specify run dates in chronological order for invoice schedule items.
format: date
type: string
targetDateForAdditionalSubscriptions:
description: |
The date in the tenant's time zone used by the invoice schedule to determine which fixed-period regular charges to be billed together with the invoice schedule item.
The regular charges must come from the subscriptions specified in the `additionalSubscriptionsToBill` field.
format: date
type: string
type: object
- $ref: '#/components/schemas/InvoiceScheduleItemCustomFields'
- {}
title: scheduleItems
PUTUpdateInvoiceScheduleRequest:
allOf:
- properties:
additionalSubscriptionsToBill:
description: |
A list of the numbers of the subscriptions that need to be billed together with the invoice schedule.
One invoice schedule can have at most 600 additional subscriptions.
items:
type: string
type: array
invoiceSeparately:
description: |
Whether the invoice items created from the invoice schedule appears on a separate invoice when Zuora generates invoices.
type: boolean
nextRunDate:
description: |
The run date of the next execution of the invoice schedule.
By default, the next run date is the same as the run date of next pending invoice schedule item. The date can be overwritten by a different date other than the default value. If the invoice schedule has completed the execution, the next run date is `null`.
format: date
type: string
notes:
description: |
Comments on the invoice schedule.
maxLength: 255
type: string
orders:
description: |
A list of the IDs or numbers of the orders associated with the invoice schedule. One invoice schedule can be associated with at most 10 orders.
The orders specified in this field override all the existing orders associated with the invoice schedule.
items:
type: string
type: array
scheduleItems:
description: |
Container for invoice schedule items. The maximum number of schedule items is 50.
The invoice schedule items specified in this field override all the existing invoice schedule items.
items:
$ref: '#/components/schemas/UpdateScheduleItems'
type: array
specificSubscriptions:
description: |
A list of the numbers of specific subscriptions associated with the invoice schedule.
- If the subscriptions specified in this field belong to the orders specified in the `orders` field, only the specific subscriptions instead of the orders are associated with the invoice schedule.
- If only the `orders` field is specified, all the subscriptions from the order are associated with the invoice schedule.
The specific subscriptions specified in this field override all the existing specific subscriptions associated with the invoice schedule.
Example:
```
{
"orders": [
"O-00000001", "O-00000002"
],
"specificSubscriptions": [
{
"orderKey": "O-00000001",
"subscriptionKey": "S-00000001"
}
]
}
```
- For the order with number O-00000001, only subscription S-00000001 contained in the order is associated with the invoice schedule.
- For the order with number O-00000002, all subscriptions contained in the order are associated with the invoice schedule.
items:
$ref: '#/components/schemas/InvoiceScheduleSpecificSubscriptions'
type: array
type: object
- $ref: '#/components/schemas/InvoiceScheduleCustomFields'
- {}
example:
additionalSubscriptionsToBill:
- S-00000001
- S-00000002
invoiceSeparately: false
nextRunDate: '2022-02-01'
notes: 2022 Billing Schedule - V2
orders:
- O-00000007
- O-00000008
scheduleItems:
- amount: 54000
id: 8a8881aa82118bec018211daf9f01680
runDate: '2022-02-24'
targetDateForAdditionalSubscriptions: '2022-02-24'
- amount: 10000
id: 8a8881aa82118bec018211daf9f11681
runDate: '2022-10-17'
targetDateForAdditionalSubscriptions: '2022-10-17'
- amount: 6200
id: 8a8881aa82118bec018211daf9f11682
runDate: '2022-11-14'
targetDateForAdditionalSubscriptions: '2022-11-14'
specificSubscriptions:
- orderKey: O-00000008
subscriptionKey: S-00000008
UpdateScheduleItems:
allOf:
- properties:
amount:
description: |
The amount of the invoice to be generated during the processing of the invoice schedule item.
You can only specify either the `amount` field or `percentage` field in one request.
- If you choose to specify the `amount` field in the request, `null` is returned as the value of the `percentage` field in the corresponding response.
- If you choose to specify the `percentage` field in the request, the value of the `amount` field returned in the corresponding response is calculated based on the percentage of the total amount.
format: number
type: string
id:
description: |
The unique ID of the invoice schedule item to be updated.
If this field is not provided, a new invoice schedule item is added to the invoice schedule.
type: string
name:
description: |
The name of the invoice schedule item.
maxLength: 100
type: string
percentage:
description: |
The percentage of the total amount to be billed during the processing of the invoice schedule item.
You can only specify either the `amount` field or `percentage` field in one request.
- If you choose to specify the `amount` field in the request, `null` is returned as the value of the `percentage` field in the corresponding response.
- If you choose to specify the `percentage` field in the request, the value of the `amount` field returned in the corresponding response is calculated based on the percentage of the total amount.
runDate:
description: |
The date in the tenant’s time zone when the invoice schedule item is planned to be processed to generate an invoice.
format: date
type: string
targetDateForAdditionalSubscriptions:
description: |
The date in the tenant's time zone used by the invoice schedule to determine which fixed-period regular charges to be billed together with the invoice schedule item.
The regular charges must come from the subscriptions specified in the `additionalSubscriptionsToBill` field.
format: date
type: string
type: object
- $ref: '#/components/schemas/InvoiceScheduleItemCustomFields'
- {}
title: scheduleItems
POSTExecuteInvoiceScheduleRequest:
allOf:
- properties:
scheduleItemId:
description: |
The ID of the invoice schedule item to be executed.
The item must be the earliest pending schedule item. If all the invoice schedule items have been processed and credit is needed to be generated, do not specify this field in the request.
type: string
type: object
- {}
example:
scheduleItemId: 8ad09b7d82b5c62f0182c5cd16944f73
ExecuteInvoiceScheduleBillRunResponse:
allOf:
- properties:
autoEmail:
description: |
Whether to automatically send an email after Auto-Post is complete.
type: boolean
autoPost:
description: |
Whether to automatically post the bill run after the bill run is created.
type: boolean
autoRenewal:
description: |
Whether to automatically renew auto-renew subscriptions that are up for renewal.
type: boolean
batches:
description: |
A list of the batches of accounts for this bill run.
This field cannot exist with the `billRunFilters` field.
**Values:** `AllBatches` or Batch*n* where *n* is a number between 1 and 50, for example, `Batch7`.
items:
type: string
type: array
billCycleDay:
description: |
The day of the bill cycle, this field is only valid when `batches` is specified.
**Values:**
- `AllBillCycleDays` or 1 - 31 for an ad-hoc bill run
- `AllBillCycleDays` or 1 - 31 or `AsRunDay` for a scheduled bill run
type: string
billRunFilters:
description: |
A list of the target account or subscriptions for this bill run.
This field cannot exist with the `batches` field.
items:
$ref: '#/components/schemas/BillRunFilters'
type: array
billRunNumber:
description: |
The number of bill run.
type: string
chargeTypeToExclude:
description: |
The types of the charges to be excluded from the generation of billing documents.
items:
enum:
- OneTime
- Recurring
- Usage
type: string
type: array
createdById:
description: |
The ID of the user who created the bill run.
type: string
createdDate:
description: |
The date and time when the bill run was created.
format: date-time
type: string
id:
description: |
The unique ID of the bill run.
type: string
invoiceDate:
description: |
The invoice date for this bill run, only valid for ad-hoc bill runs.
format: date
type: string
invoiceDateOffset:
description: |
The offset compared to bill run execution date, only valid for scheduled bill runs.
type: integer
noEmailForZeroAmountInvoice:
description: |
Whether to suppress emails for invoices with the total amount of zero or not for this bill run after the bill run is complete.
**Note**: Do not email invoices with the total amount of zero.
type: boolean
organizationLabels:
description: |
The organization(s) that the object belongs to.
Note: This field is available only when the Multi-Org feature is enabled.
items:
properties:
organizationId:
description: |
The organization ID.
type: string
organizationName:
description: |
The organization name.
type: string
type: object
type: array
scheduledExecutionTime:
description: |
The scheduled execution time for a bill run.
format: date-time
type: string
status:
description: |
The status of the bill run.
enum:
- Pending
- Processing
- Completed
- Error
- Canceled
- Posted
- PostInProgress
- CancelInProgress
- RemoveInProgress
- Paused
type: string
targetDate:
description: |
The target date for this bill run, only valid for ad-hoc bill run.
format: date
type: string
targetDateOffset:
description: |
The offset compared to bill run execution date, only valid for scheduled bill run.
type: integer
updatedById:
description: |
The ID of the user who updated the bill run.
type: string
updatedDate:
description: |
The date and time when the bill run was updated.
format: date-time
type: string
type: object
- {}
example:
autoEmail: false
autoPost: false
autoRenewal: false
billRunFilters:
- accountId: 2c9081a03c63c94c013c66688a2c00bf
filterType: Subscription
subscriptionId: 402882297e387c51017e38a245c313db
billRunNumber: BR-00000016
chargeTypeToExclude:
- OneTime
- Usage
createdById: ff808081298c6e5401298c7274a40005
createdDate: '2022-01-24 19:58:27'
id: 2c9890077e8a8490017e8bf3a5171a43
invoiceDate: '2020-02-01'
noEmailForZeroAmountInvoice: false
status: Pending
success: true
targetDate: '2020-02-01'
updatedById: ff808081298c6e5401298c7274a40005
updatedDate: '2022-01-24 19:58:27'
BillRunFilters:
allOf:
- properties:
accountId:
description: |
The target account of the bill run.
type: string
filterType:
description: |
The type of the filter to determine whether to create a bill run at the account level or subscription level.
enum:
- Account
- Subscription
- InvoiceSchedule
type: string
subscriptionId:
description: |
The unique ID of the target subscription belonged to the target account.
This field is required if you set the `filterType` field to `Subscription`.
type: string
type: object
- {}
title: billRunFilters
DetachInvoiceScheduleRequest:
example:
specificSubscriptions:
- orderKey: O-00017019
subscriptionKey: A-S00008953
chargeNumbers:
- C-00065317
properties:
specificSubscriptions:
description: |
A list of charge numbers to be detached from the invoice schedule.
Each item in this array represents a specific subscription associated with the invoice schedule. Use the `chargeNumbers` field to specify all the charges you want to detach for each subscription.
items:
type: object
properties:
chargeNumbers:
description: |
A list of charge numbers in the subscription to be detached from the invoice schedule.
If you want to detach all charges, you must specify all of the charge numbers in this field.
type: string
orderKey:
description: |
The unique ID or number of the order associated with the invoice schedule.
type: string
subscriptionKey:
description: |
The unique number of the subscription contained in the order associated with the invoice schedule.
type: string
title: specificSubscriptions
type: array
type: object
AttachInvoiceScheduleRequest:
example:
specificSubscriptions:
- orderKey: O-00017019
subscriptionKey: A-S00008953
chargeNumbers:
- C-00065317
properties:
specificSubscriptions:
description: |
A list of charge numbers to be attached to the invoice schedule.
Each item in this array represents a specific subscription associated with the invoice schedule. Use the `chargeNumbers` field to specify all the charges you want to attach for each subscription.
items:
type: object
properties:
chargeNumbers:
description: |
A list of charge numbers in the subscription to be attached to the invoice schedule.
If you want to attach all charges, you must specify all of the charge numbers in this field.
type: string
orderKey:
description: |
The unique ID or number of the order associated with the invoice schedule.
type: string
subscriptionKey:
description: |
The unique number of the subscription contained in the order associated with the invoice schedule.
type: string
title: specificSubscriptions
type: array
type: object
ProxyCreateTaxationItem:
allOf:
- properties:
AccountingCode:
description: ' The Chart of Accounts '
type: string
ExemptAmount:
description: |2-
The calculated tax amount excluded due to the exemption.
**Character limit**: 16 **Values**: a decimal value
format: double
type: number
InvoiceItemId:
description: |2-
The ID of the specific invoice item that the taxation information applies to.
**Character limit**: 32 **Values**: a valid invoice item ID
type: string
Jurisdiction:
description: |2-
The jurisdiction that applies the tax or VAT. This value is typically a state, province, county, or city.
**Character limit**: 32 **Values**: a string of 32 characterrs or fewer
type: string
LocationCode:
description: |2-
The identifier for the location based on the value of the `TaxCode` field.
**Character limit**: 32 **Values**: automatically generated
type: string
Name:
description: |2-
The name of the tax rate, such as sales tax or GST. This name is displayed on invoices.
**Character limit**: 128 **Values**: a string of 128 characters or fewer
type: string
TaxAmount:
description: |2-
The amount of the tax applied to the charge.
**Character limit**: 16 **Values**: a decimal value
format: double
type: number
TaxCode:
description: |2-
The tax code identifies which tax rules and tax rates to apply to a specific charge.
**Character limit**: 32 **Values**: a string of 32 characters or fewer
type: string
TaxCodeDescription:
description: |2-
The description for the tax code.
**Character limit**: 255 **Values**: a string of 255 characters or fewer
type: string
TaxDate:
description: |2-
The date that the tax is applied to the charge, in `yyyy-mm-dd` format.
**Character limit**: 29
format: date
type: string
TaxRate:
description: |2-
The tax rate applied to the charge.
**Character limit**: 16 **Values**: a valid decimal value
format: double
type: number
TaxRateDescription:
description: |2-
The description of the tax rate.
**Character limit**: 255 **Values**: a string of 255 characters or fewer
type: string
TaxRateType:
description: |2-
The type of the tax rate applied to the charge.
**Character limit**: 10 **Values**: `Percentage`, `FlatFee`
type: string
required:
- InvoiceItemId
- Jurisdiction
- Name
- TaxAmount
- TaxRate
- TaxDate
- TaxRateType
type: object
- $ref: '#/components/schemas/TaxationItemObjectCustomFields'
example:
InvoiceItemId: 8ad086fa92d66ffe0192dc7e5dd65161
Jurisdiction: CALIFORNIA
Name: CA TAX
TaxAmount: 3
TaxDate: '2024-11-04'
TaxRate: 3
TaxRateType: FlatFee
GETTaxationItemType:
allOf:
- properties:
createdById:
description: |
The ID of the Zuora user who created the taxation item.
type: string
createdDate:
description: |
The date and time when the taxation item was created in the Zuora system, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
exemptAmount:
description: |
The calculated tax amount excluded due to the exemption.
format: double
type: number
financeInformation:
description: |
Container for the finance information related to the taxation item.
properties:
onAccountAccountingCode:
description: |
The accounting code that maps to an on account in your accounting system.
type: string
onAccountAccountingCodeType:
description: |
The type of the accounting code that maps to an on account in your accounting system.
type: string
salesTaxPayableAccountingCode:
description: |
The accounting code for the sales taxes payable.
type: string
salesTaxPayableAccountingCodeType:
description: |
The type of the accounting code for the sales taxes payable.
type: string
type: object
id:
description: |
The ID of the taxation item.
type: string
jurisdiction:
description: |
The jurisdiction that applies the tax or VAT. This value is typically a state, province, county, or city.
type: string
locationCode:
description: |
The identifier for the location based on the value of the `taxCode` field.
type: string
memoItemId:
description: |
The ID of the credit or debit memo associated with the taxation item.
type: string
name:
description: |
The name of the taxation item.
type: string
sourceTaxItemId:
description: |
The ID of the taxation item of the invoice, which the credit or debit memo is created from.
type: string
success:
description: Returns `true` if the request was processed successfully.
type: boolean
taxAmount:
description: |
The amount of the tax applied to the credit or debit memo.
format: double
type: number
taxCode:
description: |
The tax code identifies which tax rules and tax rates to apply to a specific credit or debit memo.
type: string
taxCodeDescription:
description: |
The description of the tax code.
type: string
taxDate:
description: |
The date when the tax is applied to the credit or debit memo.
format: date
type: string
taxRate:
description: |
The tax rate applied to the credit or debit memo.
format: double
type: number
taxRateDescription:
description: |
The description of the tax rate.
type: string
taxRateType:
description: |
The type of the tax rate applied to the credit or debit memo.
enum:
- Percentage
- FlatFee
type: string
updatedById:
description: |
The ID of the Zuora user who last updated the taxation item.
type: string
updatedDate:
description: |
The date and time when the taxation item was last updated, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
type: object
- $ref: '#/components/schemas/TaxationItemObjectCustomFields'
PUTTaxationItemType:
allOf:
- properties:
exemptAmount:
description: |
The calculated tax amount excluded due to the exemption.
format: double
type: number
financeInformation:
description: |
Container for the finance information related to the taxation item.
properties:
onAccountAccountingCode:
description: |
The accounting code that maps to an on account in your accounting system.
maxLength: 100
minLength: 0
type: string
salesTaxPayableAccountingCode:
description: |
The accounting code for the sales taxes payable.
maxLength: 100
minLength: 0
type: string
type: object
jurisdiction:
description: |
The jurisdiction that applies the tax or VAT. This value is typically a state, province, county, or city.
type: string
locationCode:
description: |
The identifier for the location based on the value of the `taxCode` field.
type: string
name:
description: |
The name of the taxation item to be updated.
type: string
taxAmount:
description: |
The amount of the tax applied to the credit or debit memo.
format: double
type: number
taxCode:
description: |
The tax code identifies which tax rules and tax rates to apply to a specific credit or debit memo.
type: string
taxCodeDescription:
description: |
The description of the tax code.
type: string
taxDate:
description: |
The date when the tax is applied to the credit or debit memo.
format: date
type: string
taxRate:
description: |
The tax rate applied to the credit or debit memo.
format: double
type: number
taxRateDescription:
description: |
The description of the tax rate.
type: string
taxRateType:
description: |
The type of the tax rate applied to the credit or debit memo.
enum:
- Percentage
- FlatFee
type: string
type: object
- $ref: '#/components/schemas/TaxationItemObjectCustomFields'
example:
taxRateDescription: Details of the tax rate
GETSequenceSetsResponse:
description: ''
properties:
sequenceSets:
description: |
Array of sequence sets configured for billing documents, payments, and refunds.
items:
$ref: '#/components/schemas/GETSequenceSetResponse'
type: array
success:
description: |
Indicates whether the call succeeded.
type: boolean
type: object
GETSequenceSetResponse:
description: ''
properties:
creditMemo:
$ref: '#/components/schemas/CreditMemoEntityPrefix'
debitMemo:
$ref: '#/components/schemas/DebitMemoEntityPrefix'
id:
description: |
The unique ID of the sequence set. For example, 402892c74c9193cd014c96bbe7c101f9.
type: string
invoice:
$ref: '#/components/schemas/InvoiceEntityPrefix'
name:
description: |
The name of the sequence set.
type: string
payment:
$ref: '#/components/schemas/PaymentEntityPrefix'
refund:
$ref: '#/components/schemas/RefundEntityPrefix'
title: sequenceSets
type: object
CreditMemoEntityPrefix:
description: |
Container for the prefix and starting document number of credit memos.
**Note:** This field is only available if you have the 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.
properties:
prefix:
description: |
The prefix of credit memos.
example: CM
type: string
startNumber:
description: |
The starting document number of credit memos.
example: 10
type: integer
title: creditMemo
type: object
DebitMemoEntityPrefix:
description: |
Container for the prefix and starting document number of debit memos.
**Note:** This field is only available if you have the 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.
properties:
prefix:
description: |
The prefix of debit memos.
example: DM
type: string
startNumber:
description: |
The starting document number of debit memos.
example: 10
type: integer
title: debitMemo
type: object
InvoiceEntityPrefix:
description: |
Container for the prefix and starting document number of invoices.
properties:
prefix:
description: |
The prefix of invoices.
example: INV
type: string
startNumber:
description: |
The starting document number of invoices.
example: 10
type: integer
title: Invoice
type: object
PaymentEntityPrefix:
description: |
Container for the prefix and starting number of payments.
properties:
prefix:
description: |
The prefix of payments.
example: P-
type: string
startNumber:
description: |
The starting number of payments.
example: 10
type: integer
title: payment
type: object
RefundEntityPrefix:
description: |
Container for the prefix and starting number of refunds.
properties:
prefix:
description: |
The prefix of refunds.
example: R-
type: string
startNumber:
description: |
The starting number of refunds.
example: 10
type: integer
title: refund
type: object
POSTSequenceSetsRequest:
description: ''
example:
sequenceSets:
- name: FR
creditMemo:
prefix: FCM
startNumber: 10
debitMemo:
prefix: FDM
startNumber: 10
invoice:
prefix: FINV
startNumber: 10
payment:
prefix: FP-
startNumber: 10
refund:
prefix: FR-
startNumber: 10
properties:
sequenceSets:
description: |
Array of sequence sets configured for billing documents, payments, and refunds.
items:
$ref: '#/components/schemas/POSTSequenceSetRequest'
type: array
type: object
POSTSequenceSetsResponse:
description: ''
properties:
sequenceSets:
description: |
Array of sequence sets configured for billing documents, payments, and refunds.
items:
$ref: '#/components/schemas/GETSequenceSetResponse'
type: array
success:
description: |
Indicates whether the call succeeded.
example: true
type: boolean
type: object
POSTSequenceSetRequest:
description: ''
properties:
creditMemo:
$ref: '#/components/schemas/CreditMemoEntityPrefix'
debitMemo:
$ref: '#/components/schemas/DebitMemoEntityPrefix'
invoice:
$ref: '#/components/schemas/InvoiceEntityPrefix'
name:
description: |
The name of the sequence set to configure for billing documents, payments, and refunds.
example: FRANCE
type: string
payment:
$ref: '#/components/schemas/PaymentEntityPrefix'
refund:
$ref: '#/components/schemas/RefundEntityPrefix'
required:
- name
- invoice
- creditMemo
- debitMemo
title: sequenceSets
type: object
PUTSequenceSetRequest:
description: ''
example:
creditMemo:
prefix: FR-CM
properties:
creditMemo:
$ref: '#/components/schemas/CreditMemoEntityPrefix'
debitMemo:
$ref: '#/components/schemas/DebitMemoEntityPrefix'
invoice:
$ref: '#/components/schemas/InvoiceEntityPrefix'
name:
description: |
The name of the sequence set configured for billing documents, payments, and refunds.
type: string
payment:
$ref: '#/components/schemas/PaymentEntityPrefix'
refund:
$ref: '#/components/schemas/RefundEntityPrefix'
type: object
PUTSequenceSetResponse:
description: ''
properties:
success:
description: |
Indicates whether the call succeeded.
type: boolean
type: object
PostBillingPreviewParam:
example:
accountId: 8ad09bce83f1da020183f97e245c1c47
targetDate: '2024-09-30'
properties:
accountId:
description: |
The ID of the customer account to which the billing preview applies.
**Note**: When posting billing preview, you must specify either `accountId` or `accountNumber` in the request body.
maxLength: 255
type: string
accountNumber:
description: |
The number of the customer account to which the billing preview applies.
**Note**: When posting billing preview, you must specify either `accountId` or `accountNumber` in the request body.
type: string
assumeRenewal:
description: |
Indicates whether to generate a preview of future invoice items and credit memo items with the assumption that the subscriptions are renewed.
Set one of the following values in this field to decide how the assumption is applied in the billing preview.
* **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.
* **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.
* 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.
* If the target date is earlier 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 target date.
* **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.
**Note:**
- This field can only be used if the subscription renewal term is not set to 0.
- 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
chargeTypeToExclude:
description: |
The charge types to exclude from the billing preview.
**Possible values:** OneTime, Recurring, Usage, and any 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: |
Indicates if evergreen subscriptions are included in the billingPreview call.
type: boolean
targetDate:
description: |
The target date for the billingPreview call. The billingPreview call generates preview invoice item data and credit memo item data from the first day of the customer's next billing period to the TargetDate.
If the TargetDate 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.
**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.
format: date
type: string
required:
- targetDate
type: object
BillingPreviewResult:
properties:
accountId:
description: |
ID of the customer account to which the billing preview applies.
type: string
creditMemoItems:
description: |
An array of credit memo items returned as the result of the billing preivew request.
**Note:** The credit memo items are 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.
items:
$ref: '#/components/schemas/POSTBillingPreviewCreditMemoItem'
type: array
invoiceItems:
description: |
An array of invoice items returned as the result of the billing preview request.
items:
$ref: '#/components/schemas/POSTBillingPreviewInvoiceItem'
type: array
success:
description: |
Returns `true` if the request was processed successfully.
type: boolean
type: object
POSTBillingPreviewCreditMemoItem:
properties:
amount:
description: |
The amount of the credit memo item. For tax-inclusive credit memo items, the amount indicates the credit memo item amount including tax. For tax-exclusive credit memo items, the amount indicates the credit memo item amount excluding tax
format: double
type: number
amountWithoutTax:
description: |
The credit memo item amount excluding tax.
format: double
type: number
appliedToItemId:
description: |
The unique ID of the credit memo item that the discount charge is applied to.
type: string
nullable: true
chargeDate:
description: |
The date when the credit memo item is created.
format: date-time
type: string
chargeNumber:
description: |
Number of the charge.
type: string
chargeType:
description: |
The type of charge.
Possible values are `OneTime`, `Recurring`, and `Usage`.
type: string
comment:
description: |
Comment of the credit memo item.
type: string
id:
description: |
Credit memo item id.
type: string
numberOfDeliveries:
description: |
The number of deliveries dedicated to the Delivery Pricing charges.
**Note**: This field is available only if you have the Delivery Pricing feature enabled.
type: number
processingType:
description: |
Identifies the kind of charge.
Possible values:
* charge
* discount
* prepayment
* tax
type: string
quantity:
description: |
Quantity of this item, in the configured unit of measure for the charge.
format: decimal
type: string
ratePlanChargeId:
description: |
Id of the rate plan charge associated with this item.
type: string
serviceEndDate:
description: |
End date of the service period for this item, i.e., the last day of the service period, in yyyy-mm-dd format.
format: date
type: string
serviceStartDate:
description: |
Start date of the service period for this item, in yyyy-mm-dd format. If the charge is a one-time fee, this is the date of that charge.
format: date
type: string
sku:
description: |
Unique SKU for the product associated with this item.
type: string
skuName:
description: |
Name of the unique SKU for the product associated with this item.
type: string
subscriptionId:
description: |
ID of the subscription associated with this item.
type: string
subscriptionNumber:
description: |
Name of the subscription associated with this item.
type: string
unitOfMeasure:
description: |
Unit used to measure consumption.
type: string
title: creditMemoItems
type: object
POSTBillingPreviewInvoiceItem:
properties:
appliedToItemId:
description: |
The unique ID of the invoice item that the discount charge is applied to.
type: string
nullable: true
chargeAmount:
description: |
The amount of the charge. This amount doesn't include taxes regardless if the charge's tax mode is inclusive or exclusive.
format: decimal
type: string
chargeDate:
description: |
The date when the invoice item was created.
format: date-time
type: string
chargeDescription:
description: |
Description of the charge.
type: string
chargeId:
description: |
Id of the charge.
type: string
chargeName:
description: |
Name of the charge.
type: string
chargeNumber:
description: |
Number of the charge.
type: string
chargeType:
description: |
The type of charge.
Possible values are `OneTime`, `Recurring`, and `Usage`.
type: string
id:
description: |
Invoice item ID.
type: string
numberOfDeliveries:
description: |
The number of deliveries dedicated to the Delivery Pricing charges.
**Note**: This field is available only if you have the Delivery Pricing feature enabled.
type: number
processingType:
description: |
Identifies the kind of charge.
Possible values:
* charge
* discount
* prepayment
* tax
type: string
productName:
description: |
Name of the product associated with this item.
type: string
quantity:
description: |
Quantity of this item, in the configured unit of measure for the charge.
format: decimal
type: string
serviceEndDate:
description: |
End date of the service period for this item, i.e., the last day of the service period, in `yyyy-mm-dd` format.
format: date
type: string
serviceStartDate:
description: |
Start date of the service period for this item, in `yyyy-mm-dd` format. If the charge is a one-time fee, this is the date of that charge.
format: date
type: string
subscriptionId:
description: |
ID of the subscription associated with this item.
type: string
subscriptionName:
description: |
Name of the subscription associated with this item.
type: string
subscriptionNumber:
description: |
Number of the subscription associated with this item.
type: string
taxAmount:
description: |
If you use [Zuora Tax](https://knowledgecenter.zuora.com/Billing/Taxes/A_Zuora_Tax) and the product rate plan charge associated with the invoice item is of [tax inclusive mode](https://knowledgecenter.zuora.com/Billing/Taxes/A_Zuora_Tax/D_Associate_tax_codes_with_product_charges_and_set_the_tax_mode), the value of this field is the amount of tax applied to the charge. Otherwise, the value of this field is `0`.
format: decimal
type: string
unitOfMeasure:
description: |
Unit used to measure consumption.
type: string
title: invoiceItems
type: object
POSTInvoiceCollectType:
example:
accountKey: 4028925a4cb74ec9014cb7520fc00005
invoiceId: 4028925a4cb74ec9014cb7540988002e
properties:
accountKey:
description: |
Customer account ID or account number.
type: string
documentDate:
description: |
The date that should appear on the invoice and credit memo being generated,
in `yyyy-mm-dd` format. If this field is omitted
and `invoiceId` is not specified, the current date is used by default.
**Note:** The credit memo is only available if you have the Invoice Settlement feature enabled.
**Note**: This field is available only if you are on the latest Zuora API version, or you set the `Zuora-Version` request header to `215.0` or [a later available version](https://developer.zuora.com/v1-api-reference/api-versions/#minor-version).
format: date
type: string
invoiceId:
description: |
The ID or number of an existing invoice for which to collect payment using
the account's default payment method. If this value is specified, no new
invoice is generated, and the following fields are ignored:
- `invoiceDate` and `invoiceTargetDate` (if the Zuora minor API version is 214.0 or earlier)
- `documentDate` and `targetDate` (if the Zuora minor API version is 215.0 or [a later available version](https://developer.zuora.com/v1-api-reference/api-versions/#minor-version))
type: string
paymentGateway:
description: |
The name of the gateway that will be used for the payment. Must be a valid gateway name and the gateway must support the specific payment method. If a value is not specified, the default gateway on the Account will be used.
type: string
targetDate:
description: |
The date through which to calculate charges on this account if an invoice or a credit memo is generated, in `yyyy-mm-dd` format. If this field is omitted and `invoiceId` is not specified, the current date is used by default.
This field is available only if you are on the latest Zuora API version, or you set the `Zuora-Version` request header to `215.0` or [a later available version](https://developer.zuora.com/v1-api-reference/api-versions/#minor-version).
**Note:** The credit memo is only available if you have the Invoice Settlement feature enabled.
format: date
type: string
required:
- accountKey
type: object
POSTInvoiceCollectResponseType:
properties:
amountCollected:
description: |
Payment amount applied.
format: double
type: number
creditMemos:
description: |
Information on one or more credit memos associated with this operation.
items:
$ref: '#/components/schemas/POSTInvoiceCollectCreditMemosType'
type: array
invoices:
description: |
Information on one or more invoices associated with this operation.
items:
$ref: '#/components/schemas/POSTInvoiceCollectInvoicesType'
type: array
paymentId:
description: |
Payment ID.
type: string
success:
description: |
Returns `true` if the request was processed successfully.
type: boolean
type: object
POSTInvoiceCollectCreditMemosType:
properties:
id:
description: |
The ID of the credit memo.
type: string
totalAmount:
description: |
The amount of the credit memo.
format: double
type: number
memoNumber:
description: |
The unique identification number of the credit memo.
type: string
title: creditMemos
type: object
POSTInvoiceCollectInvoicesType:
properties:
invoiceAmount:
description: |
The amount of the invoice.
format: decimal
type: string
invoiceId:
description: |
The ID of the invoice.
type: string
invoiceNumber:
description: |
The unique identification number of the invoice.
type: string
title: invoices
type: object
GetOperationJobResponseType:
properties:
id:
description: |
The ID of the operation job to retrieve information about.
type: string
objectId:
description: |
The ID of the business object which is being operated.
type: string
objectType:
description: |
The object type of the job.
enum:
- Invoice
type: string
operationType:
description: |
The operation type of the job.
enum:
- Delete
- Reverse
type: string
reasons:
items:
properties:
code:
description: |
The error code of the response.
type: string
message:
description: |
The detail information of the error response.
type: string
type: object
type: array
status:
description: |
The status of the operation job.
enum:
- Pending
- Processing
- Failed
- Completed
type: string
success:
description: |
Whether the call succeeded.
type: boolean
type: object
POSTBulkPdfGenerationJobRequestType:
allOf:
- type: object
required:
- documents
- fileName
- indexFileFormat
example:
documents:
- docType: Invoice
objectIds:
- 402880de8ce7edc3018ce7f18404315a
- 402880de8ce7edc3018ce7f18e0b3804
fileName: all-invoices-posted-jan-2024
name: BulkPDFGenerationJobV1
indexFileFormat: JSON
generateMissingPDF: true
ignoreArchivedFiles: true
properties:
documents:
description: |
An array that contains a collection of objects where each object contains billing document type and their IDs.
items:
$ref: '#/components/schemas/DocumentList'
type: array
fileName:
description: |
The prefix part of output file name(s). The response will include multiple file URLs. The number of zip files generated corresponds to the number of invoice IDs. Each zip file contains up to 1000 document IDs.
Eg:
if fileName is "all-invoices-posted-jan-2024" then fileURL(s) will start with the file name followed by an underscore and a number. For instance, all-invoices-posted-jan-2024_1.zip, all-invoices-posted-jan-2024_2.zip, and so on.
type: string
maxLength: 32
name:
description: |
The name of the job.
type: string
maxLength: 32
indexFileFormat:
description: |
The format of the index file. It contains the metadata about the files and their contents.
enum:
- JSON
- CSV
type: string
generateMissingPDF:
description: |
This flag controls the behavior of whether to generate PDF(s) for billing documents that do not already have one.
- setting it to true indicates service would go through the provided document ID list, find the billing documents that do not have a generated PDF,
generate them all at once, and then proceed to the zipping process.
- setting it to false indicates service would go through the provided document ID list, find the billing documents that do not have a generated PDF,
mark them as Invalid, and skip them from the zipping process. IDs marked as invalid will be included in the response.
The default value is false.
type: boolean
ignoreArchivedFiles:
description: |
Ignores archived PDF files during export without causing the entire job request to fail when enabled.
type: boolean
persistIndexFile:
description: |
Controls the generation of the index file, allowing you to efficiently handle high volumes of requests. By default, this field is set to `true`.
- When set to `true`, the index file is generated and included in the zip file.
- When set to `false`, the index file is not generated and consequently not included in the zip file.
type: boolean
POSTBulkPdfGenerationJobResponseType:
example:
jobId: 402880de8ce7edc3018ce7f18404312a
invalidIds: []
success: true
allOf:
- $ref: '#/components/schemas/CommonResponse'
- properties:
jobId:
description: |
Unique Id for the Job Triggered.
type: string
invalidIds:
description: |
Collection of Ids that are not valid.
Id is considered to be invalid if,
* Billing Document Id doesn't exist in the database for the corresponding Billing Document Type
* generateMissingPDF property is false in the Job Request and Valid PDF doesn't exist for the Billing Document Id
skippedDocuments:
description: |
The `skippedDocuments` array will be empty unless archived files are marked to skip during job creation.
items:
type: object
properties:
docType:
description: |
The document type of the skipped document.
enum:
- Invoice
- CreditMemo
- DebitMemo
type: string
objectIds:
description: |
The IDs of the skipped document objects.
type: array
items:
type: string
type: array
type: object
DocumentList:
example:
docType: Invoice
objectIds:
- 402880de8ce7edc3018ce7f18404315a
- 402880de8ce7edc3018ce7f18e0b3804
properties:
docType:
description: The type of billing document.
enum:
- Invoice
- CreditMemo
- DebitMemo
type: string
objectIds:
description: The collection of billing document IDs.
items:
type: string
type: array
type: object
GETBulkpdfGenerationJobResponseType:
example:
jobId: 402880de8ce7edc3018ce7f18404312a
jobName: BulkPDFGenerationJobV1
status: Completed
stepStatus: PostProcessing
fileUrls:
- https://s3.us-west-2.amazonaws.com/billing-file-repository/bulk-pdf-generation/12345/all-invoices-posted-jan-2024_1.zip?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20231222T075849Z&X-Amz-SignedHeaders=host&X-Amz-Expires=259199&X-Amz-Credential=fakeMyKeyId%2F20231222%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=62368dbec1763101fba328cf83ae7d3efd780fa03f443370d2f353757e79fc99
- https://s3.us-west-2.amazonaws.com/billing-file-repository/bulk-pdf-generation/12345/all-invoices-posted-jan-2024_2.zip?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20231222T075849Z&X-Amz-SignedHeaders=host&X-Amz-Expires=259199&X-Amz-Credential=fakeMyKeyId%2F20231222%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=62368dbec1763101fba328cf83ae7d3efd780fa03f443370d2f353757e79fc99
createdOn: '2024-01-08 12:52:05'
createdBy: caf630704a6f4100818601625ecffe0b
success: true
properties:
jobId:
description: Unique Id for the Triggered Job
type: string
jobName:
description: Name of the Job provided during the POST request of the Job
type: string
status:
description: Status of the job
enum:
- Submitted
- Executing
- Completed
- Error
- Aborted
- Cancelled
type: string
stepStatus:
description: Status of the Current Step that the Job is undergoing
enum:
- JobCreated
- TasksCreated
- GenerateMissPDF
- PdfToZip
- PostProcessing
type: string
fileUrls:
description: Collection of S3 Pre-Signed URL(s) that can be downloaded
items:
type: string
type: array
failedDocuments:
description: Array of objects where each object contains billing document type and the IDs which failed to execute.
items:
$ref: '#/components/schemas/DocumentList'
type: array
createdOn:
description: Job Created Time
type: string
createdBy:
description: Id of the user who created the job
type: string
success:
description: Returns `true` if the request was processed successfully.
type: boolean
type: object
POSTCreateBillRunRequestType:
allOf:
- properties:
autoEmail:
default: false
description: |
Whether to automatically send emails after Auto-Post is complete.
**Note:** To use this field, you must first set the Support Bill Run Auto-Post? billing rule to **Yes** through the Zuora UI.
type: boolean
autoPost:
default: false
description: |
Whether to automatically post the bill run after the bill run is created.
**Note:** To use this field, you must first set the Support Bill Run Auto-Post? billing rule to **Yes** through the Zuora UI.
type: boolean
autoRenewal:
default: false
description: |
Whether to automatically renew auto-renew subscriptions that are up for renewal.
type: boolean
batches:
description: |
The batch of accounts for this bill run.
You can only specify either this field or the `billRunFilters` field.
**Values:** `AllBatches` or an array of `Batch*n*` where *n* is one of numbers 1 - 50, for example, `Batch7`.
**Note**: By default, you have 50 configurable account batches. To increase the limit to 200 batches, you must have the Performance Booster Elite package.
items:
type: string
type: array
billCycleDay:
description: |
The day of the bill cycle. This field is only valid if the `batches` field is specified.
**Values:**
- `AllBillCycleDays` or one of numbers 1 - 31 for an ad-hoc bill run
- `AllBillCycleDays`, one of numbers 1 - 31, or `AsRunDay` for a scheduled bill run
type: string
billRunFilters:
description: |
The target account, subscriptions, invoice schedule, or a combination of objects for this bill run. You can only specify either this field or the `batches` field.
items:
$ref: '#/components/schemas/BillRunFilterRequestType'
type: array
billRunType:
description: |
The type of the bill run. If you do not specify any value for this field, the default value is `Regular`.
- You can use this field only if the "Catch-Up Bill Run" feature is enabled.
- You must specify this field to create a catch up bill run.
**Values:**
- `Regular`
- `CatchUp`
type: string
chargeTypeToExclude:
description: |
The types of the charges to be excluded from the generation of billing documents. You can specify at most two charge types in the array.
items:
enum:
- OneTime
- Recurring
- Usage
type: string
type: array
includeSubscriptions:
default: true
description: |
Indicates whether to bill subscriptions in the bill run.
type: boolean
includeOrderLineItems:
default: true
description: |
Indicates whether to bill order line items in the bill run.
type: boolean
invoiceDate:
description: |
The invoice date for the bill run.
- When creating an ad-hoc bill run, if you do not specify any value for this field, the default value is the current date.
- When creating a scheduled bill run, if you do not specify any value for this field, the invoice date is the value of the `repeatFrom` field.
**Note**: You can use one of the following methods to specify the invoice date:
- Specify `invoiceDate`
- Specify `invoiceDateMonthOffset` and `InvoiceDateDayOfMonth`
format: date
type: string
invoiceDateMonthOffset:
description: |
The month offset of invoice date for this bill run compared to bill run execution date.
**Notes**:
- This field is only valid when the `repeatType` field is set to `Monthly`.
- You can use one of the following methods to specify the invoice date:
- Specify `invoiceDate`
- Specify `invoiceDateMonthOffset` and `InvoiceDateDayOfMonth`
type: integer
invoiceDateDayOfMonth:
description: |
The day of month of invoice date for this bill run. Specify a day of the month. If you specify 31, even though the month doesn't have 31, for example, February or April, the date recurs on the end day of each scheduled month.
**Notes**:
- This field is only valid when the `repeatType` field is set to `Monthly`.
- You can use one of the following methods to specify the invoice date:
- Specify `invoiceDate`
- Specify `invoiceDateMonthOffset` and `InvoiceDateDayOfMonth`
type: integer
maximum: 31
minimum: 1
name:
description: |
The name of the bill run.
type: string
noEmailForZeroAmountInvoice:
default: false
description: |
Whether to suppress emails for invoices with zero total amount generated in this bill run after the bill run is complete.
It is best practice to not send emails for invoices with zero amount.
type: boolean
organizationLabels:
description: |
The organization(s) that the bill run is created for.
For each item in the array, either the `organizationId` or the `organizationName` field is required.
This field is only required when you have already turned on Multi-Org feature.
items:
properties:
organizationId:
description: |
The organization ID.
type: string
organizationName:
description: |
The organization name.
type: string
type: object
type: array
schedule:
$ref: '#/components/schemas/BillRunScheduleRequestType'
targetDate:
description: |
The target date for this bill run.
- You must specify this field when creating an ad-hoc bill run.
- For scheduled bill runs, if you do not specify any value for this field, the target date is the value of the `repeatFrom` field.
format: date
type: string
targetDateMonthOffset:
description: |
The month offset of target date for this bill run compared to bill run execution date.
**Note**: This field is only valid when the `repeatType` field is set to `Monthly`.
type: integer
targetDateDayOfMonth:
description: |
The day of month of target date for this bill run. Specify a day of the month. If you specify 31, even though the month doesn't have 31, for example, February or April, the date recurs on the end day of each scheduled month.
**Note**: This field is only valid when the `repeatType` field is set to `Monthly`.
type: integer
maximum: 31
minimum: 1
type: object
example:
autoEmail: false
autoPost: false
autoRenewal: false
billRunFilters:
- accountId: 2c9081a03c63c94c013c66688a2c00bf
filterType: Subscription
subscriptionId: 402882297e387c51017e38a245c313db
chargeTypeToExclude:
- OneTime
- Usage
invoiceDate: '2020-02-01'
name: test
noEmailForZeroAmountInvoice: false
targetDate: '2020-02-01'
GetBillRunResponseType:
allOf:
- properties:
autoEmail:
description: |
Whether to automatically send emails after Auto-Post is complete.
type: boolean
autoPost:
description: |
Whether to automatically post the bill run after the bill run is created.
type: boolean
autoRenewal:
description: |
Whether to automatically renew auto-renew subscriptions that are up for renewal.
type: boolean
batches:
description: |
The batch of accounts for this bill run, this field can not exist with `billRunFilters` together.
**Values:** `AllBatches` or an array of `Batch`*n* where *n* is a number between 1 and 50, for example, `Batch7`.
items:
type: string
type: array
billCycleDay:
description: |
The day of the bill cycle, this field is only valid when `batches` is specified.
**Values:**
- `AllBillCycleDays` or one of numbers 1 - 31 for an ad-hoc bill run
- `AllBillCycleDays`, one of numbers 1 - 31, or `AsRunDay` for a scheduled bill run
type: string
billRunFilters:
description: |
The target account, subscriptions, invoice schedule, or a combination of objects for this bill run.
You can only specify either this field or the `batches` field.
items:
$ref: '#/components/schemas/BillRunFilterResponseType'
type: array
billRunNumber:
description: |
The number of the bill run.
type: string
chargeTypeToExclude:
description: |
The types of the charges to be excluded from the generation of billing documents.
items:
enum:
- OneTime
- Recurring
- Usage
type: string
type: array
createdById:
description: |
The ID of the user who created the bill run.
type: string
createdDate:
description: |
The date and time when the bill run was created.
format: date-time
type: string
includeSubscriptions:
default: true
description: |
Indicates whether to bill subscriptions in the bill run.
type: boolean
includeOrderLineItems:
default: true
description: |
Indicates whether to bill order line items in the bill run.
type: boolean
id:
description: |
The unqie ID of the bill run.
type: string
invoiceDate:
description: |
The invoice date for this bill run, only valid for ad-hoc bill runs.
format: date
type: string
invoiceDateOffset:
description: |
The offset compared to bill run execution date, only valid for scheduled bill runs.
type: integer
invoiceDateMonthOffset:
description: |
The month offset of invoice date for this bill run compared to bill run execution date.
**Note**: This field is only valid when the `repeatType` field is set to `Monthly`. When using the `invoiceDateMonthOffset` and `invoiceDateDayOfMonth` fields, do not use the `invoiceDateOffset` field, and vice versa.
type: integer
invoiceDateDayOfMonth:
description: |
The day of month of invoice date for this bill run. Specify a day of the month. If you specify 31, even though the month doesn't have 31, for example, February or April, the date recurs on the end day of each scheduled month.
**Note**: This field is only valid when the `repeatType` field is set to `Monthly`. When using the `invoiceDateMonthOffset` and `invoiceDateDayOfMonth` fields, do not use the `invoiceDateOffset` field, and vice versa.
type: integer
maximum: 31
minimum: 1
name:
description: |
The name of the bill run.
type: string
noEmailForZeroAmountInvoice:
description: |
Whether to suppress emails for invoices with zero total amount generated in this bill run after the bill run is complete.
type: boolean
organizationLabels:
description: |
The organization(s) that the run is created for.
Note: This field is available only when the Multi-Org feature is enabled.
items:
properties:
organizationId:
description: |
The organization ID.
type: string
organizationName:
description: |
The organization name.
type: string
type: object
type: array
schedule:
$ref: '#/components/schemas/BillRunScheduleResponseType'
scheduledExecutionTime:
description: |
The scheduled execution time for a bill run.
format: date-time
type: string
status:
description: |
The status of the bill run.
enum:
- Pending
- Processing
- Completed
- Error
- Canceled
- Posted
- PostInProgress
- CancelInProgress
- RemoveInProgress
- Paused
type: string
targetDate:
description: |
The target date for this bill run, only valid for ad-hoc bill runs.
format: date
type: string
targetDateOffset:
description: |
The offset compared to bill run execution date, only valid for scheduled bill runs.
type: integer
targetDateMonthOffset:
description: |
The month offset of target date for this bill run compared to bill run execution date.
**Note**: This field is only valid when the `repeatType` field is set to `Monthly`. When using the `targetDateMonthOffset` and `targetDateDayOfMonth` fields, do not use the `targetDateOffset` field, and vice versa.
type: integer
targetDateDayOfMonth:
description: |
The day of month of target date for this bill run. Specify a day of the month. If you specify 31, even though the month doesn't have 31, for example, February or April, the date recurs on the end day of each scheduled month.
**Note**: This field is only valid when the `repeatType` field is set to `Monthly`. When using the `targetDateMonthOffset` and `targetDateDayOfMonth` fields, do not use the `targetDateOffset` field, and vice versa.
type: integer
maximum: 31
minimum: 1
updatedById:
description: |
The ID of the user who last updated the bill run.
type: string
updatedDate:
description: |
The date and time when the bill run was last updated.
format: date-time
type: string
type: object
example:
autoEmail: false
autoPost: false
autoRenewal: false
batches: null
billCycleDay: 1
billRunFilters:
- accountId: 2c9081a03c63c94c013c66688a2c00bf
filterType: Subscription
subscriptionId: 402882297e387c51017e38a245c313db
billRunNumber: BR-00000016
chargeTypeToExclude:
- OneTime
- Usage
createdById: ff808081298c6e5401298c7274a40005
createdDate: '2022-01-24 19:58:27'
id: 2c9890077e8a8490017e8bf3a5171a43
invoiceDate: '2020-02-01'
invoiceDateOffset: null
name: test
noEmailForZeroAmountInvoice: false
schedule: null
scheduledExecutionTime: null
status: Pending
success: true
targetDate: '2020-02-01'
targetDateOffset: null
updatedById: ff808081298c6e5401298c7274a40005
updatedDate: '2022-01-24 19:58:27'
BillRunFilterResponseType:
allOf:
- properties:
accountId:
description: |
The target account of the bill run.
type: string
filterType:
description: |
The bill runs are created based on the selected filter type:
- `Account`: Create a bill run at account level.
- `Subscription`: Create a bill run at subscription level, you must specify the `subscriptionId` field.
- `InvoiceSchedule`: Create a scheduled bill run, you must specify the `schedule` field. See Manage scheduled bill runs.
- `FilterCondition`: Create a bill run based on a custom filter, you must specify the `condition` and `objectType` fields. See Bill Run Advanced Filter.
enum:
- Account
- Subscription
- InvoiceSchedule
- FilterCondition
type: string
condition:
$ref: '#/components/schemas/Condition'
objectType:
description: |
The target object type of the condition when the `filterType` field is specified as `FilterCondition`. See Bill Run Advanced Filter.
type: string
enum:
- Account
- Subscription
- RatePlanCharge
subscriptionId:
description: |
The target subscripiton ID of the account.
type: string
type: object
title: billRunFilters
BillRunScheduleResponseType:
allOf:
- description: |
Container for information about the scheduled bill run.
properties:
repeatFrom:
description: |
The start date of the scheduled bill run.
format: date
type: string
repeatTo:
description: |
The end date of of the scheduled bill run.
format: date
type: string
repeatType:
description: |
The repeat type of the bill run.
enum:
- None
- Daily
- Weekly
- Monthly
type: string
runTime:
description: |
The scheduled run time (hour) of day.
**Values:** 0 - 23
type: integer
weeklyOnDay:
description: |
The repeat day in a week.
items:
enum:
- Mon
- Tue
- Wed
- Thu
- Fri
- Sat
- Sun
type: string
type: array
monthlyOnEndOfMonth:
description: |
Whether to schedule monthly bill run on the end of month or the specific day of month.
**Note**: This field is available only when the `repeatType` field is set to `Monthly` and the `repeatFrom` field is set to the end of month.
For example:
- When repeatFrom = `2024-04-30` and monthlyOnEndOfMonth = `true`, next bill run will be scheduled on `2024-05-31`.
- When repeatFrom = `2024-04-30` and monthlyOnEndOfMonth = `false`, next bill run will be scheduled on `2024-05-30`.
type: boolean
type: object
title: schedule
Condition:
allOf:
- description: Container for condition information about the Bill Run Advanced Filter.
properties:
conditions:
description: |
Multiple `conditions` fields are combined by the `relation` fields. These `conditions` fields form a custom filter.
Each `conditions` field is a formula combined by the `field`, `operator`, and `value` fields. See Common use cases of Bill Run Advanced Filter.
type: array
items:
$ref: '#/components/schemas/Condition'
field:
description: |
The field name of a single condition that is indicated by the `conditions` field.
type: string
operator:
description: |
The operator of a single condition that is indicated by the `conditions` field. The operator is added between the `field` and `value` fields.
- eq: equal (`field` = `value`)
- neq: not equal (`field` != `value`)
- gt: greater than (`field` > `value`)
- lt: less than (`field` < `value`)
- gte: greater than or equal (`field` >= `value`)
- lte: less than or equal (`field` <= `value`)
- lk: like (`field` like `value`)
- in: in (`field` in `value`, the values are separated by comma)
- nl: null (`field` is null)
- nnl: not null (`field` is not null)
type: string
enum:
- eq
- neq
- gt
- lt
- gte
- lte
- lk
- in
- nl
- nnl
relation:
description: |
The relation among the `conditions` fields.
type: string
enum:
- and
- or
value:
description: |
The value of a single condition that is indicated by the `conditions` field.
type: string
type: object
title: Condition
BillRunFilterRequestType:
allOf:
- properties:
accountId:
description: |
The target account of the bill run.
If multiple subscriptions are specified, the account ID must be the same.
type: string
filterType:
description: |
To create bill runs based on the selected filter type:
- `Account`: Create bill runs by account.
- `Subscription`: Create bill runs by subscription, you must specify the `subscriptionId` field.
- `FilterCondition`: Create bill runs by custom filter combining the Account, Subscription, and Rate Plan objects, you must specify the `condition` and `objectType` fields. See Bill Run Advanced Filter.
enum:
- Account
- Subscription
- FilterCondition
type: string
condition:
$ref: '#/components/schemas/Condition'
objectType:
description: |
The target object type of the condition when the `filterType` field is specified as `FilterCondition`. See Bill Run Advanced Filter.
type: string
enum:
- Account
- Subscription
- RatePlanCharge
subscriptionId:
description: |
The target subscripiton ID of the account.
If you set the `filterType` field to `Subscription`, you must specify the `subscriptionId` field.
type: string
required:
- accountId
- filterType
type: object
title: billRunFilters
BillRunScheduleRequestType:
allOf:
- description: |
Container for information about the scheduled bill run.
properties:
repeatFrom:
description: |
The start date of the scheduled bill run.
format: date
type: string
repeatTo:
description: |
The end date of of the scheduled bill run.
format: date
type: string
repeatType:
description: |
The repeat type of the bill run.
enum:
- None
- Daily
- Weekly
- Monthly
type: string
runTime:
description: |
The scheduled run time (hour) of day.
**Values:** 0 - 23
type: integer
weeklyOnDay:
description: |
The repeat day in a week.
This field is required if you set `repeatType` field to `Weekly`.
items:
enum:
- Mon
- Tue
- Wed
- Thu
- Fri
- Sat
- Sun
type: string
type: array
monthlyOnEndOfMonth:
description: |
Whether to schedule monthly bill run on the end of month or the specific day of month.
**Note**: This field is available only when the `repeatType` field is set to `Monthly` and the `repeatFrom` field is set to the end of month.
For example:
- When repeatFrom = `2024-04-30` and `monthlyOnEndOfMonth` = `true`, next bill run will be scheduled on `2024-05-31`.
- When repeatFrom = `2024-04-30` and `monthlyOnEndOfMonth` = `false`, next bill run will be scheduled on `2024-05-30`.
type: boolean
required:
- repeatFrom
- repeatType
- runTime
type: object
title: schedule
CancelBillRunResponseType:
allOf:
- $ref: '#/components/schemas/GetBillRunResponseType'
- properties:
nextRun:
$ref: '#/components/schemas/NextRunResponseType'
type: object
example:
autoEmail: false
autoPost: false
autoRenewal: true
batches: null
billCycleDay: 1
billRunFilters: []
billRunNumber: BR-00000014
chargeTypeToExclude: null
createdById: ff808081298c6e5401298c7274a40005
createdDate: '2022-01-19 11:28:34'
id: 2c9890e97e57e546017e706109df04a1
invoiceDate: '2022-01-26'
invoiceDateOffset: 0
name: test
nextRun:
autoEmail: false
autoPost: false
autoRenewal: true
batches: null
billCycleDay: 1
billRunFilters: []
billRunNumber: BR-00000021
chargeTypeToExclude: null
createdById: ff808081298c6e5401298c7274a40005
createdDate: '2022-01-26 14:47:05'
id: 2c9890077e901749017e95235b13093d
invoiceDate: null
invoiceDateOffset: 0
noEmailForZeroAmountInvoice: false
schedule:
repeatFrom: '2022-02-28'
repeatTo: '2023-01-31'
repeatType: Monthly
runTime: 0
weeklyOnDay: null
scheduledExecutionTime: '2022-02-28 00:00:00'
status: Pending
targetDate: null
targetDateOffset: 0
updatedById: ff808081298c6e5401298c7274a40005
updatedDate: '2022-01-26 14:47:05'
noEmailForZeroAmountInvoice: false
schedule: null
scheduledExecutionTime: '2022-01-28 00:00:00'
status: CancelInProgress
success: true
targetDate: null
targetDateOffset: 0
updatedById: ff808081298c6e5401298c7274a40005
updatedDate: '2022-01-26 14:47:09'
NextRunResponseType:
allOf:
- description: |
Container about information about the next bill run to be executed.
properties:
autoEmail:
description: |
Whether to automatically send emails after Auto-Post is complete.
type: boolean
autoPost:
description: |
Whether to automatically post the bill run after the bill run is created.
type: boolean
autoRenewal:
description: |
Whether to automatically renew auto-renew subscriptions that are up for renewal.
type: boolean
batches:
description: |
The batch of accounts for this bill run.
**Values:** `AllBatches` or an array of `Batch`*n* where *n* is one of numbers 1 - 50, for example, `Batch7`.
items:
type: string
type: array
billCycleDay:
description: |
The day of the bill cycle. This field is only valid if the `batches` field is specified.
**Values:**
- `AllBillCycleDays` or one of numbers 1 - 31 for an ad-hoc bill run
- `AllBillCycleDays`, one of numbers 1 - 31, or `AsRunDay` for a scheduled bill run
type: string
billRunFilters:
description: |
The target account or subscriptions for this bill run.
items:
$ref: '#/components/schemas/BillRunFilterResponseType'
type: array
billRunNumber:
description: |
The number of the bill run.
type: string
chargeTypeToExclude:
description: |
The types of the charges to be excluded from the generation of billing documents.
items:
enum:
- OneTime
- Recurring
- Usage
type: string
type: array
createdById:
description: |
The ID of the user who created the bill run.
type: string
createdDate:
description: |
The date and time when the bill run was created.
format: date-time
type: string
id:
description: |
The ID of the bill run.
type: string
invoiceDate:
description: |
The invoice date for this bill run, only valid for ad-hoc bill runs.
format: date
type: string
invoiceDateOffset:
description: |
The offset compared to the bill run execution date, only valid for scheduled bill runs.
type: integer
noEmailForZeroAmountInvoice:
description: |
Whether to suppress emails for invoices with zero total amount generated in this bill run after the bill run is complete.
type: boolean
schedule:
$ref: '#/components/schemas/BillRunScheduleResponseType'
scheduledExecutionTime:
description: |
The scheduled execution time for the bill run.
format: date-time
type: string
status:
description: |
The status of the bill run.
enum:
- Pending
- Processing
- Completed
- Error
- Canceled
- Posted
- PostInProgress
- CancelInProgress
- RemoveInProgress
- Paused
type: string
targetDate:
description: |
The target date for this bill run, only valid for ad-hoc bill runs.
format: date
type: string
targetDateOffset:
description: |
The offset compared to the bill run execution date, only valid for scheduled bill runs.
type: integer
updatedById:
description: |
The ID of the user who last updated the bill run.
type: string
updatedDate:
description: |
The date and time when the bill run was last updated.
format: date-time
type: string
type: object
example:
autoEmail: false
autoPost: false
autoRenewal: false
batches: null
billCycleDay: null
billRunFilters:
- accountId: 2c9081a03c63c94c013c66688a2c00bf
filterType: Subscription
subscriptionId: 402882297e387c51017e38a245c313db
billRunNumber: BR-00000016
chargeTypeToExclude:
- OneTime
- Usage
createdById: ff808081298c6e5401298c7274a40005
createdDate: '2022-01-24 19:58:27'
id: 2c9890077e8a8490017e8bf3a5171a43
invoiceDate: '2020-02-01'
invoiceDateOffset: null
noEmailForZeroAmountInvoice: false
schedule: null
scheduledExecutionTime: null
status: Pending
success: true
targetDate: '2020-02-01'
targetDateOffset: null
updatedById: ff808081298c6e5401298c7274a40005
updatedDate: '2022-01-24 19:58:27'
title: nextRun
POSTEmailBillingDocfromBillRunType:
example:
resend: 'true'
properties:
resend:
default: false
description: |
Whether to send out emails for all the billing documents that are associated with the bill run.
- If the value is `false`, emails are sent out only for the billing documents that never have emails sent out. **Note**: Do not perform this API operation with the `resend` field set to `false` multiple times in a short period. Otherwise, you may receive the same email multiple times, which contradicts the purpose of this setting.
- If the value is `true`, emails are sent out for all the billing documents.
type: boolean
type: object
PostBillingPreviewRunParam:
example:
batches: Batch1
targetDate: '2024-11-05'
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.
Set one of the following values in this field to decide how the assumption is applied in the billing preview.
* **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.
* **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.
* 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.
* 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.
* **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.
**Note:**
- This field can only be used if the subscription renewal term is not set to 0.
- 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
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.
**Note**:
- By default, you have 50 configurable account batches. To increase the limit to 200 batches, you must have the Performance Booster Elite package.
- This field is available only if you are on the latest Zuora API version, or you set the `Zuora-Version` request header to `314.0` or [a later available version](https://developer.zuora.com/v1-api-reference/api-versions/#minor-version).
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.
For each item in the array, either the `organizationId` or the `organizationName` field is required.
This field is only required when you have already turned on Multi-Org feature.
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`.
To compare the current billing preview run result with a specified billing preview run result and store the difference in the database, you must set the `storageOption` field to `Database`. For more information, see [Billing Preview Run Result data source](https://knowledgecenter.zuora.com/Zuora_Central_Platform/Reporting/D_Data_Sources_and_Exports/C_Data_Source_Reference/Billing_Preview_Run_Result_data_source).
enum:
- Csv
- Database
type: string
storeDifference:
description: |
Specify this field to `yes` to compare the current billing preview run result with a specified billing preview run result and store the difference in the database. You can view the difference in the Billing Preview Run Result Difference data source. **Note**: This feature is in the **Early Adopter** phase. If you want to use the feature, submit a request at Zuora Global Support.
The default value is `false`.
type: boolean
comparedBillingPreviewRunId:
description: |
Specify an existing billing preview run result to compare the current billing preview result with. You can view the difference in the Billing Preview Run Result Difference data source. **Note**: This feature is in the **Early Adopter** phase. If you want to use the feature, submit a request at Zuora Global Support.
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.
The value for the `targetDate` field must be in _`YYYY-MM-DD`_ format.
If 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.
**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.
format: date
type: string
filters:
$ref: '#/components/schemas/BillingPreviewRunFilter'
required:
- targetDate
type: object
BillingPreviewRunFilter:
type: array
description: |
A list of filters to apply to the billing preview run. You can specify only one filter.
maxItems: 1
items:
type: object
properties:
filterType:
description: |
The type of filter to apply.
enum:
- Account
type: string
accountId:
description: |
The target account ID.
type: string
pattern: ^[0-9a-fA-F]{32}$
required:
- filterType
- accountId
GetBillingPreviewRunResponse:
description: get billingPreviewRun response
properties:
assumeRenewal:
description: ''
type: string
batches:
description: |
The customer batches included in the billing preview run.
**Note**: This field is available only if you are on the latest Zuora API minor version, or you set the `Zuora-Version` request header to `314.0` or [a later available version](https://developer.zuora.com/v1-api-reference/api-versions/#minor-version).
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.
Note: This field is available only when the Multi-Org feature is enabled.
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.
**Possible values:**
* 0: Pending
* 1: Processing
* 2: Completed
* 3: Error
* 4: Canceled
type: string
storageOption:
description: |
The saving options. The default value is `Csv`.
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.
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
POSTPaymentMethodResponse:
allOf:
- $ref: '#/components/schemas/CommonResponse'
- properties:
id:
description: |
Internal ID of the payment method that was created.
type: string
reasons:
items:
description: |
Error information. Only applicable if the payment method was not created.
properties:
code:
description: |
Error code.
type: string
message:
description: |
Error message.
type: string
type: object
type: array
type: object
POSTPaymentMethodDecryption:
example:
accountID: 402891a25a02e11c015a02f3c6100003
cardHolderInfo:
cardHolderName: Amy Lawrence
addressLine1: 101 Redwood Shores Parkway
city: Redwood City
country: USA
integrationType: ApplePay
invoiceId: INV000000005
merchantID: merchant.US.com.zuora.services001
mitConsentAgreementSrc: External
mitProfileAction: Activate
mitProfileType: Recurring
paymentGateway: CyberSourceOPG
paymentToken:
data: xGc......JDxuYz1gug0KZRrGXJQ=
header:
ephemeralPublicKey: MFkwEw......TMbLoojKBA==
publicKeyHash: HuLvfqvLon......9jEyX0w=
transactionId: abbadd18818baea1f37b40844c9e09afa9733b0eccb373905b811da43cf1753b
signature: MIAGCSqGSIb......AEtrLSv7hE9gAAAAAAAA==
version: EC_v1
processPayment: true
properties:
accountID:
description: |-
The ID of the customer account associated with this payment method.
To create an orphan payment method that is not associated with any customer account, you can skip this field. As soon as the account information is available, associate the payment method with an account through the [Update a payment method](https://developer.zuora.com/v1-api-reference/api/operation/PUT_PaymentMethod/) operation.
type: string
cardHolderInfo:
$ref: '#/components/schemas/CreateApplePayPaymentMethodCardholderInfo'
integrationType:
description: |
Field to identify the token decryption type.
**Note:** The only value at this time is `ApplePay`.
type: string
invoiceId:
description: |
The id of invoice this payment will apply to.
**Note:** When `processPayment` is `true`, this field is required.
Only one invoice can be paid; for scenarios where you want to pay for multiple invoices, set `processPayment` to `false` and call payment API separately.
type: string
merchantID:
description: |
The Merchant ID that was configured for use with Apple Pay in the Apple iOS Developer Center.
type: string
mitConsentAgreementSrc:
description: |
This field is only available for the following gateway integrations to create stored credential profiles within payment methods:
- Chase Paymentech Orbital Gateway
- CyberSource Payment API v2.0
- Stripe v2
- Vantiv (Now Worldpay)
- Worldpay 1.4
Specify how the consent agreement has been established with the customer. The allowed value is `External`. It is required if the `mitProfileAction` field is specified. If you do not specify the `mitProfileAction` field, Zuora will automatically create a stored credential profile for the payment method, with the default value `External` set to this field.
enum:
- External
type: string
mitProfileAction:
description: |
This field is only available for the following gateway integrations to create stored credential profiles within payment methods:
- Chase Paymentech Orbital Gateway
- CyberSource Payment API v2.0
- Stripe v2
- Vantiv (Now Worldpay)
- Worldpay 1.4
Specify either of the following values in this field:
- `Activate` - Use this value if you are creating the stored credential profile after receiving the customer's consent.
Zuora will create the stored credential profile then send a cardholder-initiated transaction (CIT) to the payment gateway to validate the stored credential profile. If the CIT succeeds, the status of the stored credential profile will be `Active`. If the CIT does not succeed, Zuora will not create a stored credential profile.
If the payment gateway does not support the stored credential transaction framework, the status of the stored credential profile will be `Agreed`.
- `Persist` - Use this value if the stored credential profile represents a stored credential profile in an external system. The status of the payment method's stored credential profile will be `Active`.
If you do not specify this field, Zuora will automatically create a stored credential profile for the payment method, with the default value `Activate` set to this field.
enum:
- Activate
- Persist
type: string
mitProfileType:
description: |
This field is only available for the following gateway integrations to create stored credential profiles within payment methods:
- Chase Paymentech Orbital Gateway
- CyberSource Payment API v2.0
- Stripe v2
- Vantiv (Now Worldpay)
- Worldpay 1.4
This field indicates the type of the stored credential profile to process recurring or unsecheduled transactions. It is required if the `mitProfileAction` field is specified. If you do not specify the `mitProfileAction` field, Zuora will automatically create a stored credential profile for the payment method, with the default value `Recurring` set to this field.
enum:
- Recurring
- Unscheduled
type: string
paymentGateway:
description: |
The label name of the gateway instance configured in Zuora that will be used for
payment method validation and payment processing.
- When `processPayment` is `true`, this `paymentGateway` field is required.
- When `processPayment` is `false` or is not provided, the specified gateway instance will be used for
payment method validation.
Specify a valid gateway instance and it must support the Apple Pay payment method.
If not specified, the default gateway of your Zuora customer account will be used.
type: string
paymentToken:
description: |
The payload with the Apple Pay token or payment data.
type: object
processPayment:
description: |
A boolean flag to control whether a payment should be processed after
creating payment method. The payment amount will be equivalent to the
amount the merchant supplied in the ApplePay session. Default is false.
If this field is set to `true`, you must specify the `paymentGateway`
field with the payment gateway instance name.
If this field is set to `false`:
- You must select the **Verify new credit card** check box on the gateway instance settings page. Otherwise, the cryptogram will not be sent to the gateway.
- A separate subscribe or payment API call is required after this payment method creation call.
type: boolean
required:
- integrationType
- merchantID
- paymentToken
type: object
POSTPaymentMethodResponseDecryption:
properties:
amount:
description: |
The payment amount contained within the encrypted token.
type: string
paymentId:
description: |
The ID of newly processed payment,
type: string
paymentMethodId:
description: |
ID of the newly-created payment method.
type: string
success:
description: |
Returns `true` if the request was processed successfully.
type: boolean
type: object
CreateApplePayPaymentMethodCardholderInfo:
description: |
The container for the cardholder information.
The cardholder name is required for credit card validation. It is strongly recommended to specify the nested `cardHolderName` field in this container. For more information, see `cardHolderName`.
The required cardholder address fields vary by gateway. It is strongly recommended to review the gateway's documentation for the most accurate and up-to-date information.
properties:
addressLine1:
description: |
The first address line.
maxLength: 255
type: string
addressLine2:
description: |
The second address line.
maxLength: 255
type: string
cardHolderName:
description: |
The cardholder's full name as it appears on the card.
The cardholder name information is required for credit card validation.
Zuora retrieves the cardholder name using the following priority:
1. This `cardHolderName` field if available.
2. The cardholder name in the `paymentToken` field if available.
3. The full bill-to-contact name of the customer account.
It is strongly recommended to provide the cardholder name through this field.
maxLength: 50
type: string
city:
description: |
The city.
It is recommended to provide the city and country information when
creating a payment method. The information will be used to process
payments. If the information is not provided during payment method
creation, the city and country data will be missing during payment
processing.
maxLength: 40
type: string
country:
description: |
The country, which must be a valid country name or abbreviation.
It is recommended to provide the city and country information when
creating a payment method. The information will be used to process
payments. If the information is not provided during payment method
creation, the city and country data will be missing during payment
processing.
type: string
email:
description: |
The cardholder's email address.
maxLength: 80
type: string
phone:
description: |
The phone number.
maxLength: 40
type: string
state:
description: |
The state, which must be a valid subregion (state or province) name or code. For more information, see View subregions of a specific country or region.
type: string
zipCode:
description: |
The zip code.
maxLength: 20
type: string
title: CardHolderInfo
type: object
GETPaymentMethodResponse:
allOf:
- properties:
accountHolderInfo:
$ref: '#/components/schemas/GETPMAccountHolderInfo'
accountVerificationService:
description: |
Displays the name of the service provider. For example, Plaid.
type: string
accountVerificationStatus:
description: |
Displays the status of the account.
**Note:**
- `Active` - Access token is active.
- `Expired` - Access token has expired and must be linked again.
- `Expiring` - Access token will expire in few days(7 days for Plaid) and must be linked again
- `Inactive` - The end customer has revoked the account permission. The end customer can login again and select the same method for the access token to be linked again.
enum:
- Active
- Expired
- Expiring
- Inactive
type: string
bankIdentificationNumber:
description: |
The first six or eight digits of the payment method's number, such as the credit card number or account number. Banks use this number to identify a payment method.
type: string
createdBy:
description: ID of the user who created this payment method.
type: string
createdOn:
description: |
The date and time when the payment method was created, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
creditCardMaskNumber:
description: |
The masked credit card number, such as:
```
*********1112
```
type: string
creditCardType:
description: |
The type of the credit card or debit card.
Possible values include `Visa`, `MasterCard`, `AmericanExpress`, `Discover`, `JCB`, and `Diners`. For more information about credit card types supported by different payment gateways, see [Supported Payment Gateways](https://knowledgecenter.zuora.com/CB_Billing/M_Payment_Gateways/Supported_Payment_Gateways).
**Note:** This field is only returned for the Credit Card and Debit Card payment types.
type: string
deviceSessionId:
description: |
The session ID of the user when the `PaymentMethod` was created or updated.
type: string
existingMandate:
description: |
Indicates whether the mandate is an existing mandate.
enum:
- 'Yes'
- 'No'
type: string
id:
description: |
The payment method ID.
type: string
ipAddress:
description: |
The IP address of the user when the payment method was created or updated.
type: string
isDefault:
description: |
Indicates whether this payment method is the default payment method for the account.
type: boolean
lastFailedSaleTransactionDate:
description: |
The date of the last failed attempt to collect payment with this payment method.
format: date-time
type: string
lastTransaction:
description: Indicates the occurrence and status of the last transaction.
type: string
lastTransactionTime:
description: The time when the last transaction of this payment method happened.
format: date-time
type: string
mandateInfo:
$ref: '#/components/schemas/POSTPMMandateInfo'
maxConsecutivePaymentFailures:
description: |
The number of allowable consecutive failures Zuora attempts with the payment method before stopping.
type: integer
numConsecutiveFailures:
description: |
The number of consecutive failed payments for this payment method. It is reset to `0` upon successful payment.
format: int32
type: integer
paymentRetryWindow:
description: |
The retry interval setting, which prevents making a payment attempt if the last failed attempt was within the last specified number of hours.
type: integer
secondTokenId:
description: |
A gateway unique identifier that replaces sensitive payment method data.
**Note:** This field is only returned for the Credit Card Reference Transaction payment type.
type: string
status:
description: |
The status of the payment method.
enum:
- Active
- Closed
- Scrubbed
type: string
tokenId:
description: |
A gateway unique identifier that replaces sensitive payment method data or represents a gateway's unique customer profile.
**Note:** This field is only returned for the Credit Card Reference Transaction payment type.
type: string
totalNumberOfErrorPayments:
description: |
The number of error payments that used this payment method.
format: int32
type: integer
totalNumberOfProcessedPayments:
description: |
The number of successful payments that used this payment method.
format: int32
type: integer
type:
description: |
The type of the payment method.
type: string
enum:
- CreditCard
- CreditCardReferenceTransaction
- ACH
- SEPA
- Betalingsservice
- Autogiro
- Bacs
- Becs
- Becsnz
- PAD
- PayPalCP
- PayPalEC
- PayPalNativeEC
- PayPalAdaptive
- AdyenApplePay
- AdyenGooglePay
- GooglePay
updatedBy:
description: ID of the user who made the last update to this payment method.
type: string
updatedOn:
description: |
The last date and time when the payment method was updated, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
useDefaultRetryRule:
description: |
Indicates whether this payment method uses the default retry rules configured in the Zuora Payments settings.
type: boolean
cardBinInfo:
description: |
The BIN information of a card payment method.
properties:
brand:
description: |
The card brand, such as `Visa` and `MasterCard`.
type: string
cardClass:
description: |
The type of the card.
type: string
enum:
- ChargeCard
- Credit
- Debit
- DeferredDebit
- Prepaid
productType:
description: |
The product type of the card.
type: string
enum:
- Commercial_or_Corporate_Card
- Consumer_Card
issuer:
description: |
The issuer bank of the card, such as `JPMORGAN CHASE BANK N.A.`.
type: string
issuingCountryCode:
description: |
The issuing country code of the card, such as `US`.
type: string
type: object
type: object
- $ref: '#/components/schemas/PaymentMethodObjectCustomFields'
- $ref: '#/components/schemas/GETPaymentMethodResponseBankTransfer'
- $ref: '#/components/schemas/GETPaymentMethodResponseACH'
- $ref: '#/components/schemas/GETPaymentMethodResponseCreditCard'
- $ref: '#/components/schemas/GETPaymentMethodResponsePayPal'
- $ref: '#/components/schemas/GETPaymentMethodResponseGooglePay'
- $ref: '#/components/schemas/GETPaymentMethodResponseApplePay'
GETPMAccountHolderInfo:
description: |
The account holder information.
properties:
accountHolderName:
description: |
The full name of the account holder.
type: string
addressLine1:
description: |
The first line of the address for the account holder.
type: string
addressLine2:
description: |
The second line of the address for the account holder.
type: string
city:
description: |
The city where the account holder stays.
type: string
country:
description: |
The country where the account holder stays.
When creating a payment method through a translated UI or Payment Page, a country name in a translated language might be selected. Regardless of the country texts selected when creating the payment method, only the supported country name returns in this field. For a complete list of supported country names, see View countries or regions. Internationalization is not supported for the API field value.
type: string
email:
description: |
The email address of the account holder.
type: string
phone:
description: |
The phone number of the account holder.
type: string
state:
description: |
The state where the account holder stays.
type: string
zipCode:
description: |
The zip code for the address of the account holder.
type: string
title: accountHolderInfo
type: object
POSTPMMandateInfo:
description: |
The mandate information for the Credit Card, Apple Pay, Google Pay, Credit Card Reference Transaction, ACH, or Bank Transfer payment method.
The following mandate fields are common to all supported payment methods:
* `mandateId`
* `mandateReason`
* `mandateStatus`
The following mandate fields are specific to the ACH and Bank Transfer payment methods:
* `mandateReceivedStatus`
* `existingMandateStatus`
* `mandateCreationDate`
* `mandateUpdateDate`
The following mandate fields are specific to the Credit Card, Apple Pay, and Google Pay payment methods:
* `mitTransactionId`
* `mitProfileAgreedOn`
* `mitConsentAgreementRef`
* `mitConsentAgreementSrc`
* `mitProfileType`
* `mitProfileAction`
properties:
existingMandateStatus:
description: |
Indicates whether the mandate is an existing mandate.
enum:
- 'Yes'
- 'No'
type: string
mandateCreationDate:
description: |
The date on which the mandate was created.
format: date
type: string
mandateId:
description: |
The mandate ID.
type: string
mandateReason:
description: |
The reason of the mandate from the gateway side.
type: string
mandateReceivedStatus:
description: |
Indicates whether the mandate is received from the gateway
enum:
- 'Yes'
- 'No'
type: string
mandateStatus:
description: |
The status of the mandate from the gateway side.
type: string
mandateUpdateDate:
description: |
The date on which the mandate was updated.
format: date
type: string
mitConsentAgreementRef:
description: |
Reference for the consent agreement that you have established with the customer.
type: string
mitConsentAgreementSrc:
description: |
Required if you set the `mitProfileAction` field. Specifies how the consent agreement has been established with the customer. The allowed value is `External`. If you do not specify the `mitProfileAction` field, Zuora will automatically create a stored credential profile for the payment method, with the default value `External` set to this field.
enum:
- External
type: string
mitProfileAction:
description: |
Specifies how Zuora creates and activates the stored credential profile. Only applicable if you set the `status` field to `Active`.
- `Activate` (default) - Use this value if you are creating the stored credential profile after receiving the customer's consent.
Zuora will create the stored credential profile then send a cardholder-initiated transaction (CIT) to the payment gateway to validate the stored credential profile. If the CIT succeeds, the status of the stored credential profile will be `Active`. If the CIT does not succeed, Zuora will not create a stored credential profile.
If the payment gateway does not support the stored credential transaction framework, the status of the stored credential profile will be `Agreed`.
- `Persist` - Use this value if the stored credential profile represents a stored credential profile in an external system. The status of the payment method's stored credential profile will be `Active`.
If you do not specify this field, Zuora will automatically create a stored credential profile for the payment method, with the default value `Activate` set to this field.
enum:
- Activate
- Persist
type: string
mitProfileAgreedOn:
description: |
The date on which the stored credential profile is agreed. The date format is `yyyy-mm-dd`.
format: date
type: string
mitProfileType:
description: |
Indicates the type of the stored credential profile. If you do not specify the `mitProfileAction` field, Zuora will automatically create a stored credential profile for the payment method, with the default value `Recurring` set to this field.
type: string
mitTransactionId:
description: |
Specifies the ID of the transaction. Only applicable if you set the `mitProfileAction` field to `Persist`.
maxLength: 128
type: string
title: mandateInfo
type: object
GETPaymentMethodResponseBankTransfer:
properties:
IBAN:
description: |
The International Bank Account Number used to create the SEPA payment method. The value is masked.
type: string
accountNumber:
description: |
The number of the customer's bank account and it is masked.
type: string
bankCode:
description: |
The sort code or number that identifies the bank. This is also known as the sort code.
type: string
bankTransferType:
description: |
The type of the Bank Transfer payment method. For example, `SEPA`.
type: string
branchCode:
description: |
The branch code of the bank used for Direct Debit.
type: string
businessIdentificationCode:
description: |
The BIC code used for SEPA. The value is masked.
type: string
identityNumber:
description: |
The identity number of the account holder or the cardholder.
type: string
type: object
GETPaymentMethodResponseACH:
properties:
bankABACode:
description: |
The nine-digit routing number or ABA number used by banks. This field is only required if the `type` field is set to `ACH`.
type: string
bankAccountName:
description: |
The name of the account holder, which can be either a person or a company. This field is only required if the `type` field is set to `ACH`.
type: string
bankAccountNumber:
description: |
The bank account number associated with the ACH payment. This field is only required if the `type` field is set to `ACH`.
type: string
bankAccountType:
description: |
The type of bank account associated with the ACH payment. This field is only required if the `type` field is set to `ACH`.
When creating an ACH payment method on Adyen, this field is required by Zuora but it is not required by Adyen. To create the ACH payment method successfully, specify a real value for this field if you can. If it is not possible to get the real value for it, specify any of the allowed values as a dummy value, `Checking` preferably.
enum:
- BusinessChecking
- Checking
- Saving
type: string
bankName:
description: |
The name of the bank where the ACH payment account is held. This field is only required if the `type` field is set to `ACH`.
When creating an ACH payment method on Adyen, this field is required by Zuora but it is not required by Adyen. To create the ACH payment method successfully, specify a real value for this field if you can. If it is not possible to get the real value for it, specify a dummy value.
type: string
type: object
GETPaymentMethodResponseCreditCard:
properties:
cardNumber:
description: |
The masked credit card number.
When `cardNumber` is `null`, the following fields will not be returned:
- `expirationMonth`
- `expirationYear`
- `accountHolderInfo`
type: string
expirationMonth:
description: |
One or two digits expiration month (1-12).
type: integer
expirationYear:
description: |
Four-digit expiration year.
type: integer
securityCode:
description: |
The CVV or CVV2 security code for the credit card or debit card.
Only required if changing expirationMonth, expirationYear, or cardHolderName.
To ensure PCI compliance, this value isn''t stored and can''t be queried.
type: string
type: object
GETPaymentMethodResponsePayPal:
properties:
BAID:
description: |
ID of a PayPal billing agreement. For example, I-1TJ3GAGG82Y9.
type: string
email:
description: |
Email address associated with the PayPal payment method.
type: string
preapprovalKey:
description: |
The PayPal preapproval key.
type: string
type: object
GETPaymentMethodResponseGooglePay:
properties:
googleBIN:
description: |
This field is only available for Google Pay payment methods.
type: string
googleCardNumber:
description: |
This field is only available for Google Pay payment methods.
type: string
googleCardType:
description: |
This field is only available for Google Pay payment methods.
For Google Pay payment methods on Adyen, the first 100 characters of [paymentMethodVariant](https://docs.adyen.com/development-resources/paymentmethodvariant) returned from Adyen are stored in this field.
type: string
googleExpiryDate:
description: |
This field is only available for Google Pay payment methods.
type: string
googleGatewayToken:
description: |
This field is only available for Google Pay payment methods.
type: string
type: object
GETPaymentMethodResponseApplePay:
properties:
appleBIN:
description: |
This field is only available for Apple Pay payment methods.
type: string
appleCardNumber:
description: |
This field is only available for Apple Pay payment methods.
type: string
appleCardType:
description: |
This field is only available for Apple Pay payment methods.
For Apple Pay payment methods on Adyen, the first 100 characters of [paymentMethodVariant](https://docs.adyen.com/development-resources/paymentmethodvariant) returned from Adyen are stored in this field.
type: string
appleExpiryDate:
description: |
This field is only available for Apple Pay payment methods.
type: string
appleGatewayToken:
description: |
This field is only available for Apple Pay payment methods.
type: string
type: object
PUTPaymentMethodRequest:
allOf:
- properties:
accountHolderInfo:
$ref: '#/components/schemas/PUTPMAccountHolderInfo'
accountKey:
description: |
The customer account ID such as `2x92c0f859b0480f0159d3a4a6ee5bb6` or the customer account number such as `A02855638`.
**Note:** You can use this field to associate an orphan payment method with a customer account. If a payment method is already associated with a customer account, you cannot change the associated payment method through this operation. You cannot remove the previous account ID and leave this field empty, either.
type: string
authGateway:
description: |
Specifies the ID of the payment gateway that Zuora will use to authorize the payments that are made with the payment method.
This field is not supported in updating Credit Card Reference Transaction payment methods.
If Payment Gateway Routing is enabled:
- If this field is not specified, gateway routing rules will be invoked.
- If this field is specified, the specified gateway will be used to update the payment.
If Payment Gateway Routing is disabled:
- If this field is not specified, the default payment gateway will be used to update the payment. The default gateway of the customer account takes precedence over the default gateway of the tenant.
- If this field is specified, the specified gateway will be used to update the payment.
type: string
currencyCode:
description: |
The currency used for payment method authorization.
type: string
gatewayOptions:
description: |
The field used to pass gateway-specific parameters and parameter values. The fields supported by gateways vary. For more information, see the Overview topic of each gateway integration in [Zuora Knowledge Center](https://knowledgecenter.zuora.com/Zuora_Billing/Billing_and_Payments/M_Payment_Gateways/Supported_Payment_Gateways).
Zuora sends all the information that you specified to the gateway. If you specify any unsupported gateway option parameters, they will be ignored without error prompts.
This field is not supported in updating Credit Card Reference Transaction payment methods.
properties:
key:
description: |
The name of a gateway-specific parameter.
type: string
value:
description: |
The value of the gateway-specific parameter.
type: string
type: object
ipAddress:
description: |
The IPv4 or IPv6 information of the user when the payment method is created or updated. Some gateways use this field for fraud prevention. If this field is passed to Zuora, Zuora directly passes it to gateways.
If the IP address length is beyond 45 characters, a validation error occurs.
For validating SEPA payment methods on Stripe v2, this field is required.
type: string
mandateInfo:
description: |
The mandate information for the Credit Card, Credit Card Reference Transaction, ACH, or Bank Transfer payment method.
properties:
mandateId:
description: |
The mandate ID.
maxLength: 36
type: string
mandateReason:
description: |
The reason of the mandate from the gateway side.
maxLength: 64
type: string
mandateStatus:
description: |
The status of the mandate from the gateway side.
maxLength: 64
type: string
type: object
processingOptions:
description: |
The container for payment method processing options.
properties:
checkDuplicated:
description: |
Indicates whether to perform a duplication check when you create a payment method of the following types:
- Credit Card
- ACH
- Bank Transfer
The default value is `false`.
With this field set to `true`, Zuora will check the active and closed payment methods associated with the same billing account to ensure that no duplicate payment methods are created.
For more information, see Duplication check on payment methods.
type: boolean
type: object
maxConsecutivePaymentFailures:
description: |
The maximum number of payment failures allowed for this payment method.
This field is only applicable if `useDefaultRetryRule` is set to `false`.
type: integer
minimum: 1
maximum: 100
nullable: true
paymentRetryWindow:
description: |
The retry interval in hours.
This field is only applicable if `useDefaultRetryRule` is set to `false`.
type: integer
minimum: 1
maximum: 1000
nullable: true
useDefaultRetryRule:
description: |
Specifies whether to apply the default retry rule configured for your tenant in the Zuora Payments settings:
- To use the default retry rule, specify `true`.
- To use the custom retry rule specific to this payment method, specify `false`.
type: boolean
type: object
- $ref: '#/components/schemas/PUTPMCreditCardInfo'
- $ref: '#/components/schemas/PUTPaymentMethodObjectCustomFields'
example:
securityCode: '331'
PUTPaymentMethodResponse:
properties:
id:
description: |
ID of the updated payment method.
type: string
success:
description: |
Returns `true` if the request was processed successfully.
type: boolean
type: object
PUTPMAccountHolderInfo:
description: |
The account holder information. This field is not supported in updating Credit Card Reference Transaction payment methods.
properties:
addressLine1:
description: |
The first line of the address for the account holder.
This field is required for SEPA Direct Debit payment methods on Stripe v2 for [certain countries](https://stripe.com/docs/payments/sepa-debit/set-up-payment?platform=web#web-submit-payment-method).
type: string
addressLine2:
description: |
The second line of the address for the account holder.
type: string
city:
description: |
The city where the account holder stays.
type: string
country:
description: |
The country where the account holder stays.
This field is required for SEPA payment methods on Stripe v2 for [certain countries](https://stripe.com/docs/payments/sepa-debit/set-up-payment?platform=web#web-submit-payment-method).
type: string
email:
description: |
The email address of the account holder.
type: string
phone:
description: |
The phone number of the account holder.
type: string
state:
description: |
The state where the account holder stays.
type: string
zipCode:
description: |
The zip code for the address of the account holder.
type: string
title: accountHolderInfo
type: object
PUTPMCreditCardInfo:
properties:
expirationMonth:
description: |
One or two digits expiration month (1-12).
type: integer
expirationYear:
description: |
Four-digit expiration year.
type: integer
securityCode:
description: |
Optional. It is the CVV or CVV2 security code specific for the credit card or debit card. To ensure PCI compliance, this value is not stored and cannot be queried.
If securityCode code is not passed in the request payload, this operation only updates related fields in the payload. It does not validate the payment method through the gateway.
If securityCode is passed in the request payload, this operation retrieves the credit card information from payload and validates them through the gateway.
type: string
type: object
PUTPaymentMethodObjectCustomFields:
additionalProperties:
description: |
Custom fields of the payment method. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
Custom fields are not supported in updating Credit Card Reference Transaction payment methods.
description: |
Container for custom fields of a payment method object.
title: paymentMethodFieldsCustom
type: object
PUTVerifyPaymentMethodType:
example:
securityCode: '737'
properties:
currencyCode:
description: |
The currency used for payment method authorization.
type: string
gatewayOptions:
description: |
The field used to pass gateway-specific parameters and parameter values. The fields supported by gateways vary. For more information, see the Overview topic of each gateway integration in [Zuora Knowledge Center](https://knowledgecenter.zuora.com/Zuora_Billing/Billing_and_Payments/M_Payment_Gateways/Supported_Payment_Gateways).
Zuora sends all the information that you specified to the gateway. If you specify any unsupported gateway option parameters, they will be ignored without error prompts.
properties:
key:
description: |
The name of a gateway-specific parameter.
type: string
value:
description: |
The value of the gateway-specific parameter.
type: string
type: object
paymentGatewayName:
description: |
The name of the payment gateway instance.
If Payment Gateway Routing is enabled:
- If this field is not specified, gateway routing rules will be invoked.
- If this field is specified, the specified gateway will be used to verify the payment.
If Payment Gateway Routing is disabled:
- If this field is not specified, the default payment gateway will be used to verify the payment. The default gateway of the customer account takes precedence over the default gateway of the tenant.
- If this field is specified, the specified gateway will be used to verify the payment.
type: string
securityCode:
description: |
The CVV or CVV2 security code for the credit card or debit card. To ensure PCI compliance, the value of this field is not stored and cannot be queried.
type: string
type: object
PUTVerifyPaymentMethodResponseType:
properties:
paymentMethodId:
description: |
The ID of the verified payment method.
type: string
success:
description: |
Returns `true` if the request was processed successfully.
type: boolean
type: object
GetBankAccountBalanceResponse:
properties:
success:
description: |
Indicates whether this call succeeds.
type: boolean
currency:
description: |
The currency of the account balance.
type: string
availableBalance:
description: |
The amount of funds available to be withdrawn from the account.
For more information, see Plaid's documentation.
type: number
format: double
currentBalance:
description: |
The total amount of funds in the account, which does not take pending transactions into account.
For more information, see Plaid's documentation.
type: number
format: double
type: object
GetStoredCredentialProfilesResponse:
properties:
profiles:
description: |
Container for stored credential profiles.
items:
properties:
activatedOn:
description: |
The date when the stored credential profile was activated (if applicable).
format: date-time
type: string
agreedOn:
description: |
The date when the stored credential profile was created.
format: date-time
type: string
brand:
description: |
The stored credential transaction framework. For example, Visa.
type: string
cancelledOn:
description: |
The date when the stored credential profile was cancelled (if applicable).
format: date-time
type: string
consentAgreementRef:
description: |
Your reference for the consent agreement that you have established with the customer.
maxLength: 128
type: string
consentAgreementSrc:
enum:
- External
type: string
expiredOn:
description: |
The date when the stored credential profile was expired (if applicable).
format: date-time
type: string
number:
description: |
The number that identifies the stored credential profile within the payment method.
type: integer
paymentMethodId:
description: |
ID of the payment method.
type: string
status:
description: |
The status of the stored credential profile.
* `Agreed` - The stored credential profile has not been validated via an authorization transaction with the payment gateway.
* `Active` - The stored credential profile has been validated via an authorization transaction with the payment gateway.
* `Cancelled` - The stored credentials are no longer valid, per a customer request. Zuora cannot use the stored credentials in transactions.
* `Expired` - The stored credentials are no longer valid, per an expiration policy in the stored credential transaction framework. Zuora cannot use the stored credentials in transactions.
enum:
- Agreed
- Active
- Cancelled
- Expired
type: string
type:
enum:
- Recurring
- Unscheduled
type: string
type: array
success:
type: boolean
type: object
CreateStoredCredentialProfileRequest:
example:
authGateway: 4028905f5702783601570291e14c0015
consentAgreementRef: ACCT1338AgreementV1.pdf
consentAgreementSrc: External
status: Active
type: Recurring
properties:
action:
description: |
Specifies how Zuora activates the stored credential profile. Only applicable if you set the `status` field to `Active`.
- `Activate` (default) - Use this value if you are creating the stored credential profile after receiving the customer's consent.
Zuora will create the stored credential profile then send a cardholder-initiated transaction (CIT) to the payment gateway to validate the stored credential profile. If the CIT succeeds, the status of the stored credential profile will be `Active`. If the CIT does not succeed, Zuora will not create a stored credential profile.
If the payment gateway does not support the stored credential transaction framework, the status of the stored credential profile will be `Agreed`.
- `Persist` - Use this value if the stored credential profile represents a stored credential profile in an external system. The status of the payment method's stored credential profile will be `Active`.
enum:
- Activate
- Persist
type: string
agreedOn:
description: |
The date on which the profile is agreed. The date format is `yyyy-mm-dd`.
format: date
type: string
authGateway:
description: |
Specifies the ID of the payment gateway that Zuora will use when activating the stored credential profile.
type: string
cardSecurityCode:
description: |
The security code of the credit card.
type: string
consentAgreementRef:
description: |
Specifies your reference for the consent agreement that you have established with the customer.
maxLength: 128
type: string
consentAgreementSrc:
description: |
Specifies how the consent agreement has been established with the customer. The allowed value is `External`.
enum:
- External
type: string
networkTransactionId:
description: |
The ID of a network transaction. Only applicable if you set the `action` field to `Persist`.
maxLength: 128
type: string
status:
description: |
Specifies the status of the stored credential profile.
- `Active` - Use this value if you are creating the stored credential profile after receiving the customer's consent, or if the stored credential profile represents a stored credential profile in an external system.
You can use the `action` field to specify how Zuora activates the stored credential profile.
- `Agreed` - Use this value if you are migrating the payment method to the stored credential transaction framework.
In this case, Zuora will not send a cardholder-initiated transaction (CIT) to the payment gateway to validate the stored credential profile.
enum:
- Agreed
- Active
type: string
type:
description: |
Indicates the type of the stored credential profile to process recurring or unsecheduled transactions.
enum:
- Recurring
- Unscheduled
type: string
required:
- status
- type
- consentAgreementSrc
type: object
ModifiedStoredCredentialProfileResponse:
properties:
number:
description: |
The number that identifies the stored credential profile within the payment method.
type: integer
paymentMethodId:
description: |
ID of the payment method.
type: string
success:
type: boolean
type: object
GETListApplePayDomainsResponse:
properties:
domains:
description: |
Container for domains that are already registered with Apple Pay.
items:
properties:
createdBy:
description: |
The ID of the user who created this domain.
type: string
createdOn:
description: |
The date and time when the domain was created, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
domainName:
description: |
The name of the domain registered with Apple Pay, such as `testapplepay.zuora.com`.
type: string
domainVerified:
description: |
Indicates whether the domain registration is successfully verified.
type: boolean
id:
description: |
The ID of the domain, such as `402881a38924ff1001892502da090021`.
type: string
updatedBy:
description: |
The ID of the user who made the last update to this domain.
type: string
updatedOn:
description: |
The last date and time when the domain was updated, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
type: array
success:
description: |
Indicates whether this call succeeds.
type: boolean
type: object
POSTRegisterApplePayDomainRequest:
example:
domainName: testapplepay.zuora.com
properties:
domainName:
description: |
The name of the domain to be registered with Apple Pay, such as `testapplepay.zuora.com`.
type: string
required:
- domainName
type: object
POSTRegisterApplePayDomainResponse:
properties:
domainName:
description: |
The name of the domain registered with Apple Pay, such as `testapplepay.zuora.com`.
type: string
domainVerified:
description: |
Indicates whether the domain registration is successfully verified.
type: boolean
id:
description: |
The ID of the domain, such as `402881a38924ff1001892502da090021`.
type: string
success:
description: |
Indicates whether this call succeeds.
type: boolean
type: object
DELETEUnresigerApplePayDomainResponse:
properties:
success:
description: Indicates whether this call succeeds.
type: boolean
type: object
POSTCreatePaymentSessionRequest:
example:
currency: USD
accountId: 402882e98d3a964b018d3a9c99ef0167
processPayment: true
storePaymentMethod: true
paymentGateway: 402883827d097a28017d09b41f690261
invoices:
- invoiceNumber: INV00001274
- invoiceNumber: INV00001278
amount: 100
properties:
accountId:
description: |
The ID of the customer account in Zuora that is associated with this
payment method.
This field is required when `processPayment` is set to `true`. It is optional when `processPayment` is set to `false`.
type: string
amount:
description: |
If `processPayment` is `true`, it is the amount of the payment. If `invoices` is specified, the value of `amount` must be the current total balances of the specified invoices.
If `processPayment` is `false`, it is the authorization amount for the payment method.
type: number
authAmount:
description: |
The authorization amount for the payment method. Specify a value greater
than 0.
**Note:** This field is being deprecated. It is recommended to use the `amount` field.
type: number
currency:
description: |
The currency of the payment in the format of the three-character ISO
currency code.
type: string
gatewayOptions:
description: |
The field used to pass gateway-specific parameters and parameter values.
The fields supported by gateways vary. For more information, see the
overview topic of each gateway integration in Zuora Knowledge Center.
Zuora sends all the information that you specified to the gateway. If you
specify any unsupported gateway option parameters, they will be ignored
without error prompts.
type: object
title: GatewayOptions
additionalProperties:
type: string
description: |
The gateway options specification consists of key-value pairs:
- Field name: The name of a gateway-specific parameter.
- Field value: The value of the gateway-specific parameter.
paymentGateway:
description: |
The ID of the payment gateway instance configured in Zuora that will
process the payment, such as `e884322ab8c711edab030242ac120004`.
If Payment Gateway Routing is enabled:
- If this field is not specified, gateway routing rules will be invoked.
- If this field is specified, the specified gateway will be used to process the payment.
If Payment Gateway Routing is disabled:
- If this field is not specified, the default payment gateway will be used to process the payment. The default gateway of the customer account takes precedence over the default gateway of the tenant.
- If this field is specified, the specified gateway will be used to process the payment.
type: string
processPayment:
description: |
Indicate whether a payment should be processed after creating the payment
method.
If this field is set to `true`, you must specify either the `amount` field or the `invoices` and `amount` fields.
If this field is set to `false`, you must specify the `amount` field.
type: boolean
storePaymentMethod:
description: |
`true` indicates that the payment method will be stored in Zuora and will be used
in subsequent recurring payments.
`false` indicates that the payment method will not be stored in Zuora.
End-customers need to be brought back on-session to authenticate the payment.
type: boolean
default: true
invoices:
description: |
The array of invoices that a payment applies to. All the specified invoices will be fully paid.
The value of the `amount` field must be the current total balances of the specified invoices.
Here is an example:
```
"invoices": [
{
"invoiceNumber": "INV00001274"
},
{
"invoiceNumber": "INV00001278"
}
]
```
items:
type: object
properties:
invoiceNumber:
description: |
The invoice number, such as `INV0000001`.
type: string
type: array
required:
- currency
- processPayment
- amount
type: object
POSTCreatePaymentSessionResponse:
properties:
token:
description: |
The token for the payment session data.
type: string
type: object
ProxyGetPaymentMethodSnapshot:
properties:
AccountId:
description: The ID of the customer account associated with this payment method.
type: string
AchAbaCode:
description: The nine-digit routing number or ABA number used by banks. Applicable to ACH payment methods.
type: string
AchAccountName:
description: The name of the account holder, which can be either a person or a company. Applicable to ACH payment methods.
type: string
AchAccountNumberMask:
description: 'This is a masked displayable version of the ACH account number, used for security purposes. For example: `XXXXXXXXX54321`.'
type: string
AchAccountType:
description: The type of bank account associated with the ACH payment.
enum:
- BusinessChecking
- Checking
- Saving
type: string
AchBankName:
description: The name of the bank where the ACH payment account is held.
type: string
BankBranchCode:
description: The branch code of the bank used for direct debit.
type: string
BankCheckDigit:
description: The check digit in the international bank account number, which confirms the validity of the account. Applicable to direct debit payment methods.
type: string
BankCity:
description: The city of the direct debit bank.
type: string
BankCode:
description: The sort code or number that identifies the bank. This is also known as the sort code.
type: string
BankIdentificationNumber:
description: The first six or eight digits of the payment method's number, such as the credit card number or account number. Banks use this number to identify a payment method.
type: string
BankName:
description: The name of the direct debit bank.
type: string
BankPostalCode:
description: The zip code or postal code of the direct debit bank.
type: string
BankStreetName:
description: The name of the street of the direct debit bank.
type: string
BankStreetNumber:
description: The number of the direct debit bank.
type: string
BankTransferAccountName:
description: The name on the direct debit bank account.
type: string
BankTransferAccountNumberMask:
description: 'This is a masked displayable version of the bank account number, used for security purposes. For example: `XXXXXXXXX54321`.'
type: string
BankTransferAccountType:
description: The type of the customer's bank account. Applicable to direct debit payment methods.
type: string
BankTransferType:
description: |
Specifies the type of direct debit transfer. The value of this field is dependent on the country of the user.
Possible Values:
* `AutomatischIncasso` (NL)
* `LastschriftDE` (Germany)
* `LastschriftAT` (Austria)
* `DemandeDePrelevement` (FR)
* `DirectDebitUK` (UK)
* `Domicil` (Belgium)
* `LastschriftCH` (CH)
* `RID` (Italy)
* `OrdenDeDomiciliacion` (Spain)
* `Autogiro` (Sweden)
* `Betalingsservice` (Denmark)
enum:
- AutomatischIncasso
- LastschriftDE
- LastschriftAT
- DemandeDePrelevement
- DirectDebitUK
- Domicil
- LastschriftCH
- RID
- OrdenDeDomiciliacion
- Autogiro
- Betalingsservice
type: string
BusinessIdentificationCode:
description: The business identification code for Swiss direct payment methods that use the Global Collect payment gateway. Only applicable to direct debit payments in Switzerland with Global Collect.
type: string
City:
description: The city of the customer's address. Applicable to debit payment methods.
type: string
CompanyName:
description: |
The name of the company.
type: string
Country:
description: The two-letter country code of the customer's address. Applicable to direct debit payment methods.
type: string
CreditCardAddress1:
description: The first line of the card holder's address, which is often a street address or business name. Applicable to credit card and direct debit payment methods.
type: string
CreditCardAddress2:
description: The second line of the card holder's address. Applicable to credit card and direct debit payment methods.
type: string
CreditCardCity:
description: The city of the card holder's address. Applicable to credit card and direct debit payment methods.
type: string
CreditCardCountry:
description: The country of the card holder's address.
type: string
CreditCardExpirationMonth:
description: The expiration month of the credit card or debit card. Applicable to credit card and direct debit payment methods.
format: int32
type: integer
CreditCardExpirationYear:
description: The expiration month of the credit card or debit card. Applicable to credit card and direct debit payment methods.
format: int32
type: integer
CreditCardHolderName:
description: The full name of the card holder. Applicable to credit card and direct debit payment methods.
type: string
CreditCardMaskNumber:
description: A masked version of the credit or debit card number.
type: string
CreditCardPostalCode:
description: The billing address's zip code.
type: string
CreditCardState:
description: The billing address's state. Applicable if `CreditCardCountry` is either Canada or the US.
type: string
CreditCardType:
description: The type of credit card or debit card.
enum:
- AmericanExpress
- Discover
- MasterCard
- Visa
type: string
DeviceSessionId:
description: The session ID of the user when the `PaymentMethod` was created or updated.
type: string
Email:
description: An email address for the payment method in addition to the bill to contact email address.
type: string
ExistingMandate:
description: Indicates if the customer has an existing mandate or a new mandate. Only applicable to direct debit payment methods.
enum:
- 'Yes'
- 'No'
type: string
FirstName:
description: The customer's first name. Only applicable to direct debit payment methods.
type: string
IBAN:
description: The International Bank Account Number. Only applicable to direct debit payment methods.
type: string
IPAddress:
description: The IP address of the user when the payment method was created or updated.
type: string
Id:
description: Object identifier.
type: string
IdentityNumber:
description: |
The unique identity number of the customer account.
type: string
IsCompany:
description: |
Whether the customer account is a company.
type: boolean
LastFailedSaleTransactionDate:
description: The date of the last failed attempt to collect payment with this payment method.
format: date-time
type: string
LastName:
description: The customer's last name. Only applicable to direct debit payment methods.
type: string
LastTransactionDateTime:
description: The date of the most recent transaction.
format: date-time
type: string
LastTransactionStatus:
description: The status of the most recent transaction.
type: string
MandateCreationDate:
description: The date when the mandate was created, in `yyyy-mm-dd` format. A mandate is a signed authorization for UK and NL customers. Only applicable to direct debit payment methods.
format: date
type: string
MandateID:
description: The ID of the mandate. A mandate is a signed authorization for UK and NL customers. Only applicable to direct debit payment methods.
type: string
MandateReceived:
description: Indicates if the mandate was received. A mandate is a signed authorization for UK and NL customers. Only applicable to direct debit payment methods.
type: string
MandateUpdateDate:
description: The date when the mandate was last updated, in `yyyy-mm-dd` format. A mandate is a signed authorization for UK and NL customers. Only applicable to direct debit payment methods.
format: date
type: string
MaxConsecutivePaymentFailures:
description: The number of allowable consecutive failures Zuora attempts with the payment method before stopping.
type: integer
Name:
description: The name of the payment method.
type: string
NumConsecutiveFailures:
description: The number of consecutive failed payment for the payment method.
format: int32
type: integer
PaymentMethodId:
description: Object identifier of the payment method.
type: string
PaymentMethodStatus:
description: Specifies the status of the payment method.
enum:
- Active
- Closed
type: string
PaymentRetryWindow:
description: The retry interval setting, which prevents making a payment attempt if the last failed attempt was within the last specified number of hours.
type: integer
PaypalBaid:
description: The PayPal billing agreement ID, which is a contract between two PayPal accounts.
type: string
PaypalEmail:
description: The email address associated with the account holder's PayPal account or of the PayPal account of the person paying for the service.
type: string
PaypalPreapprovalKey:
description: PayPal's Adaptive Payments API key.
type: string
PaypalType:
description: 'Specifies the PayPal gateway: PayFlow Pro (Express Checkout) or Adaptive Payments.'
enum:
- ExpressCheckout
- AdaptivePayments
type: string
Phone:
description: The phone number that the account holder registered with the bank. This field is used for credit card validation when passing to a gateway.
type: string
PostalCode:
description: The zip code of the customer's address. Only applicable to direct debit payment methods.
type: string
SecondTokenId:
description: A gateway unique identifier that replaces sensitive payment method data. Applicable to CC Reference Transaction payment methods.
type: string
State:
description: The state of the customer's address. Only applicable to direct debit payment methods.
type: string
StreetName:
description: The street name of the customer's address. Only applicable to direct debit payment methods.
type: string
StreetNumber:
description: The street number of the customer's address. Only applicable to direct debit payment methods.
type: string
TokenId:
description: A gateway unique identifier that replaces sensitive payment method data or represents a gateway's unique customer profile. Applicable to CC Reference Transaction payment methods.
type: string
TotalNumberOfErrorPayments:
description: The number of error payments that used this payment method.
format: int32
type: integer
TotalNumberOfProcessedPayments:
description: The number of successful payments that used this payment method.
format: int32
type: integer
Type:
description: The type of payment method.
enum:
- ACH
- ApplePay
- BankTransfer
- Cash
- Check
- CreditCard
- CreditCardReferenceTransaction
- DebitCard
- Other
- PayPal
- WireTransfer
type: string
UseDefaultRetryRule:
description: Determines whether to use the default retry rules configured in the Zuora Payments settings.
type: boolean
type: object
ProxyGetPaymentMethodTransactionLog:
properties:
Gateway:
description: ''
type: string
GatewayReasonCode:
description: ''
type: string
GatewayReasonCodeDescription:
description: ''
type: string
GatewayTransactionType:
description: ''
type: string
Id:
description: Object identifier.
type: string
PaymentMethodId:
description: ''
type: string
PaymentMethodType:
description: ''
type: string
RequestString:
description: ''
type: string
ResponseString:
description: ''
type: string
TransactionDate:
description: ''
format: date-time
type: string
TransactionId:
description: ''
type: string
type: object
GETPaymentMethodUpdaterInstancesResponse:
properties:
success:
description: Indicates whether the call is successful.
type: boolean
updaters:
description: |
Container for PMU instances available on your tenant.
properties:
daysToUpdateBeforeBcd:
description: |
The days prior to the Bill Cycle Day to start PMU service.
type: integer
id:
description: |
The ID of the PMU instance.
type: string
isActive:
description: |
`true` indicates that this PMU instance is active.
type: boolean
isDefault:
description: |
`true` indicates that it is the default PMU instance.
type: boolean
isTest:
description: |
`true` indicates that this PMU instance is for testing.
type: string
processAssociatedGwOnly:
description: |
`true` indicates that only the payment methods for customer accounts that meet either of the following conditions are included in the updates:
- The default payment gateway of the customer account is set to an instance of the same type as `updaterGatewayType`.
- The default payment gateway of the customer account is not configured, but the default payment gateway of the tenant is set to an instance of the same type as `updaterGatewayType`.
`false` indicates that information of all payment methods is submitted.
type: boolean
processAutopayDefaultPmOnly:
description: |
`true` indicates that only the default payment methods for customer accounts with the AutoPay setting enabled are included in the updates.
`false` indicates that data of all payment methods for all customer accounts is submitted, regardless of whether AutoPay is enabled for the customer account or not.
type: boolean
processMastercard:
description: |
`true` indicates that Mastercard data processing is supported.
type: boolean
processVisa:
description: |
`true` indicates that Visa data processing is supported.
type: boolean
updaterGatewayType:
description: |
The payment gateway type of the PMU instance.
type: string
updaterName:
description: |
The name of the PMU instance.
type: string
type: object
type: object
POSTPaymentMethodUpdaterBatchRequest:
example:
billingCycleDay: 5
updaterAccountId: 418734b01fbb11ee821f0e4e5eec84cf
properties:
billingCycleDay:
description: |
The billing cycle day. The allowed value is an integer in the range of 1 - 31.
The payment methods from accounts where the billing cycle day is the specified value in this field will be included in the updates.
type: integer
updaterAccountId:
description: |
The ID (UUID) of the PMU account. This field must be a string of 32 characters consisting of digits and letters a - f.
type: string
required:
- updaterAccountId
- billingCycleDay
type: object
POSTPaymentMethodUpdaterResponse:
properties:
success:
description: |
Indicates whether the request to create a PMU batch is sent successfully.
type: boolean
type: object
POSTRSASignatureType:
example:
method: POST
pageId: 2c92c0f855e2b4630155ec9e6a1b6eec
uri: https://apisandbox.zuora.com/apps/PublicHostedPageLite.do
properties:
IBAN:
description: |
An optional client parameter that can be used for validating client-side HPM parameters specific for Bank Transfer - Direct Debit.
See [Client parameters for Payment Pages 2.0](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/J_Client_Parameters_for_Payment_Pages_2.0)
and [Validate client-side HPM parameters](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/F_Generate_the_Digital_Signature_for_Payment_Pages_2.0#Validate_Client-side_HPM_Parameters)
for details.
type: string
accountId:
description: |
An optional client parameter that can be used for validating client-side HPM parameters.
See [Client parameters for Payment Pages 2.0](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/J_Client_Parameters_for_Payment_Pages_2.0)
and [Validate client-side HPM parameters](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/F_Generate_the_Digital_Signature_for_Payment_Pages_2.0#Validate_Client-side_HPM_Parameters)
for details.
type: string
authorizationAmount:
description: |
An optional client parameter that can be used for validating client-side HPM parameters.
See [Client parameters for Payment Pages 2.0](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/J_Client_Parameters_for_Payment_Pages_2.0)
and [Validate client-side HPM parameters](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/F_Generate_the_Digital_Signature_for_Payment_Pages_2.0#Validate_Client-side_HPM_Parameters)
for details.
type: number
bankBranchCode:
description: |
An optional client parameter that can be used for validating client-side HPM parameters specific for Bank Transfer - Direct Debit.
See [Client parameters for Payment Pages 2.0](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/J_Client_Parameters_for_Payment_Pages_2.0)
and [Validate client-side HPM parameters](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/F_Generate_the_Digital_Signature_for_Payment_Pages_2.0#Validate_Client-side_HPM_Parameters)
for details.
type: string
bankCheckDigit:
description: |
An optional client parameter that can be used for validating client-side HPM parameters specific for Bank Transfer - Direct Debit.
See [Client parameters for Payment Pages 2.0](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/J_Client_Parameters_for_Payment_Pages_2.0)
and [Validate client-side HPM parameters](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/F_Generate_the_Digital_Signature_for_Payment_Pages_2.0#Validate_Client-side_HPM_Parameters)
for details.
type: string
bankCity:
description: |
An optional client parameter that can be used for validating client-side HPM parameters specific for Bank Transfer - Direct Debit.
See [Client parameters for Payment Pages 2.0](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/J_Client_Parameters_for_Payment_Pages_2.0)
and [Validate client-side HPM parameters](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/F_Generate_the_Digital_Signature_for_Payment_Pages_2.0#Validate_Client-side_HPM_Parameters)
for details.
type: string
bankPostalCode:
description: |
An optional client parameter that can be used for validating client-side HPM parameters specific for Bank Transfer - Direct Debit.
See [Client parameters for Payment Pages 2.0](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/J_Client_Parameters_for_Payment_Pages_2.0)
and [Validate client-side HPM parameters](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/F_Generate_the_Digital_Signature_for_Payment_Pages_2.0#Validate_Client-side_HPM_Parameters)
for details.
type: string
bankStreetName:
description: |
An optional client parameter that can be used for validating client-side HPM parameters specific for Bank Transfer - Direct Debit.
See [Client parameters for Payment Pages 2.0](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/J_Client_Parameters_for_Payment_Pages_2.0)
and [Validate client-side HPM parameters](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/F_Generate_the_Digital_Signature_for_Payment_Pages_2.0#Validate_Client-side_HPM_Parameters)
for details.
type: string
bankStreetNumber:
description: |
An optional client parameter that can be used for validating client-side HPM parameters specific for Bank Transfer - Direct Debit.
See [Client parameters for Payment Pages 2.0](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/J_Client_Parameters_for_Payment_Pages_2.0)
and [Validate client-side HPM parameters](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/F_Generate_the_Digital_Signature_for_Payment_Pages_2.0#Validate_Client-side_HPM_Parameters)
for details.
type: string
businessIdentificationCode:
description: |
An optional client parameter that can be used for validating client-side HPM parameters specific for Bank Transfer - Direct Debit.
See [Client parameters for Payment Pages 2.0](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/J_Client_Parameters_for_Payment_Pages_2.0)
and [Validate client-side HPM parameters](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/F_Generate_the_Digital_Signature_for_Payment_Pages_2.0#Validate_Client-side_HPM_Parameters)
for details.
type: string
cityBlackList:
description: |
An optional client parameter that can be used for validating client-side HPM parameters specific for credit cards.
See [Client parameters for Payment Pages 2.0](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/J_Client_Parameters_for_Payment_Pages_2.0)
and [Validate client-side HPM parameters](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/F_Generate_the_Digital_Signature_for_Payment_Pages_2.0#Validate_Client-side_HPM_Parameters)
for details.
type: string
cityWhiteList:
description: |
An optional client parameter that can be used for validating client-side HPM parameters specific for credit cards.
See [Client parameters for Payment Pages 2.0](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/J_Client_Parameters_for_Payment_Pages_2.0)
and [Validate client-side HPM parameters](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/F_Generate_the_Digital_Signature_for_Payment_Pages_2.0#Validate_Client-side_HPM_Parameters)
for details.
type: string
currency:
description: |
An optional client parameter that can be used for validating client-side HPM parameters.
See [Client parameters for Payment Pages 2.0](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/J_Client_Parameters_for_Payment_Pages_2.0)
and [Validate client-side HPM parameters](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/F_Generate_the_Digital_Signature_for_Payment_Pages_2.0#Validate_Client-side_HPM_Parameters)
for details.
type: string
deviceSessionId:
description: |
An optional client parameter that can be used for validating client-side HPM parameters.
See [Client parameters for Payment Pages 2.0](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/J_Client_Parameters_for_Payment_Pages_2.0)
and [Validate client-side HPM parameters](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/F_Generate_the_Digital_Signature_for_Payment_Pages_2.0#Validate_Client-side_HPM_Parameters)
for details.
type: string
gatewayName:
description: |
An optional client parameter that can be used for validating client-side HPM parameters.
See [Client parameters for Payment Pages 2.0](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/J_Client_Parameters_for_Payment_Pages_2.0)
and [Validate client-side HPM parameters](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/F_Generate_the_Digital_Signature_for_Payment_Pages_2.0#Validate_Client-side_HPM_Parameters)
for details.
type: string
id:
description: |
An optional client parameter that can be used for validating client-side HPM parameters.
See [Client parameters for Payment Pages 2.0](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/J_Client_Parameters_for_Payment_Pages_2.0)
and [Validate client-side HPM parameters](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/F_Generate_the_Digital_Signature_for_Payment_Pages_2.0#Validate_Client-side_HPM_Parameters)
for details.
type: string
key:
description: |
An optional client parameter that can be used for validating client-side HPM parameters.
See [Client parameters for Payment Pages 2.0](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/J_Client_Parameters_for_Payment_Pages_2.0)
and [Validate client-side HPM parameters](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/F_Generate_the_Digital_Signature_for_Payment_Pages_2.0#Validate_Client-side_HPM_Parameters)
for details.
type: string
locale:
description: |
An optional client parameter that can be used for validating client-side HPM parameters.
See [Client parameters for Payment Pages 2.0](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/J_Client_Parameters_for_Payment_Pages_2.0)
and [Validate client-side HPM parameters](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/F_Generate_the_Digital_Signature_for_Payment_Pages_2.0#Validate_Client-side_HPM_Parameters)
for details.
type: string
maxConsecutivePaymentFailures:
description: |
An optional client parameter that can be used for validating client-side HPM parameters.
See [Client parameters for Payment Pages 2.0](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/J_Client_Parameters_for_Payment_Pages_2.0)
and [Validate client-side HPM parameters](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/F_Generate_the_Digital_Signature_for_Payment_Pages_2.0#Validate_Client-side_HPM_Parameters)
for details.
type: integer
method:
description: |
The type of the request. Set it to POST.
type: string
pageId:
description: |
The page id of your Payment Pages 2.0 form. Click **Show Page Id** next to the Payment Page name in the Hosted Page List to retrieve the page id.
type: string
param_gwOptions_[*option*]:
description: |
An optional client parameter that can be used for validating client-side HPM parameters.
See [Client parameters for Payment Pages 2.0](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/J_Client_Parameters_for_Payment_Pages_2.0)
and [Validate client-side HPM parameters](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/F_Generate_the_Digital_Signature_for_Payment_Pages_2.0#Validate_Client-side_HPM_Parameters)
for details.
type: string
param_supportedTypes:
description: |
An optional client parameter that can be used for validating client-side HPM parameters specific for credit cards.
See [Client parameters for Payment Pages 2.0](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/J_Client_Parameters_for_Payment_Pages_2.0)
and [Validate client-side HPM parameters](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/F_Generate_the_Digital_Signature_for_Payment_Pages_2.0#Validate_Client-side_HPM_Parameters)
for details.
type: string
passthrough[1,2,3,4,5]:
description: |
An optional client parameter that can be used for validating client-side HPM parameters.
See [Client parameters for Payment Pages 2.0](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/J_Client_Parameters_for_Payment_Pages_2.0)
and [Validate client-side HPM parameters](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/F_Generate_the_Digital_Signature_for_Payment_Pages_2.0#Validate_Client-side_HPM_Parameters)
for details.
Note: Although up to 15 passthrough parameters can be supported when passing in your client parameters, only the first 5 parameters are used for signature generation and validation.
type: string
paymentGateway:
description: |
An optional client parameter that can be used for validating client-side HPM parameters.
See [Client parameters for Payment Pages 2.0](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/J_Client_Parameters_for_Payment_Pages_2.0)
and [Validate client-side HPM parameters](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/F_Generate_the_Digital_Signature_for_Payment_Pages_2.0#Validate_Client-side_HPM_Parameters)
for details.
type: string
paymentRetryWindow:
description: |
An optional client parameter that can be used for validating client-side HPM parameters.
See [Client parameters for Payment Pages 2.0](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/J_Client_Parameters_for_Payment_Pages_2.0)
and [Validate client-side HPM parameters](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/F_Generate_the_Digital_Signature_for_Payment_Pages_2.0#Validate_Client-side_HPM_Parameters)
for details.
type: integer
pmId:
description: |
An optional client parameter that can be used for validating client-side HPM parameters specific for credit cards.
See [Client parameters for Payment Pages 2.0](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/J_Client_Parameters_for_Payment_Pages_2.0)
and [Validate client-side HPM parameters](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/F_Generate_the_Digital_Signature_for_Payment_Pages_2.0#Validate_Client-side_HPM_Parameters)
for details.
type: string
signature:
description: |
An optional client parameter that can be used for validating client-side HPM parameters.
See [Client parameters for Payment Pages 2.0](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/J_Client_Parameters_for_Payment_Pages_2.0)
and [Validate client-side HPM parameters](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/F_Generate_the_Digital_Signature_for_Payment_Pages_2.0#Validate_Client-side_HPM_Parameters)
for details.
type: string
signatureType:
description: |
An optional client parameter that can be used for validating client-side HPM parameters.
See [Client parameters for Payment Pages 2.0](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/J_Client_Parameters_for_Payment_Pages_2.0)
and [Validate client-side HPM parameters](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/F_Generate_the_Digital_Signature_for_Payment_Pages_2.0#Validate_Client-side_HPM_Parameters)
for details.
type: string
style:
description: |
An optional client parameter that can be used for validating client-side HPM parameters.
See [Client parameters for Payment Pages 2.0](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/J_Client_Parameters_for_Payment_Pages_2.0)
and [Validate client-side HPM parameters](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/F_Generate_the_Digital_Signature_for_Payment_Pages_2.0#Validate_Client-side_HPM_Parameters)
for details.
type: string
submitEnabled:
description: |
An optional client parameter that can be used for validating client-side HPM parameters.
See [Client parameters for Payment Pages 2.0](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/J_Client_Parameters_for_Payment_Pages_2.0)
and [Validate client-side HPM parameters](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/F_Generate_the_Digital_Signature_for_Payment_Pages_2.0#Validate_Client-side_HPM_Parameters)
for details.
type: boolean
tenantId:
description: |
An optional client parameter that can be used for validating client-side HPM parameters.
See [Client parameters for Payment Pages 2.0](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/J_Client_Parameters_for_Payment_Pages_2.0)
and [Validate client-side HPM parameters](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/F_Generate_the_Digital_Signature_for_Payment_Pages_2.0#Validate_Client-side_HPM_Parameters)
for details.
type: string
token:
description: |
An optional client parameter that can be used for validating client-side HPM parameters.
See [Client parameters for Payment Pages 2.0](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/J_Client_Parameters_for_Payment_Pages_2.0)
and [Validate client-side HPM parameters](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/F_Generate_the_Digital_Signature_for_Payment_Pages_2.0#Validate_Client-side_HPM_Parameters)
for details.
type: string
uri:
description: |
The URL that the Payment Page will be served from.
* For US Cloud 1 Production environment: Use https://na.zuora.com/apps/PublicHostedPageLite.do
* For US Cloud 1 Sandbox environment: Use https://sandbox.na.zuora.com/apps/PublicHostedPageLite.do
* For US Cloud 2 Production environment: Use https://www.zuora.com/apps/PublicHostedPageLite.do
* For US Cloud 2 API Sandbox environment: Use https://apisandbox.zuora.com/apps/PublicHostedPageLite.do
* For US Central Sandbox environment: Use https://test.zuora.com/apps/PublicHostedPageLite.do
* For EU Cloud Production environment: Use https://eu.zuora.com/apps/PublicHostedPageLite.do
* For EU Cloud Sandbox environment: Use https://sandbox.eu.zuora.com/apps/PublicHostedPageLite.do
* For EU Central Sandbox environment: Use https://test.eu.zuora.com/apps/PublicHostedPageLite.do
type: string
useDefaultRetryRule:
description: |
An optional client parameter that can be used for validating client-side HPM parameters.
See [Client parameters for Payment Pages 2.0](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/J_Client_Parameters_for_Payment_Pages_2.0)
and [Validate client-side HPM parameters](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages/B_Payment_Pages_2.0/F_Generate_the_Digital_Signature_for_Payment_Pages_2.0#Validate_Client-side_HPM_Parameters)
for details.
type: boolean
required:
- method
- pageId
- uri
type: object
POSTRSASignatureResponseType:
properties:
key:
description: |
Public key generated for this Payment Page.
type: string
signature:
description: |
Digital signature generated for this Payment Page.
If `signature` returns `null` but `token` is successfully returned, please limit the number of the fields in your request to make sure that the maximum length supported by the RSA signature algorithm is not exceeded.
type: string
success:
description: |
Returns `true` if the request was processed successfully.
type: boolean
tenantId:
description: |
ID of the Zuora tenant.
type: string
token:
description: |
Token generated for this Payment Page.
type: string
type: object
POSTDecryptionType:
example:
method: POST
publicKey: MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAmWRFTwxQOqaG4JDZSQF/NJWvCDoSXm3TYilNzoN8nBbuvhKa7SZBBS+VP6rFqcbIU38Fu+Rf09vqyYOxuasPJe7yhqeOiStWB/aCPLhwXBeKt37L/qkwpNOKb1FETtUgrc+UjbtT0pnl55wCfi+Ik//X5SQi0B+c0ei1DQv99qmPJJErrhnBtdxeaWAT0EYAo42AOQ5cp0UWDY6OdOYL6+RyFOUFIs1yEgtfg4VMMSpSOKBOhYclQYuSC7nBF5Cc18ydtzsBpf7l49gCLTFzG45NCDAocada8KihFNpGXbauV9V4EPRD4lofaXdsXJ5Tw8/+KCsrUlvIQI3vcEv9LQIDAQAB
signature: BeNYuHFkp/sbfm3clYyCkKEqd7XVTRDOJ1/5rL0tpkqxiSq+maqYkDz5kA+lN64ipoefQuJ7Rdm5TpICErufeJfa2sfTmGARDJ0hr+StXfLsIxHmDoNH5dqcXv3W6MR4kaljEqPVuhzGQ0We98DG52JcHWqqN53oHwTyuZuXocQqnmiE23IPm8UrU3g4hX/OLat0R81wDQ1SslZ+4pnqlncpTpopCK4FxeG3B0gYMhZcYd17Cmf0N3tEHVXHDlJIm4rOx0OVT+YBnjbKYLM0jxYu7PRKRis+yzN1BoappOEB0gmPjznIeiYF0u/fJdZWoEwK7d9mrfJeOBbpFyRoHA==
properties:
method:
description: |
The type of the request. Set it to POST.
type: string
publicKey:
description: |
The public key generated by Zuora.
type: string
signature:
description: |
The signature generated by Zuora.
type: string
required:
- method
- publicKey
- signature
type: object
POSTDecryptResponseType:
properties:
decryptedSignature:
description: |
The string of a list of the following items: Payment Pages 2.0 URL, tenant ID, timestamp,the Payment Page ID
The items are separated by '#', e.g., "/apps/publichostedpagelite.do#12271#rvBp1AxBJwk6FrT7aqFuABIINiRbwJCc
#1418848373103#2c92c0f948f899"
type: string
publicKey:
description: |
The public key passed in as a request parameter.
type: string
signature:
description: |
The signature passed in as a request parameter.
type: string
success:
description: |
Returns `true` if the request was processed successfully.
type: boolean
type: object
GetHostedPagesType:
properties:
hostedpages:
description: |
Container for the hosted page information.
items:
$ref: '#/components/schemas/GetHostedPageType'
type: array
success:
description: |
Returns `true` if the request was processed successfully.
type: boolean
type: object
GetHostedPageType:
properties:
pageId:
description: |
Page ID of the Payment Page that Zuora assigns when it is created.
type: string
pageName:
description: |
Name of the Payment Page that specified during the page configuration.
type: string
pageType:
description: |
Payment method type of this Payment Page, e.g. 'Credit Card', 'ACH', or 'Bank Transfer'.
type: string
pageVersion:
description: |
Version of the Payment Page. 2 for Payment Pages 2.0.
type: string
title: hostedpages
type: object
POSTCreateOpenPaymentMethodTypeRequest:
example:
entityId: ''
fields:
- checksum: true
defaultValue: null
description: The Token value
editable: true
index: 1
label: AmazonToken
maxLength: 100
minLength: 1
name: AmazonToken
representer: true
required: true
type: string
visible: true
- checksum: true
defaultValue: null
description: The Type of Token, e.g. GoCardlessToken
editable: true
index: 2
label: Amazon TokenType
maxLength: 100
minLength: 1
name: AmazonTokenType
representer: true
required: true
type: string
visible: true
internalName: AmazonPay
label: ZuoraQA Amazon Pay
methodReferenceIdField: AmazonToken
subTypeField: AmazonTokenType
tenantId: '9'
userReferenceIdField: ''
properties:
entityId:
description: |
If this custom payment method type is specific to one entity only, provide the entity ID in this field in UUID format, such as `123e4567-e89b-12d3-a456-426614174000`. If no entity UUID is provided, the custom payment method type is available to the global entity and all the sub entities in the tenant.
You can get the entity ID through the [Multi-entity: List entities](https://developer.zuora.com/api-references/older-api/operation/GET_Entities/) API operation or the **Manage Entity Profile** administration setting in the UI. To convert the format of the entity ID to UUID, separate the entity ID string in five groups with hyphens, in the form `<8-characters>-<4-characters>-<4-characters>-<4-characters>-<12-characters>` for a total of 36 characters.
Note: After the custom payment method type is created, you can only update this field to be empty.
type: string
fields:
description: |
An array containing field metadata of the custom payment method type.
Notes:
- All the following nested metadata must be provided in the request to define a field.
- At least one field must be defined in the fields array for a custom payment method type.
- Up to 20 fields can be defined in the fields array for a custom payment method type.
items:
$ref: '#/components/schemas/OpenPaymentMethodTypeRequestFields'
type: array
internalName:
description: |
A string to identify the custom payment method type in the API name of the payment method type.
This field must be alphanumeric, starting with a capital letter, excluding JSON preserved characters such as * \ ’ ”. Additionally, '_' or '-' is not allowed.
This field must be unique in a tenant.
This field is used along with the `tenantId` field by the system to construct and generate the API name of the custom payment method type in the following way:
`*customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
description: |
Container for custom fields of a Payment object.
title: paymentFieldsCustom
type: object
CreatePaymentType:
allOf:
- properties:
accountId:
description: |
The ID of the customer account that the payment is created for.
type: string
accountNumber:
description: |
The number of the customer account that the payment is created for, such as `A00000001`.
You can specify either `accountNumber` or `accountId` for a customer account. If both of them are specified, they must refer to the same customer account.
type: string
amount:
description: |
The total amount of the payment.
format: double
type: number
authTransactionId:
description: |
The authorization transaction ID from the payment gateway. Use this field for electronic payments, such as credit cards.
When you create a payment for capturing the authorized funds, it is highly recommended to pass in the gatewayOrderId that you used when authorizing the funds by using the [Create authorization](https://www.zuora.com/developer/api-references/api/operation/POST_CreateAuthorization) operation, together with the `authTransactionId` field.
The following payment gateways support this field:
- Adyen Integration v2.0
- CyberSource 1.28
- CyberSource 1.97
- CyberSource 2.0
- Chase Paymentech Orbital
- Ingenico ePayments
- SlimPay
- Stripe v2
- Verifi Global Payment Gateway
- WePay Payment Gateway Integration
maxLength: 50
type: string
comment:
description: |
Additional information related to the payment.
maxLength: 255
minLength: 0
type: string
currency:
description: |
When Standalone Payment is not enabled, the `currency` of the payment must be the same as the payment currency defined in the customer account settings through Zuora UI. But if you have the [Multiple Currencies](https://knowledgecenter.zuora.com/Zuora_Billing/Bill_your_customers/Flexible_Billing/Multiple_Currencies) feature enabled, you can have a different payment currency.
When Standalone Payment is enabled and `standalone` is `true`, the `currency` of the standalone payment can be different from the payment currency defined in the customer account settings. The amount will not be summed up to the account balance or key metrics regardless of currency.
type: string
customRates:
description: |
It contains Home currency and Reporting currency custom rates currencies. The maximum number of items is 2 (you can pass the Home currency item or Reporting currency item or both).
**Note**:
- This field is only available if you are on the latest Zuora API minor version, or you set the `Zuora-Version` request header to `224.0` or [a later available version](https://developer.zuora.com/v1-api-reference/api-versions/#minor-version).
- You cannot set the custom rates, if both the **Automatically include additional Currency Conversion information in data source exports** option and **Fx data** feature are enabled.
- Payment, PaymentApplication, and PaymentApplicationItem will utilize the provided custom Fx rate to convert amounts from the transactional currency to the home currency.
items:
$ref: '#/components/schemas/PaymentWithCustomRatesType'
maxItems: 2
type: array
debitMemos:
description: |
Container for debit memos. The maximum number of debit memos is 1,000.
items:
$ref: '#/components/schemas/PaymentDebitMemoApplicationCreateRequestType'
type: array
effectiveDate:
description: |
The date when the payment takes effect, in `yyyy-mm-dd` format.
**Note:**
- This field is required for only electronic payments. It's an optional field for external payments.
- When specified, this field must be set to the date of today.
- When applying or transferring payments, this field must be later than or equal to the maximum effective date of the payment.
format: date
type: string
financeInformation:
description: |
Container for the finance information related to the payment.
properties:
bankAccountAccountingCode:
description: |
The accounting code that maps to a bank account in your accounting system.
maxLength: 100
minLength: 0
type: string
transferredToAccounting:
description: |
Whether the payment was transferred to an external accounting system. Use this field for integration with accounting systems, such as NetSuite.
enum:
- Processing
- 'Yes'
- 'No'
- Error
- Ignore
type: string
unappliedPaymentAccountingCode:
description: |
The accounting code for the unapplied payment.
maxLength: 100
minLength: 0
type: string
type: object
gatewayId:
description: |
The ID of the gateway instance that processes the payment. The ID must be a valid gateway instance ID and this gateway must support the specific payment method.
- If Payment Gateway Routing is enabled, when creating electronic payments, this field is optional.
- If this field is not specified, gateway routing rules will be invoked.
- If this field is specified, the specified gateway will be used to process the payment.
- If Payment Gateway Routing is disabled, when creating electronic payments, this field is required.
- When creating external payments, this field is optional.
Use the same gateway instance if both `paymentGatewayNumber` and
`gatewayId` are sent in the request.
type: string
gatewayOptions:
description: |
The field used to pass gateway-specific parameters and parameter values. The fields supported by gateways vary. For more information, see the Overview topic of each gateway integration in [Zuora Knowledge Center](https://knowledgecenter.zuora.com/Zuora_Billing/Billing_and_Payments/M_Payment_Gateways/Supported_Payment_Gateways).
Zuora sends all the information that you specified to the gateway. If you specify any unsupported gateway option parameters, they will be ignored without error prompts.
properties:
key:
description: |
The name of a gateway-specific parameter.
maxLength: 255
type: string
value:
description: |
The value of the gateway-specific parameter.
maxLength: 255
type: string
type: object
gatewayOrderId:
description: |
A merchant-specified natural key value that can be passed to the electronic payment gateway when a payment is created. If not specified, the payment number will be passed in instead.
Gateways check duplicates on the gateway order ID to ensure that the merchant do not accidentally enter the same transaction twice. This ID can also be used to do reconciliation and tie the payment to a natural key in external systems. The source of this ID varies by merchant. Some merchants use their shopping cart order IDs, and others use something different. Merchants use this ID to track transactions in their eCommerce systems.
When you create a payment for capturing the authorized funds, it is highly recommended to pass in the gatewayOrderId that you used when authorizing the funds by using the [Create authorization](https://www.zuora.com/developer/api-references/api/operation/POST_CreateAuthorization) operation, together with the `authTransactionId` field.
maxLength: 50
type: string
invoices:
description: |
Container for invoices. The maximum number of invoices is 1,000.
items:
$ref: '#/components/schemas/PaymentInvoiceApplicationCreateRequestType'
type: array
mitTransactionSource:
description: |
Payment transaction source used to differentiate the transaction source in Stored Credential Transaction framework.
- `C_Unscheduled`: Cardholder-initiated transaction (CIT) that does not occur on scheduled or regularly occurring dates.
- `M_Recurring`: Merchant-initiated transaction (MIT) that occurs at regular intervals.
- `M_Unscheduled`: Merchant-initiated transaction (MIT) that does not occur on scheduled or regularly occurring dates.
- `M_MOTO`: Mail Order Telephone Order (MOTO) payment transaction. This option is only available for credit card payments on Stripe v2. See [Overview of Stripe payment gateway integration](https://knowledgecenter.zuora.com/Zuora_Collect/Payment_gateway_integrations/Supported_payment_gateways/Stripe_Payment_Gateway/A_Overview_of_Stripe_payment_gateway_integration) for more information.
enum:
- C_Unscheduled
- M_Recurring
- M_Unscheduled
- M_MOTO
type: string
paymentGatewayNumber:
description: |
The natural key for the payment gateway.
Use the same gateway instance if both `paymentGatewayNumber` and `gatewayId` are sent in the request.
type: string
paymentMethodId:
description: |
The unique ID of the payment method that the customer used to make the payment.
If no payment method ID is specified in the request body, the default payment method for the customer account is used automatically. If the default payment method is different from the type of payments that you want to create, an error occurs.
type: string
paymentMethodType:
default: null
description: |
The type of the payment method that the customer used to make the payment.
Specify this value when you are creating an external payment method. If both `paymentMethodType` and `paymentMethodId` are specified, only the `paymentMethodId` value is used to create the payment.
type: string
paymentOption:
description: |
Container for the paymentOption items, which describe the transactional level rules for processing payments. Currently, only the Gateway Options type is supported.
Here is an example:
```
"paymentOption": [
{
"type": "GatewayOptions",
"detail": {
"SecCode":"WEB"
}
}
]
```
`paymentOption` of the payment schedule takes precedence over `paymentOption` of the payment schedule item.
You can use this field or the `gatewayOptions` field to pass the Gateway Options fields supported by a payment gateway. However, the Gateway Options fields passed through the `paymentOption` field will be stored in the Payment Option object and can be easily retrieved.
items:
$ref: '#/components/schemas/PaymentSchedulePaymentOptionFields'
type: array
paymentScheduleKey:
description: The unique ID or the number of the payment schedule to be linked with the payment. See [Link payments to payment schedules](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Payment_Schedules/Link_payments_with_payment_schedules) for more information.
type: string
prepayment:
description: |
Indicates whether the payment will be used as a reserved payment. See [Prepaid Cash with Drawdown](https://knowledgecenter.zuora.com/Zuora_Billing/Billing_and_Invoicing/JA_Advanced_Consumption_Billing/Prepaid_Cash_with_Drawdown) for more information.
type: boolean
referenceId:
description: |
The transaction ID returned by the payment gateway. Use this field to reconcile payments between your gateway and Zuora Payments.
maxLength: 100
minLength: 0
type: string
softDescriptor:
description: A payment gateway-specific field that maps to Zuora for the gateways, Orbital, Vantiv and Verifi.
maxLength: 35
type: string
softDescriptorPhone:
description: A payment gateway-specific field that maps to Zuora for the gateways, Orbital, Vantiv and Verifi.
maxLength: 20
type: string
standalone:
default: false
description: |
This field is only available if support for standalone payments is enabled.
Specify `true` to create a standalone payment that will be processed in Zuora through Zuora gateway integration but will be settled outside of Zuora.
When `standalone` is set to `true`:
- `accountId`, `amount`, `currency`, and `type` are required.
- `type` must be `Electronic`.
- `currency` of the payment can be different from the payment currency in the customer account settings.
- The amount will not be summed up into the account balance and key metrics regardless of the payment currency.
- No settlement data will be created.
- Either the applied amount or the unapplied amount of the payment is zero.
- The standalone payment cannot be applied, unapplied, or transferred.
Specify `false` to create an ordinary payment that will be created, processed, and settled in Zuora. The `currency` of an ordinary payment must be the same as the currency in the customer account settings.
type: boolean
type:
description: |
The type of the payment.
**Note**: If you specify the type as `Electronic`, you must specify the value for `accountId` or `accountNumber`.
enum:
- External
- Electronic
type: string
required:
- amount
- currency
- type
type: object
- $ref: '#/components/schemas/PaymentObjectNSFields'
- $ref: '#/components/schemas/PaymentObjectCustomFields'
example:
accountId: 8a90b4488e7d5c0f018e7db3892400b2
type: External
paymentMethodId: 2c92c8f95e2d6ebb015e325df7a70356
amount: 14.99
currency: USD
invoices:
- invoiceId: 8a90e5e4914ad4fa01914b25ff2c036e
amount: 14.99
GETARPaymentTypeWithPaymentOption:
allOf:
- properties:
accountId:
description: |
The ID of the customer account that the payment is for.
type: string
accountNumber:
description: |
The number of the customer account that the payment is for.
type: string
amount:
description: |
The total amount of the payment.
format: double
type: number
appliedAmount:
description: |
The applied amount of the payment.
format: double
type: number
authTransactionId:
description: |
The authorization transaction ID from the payment gateway.
type: string
bankIdentificationNumber:
description: |
The first six or eight digits of the credit card or debit card used for the payment, when applicable.
type: string
cancelledOn:
description: |
The date and time when the payment was cancelled, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
nullable: true
comment:
description: |
Comments about the payment.
type: string
nullable: true
createdById:
description: |
The ID of the Zuora user who created the payment.
type: string
createdDate:
description: |
The date and time when the payment was created, in `yyyy-mm-dd hh:mm:ss` format. For example, 2017-03-01 15:31:10.
format: date-time
type: string
creditBalanceAmount:
description: |
The amount that the payment transfers to the credit balance. The value is not `0` only for those payments that come from legacy payment operations performed without the Invoice Settlement feature.
format: double
type: number
currency:
description: |
When Standalone Payment is not enabled, the `currency` of the payment must be the same as the payment currency defined in the customer account settings through Zuora UI.
When Standalone Payment is enabled and `standalone` is `true`, the `currency` of the standalone payment can be different from the payment currency defined in the customer account settings. The amount will not be summed up to the account balance or key metrics regardless of currency.
type: string
effectiveDate:
description: |
The date and time when the payment takes effect, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
financeInformation:
description: |
Container for the finance information related to the payment.
properties:
bankAccountAccountingCode:
description: |
The accounting code that maps to a bank account in your accounting system.
type: string
nullable: true
bankAccountAccountingCodeType:
description: |
The type of the accounting code that maps to a bank account in your accounting system.
type: string
nullable: true
transferredToAccounting:
description: |
Whether the payment was transferred to an external accounting system. Use this field for integration with accounting systems, such as NetSuite.
enum:
- Processing
- 'Yes'
- 'No'
- Error
- Ignore
type: string
nullable: true
unappliedPaymentAccountingCode:
description: |
The accounting code for the unapplied payment.
type: string
nullable: true
unappliedPaymentAccountingCodeType:
description: |
The type of the accounting code for the unapplied payment.
type: string
nullable: true
type: object
gatewayId:
description: |
The ID of the gateway instance that processes the payment.
type: string
nullable: true
gatewayOrderId:
description: |
A merchant-specified natural key value that can be passed to the electronic payment gateway when a payment is created. If not specified, the payment number will be passed in instead.
type: string
gatewayReconciliationReason:
description: |
The reason of gateway reconciliation.
type: string
nullable: true
gatewayReconciliationStatus:
description: |
The status of gateway reconciliation.
type: string
nullable: true
gatewayResponse:
description: |
The message returned from the payment gateway for the payment. This message is gateway-dependent.
type: string
nullable: true
gatewayResponseCode:
description: |
The code returned from the payment gateway for the payment. This code is gateway-dependent.
type: string
gatewayState:
description: |
The status of the payment in the gateway; use for reconciliation.
enum:
- MarkedForSubmission
- Submitted
- Settled
- NotSubmitted
- FailedToSettle
type: string
id:
description: |
The unique ID of the created payment. For example, 4028905f5a87c0ff015a87eb6b75007f.
type: string
markedForSubmissionOn:
description: |
The date and time when a payment was marked and waiting for batch submission to the payment process, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
number:
description: |
The unique identification number of the payment. For example, P-00000001.
type: string
organizationLabel:
description: |
The organization that this object belongs to.
Note: This field is available only when the Multi-Org feature is enabled.
type: string
paymentGatewayNumber:
description: |
The natural key for the payment gateway.
type: string
nullable: true
paymentMethodId:
description: |
The unique ID of the payment method that the customer used to make the payment.
type: string
paymentMethodSnapshotId:
description: |
The unique ID of the payment method snapshot which is a copy of the particular Payment Method used in a transaction.
type: string
nullable: true
paymentOption:
description: |
Container for the paymentOption items, which describe the transactional level rules for processing payments. Currently, only the Gateway Options type is supported.
`paymentOption` of the payment schedule takes precedence over `paymentOption` of the payment schedule item.
items:
$ref: '#/components/schemas/PaymentSchedulePaymentOptionFields'
type: array
paymentScheduleKey:
description: The unique ID or the number of the payment schedule that is linked to the payment. See [Link payments to payment schedules](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Payment_Schedules/Link_payments_with_payment_schedules) for more information.
type: string
payoutId:
description: |
The payout ID of the payment from the gateway side.
type: string
nullable: true
prepayment:
description: |
Indicates whether the payment is used as a reserved payment. See [Prepaid Cash with Drawdown](https://knowledgecenter.zuora.com/Zuora_Billing/Billing_and_Invoicing/JA_Advanced_Consumption_Billing/Prepaid_Cash_with_Drawdown) for more information.
type: boolean
referenceId:
description: |
The transaction ID returned by the payment gateway. Use this field to reconcile payments between your gateway and Zuora Payments.
type: string
nullable: true
refundAmount:
description: |
The amount of the payment that is refunded.
format: double
type: number
secondPaymentReferenceId:
description: |
The transaction ID returned by the payment gateway if there is an additional transaction for the payment. Use this field to reconcile payments between your gateway and Zuora Payments.
type: string
nullable: true
settledOn:
description: |
The date and time when the payment was settled in the payment processor, in `yyyy-mm-dd hh:mm:ss` format. This field is used by the Spectrum gateway only and not applicable to other gateways.
format: date-time
type: string
nullable: true
softDescriptor:
description: |
A payment gateway-specific field that maps to Zuora for the gateways, Orbital, Vantiv and Verifi.
type: string
nullable: true
softDescriptorPhone:
description: |
A payment gateway-specific field that maps to Zuora for the gateways, Orbital, Vantiv and Verifi.
type: string
nullable: true
standalone:
default: false
description: |
This field is only available if the support for standalone payment is enabled. This field is not available for transferring, applying, or unapplying a payment.
The value `true` indicates this is a standalone payment that is created and processed in Zuora through Zuora gateway integration but will be settled outside of Zuora. No settlement data will be created. The standalone payment cannot be applied, unapplied, or transferred.
The value `false` indicates this is an ordinary payment that is created, processed, and settled in Zuora.
type: boolean
status:
description: |
The status of the payment.
If the Asynchronous Payment Statuses feature is not enabled, possible values are `Draft`, `Processing`, `Processed`, `Error`, `Canceled`, and `Posted`.
If the Asynchronous Payment Statuses feature is enabled, when the ACH or Bank Transfer payment is created, it is in a `Pending` status upon successful network communication with the gateway. To transition from a `Pending` status to another status, use one of our Gateway Reconciliation options or cancel the payment.
enum:
- Draft
- Processing
- Processed
- Error
- Canceled
- Posted
- Pending
type: string
submittedOn:
description: |
The date and time when the payment was submitted, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
success:
description: Returns `true` if the request was processed successfully.
type: boolean
type:
description: |
The type of the payment.
enum:
- External
- Electronic
type: string
unappliedAmount:
description: |
The unapplied amount of the payment.
format: double
type: number
updatedById:
description: |
The ID of the Zuora user who last updated the payment.
type: string
updatedDate:
description: |
The date and time when the payment was last updated, in `yyyy-mm-dd hh:mm:ss` format. For example, 2017-03-02 15:36:10.
format: date-time
type: string
type: object
- $ref: '#/components/schemas/PaymentObjectNSFields'
- $ref: '#/components/schemas/PaymentObjectCustomFields'
PaymentWithCustomRatesType:
allOf:
- properties:
currency:
description: |
The currency code for either Reporting or Home currency.
**Note**: This field is only available if you are on the latest Zuora API minor version, or you set the `Zuora-Version` request header to `224.0` or [a later available version](https://developer.zuora.com/v1-api-reference/api-versions/#minor-version).
type: string
customFxRate:
description: |
The Custom FX conversion rate between Home/Reporting and Transactional currency items.
**Note**: This field is only available if you are on the latest Zuora API minor version, or you set the `Zuora-Version` request header to `224.0` or [a later available version](https://developer.zuora.com/v1-api-reference/api-versions/#minor-version).
format: decimal
type: number
rateDate:
description: |
The date on which a particular currency rate is fixed or obtained on.
**Note**: This field is only available if you are on the latest Zuora API minor version, or you set the `Zuora-Version` request header to `224.0` or [a later available version](https://developer.zuora.com/v1-api-reference/api-versions/#minor-version).
format: date
type: string
required:
- currency
- customFxRate
type: object
title: customRates
PaymentDebitMemoApplicationCreateRequestType:
properties:
amount:
description: |
The amount of the payment associated with the debit memo.
format: double
type: number
debitMemoId:
description: |
The unique ID of the debit memo that the payment is created on.
**Note:**
- The Payment Cross Account (PCA) feature is in the Early Adopter stage. To gain access to this capability, please create a Zuora support ticket.
- When PCA is enabled for the tenant, you can specify a debit memo / invoice that is different from the account that is specified in the request body.
type: string
items:
description: |
Container for debit memo items. The maximum number of items is 1,000.
**Note:** This field is only available if you have the [Invoice Item Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement/C_Invoice_Item_Settlement) feature enabled. Invoice Item Settlement must be used together with other Invoice Settlement features (Unapplied Payments, and Credit and Debit memos). If you wish 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.
items:
$ref: '#/components/schemas/PaymentDebitMemoApplicationItemCreateRequestType'
type: array
title: debitMemos
type: object
PaymentInvoiceApplicationCreateRequestType:
properties:
amount:
description: |
The amount of the payment associated with the invoice. This amount must be equal to or lesser than the balance of the invoice.
format: double
type: number
invoiceId:
description: |
The unique ID of the invoice that the payment is created on. The balance of the invoice specified must not be `0`.
**Note:**
- The Payment Cross Account (PCA) feature is in the Early Adopter stage. To gain access to this capability, please create a Zuora support ticket.
- When PCA is enabled for the tenant, you can specify a debit memo / invoice that is different from the account that is specified in the request body.
type: string
items:
description: |
Container for invoice items. The maximum number of items is 1,000.
**Note:** This field is only available if you have the [Invoice Item Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement/C_Invoice_Item_Settlement) feature enabled. Invoice Item Settlement must be used together with other Invoice Settlement features (Unapplied Payments, and Credit and Debit memos). If you wish 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.
items:
$ref: '#/components/schemas/PaymentInvoiceApplicationItemCreateRequestType'
type: array
title: invoices
type: object
PaymentInvoiceApplicationItemCreateRequestType:
properties:
amount:
description: |
The amount of the payment associated with the specific invoice or taxation item.
format: double
type: number
invoiceItemId:
description: |
The ID of the specific invoice item.
type: string
taxItemId:
description: |
The ID of the specific taxation item.
type: string
required:
- amount
title: items
type: object
PaymentDebitMemoApplicationItemCreateRequestType:
properties:
amount:
description: |
The amount of the payment associated with the specific debit memo or taxation item.
format: double
type: number
debitMemoItemId:
description: |
The ID of the specific debit memo item.
type: string
taxItemId:
description: |
The ID of the specific taxation item.
type: string
required:
- amount
title: items
type: object
UpdatePaymentType:
allOf:
- properties:
comment:
description: |
Comments about the payment.
maxLength: 255
minLength: 0
type: string
financeInformation:
description: |
Container for the finance information related to the payment.
For a standalone payment, the finance information cannot be updated.
properties:
bankAccountAccountingCode:
description: |
The accounting code that maps to a bank account in your accounting system.
maxLength: 100
minLength: 0
type: string
transferredToAccounting:
description: |
Whether the payment was transferred to an external accounting system. Use this field for integration with accounting systems, such as NetSuite.
enum:
- Processing
- 'Yes'
- 'No'
- Error
- Ignore
type: string
unappliedPaymentAccountingCode:
description: |
The accounting code for the unapplied payment.
maxLength: 100
minLength: 0
type: string
type: object
gatewayState:
description: |
This field is mainly used for gateway reconciliation. See Electronic payment processing for details.
You must have the **Edit Payment Gateway Status** user permission to update this field.
enum:
- NotSubmitted
- Submitted
- Settled
- FailedToSettle
type: string
paymentScheduleKey:
description: The unique ID or the number of the payment schedule to be linked with the payment. See [Link payments to payment schedules](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Payment_Schedules/Link_payments_with_payment_schedules) for more information.
type: string
referenceId:
description: |
The transaction ID returned by the payment gateway. Use this field to reconcile payments between your gateway and Zuora Payments.
You can only update the reference ID for external payments.
maxLength: 100
minLength: 0
type: string
type: object
- $ref: '#/components/schemas/PaymentObjectNSFields'
- $ref: '#/components/schemas/PaymentObjectCustomFields'
example:
comment: Details about this payment
GETARPaymentType:
allOf:
- properties:
accountId:
description: |
The ID of the customer account that the payment is for.
type: string
accountNumber:
description: |
The number of the customer account that the payment is for.
type: string
amount:
description: |
The total amount of the payment.
format: double
type: number
appliedAmount:
description: |
The applied amount of the payment.
format: double
type: number
authTransactionId:
description: |
The authorization transaction ID from the payment gateway.
type: string
bankIdentificationNumber:
description: |
The first six or eight digits of the credit card or debit card used for the payment, when applicable.
type: string
cancelledOn:
description: |
The date and time when the payment was cancelled, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
comment:
description: |
Comments about the payment.
type: string
nullable: true
createdById:
description: |
The ID of the Zuora user who created the payment.
type: string
createdDate:
description: |
The date and time when the payment was created, in `yyyy-mm-dd hh:mm:ss` format. For example, 2017-03-01 15:31:10.
format: date-time
type: string
creditBalanceAmount:
description: |
The amount that the payment transfers to the credit balance. The value is not `0` only for those payments that come from legacy payment operations performed without the Invoice Settlement feature.
format: double
type: number
currency:
description: |
When Standalone Payment is not enabled, the `currency` of the payment must be the same as the payment currency defined in the customer account settings through Zuora UI.
When Standalone Payment is enabled and `standalone` is `true`, the `currency` of the standalone payment can be different from the payment currency defined in the customer account settings. The amount will not be summed up to the account balance or key metrics regardless of currency.
type: string
effectiveDate:
description: |
The date and time when the payment takes effect, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
financeInformation:
description: |
Container for the finance information related to the payment.
properties:
bankAccountAccountingCode:
description: |
The accounting code that maps to a bank account in your accounting system.
type: string
bankAccountAccountingCodeType:
description: |
The type of the accounting code that maps to a bank account in your accounting system.
type: string
transferredToAccounting:
description: |
Whether the payment was transferred to an external accounting system. Use this field for integration with accounting systems, such as NetSuite.
enum:
- Processing
- 'Yes'
- 'No'
- Error
- Ignore
type: string
unappliedPaymentAccountingCode:
description: |
The accounting code for the unapplied payment.
type: string
unappliedPaymentAccountingCodeType:
description: |
The type of the accounting code for the unapplied payment.
type: string
type: object
gatewayId:
description: |
The ID of the gateway instance that processes the payment.
type: string
gatewayOrderId:
description: |
A merchant-specified natural key value that can be passed to the electronic payment gateway when a payment is created. If not specified, the payment number will be passed in instead.
type: string
gatewayReconciliationReason:
description: |
The reason of gateway reconciliation.
type: string
gatewayReconciliationStatus:
description: |
The status of gateway reconciliation.
type: string
gatewayResponse:
description: |
The message returned from the payment gateway for the payment. This message is gateway-dependent.
type: string
gatewayResponseCode:
description: |
The code returned from the payment gateway for the payment. This code is gateway-dependent.
type: string
gatewayState:
description: |
The status of the payment in the gateway; use for reconciliation.
enum:
- MarkedForSubmission
- Submitted
- Settled
- NotSubmitted
- FailedToSettle
type: string
id:
description: |
The unique ID of the created payment. For example, 4028905f5a87c0ff015a87eb6b75007f.
type: string
markedForSubmissionOn:
description: |
The date and time when a payment was marked and waiting for batch submission to the payment process, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
number:
description: |
The unique identification number of the payment. For example, P-00000001.
type: string
organizationLabel:
description: |
The organization that this object belongs to.
Note: This field is available only when the Multi-Org feature is enabled.
type: string
paymentGatewayNumber:
description: |
The natural key for the payment gateway.
type: string
paymentMethodId:
description: |
The unique ID of the payment method that the customer used to make the payment.
type: string
paymentMethodSnapshotId:
description: |
The unique ID of the payment method snapshot which is a copy of the particular Payment Method used in a transaction.
type: string
paymentScheduleKey:
description: The unique ID or the number of the payment schedule that is linked to the payment. See [Link payments to payment schedules](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Payment_Schedules/Link_payments_with_payment_schedules) for more information.
type: string
payoutId:
description: |
The payout ID of the payment from the gateway side.
type: string
prepayment:
description: |
Indicates whether the payment is used as a reserved payment. See [Prepaid Cash with Drawdown](https://knowledgecenter.zuora.com/Zuora_Billing/Billing_and_Invoicing/JA_Advanced_Consumption_Billing/Prepaid_Cash_with_Drawdown) for more information.
type: boolean
referenceId:
description: |
The transaction ID returned by the payment gateway. Use this field to reconcile payments between your gateway and Zuora Payments.
type: string
refundAmount:
description: |
The amount of the payment that is refunded.
format: double
type: number
secondPaymentReferenceId:
description: |
The transaction ID returned by the payment gateway if there is an additional transaction for the payment. Use this field to reconcile payments between your gateway and Zuora Payments.
type: string
settledOn:
description: |
The date and time when the payment was settled in the payment processor, in `yyyy-mm-dd hh:mm:ss` format. This field is used by the Spectrum gateway only and not applicable to other gateways.
format: date-time
type: string
softDescriptor:
description: |
A payment gateway-specific field that maps to Zuora for the gateways, Orbital, Vantiv and Verifi.
type: string
softDescriptorPhone:
description: |
A payment gateway-specific field that maps to Zuora for the gateways, Orbital, Vantiv and Verifi.
type: string
standalone:
default: false
description: |
This field is only available if the support for standalone payment is enabled. This field is not available for transferring, applying, or unapplying a payment.
The value `true` indicates this is a standalone payment that is created and processed in Zuora through Zuora gateway integration but will be settled outside of Zuora. No settlement data will be created. The standalone payment cannot be applied, unapplied, or transferred.
The value `false` indicates this is an ordinary payment that is created, processed, and settled in Zuora.
type: boolean
status:
description: |
The status of the payment.
enum:
- Draft
- Processing
- Processed
- Error
- Canceled
- Posted
type: string
submittedOn:
description: |
The date and time when the payment was submitted, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
success:
description: Returns `true` if the request was processed successfully.
type: boolean
type:
description: |
The type of the payment.
enum:
- External
- Electronic
type: string
unappliedAmount:
description: |
The unapplied amount of the payment.
format: double
type: number
updatedById:
description: |
The ID of the Zuora user who last updated the payment.
type: string
updatedDate:
description: |
The date and time when the payment was last updated, in `yyyy-mm-dd hh:mm:ss` format. For example, 2017-03-02 15:36:10.
format: date-time
type: string
type: object
- $ref: '#/components/schemas/PaymentObjectNSFields'
- $ref: '#/components/schemas/PaymentObjectCustomFields'
ApplyPaymentType:
example:
invoices:
- invoiceId: 8ad097b490c4e5aa0190c9b931817cef
amount: 12
properties:
debitMemos:
description: |
Container for debit memos. The maximum number of debit memos is 1,000.
items:
$ref: '#/components/schemas/PaymentDebitMemoApplicationApplyRequestType'
type: array
effectiveDate:
description: |
The date when the payment application takes effect, in `yyyy-mm-dd` format. The effective date must be later than or equal to the maximum effective date of the payment.
format: date
type: string
invoices:
description: |
Container for invoices. The maximum number of invoices is 1,000.
items:
$ref: '#/components/schemas/PaymentInvoiceApplicationApplyRequestType'
type: array
type: object
PaymentDebitMemoApplicationApplyRequestType:
properties:
amount:
description: |
The amount that is applied from the payment to the debit memo.
format: double
type: number
debitMemoId:
description: |
The unique ID of the debit memo that the payment is applied to.
If `debitMemoId` or `debitMemoNumber` is specified, the `writeOff` value can be set to true. This enables writing off a debit memo at the time of refund.
**Note:**
- The Payment Cross Account (PCA) feature is in the Early Adopter phase.
- When PCA is enabled for the tenant, you can specify a debit memo / invoice that is different from the account that is specified in the request body.
type: string
debitMemoNumber:
description: |
The number of the debit memo that the payment is applied to.
**Note:**
- The Payment Cross Account (PCA) feature is in the Early Adopter phase.
- When PCA is enabled for the tenant, you can specify a debit memo / invoice that is different from the account that is specified in the request body.
type: string
items:
description: |
Container for debit memo items. The maximum number of items is 1,000.
**Note:** This field is only available if you have the [Invoice Item Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement/C_Invoice_Item_Settlement) feature enabled. Invoice Item Settlement must be used together with other Invoice Settlement features (Unapplied Payments, and Credit and Debit memos). If you wish 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.
items:
$ref: '#/components/schemas/PaymentDebitMemoApplicationItemApplyRequestType'
type: array
required:
- amount
title: debitMemos
type: object
PaymentInvoiceApplicationApplyRequestType:
properties:
amount:
description: |
The amount that is applied from the payment to the invoice.
format: double
type: number
invoiceId:
description: |
The unique ID of the invoice that the payment is applied to.
If `invoiceId` or `invoiceNumber` is specified, the `writeOff` value can be set to true. This enables writing off a debit memo at the time of refund.
**Note:**
- The Payment Cross Account (PCA) feature is in the Early Adopter phase.
- When PCA is enabled for the tenant, you can specify a debit memo / invoice that is different from the account that is specified in the request body.
type: string
invoiceNumber:
description: |
The number of the invoice that the payment is applied to. For example, `INV00000001`.
**Note:** When both the `invoiceNumber` and `invoiceId` fields are specified, the two fields must match with each other.
- The Payment Cross Account (PCA) feature is in the Early Adopter phase.
- When PCA is enabled for the tenant, you can specify a debit memo / invoice that is different from the account that is specified in the request body.
type: string
items:
description: |
Container for invoice items. The maximum number of items is 1,000.
**Note:** This field is only available if you have the [Invoice Item Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement/C_Invoice_Item_Settlement) feature enabled. Invoice Item Settlement must be used together with other Invoice Settlement features (Unapplied Payments, and Credit and Debit memos). If you wish 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.
items:
$ref: '#/components/schemas/PaymentInvoiceApplicationItemApplyRequestType'
type: array
required:
- amount
title: invoices
type: object
PaymentInvoiceApplicationItemApplyRequestType:
properties:
amount:
description: |
The amount of the payment that is applied to the specific invoice or taxation item.
format: double
type: number
invoiceItemId:
description: |
The ID of the specific invoice item.
type: string
taxItemId:
description: |
The ID of the specific taxation item.
type: string
required:
- amount
title: items
type: object
PaymentDebitMemoApplicationItemApplyRequestType:
properties:
amount:
description: |
The amount of the payment that is applied to the specific debit memo or taxation item.
format: double
type: number
debitMemoItemId:
description: |
The ID of the specific debit memo item.
type: string
taxItemId:
description: |
The ID of the specific taxation item.
type: string
required:
- amount
title: items
type: object
GETPaymentPartsCollectionType:
properties:
nextPage:
description: |
URL to retrieve the next page of the response if it exists; otherwise absent.
format: URL
type: string
parts:
description: |
Container for payment parts.
items:
$ref: '#/components/schemas/GETPaymentPartTypewithSuccess'
type: array
success:
description: Returns `true` if the request was processed successfully.
type: boolean
type: object
GETPaymentPartTypewithSuccess:
properties:
amount:
description: |
The amount of the payment part.
format: double
type: number
createdById:
description: |
The ID of the Zuora user who created the payment part.
type: string
createdDate:
description: |
The date and time when the payment part was created, in `yyyy-mm-dd hh:mm:ss` format. For example, 2017-03-01 15:31:10.
format: date-time
type: string
debitMemoId:
description: |
The ID of the debit memo associated with the payment part.
type: string
id:
description: |
The ID of the payment part.
type: string
invoiceId:
description: |
The ID of the invoice associated with the payment part.
type: string
organizationLabel:
description: |
The organization that this object belongs to.
Note: This field is available only when the Multi-Org feature is enabled.
type: string
updatedById:
description: |
The ID of the Zuora user who last updated the payment part.
type: string
updatedDate:
description: |
The date and time when the payment part was last updated, in `yyyy-mm-dd hh:mm:ss` format. For example, 2017-03-02 15:36:10.
format: date-time
type: string
title: parts
type: object
GETPaymentPartType:
properties:
amount:
description: |
The amount of the payment part.
format: double
type: number
createdById:
description: |
The ID of the Zuora user who created the payment part.
type: string
createdDate:
description: |
The date and time when the payment part was created, in `yyyy-mm-dd hh:mm:ss` format. For example, 2017-03-01 15:31:10.
format: date-time
type: string
debitMemoId:
description: |
The ID of the debit memo associated with the payment part.
type: string
id:
description: |
The ID of the payment part.
type: string
invoiceId:
description: |
The ID of the invoice associated with the payment part.
type: string
organizationLabel:
description: |
The organization that this object belongs to.
Note: This field is available only when the Multi-Org feature is enabled.
type: string
success:
description: Returns `true` if the request was processed successfully.
type: boolean
updatedById:
description: |
The ID of the Zuora user who last updated the payment part.
type: string
updatedDate:
description: |
The date and time when the payment part was last updated, in `yyyy-mm-dd hh:mm:ss` format. For example, 2017-03-02 15:36:10.
format: date-time
type: string
type: object
GETPaymentItemPartCollectionType:
properties:
itemParts:
description: |
Container for payment part items.
items:
$ref: '#/components/schemas/GETPaymentItemPartTypewithSuccess'
type: array
nextPage:
description: |
URL to retrieve the next page of the response if it exists; otherwise absent.
format: URL
type: string
success:
description: Returns `true` if the request was processed successfully.
type: boolean
type: object
GETPaymentItemPartTypewithSuccess:
properties:
amount:
description: |
The amount of the payment part item.
format: double
type: number
createdById:
description: |
The ID of the Zuora user who created the payment part item.
type: string
createdDate:
description: |
The date and time when the payment part item was created, in `yyyy-mm-dd hh:mm:ss` format. For example, 2017-03-01 15:31:10.
format: date-time
type: string
debitMemoItemId:
description: |
The ID of the debit memo item associated with the payment part item.
type: string
id:
description: |
The ID of the payment part item.
type: string
invoiceItemId:
description: |
The ID of the invoice item associated with the payment part item.
type: string
organizationLabel:
description: |
The organization that this object belongs to.
Note: This field is available only when the Multi-Org feature is enabled.
type: string
taxItemId:
description: |
The ID of the taxation item associated with the payment part item.
type: string
updatedById:
description: |
The ID of the Zuora user who last updated the payment part item.
type: string
updatedDate:
description: |
The date and time when the payment part item was last updated, in `yyyy-mm-dd hh:mm:ss` format. For example, 2017-03-02 15:36:10.
format: date-time
type: string
title: itemParts
type: object
GETPaymentItemPartType:
properties:
amount:
description: |
The amount of the payment part item.
format: double
type: number
createdById:
description: |
The ID of the Zuora user who created the payment part item.
type: string
createdDate:
description: |
The date and time when the payment part item was created, in `yyyy-mm-dd hh:mm:ss` format. For example, 2017-03-01 15:31:10.
format: date-time
type: string
debitMemoItemId:
description: |
The ID of the debit memo item associated with the payment part item.
type: string
id:
description: |
The ID of the payment part item.
type: string
invoiceItemId:
description: |
The ID of the invoice item associated with the payment part item.
type: string
organizationLabel:
description: |
The organization that this object belongs to.
Note: This field is available only when the Multi-Org feature is enabled.
type: string
success:
description: Returns `true` if the request was processed successfully.
type: boolean
taxItemId:
description: |
The ID of the taxation item associated with the payment part item.
type: string
updatedById:
description: |
The ID of the Zuora user who last updated the payment part item.
type: string
updatedDate:
description: |
The date and time when the payment part item was last updated, in `yyyy-mm-dd hh:mm:ss` format. For example, 2017-03-02 15:36:10.
format: date-time
type: string
type: object
PostRefundType:
allOf:
- properties:
comment:
description: |
Comments about the refund.
maxLength: 255
minLength: 0
type: string
customRates:
description: |
It contains Home currency and Reporting currency custom rates currencies. The maximum number of items is 2 (you can pass the Home currency item, Reporting currency item, or both).
**Note**:
- This field is only available if you are on the latest Zuora API minor version, or you set the `Zuora-Version` request header to `224.0` or [a later available version](https://developer.zuora.com/v1-api-reference/api-versions/#minor-version).
- You cannot set the custom rates, if both the **Automatically include additional Currency Conversion information in data source exports** option and **Fx data** feature are enabled.
items:
$ref: '#/components/schemas/PaymentWithCustomRatesType'
maxItems: 2
type: array
financeInformation:
description: |
Container for the finance information related to the refund.
properties:
bankAccountAccountingCode:
description: |
The accounting code that maps to a bank account in your accounting system.
maxLength: 100
minLength: 0
type: string
transferredToAccounting:
description: |
Whether the refund was transferred to an external accounting system. Use this field for integration with accounting systems, such as NetSuite.
enum:
- Processing
- 'Yes'
- 'No'
- Error
- Ignore
type: string
unappliedPaymentAccountingCode:
description: |
The accounting code for the unapplied payment.
maxLength: 100
minLength: 0
type: string
type: object
gatewayOptions:
description: |
The field used to pass gateway-specific parameters and parameter values. The fields supported by gateways vary. For more information, see the Overview topic of each gateway integration in [Zuora Knowledge Center](https://knowledgecenter.zuora.com/Zuora_Billing/Billing_and_Payments/M_Payment_Gateways/Supported_Payment_Gateways).
Zuora sends all the information that you specified to the gateway. If you specify any unsupported gateway option parameters, they will be ignored without error prompts.
properties:
key:
description: |
The name of a gateway-specific parameter.
type: string
value:
description: |
The value of the gateway-specific parameter.
type: string
type: object
methodType:
description: |
How an external refund was issued to a customer. This field is required for an external refund and must be left empty for an electronic refund. You can issue an external refund on an electronic payment.
enum:
- ACH
- Cash
- Check
- CreditCard
- PayPal
- WireTransfer
- DebitCard
- CreditCardReferenceTransaction
- BankTransfer
- Other
type: string
reasonCode:
description: |
A code identifying the reason for the transaction. The value must be an existing reason code or empty. If you do not specify a value, Zuora uses the default reason code.
type: string
referenceId:
description: |
The transaction ID returned by the payment gateway for an electronic refund. Use this field to reconcile refunds between your gateway and Zuora Payments.
maxLength: 100
minLength: 0
type: string
refundDate:
description: |
The date when the refund takes effect, in `yyyy-mm-dd` format. The date of the refund cannot be before the payment date. Specify this field only for external refunds. Zuora automatically generates this field for electronic refunds.
format: date
type: string
secondRefundReferenceId:
description: |
The transaction ID returned by the payment gateway if there is an additional transaction for the refund. Use this field to reconcile payments between your gateway and Zuora Payments.
maxLength: 100
minLength: 0
type: string
softDescriptor:
description: A payment gateway-specific field that maps to Zuora for the gateways, Orbital, Vantiv and Verifi.
maxLength: 35
type: string
softDescriptorPhone:
description: A payment gateway-specific field that maps to Zuora for the gateways, Orbital, Vantiv and Verifi.
maxLength: 20
type: string
totalAmount:
description: |
The total amount of the refund. The amount cannot exceed the unapplied amount of the associated payment. If the original payment was applied to one or more invoices or debit memos, you have to unapply a full or partial payment from the invoices or debit memos, and then refund the full or partial unapplied payment to your customers.
format: double
type: number
type:
description: |
The type of the refund.
enum:
- External
- Electronic
type: string
refundTransactionType:
description: |
The transaction type of the refund.
enum:
- Chargeback
- PaymentReversal
type: string
required:
- totalAmount
- type
type: object
- $ref: '#/components/schemas/RefundObjectNSFields'
- $ref: '#/components/schemas/RefundObjectCustomFields'
example:
type: Electronic
totalAmount: 10
GETRefundPaymentType:
allOf:
- properties:
accountId:
description: |
The ID of the account associated with this refund. Zuora associates the refund automatically with the account from the associated payment.
type: string
amount:
description: |
The total amount of the refund.
format: double
type: number
cancelledOn:
description: |
The date and time when the refund was cancelled, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
nullable: true
comment:
description: |
Comments about the refund.
type: string
createdById:
description: |
The ID of the Zuora user who created the refund.
type: string
createdDate:
description: |
The date and time when the refund was created, in `yyyy-mm-dd hh:mm:ss` format. For example, 2017-03-01 15:31:10.
format: date-time
type: string
creditMemoId:
description: |
The ID of the credit memo associated with the refund.
type: string
financeInformation:
description: |
Container for the finance information related to the refund.
properties:
bankAccountAccountingCode:
description: |
The accounting code that maps to a bank account in your accounting system.
type: string
nullable: true
bankAccountAccountingCodeType:
description: |
The type of the accounting code that maps to a bank account in your accounting system.
type: string
nullable: true
transferredToAccounting:
description: |
Whether the refund was transferred to an external accounting system. Use this field for integration with accounting systems, such as NetSuite.
enum:
- Processing
- 'Yes'
- 'No'
- Error
- Ignore
type: string
unappliedPaymentAccountingCode:
description: |
The accounting code for the unapplied payment.
type: string
nullable: true
unappliedPaymentAccountingCodeType:
description: |
The type of the accounting code for the unapplied payment.
type: string
nullable: true
type: object
gatewayId:
description: |
The ID of the gateway instance that processes the refund.
type: string
gatewayReconciliationReason:
description: |
The reason of gateway reconciliation.
type: string
nullable: true
gatewayReconciliationStatus:
description: |
The status of gateway reconciliation.
type: string
nullable: true
gatewayResponse:
description: |
The message returned from the payment gateway for the refund. This message is gateway-dependent.
type: string
gatewayResponseCode:
description: |
The code returned from the payment gateway for the refund. This code is gateway-dependent.
type: string
gatewayState:
description: |
The status of the refund in the gateway.
enum:
- MarkedForSubmission
- Submitted
- Settled
- NotSubmitted
- FailedToSettle
type: string
id:
description: |
The ID of the created refund.
type: string
markedForSubmissionOn:
description: |
The date and time when a refund was marked and waiting for batch submission to the payment process, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
nullable: true
methodType:
description: |
How an external refund was issued to a customer.
enum:
- ACH
- Cash
- Check
- CreditCard
- PayPal
- WireTransfer
- DebitCard
- CreditCardReferenceTransaction
- BankTransfer
- Other
type: string
number:
description: |
The unique identification number of the refund.
type: string
organizationLabel:
description: |
The organization that this object belongs to.
Note: This field is available only when the Multi-Org feature is enabled.
type: string
paymentGatewayNumber:
description: |
The natural key for the payment gateway.
type: string
paymentId:
description: |
The ID of the payment that is refunded.
type: string
paymentMethodId:
description: |
The unique ID of the payment method that the customer used to make the refund.
type: string
paymentMethodSnapshotId:
description: |
The unique ID of the payment method snapshot, which is a copy of the particular payment method used in a transaction.
type: string
payoutId:
description: |
The payout ID of the refund from the gateway side.
type: string
nullable: true
reasonCode:
description: |
A code identifying the reason for the transaction.
type: string
referenceId:
description: |
The transaction ID returned by the payment gateway for an electronic refund. Use this field to reconcile refunds between your gateway and Zuora Payments.
type: string
nullable: true
refundDate:
description: |
The date when the refund takes effect, in `yyyy-mm-dd` format.
format: date
type: string
refundTransactionTime:
description: |
The date and time when the refund was issued, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
secondRefundReferenceId:
description: |
The transaction ID returned by the payment gateway if there is an additional transaction for the refund. Use this field to reconcile payments between your gateway and Zuora Payments.
type: string
nullable: true
settledOn:
description: |
The date and time when the refund was settled in the payment processor, in `yyyy-mm-dd hh:mm:ss` format. This field is used by the Spectrum gateway only and not applicable to other gateways.
format: date-time
type: string
nullable: true
softDescriptor:
description: |
A payment gateway-specific field that maps to Zuora for the gateways, Orbital, Vantiv and Verifi.
type: string
nullable: true
softDescriptorPhone:
description: |
A payment gateway-specific field that maps to Zuora for the gateways, Orbital, Vantiv and Verifi.
type: string
nullable: true
status:
description: |
The status of the refund.
enum:
- Processed
- Canceled
- Error
- Processing
type: string
submittedOn:
description: |
The date and time when the refund was submitted, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
success:
description: Returns `true` if the request was processed successfully.
type: boolean
type:
description: |
The type of the refund.
enum:
- External
- Electronic
type: string
updatedById:
description: |
The ID of the the Zuora user who last updated the refund.
type: string
updatedDate:
description: |
The date and time when the refund was last updated, in `yyyy-mm-dd hh:mm:ss` format. For example, 2017-03-02 15:36:10.
format: date-time
type: string
type: object
- $ref: '#/components/schemas/RefundObjectNSFields'
- $ref: '#/components/schemas/RefundObjectCustomFields'
PostRefundwithAutoUnapplyType:
allOf:
- properties:
comment:
description: |
Comments about the refund.
maxLength: 255
minLength: 0
type: string
debitMemos:
description: |
Container for debit memos. The maximum number of debit memos is 1,000.
items:
$ref: '#/components/schemas/PaymentDebitMemoApplicationApplyRequestType'
type: array
financeInformation:
description: |
Container for the finance information related to the refund.
properties:
bankAccountAccountingCode:
description: |
The accounting code that maps to a bank account in your accounting system.
maxLength: 100
minLength: 0
type: string
transferredToAccounting:
description: |
Whether the refund was transferred to an external accounting system. Use this field for integration with accounting systems, such as NetSuite.
enum:
- Processing
- 'Yes'
- 'No'
- Error
- Ignore
type: string
unappliedPaymentAccountingCode:
description: |
The accounting code for the unapplied payment.
maxLength: 100
minLength: 0
type: string
type: object
gatewayOptions:
description: |
The field used to pass gateway-specific parameters and parameter values. The fields supported by gateways vary. For more information, see the Overview topic of each gateway integration in [Zuora Knowledge Center](https://knowledgecenter.zuora.com/Zuora_Billing/Billing_and_Payments/M_Payment_Gateways/Supported_Payment_Gateways).
Zuora sends all the information that you specified to the gateway. If you specify any unsupported gateway option parameters, they will be ignored without error prompts.
properties:
key:
description: |
The name of a gateway-specific parameter.
type: string
value:
description: |
The value of the gateway-specific parameter.
type: string
type: object
invoices:
description: |
Container for invoices. The maximum number of invoices is 1,000.
items:
$ref: '#/components/schemas/PaymentInvoiceApplicationApplyRequestType'
type: array
methodType:
description: |
How an external refund was issued to a customer. This field is required for an external refund and must be left empty for an electronic refund. You can issue an external refund on an electronic payment.
enum:
- ACH
- Cash
- Check
- CreditCard
- PayPal
- WireTransfer
- DebitCard
- CreditCardReferenceTransaction
- BankTransfer
- Other
type: string
reasonCode:
description: |
A code identifying the reason for the transaction. The value must be an existing reason code or empty. If you do not specify a value, Zuora uses the default reason code.
type: string
referenceId:
description: |
The transaction ID returned by the payment gateway for an electronic refund. Use this field to reconcile refunds between your gateway and Zuora Payments.
maxLength: 100
minLength: 0
type: string
refundDate:
description: |
The date when the refund takes effect, in `yyyy-mm-dd` format. The date of the refund cannot be before the payment date. Specify this field only for external refunds. Zuora automatically generates this field for electronic refunds.
format: date
type: string
secondRefundReferenceId:
description: |
The transaction ID returned by the payment gateway if there is an additional transaction for the refund. Use this field to reconcile payments between your gateway and Zuora Payments.
maxLength: 100
minLength: 0
type: string
softDescriptor:
description: A payment gateway-specific field that maps to Zuora for the gateways, Orbital, Vantiv and Verifi.
maxLength: 35
type: string
softDescriptorPhone:
description: A payment gateway-specific field that maps to Zuora for the gateways, Orbital, Vantiv and Verifi.
maxLength: 20
type: string
totalAmount:
description: |
The total amount of the refund. If you do not specify a value, Zuora initiates a full refund of the payment amount, which is the sum of the applied and unapplied payment amounts.
- `Full Refund`: If the refund amount and debit memo/ invoice are not specified, then the payment will be unapplied completely, followed by processing a full refund.
- `Partial Refund`:
- If the total amount is specified, and the debit memo/invoice is not specified, you can unapply the refund amount from the available debit memo/invoice and refund the unapplied payment to the customer.
- If the total amount is specified, along with the debit memo and the invoice, you can unapply the applied payments from the mentioned invoices and debit memos, and refund the unapplied payments to customers.
format: double
type: number
type:
description: |
The type of the refund.
enum:
- External
- Electronic
type: string
refundTransactionType:
description: |
The transaction type of the refund.
enum:
- Chargeback
- PaymentReversal
type: string
writeOff:
default: false
description: |
Indicates whether to write off a document.
type: boolean
writeOffOptions:
description: |
Container for the write-off information to create credit memo.
properties:
comment:
description: |
Comments about the credit memo which is created as a result of the write off.
maxLength: 100
type: string
memoDate:
description: |
The date when the credit memo takes effect.
format: date
type: string
reasonCode:
description: |
A code identifying the reason for the credit memo.
type: string
taxAutoCalculation:
description: |
Specifies whether taxes are automatically recalculated for the credit memo generated during the write-off process.
When set to `true`, the system fetches the latest tax rates from the tax vendor instead of copying the tax amounts from the original invoice.
The default value is `false`.
**Note**: This feature is in the **Early Availability** phase. Contact Zuora Global Support to enable this feature before using it.
type: boolean
type: object
required:
- type
type: object
- $ref: '#/components/schemas/RefundObjectNSFields'
- $ref: '#/components/schemas/RefundObjectCustomFields'
example:
type: Electronic
totalAmount: 10
GETRefundPaymentTypeAutoUnapply:
allOf:
- properties:
accountId:
description: |
The ID of the account associated with this refund. Zuora associates the refund automatically with the account from the associated payment.
type: string
amount:
description: |
The total amount of the refund.
format: double
type: number
cancelledOn:
description: |
The date and time when the refund was cancelled, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
comment:
description: |
Comments about the refund.
type: string
createdById:
description: |
The ID of the Zuora user who created the refund.
type: string
createdDate:
description: |
The date and time when the refund was created, in `yyyy-mm-dd hh:mm:ss` format. For example, 2017-03-01 15:31:10.
format: date-time
type: string
creditMemoId:
description: |
The ID of the credit memo associated with the refund.
type: string
financeInformation:
description: |
Container for the finance information related to the refund.
properties:
bankAccountAccountingCode:
description: |
The accounting code that maps to a bank account in your accounting system.
type: string
bankAccountAccountingCodeType:
description: |
The type of the accounting code that maps to a bank account in your accounting system.
type: string
transferredToAccounting:
description: |
Whether the refund was transferred to an external accounting system. Use this field for integration with accounting systems, such as NetSuite.
enum:
- Processing
- 'Yes'
- 'No'
- Error
- Ignore
type: string
unappliedPaymentAccountingCode:
description: |
The accounting code for the unapplied payment.
type: string
unappliedPaymentAccountingCodeType:
description: |
The type of the accounting code for the unapplied payment.
type: string
type: object
gatewayId:
description: |
The ID of the gateway instance that processes the refund.
type: string
gatewayReconciliationReason:
description: |
The reason of gateway reconciliation.
type: string
gatewayReconciliationStatus:
description: |
The status of gateway reconciliation.
type: string
gatewayResponse:
description: |
The message returned from the payment gateway for the refund. This message is gateway-dependent.
type: string
gatewayResponseCode:
description: |
The code returned from the payment gateway for the refund. This code is gateway-dependent.
type: string
gatewayState:
description: |
The status of the refund in the gateway.
enum:
- MarkedForSubmission
- Submitted
- Settled
- NotSubmitted
- FailedToSettle
type: string
id:
description: |
The ID of the created refund.
type: string
markedForSubmissionOn:
description: |
The date and time when a refund was marked and waiting for batch submission to the payment process, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
methodType:
description: |
How an external refund was issued to a customer.
enum:
- ACH
- Cash
- Check
- CreditCard
- PayPal
- WireTransfer
- DebitCard
- CreditCardReferenceTransaction
- BankTransfer
- Other
type: string
number:
description: |
The unique identification number of the refund.
type: string
paymentGatewayNumber:
description: |
The natural key for the payment gateway.
type: string
paymentId:
description: |
The ID of the payment that is refunded.
type: string
paymentMethodId:
description: |
The unique ID of the payment method that the customer used to make the refund.
type: string
paymentMethodSnapshotId:
description: |
The unique ID of the payment method snapshot, which is a copy of the particular payment method used in a transaction.
type: string
payoutId:
description: |
The payout ID of the refund from the gateway side.
type: string
reasonCode:
description: |
A code identifying the reason for the transaction.
type: string
referenceId:
description: |
The transaction ID returned by the payment gateway for an electronic refund. Use this field to reconcile refunds between your gateway and Zuora Payments.
type: string
refundDate:
description: |
The date when the refund takes effect, in `yyyy-mm-dd` format.
format: date
type: string
refundTransactionTime:
description: |
The date and time when the refund was issued, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
secondRefundReferenceId:
description: |
The transaction ID returned by the payment gateway if there is an additional transaction for the refund. Use this field to reconcile payments between your gateway and Zuora Payments.
type: string
settledOn:
description: |
The date and time when the refund was settled in the payment processor, in `yyyy-mm-dd hh:mm:ss` format. This field is used by the Spectrum gateway only and not applicable to other gateways.
format: date-time
type: string
softDescriptor:
description: |
A payment gateway-specific field that maps to Zuora for the gateways, Orbital, Vantiv and Verifi.
type: string
softDescriptorPhone:
description: |
A payment gateway-specific field that maps to Zuora for the gateways, Orbital, Vantiv and Verifi.
type: string
status:
description: |
The status of the refund.
enum:
- Processed
- Canceled
- Error
- Processing
type: string
submittedOn:
description: |
The date and time when the refund was submitted, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
success:
description: Returns `true` if the request was processed successfully.
type: boolean
type:
description: |
The type of the refund.
enum:
- External
- Electronic
type: string
updatedById:
description: |
The ID of the the Zuora user who last updated the refund.
type: string
updatedDate:
description: |
The date and time when the refund was last updated, in `yyyy-mm-dd hh:mm:ss` format. For example, 2017-03-02 15:36:10.
format: date-time
type: string
writeOffResults:
description: |
Container for the write-off information of credit memo and apply information.
properties:
errorMessage:
description: |
The error message about write off failed.
type: string
transactions:
description: |
The credit memo apply information.
properties:
appliedAmount:
description: |
The credit memo applied amopunt.
format: double
type: number
creditMemoAmount:
description: |
The credit memo amount.
type: string
creditMemoNumber:
description: |
The unique identification number of the credit memo.
type: string
creditMemoStatus:
description: |
The status of the credit memo.
enum:
- Draft
- Posted
- Canceled
- Error
- PendingForTax
- Generating
- CancelInProgress
type: string
invoiceNumber:
description: |
The unique identification number of the invoice.
type: string
title: transactions
type: object
type: object
type: object
- $ref: '#/components/schemas/RefundObjectNSFields'
- $ref: '#/components/schemas/RefundObjectCustomFields'
TransferPaymentType:
example:
accountId: 4028905f5a87c0ff015a88889fe500a8
properties:
accountId:
description: |
The ID of the customer account that the payment is transferred to.
Unassign a payment by setting this field to an empty string. This will automatically transfer the payment to a null account.
type: string
type: object
UnapplyPaymentType:
example:
invoices:
- invoiceId: 8ad097b490c4e5aa0190c9b931817cef
amount: 12
properties:
debitMemos:
description: |
Container for debit memos. The maximum number of debit memos is 1,000.
items:
$ref: '#/components/schemas/PaymentDebitMemoApplicationUnapplyRequestType'
type: array
effectiveDate:
description: |
The date when the payment is unapplied, in `yyyy-mm-dd` format. The effective date must be later than or equal to the maximum effective date of the payment.
format: date
type: string
invoices:
description: |
Container for invoices. The maximum number of invoice is 1,000.
items:
$ref: '#/components/schemas/PaymentInvoiceApplicationUnapplyRequestType'
type: array
type: object
PaymentDebitMemoApplicationUnapplyRequestType:
properties:
amount:
description: |
The amount of the payment that is unapplied from the debit memo.
format: double
type: number
debitMemoId:
description: |
The unique ID of the debit memo that the payment is unapplied from.
**Note:**
- The Payment Cross Account (PCA) feature is in the Early Adopter phase.
- When PCA is enabled for the tenant, you can specify a debit memo / invoice that is different from the account that is specified in the request body.
type: string
debitMemoNumber:
description: |
The number of the debit memo that the payment is unapplied from.
**Note:**
- The Payment Cross Account (PCA) feature is in the Early Adopter phase.
- When PCA is enabled for the tenant, you can specify a debit memo / invoice that is different from the account that is specified in the request body.
type: string
items:
description: |
Container for debit memo items. The maximum number of items is 1,000.
**Note:** This field is only available if you have the [Invoice Item Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement/C_Invoice_Item_Settlement) feature enabled. Invoice Item Settlement must be used together with other Invoice Settlement features (Unapplied Payments, and Credit and Debit memos). If you wish 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.
items:
$ref: '#/components/schemas/PaymentDebitMemoApplicationItemUnapplyRequestType'
type: array
required:
- amount
title: debitMemos
type: object
PaymentInvoiceApplicationUnapplyRequestType:
properties:
amount:
description: |
The amount of the payment that is unapplied from the invoice.
format: double
type: number
invoiceId:
description: |
The unique ID of the invoice that the payment is unapplied from.
**Note:**
- The Payment Cross Account (PCA) feature is in the Early Adopter phase.
- When PCA is enabled for the tenant, you can specify a debit memo / invoice that is different from the account that is specified in the request body.
type: string
invoiceNumber:
description: |
The number of the invoice that the payment is unapplied from. For example, `INV00000001`.
**Note:** When both the `invoiceNumber` and `invoiceId` fields are specified, the two fields must match with each other.
- The Payment Cross Account (PCA) feature is in the Early Adopter phase.
- When PCA is enabled for the tenant, you can specify a debit memo / invoice that is different from the account that is specified in the request body.
type: string
items:
description: |
Container for invoice items. The maximum number of items is 1,000.
**Note:** This field is only available if you have the [Invoice Item Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement/C_Invoice_Item_Settlement) feature enabled. Invoice Item Settlement must be used together with other Invoice Settlement features (Unapplied Payments, and Credit and Debit memos). If you wish 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.
items:
$ref: '#/components/schemas/PaymentInvoiceApplicationItemUnapplyRequestType'
type: array
required:
- amount
title: invoices
type: object
PaymentInvoiceApplicationItemUnapplyRequestType:
properties:
amount:
description: |
The amount of the payment that is unapplied from the specific invoice or taxation item.
format: double
type: number
invoiceItemId:
description: |
The ID of the specific invoice item.
type: string
taxItemId:
description: |
The ID of the specific taxation item.
type: string
required:
- amount
title: items
type: object
PaymentDebitMemoApplicationItemUnapplyRequestType:
properties:
amount:
description: |
The amount of the payment that is unapplied from the specific debit mem or taxation item.
format: double
type: number
debitMemoItemId:
description: |
The ID of the specific debit memo item.
type: string
taxItemId:
description: |
The ID of the specific taxation item.
type: string
required:
- amount
title: items
type: object
ProxyGetPaymentTransactionLog:
properties:
AVSResponseCode:
description: |
The response code returned by the payment gateway referring to the AVS international response of the payment transaction.
type: string
BatchId:
description: |
The ID of the batch used to send the transaction if the request was sent in a batch.
type: string
CVVResponseCode:
description: |
The response code returned by the payment gateway referring to the CVV international response of the payment transaction.
type: string
Gateway:
description: |
The name of the payment gateway used to transact the current payment transaction log.
type: string
GatewayReasonCode:
description: |
The code returned by the payment gateway for the payment. This code is gateway-dependent.
type: string
GatewayReasonCodeDescription:
description: |
The message returned by the payment gateway for the payment. This message is gateway-dependent.
type: string
GatewayState:
description: |
The state of the transaction at the payment gateway.
enum:
- MarkedForSubmission
- Submitted
- Settled
- NotSubmitted
- FailedToSettle
type: string
GatewayTransactionType:
description: |
The type of the transaction, either making a payment, or canceling a payment.
enum:
- Authorization
- Sale
- Void
- Inquiry
- VoidAuth
type: string
Id:
description: |
The ID of the payment transaction log.
type: string
PaymentId:
description: |
The ID of the payment wherein the payment transaction log was recorded.
type: string
RequestString:
description: |
The payment transaction request string sent to the payment gateway.
type: string
ResponseString:
description: |
The payment transaction response string returned by the payment gateway.
type: string
TransactionDate:
description: |
The transaction date when the payment was performed.
format: date-time
type: string
TransactionId:
description: |
The transaction ID returned by the payment gateway. This field is used to reconcile payment transactions between the payment gateway and records in Zuora.
type: string
type: object
GETPaymentRunCollectionType:
properties:
nextPage:
description: |
The URL for requesting the next page of the response, if it exists; otherwise absent.
type: string
paymentRuns:
description: |
Container for payment runs.
items:
$ref: '#/components/schemas/GETPaymentRunType'
type: array
success:
description: |
Returns `true` if the request was processed successfully.
type: boolean
type: object
GETPaymentRunType:
properties:
accountId:
description: |
The ID of the customer account associated with the payment run.
type: string
applyCreditBalance:
description: |
**Note:** This field is only available if you have the Credit Balance feature enabled and the Invoice Settlement feature disabled.
Whether to apply credit balances in the payment run. This field is only available when you have Invoice Settlement feature disabled.
type: boolean
autoApplyCreditMemo:
description: |
**Note:** This field is only available if you have [Invoice Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement) 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.
Whether to automatically apply a posted credit memo to one or more receivables in the payment run.
type: boolean
autoApplyUnappliedPayment:
description: |
**Note:** This field is only available if you have [Invoice Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement) 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.
Whether to automatically apply unapplied payments to one or more receivables in the payment run.
type: boolean
batch:
description: |
The alias name given to a batch.
example: Batch1
type: string
billCycleDay:
description: |
The billing cycle day (BCD), the day of the month when a bill run generates invoices for the account.
example: 1
type: string
billingRunId:
description: |
The ID of the bill run.
format: uuid
type: string
collectPayment:
description: |
Whether to process electronic payments during the execution of payment runs.
type: boolean
completedOn:
description: |
The date and time when the payment run is completed, in `yyyy-mm-dd hh:mm:ss` format. For example, 2017-03-01 11:39:58.
format: date-time
type: string
nullable: true
consolidatedPayment:
description: |
**Note:** The **Process Electronic Payment** permission also needs to be allowed for a Manage Payment Runs role to work. See [Payments Roles](https://knowledgecenter.zuora.com/CF_Users_and_Administrators/A_Administrator_Settings/User_Roles/e_Payments_Roles) for more information.
Whether to process a single payment for all receivables that are due on an account.
type: boolean
createdById:
description: |
The ID of the Zuora user who created the payment run.
type: string
createdDate:
description: |
The date and time when the payment run was created, in `yyyy-mm-dd hh:mm:ss` format. For example, 2017-03-01 15:31:10.
format: date-time
type: string
currency:
description: |
A currency defined in the web-based UI administrative settings.
example: USD
type: string
executedOn:
description: |
The date and time when the payment run is executed, in `yyyy-mm-dd hh:mm:ss` format. For example, 2017-03-01 11:30:37.
format: date-time
type: string
nullable: true
id:
description: |
The ID of the payment run.
type: string
number:
description: |
The identification number of the payment run.
type: string
organizationLabels:
description: |
The organization(s) that the object belongs to.
Note: This field is available only when the Multi-Org feature is enabled.
items:
properties:
organizationId:
description: |
The organization ID.
type: string
organizationName:
description: |
The organization name.
type: string
type: object
type: array
paymentGatewayId:
description: |
The ID of the gateway instance that processes the payment.
format: uuid
type: string
nullable: true
processPaymentWithClosedPM:
description: |
**Note:** The **Process Electronic Payment** permission also needs to be allowed for a Manage Payment Runs role to work. See [Payments Roles](https://knowledgecenter.zuora.com/CF_Users_and_Administrators/A_Administrator_Settings/User_Roles/e_Payments_Roles) for more information.
Whether to process payments even if the default payment method is closed.
type: boolean
runDate:
description: |
The date and time when the scheduled payment run is to be executed for collecting payments.
format: date-time
type: string
status:
description: |
The status of the created payment run.
enum:
- Pending
- Processing
- Completed
- Error
- Canceled
type: string
success:
description: |
Returns `true` if the request was processed successfully.
type: boolean
targetDate:
description: |
The target date used to determine which receivables to be collected in the payment run.
format: date
type: string
updatedById:
description: |
The ID of the Zuora user who last updated the payment run.
type: string
updatedDate:
description: |
The date and time when the payment run was last updated, in `yyyy-mm-dd hh:mm:ss` format. For example, 2017-03-02 15:36:10.
format: date-time
type: string
useCustomPaymentMethods:
description: |
Whether to enable payment profiles for a payment run.
type: boolean
title: paymentRuns
type: object
POSTPaymentRunRequest:
example:
accountId: 8ad09be48db5aba7018db604776d4854
targetDate: '2024-07-24'
properties:
accountId:
description: |
The ID of the customer account associated with the payment run.
This field conflicts with each of the `batch`, `billCycleDay`, `currency`, `paymentGatewayId`, and `billingRunId` fields. If there are such conflicts, an error occurs and an error message is returned.
format: uuid
type: string
applyCreditBalance:
description: |
If `applyCreditBalance` is true, the credit memo or unapplied payment on the order account will be automatically applied to the invoices generated by this order. The credit memo generated by this order will not be automatically applied to any invoices.
type: boolean
autoApplyCreditMemo:
description: |
**Note:** This field is only available if you have [Invoice Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement) 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.
Whether to automatically apply a posted credit memo to one or more receivables in the payment run.
type: boolean
autoApplyUnappliedPayment:
description: |
**Note:** This field is only available if you have [Invoice Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement) 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.
Whether to automatically apply unapplied payments to one or more receivables in the payment run.
type: boolean
batch:
description: |
The alias name given to a batch. The batch name is a string of 50 characters or less.
This field conflicts with the `accountId` field. If they are both specified in the request body, an error occurs and an error message is returned.
**Note**: By default, you have 50 configurable account batches. To increase the limit to 200 batches, you must have the Performance Booster Elite package.
type: string
billCycleDay:
description: |
The billing cycle day (BCD), the day of the month when a bill run generates invoices for the account. The value must be equal to or less then 31, and 31 is mean the EOM.
This field conflicts with the `accountId` field. If they are both specified in the request body, an error occurs and an error message is returned.
type: string
billingRunId:
description: |
The ID of a bill run.
This field conflicts with the `accountId` field. If they are both specified in the request body, an error occurs and an error message is returned.
format: uuid
type: string
collectPayment:
description: |
Whether to process electronic payments during the execution of payment runs.
If the Payment user permission "Process Electronic Payment" is disabled, this field will be ignored.
type: boolean
consolidatedPayment:
description: |
**Note:** The **Process Electronic Payment** permission also needs to be allowed for a Manage Payment Runs role to work. See [Payments Roles](https://knowledgecenter.zuora.com/CF_Users_and_Administrators/A_Administrator_Settings/User_Roles/e_Payments_Roles) for more information.
Whether to process a single payment for all receivables that are due on an account.
type: boolean
currency:
description: |
A currency defined in the web-based UI administrative settings.
This field conflicts with the `accountId` field. If they are both specified in the request body, an error occurs and an error message is returned.
type: string
data:
description: |
The array of data for specifying records of accounts and invoices/debit memos that will be collected and processed by a payment run.
When you specify the data array, ensure that at least one record is passed in. If an empty array is specified, `accountId`, `batch`, `billCycleDay`, `currency`, `paymentGatewayId`, and `billingRunId` fields will be used to define the billing documents to be collected. If the [Multiple Currencies](https://knowledgecenter.zuora.com/Zuora_Billing/Bill_your_customers/Flexible_Billing/Multiple_Currencies) feature is enabled, you can filter the accounts by `currency` based on the customer's billing document.
A maximum of 50K records are allowed to be passed into the `data` array.
Here is an example:
```
{
"accountId": "60c81b5bc51649e8a7d1b48303194790",
"documentId": "2c9081a03c63c94c013c6894af5602dd",
"documentType": "Invoice",
"amount": 80,
"paymentMethodId": "2c9081a03c6d7b51013c6d7e4ada0a1c",
"paymentGatewayId": "d2abe8342e1811ea80e774b9452e17ea",
"comment": "Payment Comments",
"customField1__c": "cf_value1",
"customField2__c": "cf_value2"
}
```
Here is another example for a standalone payment:
```
{
"accountId": "account2",
"amount": 100,
"currency": "GBP",
"standalone": true
}
```
items:
$ref: '#/components/schemas/POSTPaymentRunDataElementRequest'
title: payment run data
type: array
organizationLabels:
description: |
The organizations that the run is created for.
For each item in the array, either the `organizationId` or the `organizationName` field is required.
This field is only required when you have already turned on Multi-Org feature.
items:
properties:
organizationId:
description: |
The organization ID.
type: string
organizationName:
description: |
The organization name.
type: string
type: object
type: array
paymentGatewayId:
description: |
The ID of the gateway instance that processes the payment.
This field conflicts with the `accountId` field. If they are both specified in the request body, an error occurs and an error message is returned.
format: uuid
type: string
processPaymentWithClosedPM:
description: |
**Note:** The **Process Electronic Payment** permission also needs to be allowed for a Manage Payment Runs role to work. See [Payments Roles](https://knowledgecenter.zuora.com/CF_Users_and_Administrators/A_Administrator_Settings/User_Roles/e_Payments_Roles) for more information.
Whether to process payments even if the default payment method is closed.
type: boolean
runDate:
description: |
The date and time when the scheduled payment run is to be executed, in `yyyy-mm-dd hh:mm:ss` format. The backend will ignore mintues and seconds in the field value. For example, if you specify `2017-03-01 11:30:37` for this value, this payment run will be run at 2017-03-01 11:00:00.
You must specify either the `runDate` field or the `targetDate` field in the request body. If you specify the `runDate` field, the scheduced payment run is to be executed on the run date. If you specify the `targetDate` field, the payment run is executed immediately after it is created.
format: date-time
type: string
targetDate:
description: |
The target date used to determine which receivables to be paid in the payment run. The payments are collected for all receivables with the due date no later than the target date.
You must specify either the `runDate` field or the `targetDate` field in the request body. If you specify the `runDate` field, the scheduced payment run is to be executed on the run date. If you specify the `targetDate` field, the payment run is executed immediately after it is created.
format: date
type: string
useCustomPaymentMethods:
description: |
Whether to enable payment profiles for a payment run.
type: boolean
type: object
POSTPaymentRunDataElementRequest:
allOf:
- properties:
accountId:
description: |
A valid account ID associated with the payment run.
If `consolidatedPayment` is set to `true`, this field is used in processing a single payment for invoices/debit memos due on an account.
type: string
accountNumber:
description: |
The number of the customer account associated with the payment run, such as `A00000001`.
You can specify either `accountNumber` or `accountId` for a customer account, but not both of them.
If `consolidatedPayment` is set to `true`, this field is used in processing a single payment for invoices, debit memos, and standalone payments due on an account.
type: string
amount:
description: |
The amount to be collected for the specified invoice/debit memo. `amount` must be a positive numeric value no more than the balance of the specified invoice/debit memo.
This field is only available when `documentId` is specified. If `amount` is not specified, whole balance of the invoice/debit memo is collected.
type: number
comment:
description: |
Additional comments.
type: string
currency:
description: |
Note: This field is only available if support for standalone payments is enabled.
The currency of the standalone payment. Specify this field only if the `standalone` field is `true`. The currency of the standalone payment can be different from the payment currency defined in the customer account settings.
type: string
dataItems:
description: |
The array of data for each Invoice if you want to collect payment for particular items through one payment method. The grouped items are sent as one data record. This field is available if the [Invoice Item Settlement](https://knowledgecenter.zuora.com/Zuora_Billing/Bill_your_customers/Adjust_invoice_amounts/Invoice_Settlement/Invoice_Item_Settlement/Overview_of_Invoice_Item_Settlement) permission is enabled.
Here is another example for a data item:
```
{
"accountId": "60c81b5bc51649e8a7d1b48303194790",
"documentId": "2c9081a03c63c94c013c6894af5602dd",
"documentType": "Invoice",
"dataItems": [
{
"documentItemId": "8a92ab0e8ab14c53018ac746961c10d1",
"amount": 40
},
{
"taxItemId": "8a92ab0e8ab14c53018ac746961c10d2",
"amount": 40
}
],
"amount": 80,
"paymentMethodId": "2c9081a03c6d7b51013c6d7e4ada0a1c",
"paymentGatewayId": "d2abe8342e1811ea80e774b9452e17ea",
"comment": "Payment Comments",
"customField1__c": "cf_value1",
"customField2__c": "cf_value2"
},
```
properties:
amount:
description: |
The total amount to be collected for the specified invoice/debit memo item. The sum of the item amount should be equal to document amount.
type: number
documentItemId:
description: |
The ID of a billing document of the invoice item or debit memo item.
type: string
taxItemId:
description: |
The tax ID of the invoice item or debit memo item.
type: string
title: dataItems
type: object
documentId:
description: |
The ID of a billing document associated with the payment run. `documentId` must be valid and match with `documentType`.
You must either specify both `documentId` and `documentType`, or specify neither of them.
If neither of `documentType` and `documentId` is specified, all invoices/debit memos with open balance of the account are collected.
type: string
documentNumber:
description: |
The number of a billing document associated with the payment run. `documentNumber` must be valid and match with `documentType`.
You must either specify both `documentNumber` and `documentType`, or specify neither of them.
If neither of `documentType` and `documentNumber` is specified, all invoices/debit memos with open balance of the account are collected.
type: string
documentType:
description: |
The type of a billing document associated with the payment run. The value can be `Invoice` or `DebitMemo`, but `DebitMemo` is only supported if the Invoice Settlement feature is enabled.
You must either specify both `documentType` and `documentId`, or specify neither of them.
If neither of `documentType` and `documentId` is specified, all invoices/debit memos with open balance of the account are collected.
enum:
- Invoice
- DebitMemo
type: string
paymentGatewayId:
description: |
The ID of the payment gateway for collecting invoices/debit memos. The specified payment gateway must be valid and active.
If Payment Gateway Routing is enabled:
- If this field is not specified, gateway routing rules will be invoked.
- If this field is specified, the specified gateway will be used to process the payment.
If Payment Gateway Routing is disabled:
- If this field is not specified, the default payment gateway will be used to process the payment. The default gateway of the customer account takes precedence over the default gateway of the tenant.
- If this field is specified, the specified gateway will be used to process the payment.
If `consolidatedPayment` is set to `true`, this field is used in processing a single payment for invoices/debit memos due on an account.
type: string
paymentMethodId:
description: |
The ID of the payment method for collecting invoices/debit memos. The specified payment method must be a valid non-system payment method. If it is not specified, the default payment method of the account is used regardless of the `autoPay` value of the account.
If `processPaymentWithClosedPM` is set to `false`, the payment method cannot be closed.
If the payment retry rules are enabled, the payment method must meet the rules.
If `consolidatedPayment` is set to `true`, this field is used in processing a single payment for invoices/debit memos due on an account.
type: string
standalone:
default: false
description: |
Note: This field is only available if support for standalone payments is enabled.
Specify `true` to indicate that this is a standalone payment that will be created and processed in Zuora through Zuora gateway integration but will be settled outside of Zuora. When `standalone` is set to `true`:
- `accountId` or `accountNumber` is required.
- `amount` is required.
- The amount will not be summed up into the account balance and key metrics regardless of the payment currency.
- No settlement data will be created.
- Either the applied amount or the unapplied amount of the payment is zero.
- The standalone payment cannot be applied, unapplied, or transferred.
type: boolean
type: object
- $ref: '#/components/schemas/PaymentObjectCustomFields'
PUTPaymentRunRequest:
example:
autoApplyUnappliedPayment: true
properties:
accountId:
description: |
The ID of the customer account associated with the payment run.
This field conflicts with each of the `batch`, `billCycleDay`, `currency`, `paymentGatewayId`, and `billingRunId` fields. If there are such conflicts, an error occurs and an error message is returned.
format: uuid
type: string
applyCreditBalance:
description: |
**Note:** This field is only available if you have the Credit Balance feature enabled and the Invoice Settlement feature disabled.
Whether to apply credit balances in the payment run. This field is only available when you have Invoice Settlement feature disabled.
type: boolean
autoApplyCreditMemo:
description: |
**Note:** This field is only available if you have [Invoice Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement) 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.
Whether to automatically apply a posted credit memo to one or more receivables in the payment run.
type: boolean
autoApplyUnappliedPayment:
description: |
**Note:** This field is only available if you have [Invoice Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement) 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.
Whether to automatically apply unapplied payments to one or more receivables in the payment run.
type: boolean
batch:
description: |
The alias name given to a batch. The batch name is a string of 50 characters or less.
This field conflicts with the `accountId` field. If they are both specified in the request body, an error occurs and an error message is returned.
**Note**: By default, you have 50 configurable account batches. To increase the limit to 200 batches, you must have the Performance Booster Elite package.
type: string
billCycleDay:
description: |
The billing cycle day (BCD), the day of the month when a bill run generates invoices for the account. The value must be equal to or less then 31, and 31 is mean the EOM.
This field conflicts with the `accountId` field. If they are both specified in the request body, an error occurs and an error message is returned.
type: string
billingRunId:
description: |
The ID of a bill run.
This field conflicts with the `accountId` field. If they are both specified in the request body, an error occurs and an error message is returned.
format: uuid
type: string
collectPayment:
description: |
Whether to process electronic payments during the execution of payment runs.
If the Payment user permission "Process Electronic Payment" is disabled, this field will be ignored.
type: boolean
consolidatedPayment:
description: |
**Note:** The **Process Electronic Payment** permission also needs to be allowed for a Manage Payment Runs role to work. See [Payments Roles](https://knowledgecenter.zuora.com/CF_Users_and_Administrators/A_Administrator_Settings/User_Roles/e_Payments_Roles) for more information.
Whether to process a single payment for all receivables that are due on an account.
type: boolean
currency:
description: |
A currency defined in the web-based UI administrative settings.
This field conflicts with the `accountId` field. If they are both specified in the request body, an error occurs and an error message is returned.
type: string
organizationLabels:
description: |
The organizations that the run is created for.
For each item in the array, either the `organizationId` or the `organizationName` field is required.
This field is only required when you have already turned on Multi-Org feature.
items:
properties:
organizationId:
description: |
The organization ID.
type: string
organizationName:
description: |
The organization name.
type: string
type: object
type: array
paymentGatewayId:
description: |
The ID of the gateway instance that processes the payment.
This field conflicts with the `accountId` field. If they are both specified in the request body, an error occurs and an error message is returned.
format: uuid
type: string
nullable: true
processPaymentWithClosedPM:
description: |
**Note:** The **Process Electronic Payment** permission also needs to be allowed for a Manage Payment Runs role to work. See [Payments Roles](https://knowledgecenter.zuora.com/CF_Users_and_Administrators/A_Administrator_Settings/User_Roles/e_Payments_Roles) for more information.
Whether to process payments even if the default payment method is closed.
type: boolean
runDate:
description: |
The date and time when the scheduled payment run is to be executed, in `yyyy-mm-dd hh:mm:ss` format. The backend will ignore mintues and seconds in the field value. For example, if you specify `2017-03-01 11:30:37` for this value, this payment run will be run at 2017-03-01 11:00:00.
format: date-time
type: string
targetDate:
description: |
The target date used to determine which receivables to be paid in the payment run. The payments are collected for all receivables with the due date no later than the target date.
format: date
type: string
type: object
GETPaymentRunDataArrayResponse:
properties:
data:
description: |
Container for payment run data. Each element in the array is a record processed by the payment run.
items:
$ref: '#/components/schemas/GETPaymentRunDataElementResponse'
type: array
success:
description: |
Returns `true` if the request was processed successfully.
type: boolean
type: object
GETPaymentRunDataElementResponse:
allOf:
- properties:
accountId:
description: |
The customer account ID specified in the `data` field when creating the payment run.
type: string
accountNumber:
description: |
The customer account number specified in the `data` field when creating the payment run.
type: string
amount:
description: |
The amount specified in the `data` field when creating the payment run. `null` is returned if it was not specified.
type: number
amountCollected:
description: |
The amount that is collected.
type: number
amountToCollect:
description: |
The amount to be collected.
type: number
comment:
description: |
The comment specified in the `data` field when creating the payment run. `null` is returned if it was not specified.
type: string
nullable: true
currency:
description: |
This field is only available if support for standalone payments is enabled.
The currency of the standalone payment. The currency of the standalone payment can be different from the payment currency defined in the customer account settings.
type: string
documentId:
description: |
The billing document ID specified in the `data` field when creating the payment run. `null` is returned if it was not specified.
type: string
documentNumber:
description: |
The billing document number specified in the `data` field when creating the payment run. `null` is returned if it was not specified.
type: string
documentType:
description: |
The billing document type specified in the `data` field when creating the payment run. `null` is returned if it was not specified.
enum:
- Invoice
- DebitMemo
type: string
errorCode:
description: |
The error code of the response.
type: string
errorMessage:
description: |
The detailed information of the error response.
type: string
paymentGatewayId:
description: |
The payment gateway ID specified in the `data` field when creating the payment run. `null` is returned if it was not specified.
type: string
nullable: true
paymentMethodId:
description: |
The payment method ID specified in the `data` field when creating the payment run. `null` is returned if it was not specified.
type: string
result:
description: |
Indicates whether the data is processed successfully or not.
enum:
- Processed
- Error
type: string
standalone:
description: |
This field is only available if the support for standalone payment is enabled.
The value `true` indicates this is a standalone payment that is created and processed in Zuora through Zuora gateway integration but will be settled outside of Zuora. No settlement data will be created. The standalone payment cannot be applied, unapplied, or transferred.
type: boolean
transactions:
description: |
Container for transactions that apply to the current request. Each element contains an array of the settlement/payment applied to the record.
items:
$ref: '#/components/schemas/GETPaymentRunDataTransactionElementResponse'
type: array
title: payment run data
type: object
- $ref: '#/components/schemas/PaymentObjectCustomFields'
GETPaymentRunDataTransactionElementResponse:
properties:
amount:
description: |
The total amount of the newly generated payment.
**Note:** This field is only available if `type` is `Payment`.
type: number
appliedAmount:
description: |
The amount allocated to this data record.
type: number
errorCode:
description: |
The error code of the response.
**Note:** This field is only available if `type` is `Payment`.
type: string
errorMessage:
description: |
The detailed information of the error response.
**Note:** This field is only available if `type` is `Payment`.
type: string
id:
description: |
The ID of the current transaction.
type: string
status:
description: |
The status of the newly generated payment.
**Note:** This field is only available if `type` is `Payment`.
enum:
- Processed
- Processing
- Error
type: string
type:
description: |
The type of the current transaction.
enum:
- Payment
- CreditMemo
- UnappliedPayment
- CreditBalanceAdjustment
type: string
title: payment run transaction
type: object
GETPaymentRunSummaryResponse:
properties:
numberOfCreditBalanceAdjustments:
description: |
**Note:** This field is only available if you have the Credit Balance feature enabled.
The number of credit balance adjustments that are successfully processed in the payment run.
type: integer
numberOfCreditMemos:
description: |
**Note:** This field is only available if you have the Invoice Settlement feature enabled.
The total number of credit memos that are successfully processed in the payment run.
type: integer
numberOfDebitMemos:
description: |
**Note:** This field is only available if you have the Invoice Settlement feature enabled.
The total number of debit memos that are picked up for processing in the payment run.
type: integer
numberOfErrorInputData:
description: |
The number of input data that are processed with errors.
type: integer
numberOfErrors:
description: |
The number of payments with the status of `Error` and `Processing`.
type: integer
numberOfInputData:
description: |
The total number of input data.
type: integer
numberOfInvoices:
description: |
**Note:** This field is only available if you have the Invoice Settlement feature enabled.
The total number of invoices that are picked up for processing in the payment run.
type: integer
numberOfPayments:
description: |
The number of payments that are successfully processed in the payment run.
type: integer
numberOfProcessedInputData:
description: |
The number of input data that are successfully processed.
type: integer
numberOfReceivables:
description: |
The total number of receivables that are picked up for processing in the payment run.
The value of this field is the sum of the value of the `numberOfInvoices` field and that of the `numberOfDebitMemos` field.
type: integer
numberOfUnappliedPayments:
description: |
**Note:** This field is only available if you have the Invoice Settlement feature enabled.
The number of unapplied payments that are successfully processed in the payment run.
type: integer
numberOfUnprocessedDebitMemos:
description: |
**Note:** This field is only available if you have the Invoice Settlement feature enabled.
The number of debit memos with remaining positive balances after the payment run is completed.
type: integer
numberOfUnprocessedInvoices:
description: |
**Note:** This field is only available if you have the Invoice Settlement feature enabled.
The number of invoices with remaining positive balances after the payment run is completed.
type: integer
numberOfUnprocessedReceivables:
description: |
The number of receivables with remaining positive balances after the payment run is completed.
type: integer
success:
description: |
Returns `true` if the request was processed successfully.
type: boolean
totalValues:
description: |
Container for total values.
items:
$ref: '#/components/schemas/GETPaymentRunSummaryTotalValues'
type: array
type: object
GETPaymentRunSummaryTotalValues:
properties:
totalValueOfCreditBalance:
description: |
**Note:** This field is only available if you have the Credit Balance feature enabled.
The total amount of credit balance after the payment run is completed.
type: string
totalValueOfCreditMemos:
description: |
**Note:** This field is only available if you have the Invoice Settlement feature enabled.
The total amount of credit memos that are successfully processed in the payment run.
type: string
totalValueOfDebitMemos:
description: |
**Note:** This field is only available if you have the Invoice Settlement feature enabled.
The total amount of debit memos that are picked up for processing in the payment run.
type: string
totalValueOfErrors:
description: |
The total amount of receivables associated with the payments with the status of `Error` and `Processing`.
type: string
totalValueOfInvoices:
description: |
**Note:** This field is only available if you have the Invoice Settlement feature enabled.
The total amount of invoices that are picked up for processing in the payment run.
type: string
totalValueOfPayments:
description: |
The total amount of payments that are successfully processed in the payment run.
type: string
totalValueOfReceivables:
description: |
The total amount of receivables associated with the payment run.
The value of this field is the sum of the value of the `totalValueOfInvoices` field and that of the `totalValueOfDebitMemos` field.
type: string
totalValueOfUnappliedPayments:
description: |
**Note:** This field is only available if you have the Invoice Settlement feature enabled.
The total amount of unapplied payments that are successfully processed in the payment run.
type: integer
totalValueOfUnprocessedDebitMemos:
description: |
**Note:** This field is only available if you have the Invoice Settlement feature enabled.
The total amount of debit memos with remaining positive balances after the payment run is completed.
type: string
totalValueOfUnprocessedInvoices:
description: |
**Note:** This field is only available if you have the Invoice Settlement feature enabled.
The total amount of invoices with remaining positive balances after the payment run is completed.
type: string
totalValueOfUnprocessedReceivables:
description: |
The total amount of receivables with remaining positive balances after the payment run is completed.
type: string
title: totalValues
type: object
POSTRetryPaymentScheduleItemRequest:
example:
items:
- id: 402882e97f24bc36017f2986654f0253
- id: 402882e97f24bc36017f298665570254
paymentGatewayId: 402883827d097a28017d09b41f690261
paymentMethodId: 402882e97f24bc36017f258c2ff20076
properties:
items:
description: |
The maximum number of items allowable to pass is 10.
items:
$ref: '#/components/schemas/POSTRetryPaymentScheduleItemInfo'
title: Payment schedule items to be retried.
type: array
type: object
POSTRetryPaymentScheduleItemResponse:
properties:
items:
items:
$ref: '#/components/schemas/PaymentScheduleItemCommonResponse'
type: array
success:
description: |
Returns `true` if the request was processed successfully.
type: boolean
type: object
PaymentScheduleItemCommonResponse:
allOf:
- properties:
accountId:
description: |
ID of the customer account that owns the payment schedule item, for example `402880e741112b310149b7343ef81234`.
type: string
amount:
description: |
The total amount of the payment schedule.
format: decimal
type: number
balance:
description: |
The remaining balance of payment schedule item.
format: decimal
type: number
billingDocument:
properties:
id:
description: |
ID of the billing document. for example, `2c9890306fb2121e016fb21a6b550041`.
type: string
number:
description: |
Number of the billing docuemnt, for example, `INV00002345`.
type: string
type:
description: |
Indicates whether the associated billing document is a debit memo or a invoice.
type: string
type: object
createdById:
description: |
The ID of the user who created the payment schedule item.
type: string
createdDate:
description: |
The date and time when the payment schedule item was created.
format: date
type: string
currency:
description: |
The currency of the payment.
type: string
description:
description: |
The description of the payment schedule item.
type: string
errorMessage:
description: |
The error message indicating if the error is related to configuration or payment collection.
type: string
id:
description: |
ID of the payment schedule item. For example, `412880e749b72b310149b7343ef81346`.
type: string
number:
description: |
Number of the payment schedule item.
type: string
paymentGatewayId:
description: |
ID of the payment gateway of the payment schedule item.
type: string
nullable: true
paymentMethodId:
description: |
ID of the payment method of the payment schedule item.
type: string
nullable: true
paymentOption:
description: |
Container for the paymentOption items, which describe the transactional level rules for processing payments. Currently, only the Gateway Options type is supported.
`paymentOption` of the payment schedule takes precedence over `paymentOption` of the payment schedule item.
items:
$ref: '#/components/schemas/PaymentSchedulePaymentOptionFields'
type: array
paymentScheduleId:
description: |
ID of the payment schedule that contains the payment schedule item, for example, `ID402880e749b72b310149b7343ef80005`.
type: string
paymentScheduleNumber:
description: |
Number of the payment schedule that contains the payment schedule item, for example, `ID402880e749b72b310149b7343ef80005`.
type: string
psiPayments:
description: |
Container for payments linked to the payment schedule item.
items:
$ref: '#/components/schemas/LinkedPaymentID'
type: array
runHour:
description: |
At which hour in the day in the tenant’s timezone this payment will be collected.
type: integer
scheduledDate:
description: |
The scheduled date when the payment is processed.
format: date
type: string
standalone:
description: |
Indicates if the payment created by the payment schedule item is a standalone payment or not.
type: boolean
status:
description: |
ID of the payment method of the payment schedule item.
- `Pending`: Payment schedule item is waiting for processing.
- `Processed`: The payment has been collected.
- `Error`: Failed to collect the payment.
- `Canceled`: After a pending payment schedule item is canceled by the user, the item is marked as `Canceled`.
enum:
- Pending
- Processed
- Error
- Canceled
type: string
updatedById:
description: |
The ID of the user who updated the payment schedule item.
type: string
updatedDate:
description: |
The date and time when the payment schedule item was last updated.
format: date
type: string
type: object
- $ref: '#/components/schemas/PaymentScheduleItemCustomFields'
LinkedPaymentID:
properties:
paymentId:
description: |
ID of the payment.
type: string
title: PaymentID
type: object
PaymentScheduleItemCustomFields:
additionalProperties:
description: |
Custom fields of the Payment Schedule Item object. The name of each custom field has the form *customField*__c. Custom field names are case-sensitive. See Custom Fields for more information.
description: |
Container for custom fields of a Payment Schedule Item object.
title: paymentScheduleItemFieldsCustom
type: object
POSTRetryPaymentScheduleItemInfo:
description: |
Information of the payment schedule items to be retried.
properties:
id:
description: |
Specifies the ID of the payment schedule item to be retried.
type: string
paymentGatewayId:
description: |
Specifies the ID of a payment gateway that will be used in the retry.
type: string
paymentMethodId:
description: |
Specifies the ID of a payment method that will be used in the retry.
type: string
type: object
PUTPaymentScheduleItemResponse:
allOf:
- properties:
accountId:
description: |
ID of the customer account that owns the payment schedule item, for example `402880e741112b310149b7343ef81234`.
type: string
amount:
description: |
The amount of the payment schedule item.
format: decimal
type: number
balance:
description: |
The remaining balance of payment schedule item.
format: decimal
type: number
billingDocument:
properties:
id:
description: |
ID of the billing document. for example, `2c9890306fb2121e016fb21a6b550041`.
type: string
number:
description: |
The number of the billing docuemnt, for example, `INV00002345`.
type: string
type:
description: |
Indicates whether the associated billing document is a debit memo or a invoice.
type: string
type: object
cancellationReason:
description: |
The reason for the cancellation of payment schedule item.
type: string
createdById:
description: |
The ID of the user who created the payment schedule item.
type: string
createdDate:
description: |
The date and time when the payment schedule item was created.
format: date
type: string
currency:
description: |
The currency of the payment.
type: string
description:
description: |
The description of the payment schedule item.
type: string
nullable: true
errorMessage:
description: |
The error message indicating if the error is related to the configuration or the payment collection.
type: string
id:
description: |
ID of the payment schedule item. For example, `412880e749b72b310149b7343ef81346`.
type: string
number:
description: |
Number of the payment schedule item.
type: string
paymentGatewayId:
description: |
ID of the payment gateway of the payment schedule item.
type: string
nullable: true
paymentMethodId:
description: |
ID of the payment method of the payment schedule item.
type: string
paymentOption:
description: |
Container for the paymentOption items, which describe the transactional level rules for processing payments. Currently, only the Gateway Options type is supported.
`paymentOption` of the payment schedule takes precedence over `paymentOption` of the payment schedule item.
items:
$ref: '#/components/schemas/PaymentSchedulePaymentOptionFields'
type: array
paymentScheduleId:
description: |
ID of the payment schedule that contains the payment schedule item, for example, `ID402880e749b72b310149b7343ef80005`,
type: string
paymentScheduleNumber:
description: |
Number of the payment schedule that contains the payment schedule item, for example, `ID402880e749b72b310149b7343ef80005`,
type: string
psiPayments:
description: |
Container for payments linked to the payment schedule item.
items:
$ref: '#/components/schemas/LinkedPaymentID'
type: array
runHour:
description: |
At which hour in the day in the tenant’s timezone this payment will be collected.
type: integer
scheduledDate:
description: |
The scheduled date when the payment is processed.
format: date
type: string
standalone:
description: |
Indicates if the payment created by the payment schedule item is a standalone payment.
type: boolean
status:
description: |
ID of the payment method of the payment schedule item.
- `Pending`: Waiting for processing.
- `Processed`: The payment has been collected.
- `Error`: Failed to collect the payment.
- `Canceled`: After a pending payment schedule item is canceled by the user, the item is marked as `Canceled`.
enum:
- Pending
- Processed
- Error
- Canceled
type: string
success:
description: |
Returns `true` if the request was processed successfully.
type: boolean
updatedById:
description: |
The ID of the user who updated the payment schedule item.
type: string
updatedDate:
description: |
The date and time when the payment schedule item was last updated.
format: date
type: string
type: object
- $ref: '#/components/schemas/PaymentScheduleItemCustomFields'
PUTSkipPaymentScheduleItemResponse:
allOf:
- properties:
amount:
description: |
The amount of the payment.
format: decimal
type: number
billingDocument:
properties:
id:
description: |
ID of the billing document. for example, `2c9890306fb2121e016fb21a6b550041`.
type: string
number:
description: |
The number of the billing docuemnt, for example, `INV00002345`.
type: string
type:
description: |
Indicates whether the associated billing document is a debit memo or a invoice.
type: string
type: object
cancellationReason:
description: |
The reason for the cancellation of payment schedule item.
type: string
createdById:
description: |
The ID of the user who created the payment schedule item.
type: string
createdDate:
description: |
The date and time when the payment schedule item was created.
format: date
type: string
currency:
description: |
The currency of the payment.
type: string
description:
description: |
The description of the payment schedule item.
type: string
errorMessage:
description: |
The error message indicating if the error is related to the configuration or the payment collection.
type: string
id:
description: |
ID of the newly-created payment schedule item. For example, `412880e749b72b310149b7343ef81346`.
type: string
number:
description: |
Number of the newly-created payment schedule item.
type: string
paymentGatewayId:
description: |
ID of the payment gateway of the payment schedule item.
type: string
nullable: true
paymentMethodId:
description: |
ID of the payment method of the payment schedule item.
type: string
paymentOption:
description: |
Container for the paymentOption items, which describe the transactional level rules for processing payments. Currently, only the Gateway Options type is supported.
`paymentOption` of the payment schedule takes precedence over `paymentOption` of the payment schedule item.
items:
$ref: '#/components/schemas/PaymentSchedulePaymentOptionFields'
type: array
paymentScheduleId:
description: |
ID of the payment schedule that contains the payment schedule item, for example, `ID402880e749b72b310149b7343ef80005`,
type: string
paymentScheduleNumber:
description: |
Number of the payment schedule that contains the payment schedule item, for example, `ID402880e749b72b310149b7343ef80005`,
type: string
psiPayments:
description: |
Container for payments linked to the payment schedule item.
items:
$ref: '#/components/schemas/LinkedPaymentID'
type: array
runHour:
description: |
At which hour in the day in the tenant’s timezone this payment will be collected.
type: integer
scheduledDate:
description: |
The scheduled date when the payment is processed.
format: date
type: string
standalone:
description: |
Indicates if the payment created by the payment schedule item is a standalone payment.
type: boolean
status:
description: |
ID of the payment method of the payment schedule item.
- `Pending`: Waiting for processing.
- `Processed`: The payment has been collected.
- `Error`: Failed to collect the payment.
- `Canceled`: After a pending payment schedule item is canceled by the user, the item is marked as `Canceled`.
enum:
- Pending
- Processed
- Error
- Canceled
type: string
success:
description: |
Returns `true` if the request was processed successfully.
type: boolean
updatedById:
description: |
The ID of the user who updated the payment schedule item.
type: string
updatedDate:
description: |
The date and time when the payment schedule item was last updated.
format: date
type: string
type: object
- $ref: '#/components/schemas/PaymentScheduleItemCustomFields'
GETPaymentScheduleItemResponse:
allOf:
- properties:
accountId:
description: |
ID of the customer account that owns the payment schedule item, for example `402880e741112b310149b7343ef81234`.
type: string
amount:
description: |
The total amount of the payment schedule item.
format: decimal
type: number
balance:
description: |
The remaining balance of payment schedule item.
format: decimal
type: number
billingDocument:
properties:
id:
description: |
ID of the billing document. for example, `2c9890306fb2121e016fb21a6b550041`.
type: string
number:
description: |
The number of the billing docuemnt, for example, `INV00002345`.
type: string
type:
description: |
Indicates whether the associated billing document is a debit memo or a invoice.
type: string
type: object
cancellationReason:
description: |
The reason for the cancellation of payment schedule item.
nullable: true
type: string
cancelledById:
description: |
The ID of the user who canceled this payment schedule item.
nullable: true
type: string
cancelledOn:
description: |
The date when the payment schedule item was canceled.
nullable: true
type: string
createdById:
description: |
The ID of the user who created the payment schedule item.
type: string
createdDate:
description: |
The date and time when the payment schedule item was created.
format: date
type: string
currency:
description: |
The currency of the payment.
type: string
description:
description: |
The description of the payment schedule item.
type: string
errorMessage:
description: |
The error message indicating if the error is related to the configuration or the payment collection.
type: string
id:
description: |
ID of the payment schedule item. For example, `412880e749b72b310149b7343ef81346`.
type: string
number:
description: |
Number of the payment schedule item.
type: string
paymentGatewayId:
description: |
ID of the payment gateway of the payment schedule item.
type: string
nullable: true
paymentMethodId:
description: |
ID of the payment method of the payment schedule item.
type: string
paymentOption:
description: |
Container for the paymentOption items, which describe the transactional level rules for processing payments. Currently, only the Gateway Options type is supported.
`paymentOption` of the payment schedule takes precedence over `paymentOption` of the payment schedule item.
items:
$ref: '#/components/schemas/PaymentSchedulePaymentOptionFields'
type: array
paymentScheduleId:
description: |
ID of the payment schedule that contains the payment schedule item, for example, `ID402880e749b72b310149b7343ef80005`,
type: string
paymentScheduleNumber:
description: |
Number of the payment schedule that contains the payment schedule item, for example, `ID402880e749b72b310149b7343ef80005`,
type: string
psiPayments:
description: |
Container for payments linked to the payment schedule item.
items:
$ref: '#/components/schemas/LinkedPaymentID'
type: array
runHour:
description: |
At which hour in the day in the tenant’s timezone this payment will be collected. If the payment `runHour` and `scheduledDate` are backdated, the system will collect the payment when the next runHour occurs.
type: integer
scheduledDate:
description: |
The scheduled date when the payment is processed.
format: date
type: string
standalone:
description: |
Indicates if the payment created by the payment schedule item is a standalone payment.
type: boolean
status:
description: |
ID of the payment method of the payment schedule item.
- `Pending`: Waiting for processing.
- `Processed`: The payment has been collected.
- `Error`: Failed to collect the payment.
- `Canceled`: After a pending payment schedule item is canceled by the user, the item is marked as `Canceled`.
enum:
- Pending
- Processed
- Error
- Canceled
type: string
success:
description: |
Returns `true` if the request was processed successfully.
type: boolean
updatedById:
description: |
The ID of the user who updated the payment schedule item.
type: string
updatedDate:
description: |
The date and time when the payment schedule item was last updated.
format: date
type: string
type: object
- $ref: '#/components/schemas/PaymentScheduleItemCustomFields'
PUTPaymentScheduleItemRequest:
example:
paymentMethodId: 8a90b44890c9bb0d0190d960b9191eea
allOf:
- properties:
amount:
description: |
The amount of the payment.
format: decimal
type: number
currency:
description: |
The currency of the payment.
**Note:**
- For custom payments, if Multi-currency is enabled, the payment currency can be different from the account currency for custom payment.
- For recurring payments, if Multi-currency is enabled, the payment currency can be different from the account currency but should be the same as billing currency for a recurring payment.
type: string
description:
description: |
The description of the payment schedule item.
type: string
linkPayments:
description: |
Container for payments linked to the payment schedule item.
type: array
items:
type: string
paymentGatewayId:
description: |
ID of the payment gateway of the payment schedule item.
type: string
nullable: true
paymentMethodId:
description: |
ID of the payment method of the payment schedule item.
type: string
paymentOption:
description: |
Container for the paymentOption items, which describe the transactional level rules for processing payments. Currently, only the Gateway Options type is supported.
Here is an example:
```
"paymentOption": [
{
"type": "GatewayOptions",
"detail": {
"SecCode":"WEB"
}
}
]
```
`paymentOption` of the payment schedule takes precedence over `paymentOption` of the payment schedule item.
items:
$ref: '#/components/schemas/PaymentSchedulePaymentOptionFields'
type: array
runHour:
description: |
At which hour of the day in the tenant’s timezone this payment will be collected. If the payment `runHour` and `scheduledDate` are backdated, the system will collect the payment when the next runHour occurs.
type: integer
scheduledDate:
description: |
The scheduled date when the payment is processed.
format: date
type: string
unlinkPayments:
description: |
Container for payments to be unlinked from the payment schedule item.
type: array
items:
type: string
type: object
- $ref: '#/components/schemas/PaymentScheduleItemCustomFields'
GETPaymentSchedulesResponse:
description: |
Container for payment schedules.
items:
$ref: '#/components/schemas/PaymentScheduleCommonResponse'
type: array
PaymentScheduleCommonResponse:
allOf:
- properties:
accountId:
description: |
ID of the account that owns the payment schedule.
type: string
accountNumber:
description: |
Number of the account that owns the payment schedule.
type: string
billingDocument:
properties:
id:
description: |
ID of the billing document. for example, `2c9890306fb2121e016fb21a6b550041`.
type: string
number:
description: |
The number of the billing docuemnt, for example, `INV00002345`.
type: string
type:
description: |
Indicates whether the associated billing document is a debit memo or a invoice.
type: string
type: object
billingDocuments:
description: |
Container array of the multiple billing documents associated with the payment schedule.
items:
allOf:
- properties:
id:
description: |
ID of the billing document.
type: string
number:
description: |
Number of the billing document. If the billing document is a debit memo, it contains the debit memo number. If the billing document is an invoice, it contains the invoice number.
type: string
type:
description: |
Denotes if the billing document is of the type invoice or debit memo.
enum:
- Invoice
- DebitMemo
type: string
type: array
createdById:
description: |
The ID of the user who created this payment schedule.
type: string
createdDate:
description: |
The date and time the payment schedule is created.
format: date
type: string
description:
description: |
The description of the payment schedule.
type: string
id:
description: |
ID of the payment schedule.
type: string
isCustom:
description: |
Indicates if the payment schedule is a custom payment schedule.
type: boolean
items:
description: |
Container for payment schedule items.
items:
$ref: '#/components/schemas/PaymentScheduleItemCommonResponse'
type: array
nextPaymentDate:
description: |
The date the next payment will be processed.
format: date
type: string
occurrences:
description: |
The number of payment schedule items that are created by this payment schedule.
type: integer
paymentOption:
description: |
Container for the paymentOption items, which describe the transactional level rules for processing payments. Currently, only the Gateway Options type is supported.
`paymentOption` of the payment schedule takes precedence over `paymentOption` of the payment schedule item.
items:
$ref: '#/components/schemas/PaymentSchedulePaymentOptionFields'
type: array
paymentScheduleNumber:
description: |
Number of the payment schedule.
type: string
period:
description: |
For recurring payment schedule only. The period of payment generation. Available values include: `Monthly`, `Weekly`, `BiWeekly`.
Returns `null` for custom payment schedules.
type: string
prepayment:
description: |
Indicates whether the payments created by the payment schedule are used as a reserved payment. This field is available only if the prepaid cash drawdown permission is enabled. See [Prepaid Cash with Drawdown](https://knowledgecenter.zuora.com/Zuora_Billing/Billing_and_Invoicing/JA_Advanced_Consumption_Billing/Prepaid_Cash_with_Drawdown) for more information.
type: boolean
recentPaymentDate:
description: |
The date the last payment was processed.
format: date
type: string
runHour:
description: |
[0,1,2,~,22,23]
At which hour in the day in the tenant’s timezone the recurring payment schedule items will be collected.
Return `0` for custom payment schedules.
type: integer
standalone:
description: |
Indicates if the payments that the payment schedule created are standalone payments or not.
type: boolean
startDate:
description: |
The date when the first payment of this payment schedule is proccessed.
format: date
type: string
status:
description: |
The status of the payment schedule.
- Active: There is still payment schedule item to process.
- Canceled: After a payment schedule is canceled by the user, the schedule is marked as `canceled`.
- Completed: After all payment schedule items are processed, the schedule is marked as `Completed`.
enum:
- Active
- Canceled
- Completed
type: string
totalAmount:
description: |
The total amount that will be collected by the payment schedule.
type: number
totalPaymentsErrored:
description: |
The number of errored payments.
type: integer
totalPaymentsProcessed:
description: |
The number of processed payments.
type: integer
updatedById:
description: |
The ID of the user who last updated this payment schedule.
type: string
updatedDate:
description: |
The date and time the payment schedule is last updated.
format: date
type: string
type: object
- $ref: '#/components/schemas/PaymentScheduleCustomFields'
PaymentScheduleCustomFields:
additionalProperties:
description: |
Custom fields of the Payment Schedule object. The name of each custom field has the form *customField*__c. Custom field names are case-sensitive. See Custom Fields for more information.
**Note:**
The values will automatically be pushed to payment schedule items level if the same fields exist at the payment schedule item level.
description: |
Container for custom fields of a Payment Schedule object.
title: paymentScheduleFieldsCustom
type: object
POSTPaymentScheduleRequest:
allOf:
- properties:
accountId:
description: |
ID of the customer account the payment schedule belongs to.
**Note:**
`accountId` and `accountNumber` cannot both be `null`. When both fields are specified, the two values must match each other.
type: string
accountNumber:
description: |
Account number of the customer account the payment schedule belongs to.
**Note:**
`accountId` and `accountNumber` cannot both be `null`. When both fields are specified, the two values must match each other.
type: string
amount:
description: |
The amount of each payment schedule item in the payment schedule.
**Note:**
- This field is required when `items` is not specified.
- This field will be ignored when `items` is specified.
- When creating recurring payment schedules, there are 2 options to specify amounts:
- Specify `totalAmount` and `occurrences`, `amount` will be calculated.
- Specify `amount` and `occurrences`, `totalAmount` will be calculated.
You must specify either `totalAmount` or `amount`. Specifying both fields at the same time is not allowed.
type: number
billingDocument:
description: |
Object of the billing document with which the payment schedule is associated.
**Note:**
- This field is optional. If you have the Standalone Payment feature enabled, you can leave this field blank and set `standalone` to `true` to create standalone payments. You can also choose to create unapplied payments by leaving this object blank and setting `standalone` to `false`.
- If Standalone Payment is not enabled, leaving this object unspecified will create unapplied payments.
- This field is available only if you are on the latest Zuora API version, or you set the `Zuora-Version` request header to `330.0` or [a later available version](https://developer.zuora.com/v1-api-reference/api-versions/#minor-version).
properties:
id:
description: |
ID of the billing document.
**Note:**
If a billing document is specified, either `id` or `number` of the billing document must be specified. You cannot specify both of them or skip both.
type: string
number:
description: |
Number of the billing document.
**Note:**
If a billing document is specified, either `id` or `number` of the billing document must be specified. You cannot specify both of them or skip both.
type: string
type:
description: |
The type of the billing document.
enum:
- Invoice
- DebitMemo
default: Invoice
type: string
required:
- type
type: object
billingDocuments:
description: |
Container array of the multiple billing documents associated with the payment schedule.
If multiple billing documents are associated to a payment schedule, when collecting the payment schedule item, the payment belongs to the payment schedule item will be applied to billing documents based on the due date of the billing document, in the ascending order.
items:
type: object
properties:
id:
description: |
ID of the billing document.
**Note:** If a billing document is specified, either `id` or `number` of the billing document must be specified. You cannot specify both of them or skip both.
type: string
number:
description: |
Number of the billing document. If the billing document is a debit memo, it contains the debit memo number. If the billing document is an invoice, it contains the invoice number.
**Note:** If a billing document is specified, either `id` or `number` of the billing document must be specified. You cannot specify both of them or skip both.
type: string
type:
description: |
Denotes if the billing document is of the type invoice or debit memo.
enum:
- Invoice
- DebitMemo
type: string
required:
- type
type: array
currency:
description: |
Currency of the payment schedule.
**Note:**
- This field is optional. The default value is the account's default currency.
- This field will be ignored when `items` is specified.
- For custom payments, if Multi-currency is enabled, the payment currency can be different from the account currency for custom payment.
- For recurring payments, if Multi-currency is enabled, the payment currency can be different from the account currency but should be the same as billing currency for a recurring payment.
type: string
description:
description: |
Description of the payment schedule. Max length is 255.
type: string
items:
description: |
Container array for payment schedule items.
items:
allOf:
- properties:
amount:
description: |
The amount that needs to be collected by this payment schedule item.
type: number
billingDocument:
description: |
Object for the billing document with which the payment schedule item is associated.
**Note:** You must specify the same billing document for all the payment schedule items in one payment schedule.
properties:
id:
description: |
The ID of the billing document.
**Note:**
If a billing document is specified, one of `id` or `number` must be specified. You cannot specify both of them or or skip both.
type: string
number:
description: |
The number of the billing document.
**Note:**
If a billing document is specified, one of `id` or `number` must be specified. You cannot specify both of them or skip both.
type: string
type:
description: |
The type of the billing document. The default value is `Invoice`.
enum:
- Invoice
- DebitMemo
type: string
required:
- type
type: object
currency:
description: |
The currency of the payment.
**Note**:
- This field is optional. If not specified, the default value is the currency set for the account.
- For custom payments, if Multi-currency is enabled, the payment currency can be different from the account currency for custom payment.
- For recurring payments, if Multi-currency is enabled, the payment currency can be different from the account currency but should be the same as billing currency for a recurring payment.
type: string
description:
description: |
Description of the payment schedule item.
type: string
paymentGatewayId:
description: |
The ID of the payment gateway.
**Note**:
- This field is optional. If not specified, the default value is the payment gateway id set for the account.
type: string
paymentMethodId:
description: |
The ID of the payment method.
**Note**:
- This field is optional. If not specified, the default value is the payment method id set for the account.
type: string
paymentOption:
description: |
Container for the paymentOption items, which describe the transactional level rules for processing payments. Currently, only the Gateway Options type is supported.
Here is an example:
```
"paymentOption": [
{
"type": "GatewayOptions",
"detail": {
"SecCode":"WEB"
}
}
]
```
`paymentOption` of the payment schedule takes precedence over `paymentOption` of the payment schedule item.
To enable this field, submit a request at [Zuora Global Support](https://support.zuora.com/). This field is only available if `Zuora-Version` is set to `337.0` or later [available versions](https://developer.zuora.com/api-references/api/overview/#section/API-Versions/Minor-Version).
items:
$ref: '#/components/schemas/PaymentSchedulePaymentOptionFields'
type: array
runHour:
description: |
At which hour in the day in the tenant’s timezone this payment will be collected. Available values:`[0,1,2,~,22,23]`. If the time difference between your tenant’s timezone and the timezone where Zuora servers are is not in full hours, for example, 2.5 hours, the payment schedule items will be triggered half hour later than your scheduled time.
The default value is `0`.
If the payment `runHour` and `scheduledDate` are backdated, the system will collect the payment when the next runHour occurs.
type: string
scheduledDate:
description: |
The date to collect the payment.
format: date
type: string
type: object
- $ref: '#/components/schemas/PaymentScheduleItemCustomFields'
type: array
occurrences:
description: |
The number of payment schedule item to be created. Maximum value is 1000.
**Note:**
- This field is required when `items` is not specified.
- This field will be ignored when `items` is specified.
type: integer
paymentGatewayId:
description: |
ID of the payment gateway.
**Note:**
- This field is optional. The default value is the account's default payment gateway ID. If no payment gateway ID is found on the cusotmer account level, the default value will be the tenant's default payment gateway ID.
- This field will be ignored when `items` is specified.
type: string
paymentMethodId:
description: |
ID of the payment method.
**Note:**
- This field is optional. The default value is the account's default payment method ID.
- This field will be ignored when `items` is specified.
type: string
paymentOption:
description: |
Container for the paymentOption items, which describe the transactional level rules for processing payments. Currently, only the Gateway Options type is supported.
Here is an example:
```
"paymentOption": [
{
"type": "GatewayOptions",
"detail": {
"SecCode":"WEB"
}
}
]
```
`paymentOption` of the payment schedule takes precedence over `paymentOption` of the payment schedule item.
items:
$ref: '#/components/schemas/PaymentSchedulePaymentOptionFields'
type: array
paymentScheduleNumber:
description: |
You can use this field to specify the number of the payment schedule.
Only characters from the following sets are allowed: A-Z, a-z, 0-9, and `-`.
Payment numbers must start with a letter. In addition,`-` can only be used at most once and cannot be placed at the beginning or the end of the payment numbers.
type: string
period:
description: |
The frequency for the payment collection since the `startDate`.
**Note:**
- Thie field is required when `items` is not specified.
- This field will be ignored when `items` is specified.
- If `startDate` is `30` or `31` and `period` is `Monthly`, when in February, payment schedule will use the last day of February for payment collection.
enum:
- Monthly
- Weekly
- BiWeekly
type: string
prepayment:
description: |
Indicates whether the payments created by the payment schedule will be used as reserved payments. This field will only be available if the prepaid cash drawdown permission is enabled. See [Prepaid Cash with Drawdown](https://knowledgecenter.zuora.com/Zuora_Billing/Billing_and_Invoicing/JA_Advanced_Consumption_Billing/Prepaid_Cash_with_Drawdown) for more information.
type: boolean
runHour:
description: |
Specifies at which hour in the day in the tenant’s time zone when this payment will be collected. Available values: `[0,1,2,~,22,23]`.
**Note:**
- If the time difference between your tenant’s timezone and the timezone where Zuora servers are is not in full hours, for example, 2.5 hours, the payment schedule items will be triggered half hour later than your scheduled time.
- If the payment `runHour` and `scheduledDate` are backdated, the system will collect the payment when the next runHour occurs.
- This field is optional. The default value is `0`.
- This field will be ignored when `items` is specified.
type: integer
standalone:
description: |
Indicate whether the payments created by the payment schedule are standalone payments or not. When setting to `true`, standalone payments will be created. When setting to `false`, you can either specify a billing document, or not specifying any billing documents. In the later case, unapplied payments will be created. If set to `null`, standalone payment will be created.
**Note**:
- This field is only available if the Standalone Payment is enabled. Do not include this field if Standalone Payment is not enabled.
- If Standalone Payment is enabled, default value is `true`.
type: boolean
startDate:
description: |
The date for the first payment collection.
**Note:**
- This field is required when `items` is not specified.
- This field will be ignored when `items` is specified.
format: date
type: string
totalAmount:
description: |
The total amount of that the payment schedule will collect. This field is only available for recurring payment schedules.
**Note**:
- When creating recurring payment schedules, there are 2 options to specify amounts:
- Specify `totalAmount` and `occurrences`, `amount` will be calculated.
- Specify `amount` and `occurrences`, `totalAmount` will be calculated.
You must specify either `totalAmount` or `amount`. Specifying both fields at the same time is not allowed.
- If the Standalone Payments feature is enabled and `standalone` is set to `true` for the payment schedule, `totalAmount` will be ignored.
type: number
type: object
- $ref: '#/components/schemas/PaymentScheduleCustomFields'
example:
accountId: 8a90b4488e7d5c0f018e7db3892400b2
amount: 14.99
billingDocument:
id: 8a90b44890c9bb0d0190d8c048a90da6
type: Invoice
items:
- scheduledDate: '2024-07-31'
amount: 14.99
POSTPaymentScheduleResponse:
allOf:
- properties:
accountId:
description: |
ID of the account that owns the payment schedule.
type: string
accountNumber:
description: |
Number of the account that owns the payment schedule.
type: string
billingDocument:
properties:
id:
description: |
ID of the billing document. for example, `2c9890306fb2121e016fb21a6b550041`.
type: string
number:
description: |
Number of the billing docuemnt, for example, `INV00002345`.
type: string
type:
description: |
Indicates whether the associated billing document is a debit memo or a invoice.
type: string
type: object
billingDocuments:
description: |
Container array of the multiple billing documents associated with the payment schedule.
items:
type: object
properties:
id:
description: |
ID of the billing document.
type: string
number:
description: |
Number of the billing document. If the billing document is a debit memo, it contains the debit memo number. If the billing document is an invoice, it contains the invoice number.
type: string
type:
description: |
Denotes if the billing document is of the type invoice or debit memo.
enum:
- Invoice
- DebitMemo
type: string
type: array
createdById:
description: |
ID of the user who created this payment schedule.
type: string
createdDate:
description: |
The date and time the payment schedule is created.
format: date
type: string
description:
description: |
The description of the payment schedule.
type: string
id:
description: |
ID of the payment schedule.
type: string
isCustom:
description: |
Indicates if the payment schedule is a custom payment schedule.
type: boolean
items:
description: |
Container for payment schedule items.
items:
$ref: '#/components/schemas/PaymentScheduleItemCommonResponse'
type: array
nextPaymentDate:
description: |
The date the next payment will be processed.
format: date
type: string
occurrences:
description: |
The number of payment schedule items that are created by this payment schedule.
type: integer
paymentOption:
description: |
Container for the paymentOption items, which describe the transactional level rules for processing payments. Currently, only the Gateway Options type is supported.
`paymentOption` of the payment schedule takes precedence over `paymentOption` of the payment schedule item.
items:
$ref: '#/components/schemas/PaymentSchedulePaymentOptionFields'
type: array
paymentScheduleNumber:
description: |
Number of the payment schedule.
type: string
period:
description: |
For recurring payment schedule only. The period of payment generation. Available values include: `Monthly`, `Weekly`, `BiWeekly`.
Return `null` for custom payment schedules.
type: string
nullable: true
prepayment:
description: |
Indicates whether the payments created by the payment schedule are used as a reserved payment. This field will only be available if the prepaid cash drawdown permission is enabled. See [Prepaid Cash with Drawdown](https://knowledgecenter.zuora.com/Zuora_Billing/Billing_and_Invoicing/JA_Advanced_Consumption_Billing/Prepaid_Cash_with_Drawdown) for more information.
type: boolean
recentPaymentDate:
description: |
The date the last payment was processed.
format: date
type: string
nullable: true
runHour:
description: |
[0,1,2,~,22,23]
At which hour in the day in the tenant’s timezone this payment will be collected. If the payment `runHour` and `scheduledDate` are backdated, the system will collect the payment when the next runHour occurs.
Return `0` for custom payment schedules.
type: integer
standalone:
description: |
Indicates if the payments that the payment schedule created are standalone payments or not.
type: boolean
startDate:
description: |
The date when the first payment of this payment schedule is proccessed.
format: date
type: string
status:
description: |
The status of the payment schedule.
- `Active`: There are still pament schedule items to process.
- `Canceled`: After a payment schedule is canceled by the user, the schedule is marked as `Canceled`.
- `Completed`: After all payment schedule items are processed, the schedule is marked as `Completed`.
enum:
- Active
- Canceled
- Completed
type: string
success:
description: |
Returns `true` if the request was processed successfully.
type: boolean
totalAmount:
description: |
The total amount that will be collected by this payment schedule. This field will contain a null value if the `standalone` value is `true`.
type: number
totalPaymentsErrored:
description: |
The number of errored payments.
type: integer
totalPaymentsProcessed:
description: |
The number of processed payments.
type: integer
updatedById:
description: |
ID of the user who last updated this payment schedule.
type: string
updatedDate:
description: |
The date and time the payment schedule is last updated.
format: date
type: string
type: object
- $ref: '#/components/schemas/PaymentScheduleCustomFields'
POSTPaymentSchedulesRequest:
properties:
paymentSchedules:
description: |
Container of the payment schedules to be created.
items:
$ref: '#/components/schemas/POSTPaymentScheduleRequest'
type: array
type: object
POSTPaymentSchedulesResponse:
description: |
Container of the payment schedules that are created.
properties:
paymentSchedules:
description: |
Container for payment parts.
items:
$ref: '#/components/schemas/POSTPaymentSchedulesEach'
type: array
success:
description: Returns `true` if the request was processed successfully.
type: boolean
type: object
POSTPaymentSchedulesEach:
properties:
id:
description: |
The ID of the created payment schedule.
type: string
paymentScheduleNumber:
description: |
The number of the created payment schedule.
type: string
title: Payment Schedule ID and Number
type: object
GETPaymentScheduleStatisticResponse:
description: |
The object that contains the payment schedule statistic of the specified date.
properties:
date:
description: |
The specified date.
format: date
type: string
paymentRuns:
items:
$ref: '#/components/schemas/PaymentRunStatistic'
title: PaymentRunStatistic
type: array
paymentScheduleItems:
properties:
error:
description: |
The number of errored payment schedule items.
type: integer
pending:
description: |
The number of pending payment schedule items.
type: integer
processed:
description: |
The number of processed payment schedule items.
type: integer
type: object
success:
description: |
Returns `true` if the request was processed successfully.
type: boolean
type: object
PaymentRunStatistic:
description: Payment run statistic.
properties:
completedOn:
description: |
The date and time the payment run is completed.
format: date-time
type: string
executedOn:
description: |
The date and time the payment run is executed.
format: date-time
type: string
nullable: true
number:
description: |
Payment run number.
type: string
numberOfErrors:
description: |
Number of errored payments
type: integer
numberOfPayments:
description: |
Number of processed payments.
type: integer
status:
description: |
Payment run status.
type: string
type: object
GETPaymentScheduleResponse:
allOf:
- properties:
accountId:
description: |
ID of the account that owns the payment schedule.
type: string
accountNumber:
description: |
Number of the account that owns the payment schedule.
type: string
billingDocument:
properties:
id:
description: |
ID of the billing document. for example, `2c9890306fb2121e016fb21a6b550041`.
type: string
number:
description: |
The number of the billing docuemnt, for example, `INV00002345`.
type: string
type:
description: |
Indicates whether the associated billing document is a debit memo or a invoice.
type: string
type: object
billingDocuments:
description: |
Container array of the multiple billing documents associated with the payment schedule.
items:
type: object
properties:
id:
description: |
ID of the billing document.
type: string
number:
description: |
Number of the billing document. If the billing document is a debit memo, it contains the debit memo number. If the billing document is an invoice, it contains the invoice number.
type: string
type:
description: |
Denotes if the billing document is of the type invoice or debit memo.
enum:
- Invoice
- DebitMemo
type: string
type: array
createdById:
description: |
The ID of the user who created this payment schedule.
type: string
createdDate:
description: |
The date and time the payment schedule is created.
format: date
type: string
cancellationReason:
description: |
The reason for the cancellation of the payment schedule item.
nullable: true
type: string
cancelledById:
description: |
The ID of the user who canceled this payment schedule.
type: string
nullable: true
cancelledOn:
description: |
The date when the payment schedule was canceled.
type: string
nullable: true
cancelDate:
description: |
Specifies the effective date by when the payment schedule will be canceled.
format: date
type: string
description:
description: |
The description of the payment schedule.
type: string
id:
description: |
ID of the payment schedule.
type: string
isCustom:
description: |
Indicates if the payment schedule is a custom payment schedule.
type: boolean
items:
description: |
Container for payment schedule items.
items:
$ref: '#/components/schemas/PaymentScheduleItemCommonResponse'
type: array
nextPaymentDate:
description: |
The date the next payment will be processed.
format: date
type: string
occurrences:
description: |
The number of payment schedule items that are created by this payment schedule.
type: integer
paymentOption:
description: |
Container for the paymentOption items, which describe the transactional level rules for processing payments. Currently, only the Gateway Options type is supported.
`paymentOption` of the payment schedule takes precedence over `paymentOption` of the payment schedule item.
items:
$ref: '#/components/schemas/PaymentSchedulePaymentOptionFields'
type: array
paymentScheduleNumber:
description: |
Number of the payment schedule.
type: string
period:
description: |
For recurring payment schedule only. The period of payment generation. Available values include: `Monthly`, `Weekly`, `BiWeekly`.
Return `null` for custom payment schedules.
type: string
prepayment:
description: |
Indicates whether the payments created by the payment schedule are used as a reserved payment. This field is available only if the prepaid cash drawdown permission is enabled. See [Prepaid Cash with Drawdown](https://knowledgecenter.zuora.com/Zuora_Billing/Billing_and_Invoicing/JA_Advanced_Consumption_Billing/Prepaid_Cash_with_Drawdown) for more information.
type: boolean
recentPaymentDate:
description: |
The date the last payment was processed.
format: date
type: string
runHour:
description: |
[0,1,2,~,22,23]
At which hour in the day in the tenant’s timezone this payment will be collected.
Return `0` for custom payment schedules.
type: integer
standalone:
description: |
Indicates if the payments that the payment schedule created are standalone payments.
type: boolean
startDate:
description: |
The date when the first payment of this payment schedule is proccessed.
format: date
type: string
status:
description: |
The status of the payment schedule.
- Active: There is still payment schedule item to process.
- Canceled: After a payment schedule is canceled by the user, the schedule is marked as `Canceled`.
- Completed: After all payment schedule items are processed, the schedule is marked as `Completed`.
enum:
- Active
- Canceled
- Completed
type: string
success:
description: |
Returns `true` if the request was processed successfully.
type: boolean
totalAmount:
description: |
The total amount that will be collected by the payment schedule.
type: number
totalPaymentsErrored:
description: |
The number of errored payments.
type: integer
totalPaymentsProcessed:
description: |
The number of processed payments.
type: integer
updatedById:
description: |
The ID of the user who last updated this payment schedule.
type: string
updatedDate:
description: |
The date and time the payment schedule is last updated.
format: date
type: string
type: object
- $ref: '#/components/schemas/PaymentScheduleCustomFields'
PUTPaymentScheduleRequest:
allOf:
- properties:
amount:
description: |
Indicates the updated amount of the pending payment schedule items.
type: number
currency:
description: |
Indicates the updated currency of the pending payment schedule items.
**Note:**
- For custom payments, if Multi-currency is enabled, the payment currency can be different from the account currency for custom payment.
- For recurring payments, if Multi-currency is enabled, the payment currency can be different from the account currency but should be the same as billing currency for a recurring payment.
type: string
description:
description: |
Description of the payment schedule.
maxLength: 255
type: string
occurrences:
description: |
Indicates the updated number of payment schedule items that are created by the payment schedule.
**Note:**
- If "updated `occurrences` > existing `occurrences`", the following number of pending payment schedule item will be added to the payment schedule: “updated `occurrences` - existing `occurrences`”.
- If "existing `occurrences` > updated `occurrences` >= the number of `processed`/`errored`/`canceled` payment schedule items", the following number of pending items will be removed by descending order of the schedule dates: "existing `occurrences` - updated `occurrences`".
- If "updated `occurrences` < the number of `processed`/`erroed`/`canceled` payment schedule items", a validation error will be returned.
type: integer
paymentGatewayId:
description: |
Indicates the updated payment gateway ID of the pending payment schedule items.
type: string
paymentMethodId:
description: |
Indicates the updated payment method ID of the pending payment schedule items.
type: string
paymentOption:
description: |
Container for the paymentOption items, which describe the transactional level rules for processing payments. Currently, only the Gateway Options type is supported.
Here is an example:
```
"paymentOption": [
{
"type": "GatewayOptions",
"detail": {
"SecCode":"WEB"
}
}
]
```
`paymentOption` of the payment schedule takes precedence over `paymentOption` of the payment schedule item.
**Note:** To enable this field, submit a request at [Zuora Global Support](https://support.zuora.com/).
items:
$ref: '#/components/schemas/PaymentSchedulePaymentOptionFields'
type: array
period:
description: |
Indicates the updated period of the pending payment schedule items.
enum:
- Monthly
- Weekly
- BiWeekly
type: string
periodStartDate:
description: |
Indicates the updated collection date for the next pending payment schedule item.
format: date
type: string
runHour:
description: |
Specifies at which hour of the day in the tenant’s time zone this payment will be collected. Available values: `[0,1,2,~,22,23]`.
If the time difference between your tenant’s timezone and the timezone where Zuora servers are is not in full hours, for example, 2.5 hours, the payment schedule items will be triggered half hour later than your scheduled time. If the payment `runHour` and `scheduledDate` are backdated, the system will collect the payment when the next runHour occurs.
format: date
type: integer
type: object
- $ref: '#/components/schemas/PaymentScheduleCustomFields'
example:
description: Details of this payment schedule
PUTCancelPaymentScheduleRequest:
properties:
cancelDate:
description: |
Specifies when the payment schedule will be canceled.
**Note**: If there is no legitimate payment schedule item to cancel, the payment schedule cancel operation will be rejected.
format: date
type: string
required:
- cancelDate
type: object
POSTAddItemsToPaymentScheduleRequest:
example:
items:
- amount: 50
scheduledDate: '2024-11-22'
description: |
Container for the payment schedule items to be added to the payment schedule.
properties:
items:
items:
$ref: '#/components/schemas/PaymentScheduleItemCommon'
title: paymentScheduleItem
type: array
type: object
PaymentScheduleItemCommon:
allOf:
- properties:
amount:
description: |
The amount that needs to be collected by this payment schedule item.
type: number
currency:
description: |
The currency of the payment.
**Note**:
- This field is optional. If not specified, the default value is the currency set for the account.
- For custom payments, if Multi-currency is enabled, the payment currency can be different from the account currency for custom payment.
- For recurring payments, if Multi-currency is enabled, the payment currency can be different from the account currency but should be the same as billing currency for a recurring payment.
type: string
description:
description: |
Description of the payment schedule item.
type: string
paymentGatewayId:
description: |
The ID of the payment gateway.
**Note**:
- This field is optional. If not specified, the default value is the payment gateway id set for the account.
required:
- type
type: string
paymentMethodId:
description: |
The ID of the payment method.
**Note**:
- This field is optional. If not specified, the default value is the payment method id set for the account.
type: string
paymentOption:
description: |
Container for the paymentOption items, which describe the transactional level rules for processing payments. Currently, only the Gateway Options type is supported.
Here is an example:
```
"paymentOption": [
{
"type": "GatewayOptions",
"detail": {
"SecCode":"WEB"
}
}
]
```
`paymentOption` of the payment schedule takes precedence over `paymentOption` of the payment schedule item.
items:
$ref: '#/components/schemas/PaymentSchedulePaymentOptionFields'
type: array
runHour:
description: |
At which hour of the day in the tenant’s timezone this payment will be collected. Available values:`[0,1,2,~,22,23]`.
If the payment `runHour` and `scheduledDate` are backdated, the system will collect the payment when the next runHour occurs.
The default value is `0`.
type: string
scheduledDate:
description: |
The date to collect the payment.
format: date
type: string
required:
- scheduledDate
- amount
type: object
- $ref: '#/components/schemas/PaymentScheduleItemCustomFields'
PUTPreviewPaymentScheduleRequest:
allOf:
- properties:
amount:
description: |
Indicates the updated amount of the pending payment schedule items.
type: number
currency:
description: |
Indicates the updated currency of the pending payment schedule items.
type: string
occurrences:
description: |
Indicates the updated number of payment schedule items that are created by the payment schedule.
type: integer
paymentGatewayId:
description: |
Indicates the updated payment gateway ID of the pending payment schedule items.
type: string
paymentMethodId:
description: |
Indicates the updated payment method ID of the pending payment schedule items.
type: string
paymentOption:
description: |
Container for the paymentOption items, which describe the transactional level rules for processing payments. Currently, only the Gateway Options type is supported.
Here is an example:
```
"paymentOption": [
{
"type": "GatewayOptions",
"detail": {
"SecCode":"WEB"
}
}
]
```
`paymentOption` of the payment schedule takes precedence over `paymentOption` of the payment schedule item.
items:
$ref: '#/components/schemas/PaymentSchedulePaymentOptionFields'
type: array
period:
description: |
Indicates the updated period of the pending payment schedule items.
enum:
- Monthly
- Weekly
- BiWeekly
type: string
periodStartDate:
description: |
Indicates the updated collection date for the next pending payment schedule item.
format: date
type: string
runHour:
description: |
Specifies at which hour of the day in the tenant’s time zone this payment will be collected. Available values: `[0,1,2,~,22,23]`.
If the time difference between your tenant’s timezone and the timezone where Zuora servers are is not in full hours, for example, 2.5 hours, the payment schedule items will be triggered half hour later than your scheduled time. If the payment `runHour` and `scheduledDate` are backdated, the system will collect the payment when the next runHour occurs.
format: date
type: integer
type: object
- $ref: '#/components/schemas/PaymentScheduleCustomFields'
example:
occurrences: 5
GETRefundCollectionType:
properties:
nextPage:
description: |
URL to retrieve the next page of the response if it exists; otherwise absent.
format: URL
type: string
refunds:
description: |
Container for refunds.
items:
$ref: '#/components/schemas/GETRefundTypewithSuccess'
type: array
success:
description: Returns `true` if the request was processed successfully.
type: boolean
type: object
GETRefundTypewithSuccess:
allOf:
- properties:
accountId:
description: |
The ID of the account associated with this refund. Zuora associates the refund automatically with the account from the associated payment or credit memo.
type: string
amount:
description: |
The total amount of the refund.
format: double
type: number
cancelledOn:
description: |
The date and time when the refund was cancelled, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
nullable: true
comment:
description: |
Comments about the refund.
type: string
createdById:
description: |
The ID of the Zuora user who created the refund.
type: string
createdDate:
description: |
The date and time when the refund was created, in `yyyy-mm-dd hh:mm:ss` format. For example, 2017-03-01 15:31:10.
format: date-time
type: string
creditMemoId:
description: |
The ID of the credit memo that is refunded.
type: string
nullable: true
financeInformation:
description: |
Container for the finance information related to the refund.
properties:
bankAccountAccountingCode:
description: |
The accounting code that maps to a bank account in your accounting system.
type: string
nullable: true
bankAccountAccountingCodeType:
description: |
The type of the accounting code that maps to a bank account in your accounting system.
type: string
nullable: true
transferredToAccounting:
description: |
Whether the refund was transferred to an external accounting system. Use this field for integration with accounting systems, such as NetSuite.
enum:
- Processing
- 'Yes'
- 'No'
- Error
- Ignore
type: string
unappliedPaymentAccountingCode:
description: |
The accounting code for the unapplied payment.
type: string
nullable: true
unappliedPaymentAccountingCodeType:
description: |
The type of the accounting code for the unapplied payment.
type: string
nullable: true
type: object
gatewayId:
description: |
The ID of the gateway instance that processes the refund.
type: string
nullable: true
gatewayReconciliationReason:
description: |
The reason of gateway reconciliation.
type: string
nullable: true
gatewayReconciliationStatus:
description: |
The status of gateway reconciliation.
type: string
nullable: true
gatewayResponse:
description: |
The message returned from the payment gateway for the refund. This message is gateway-dependent.
type: string
nullable: true
gatewayResponseCode:
description: |
The code returned from the payment gateway for the refund. This code is gateway-dependent.
type: string
nullable: true
gatewayState:
description: |
The status of the refund in the gateway.
enum:
- MarkedForSubmission
- Submitted
- Settled
- NotSubmitted
- FailedToSettle
type: string
id:
description: |
The ID of the refund.
type: string
markedForSubmissionOn:
description: |
The date and time when a refund was marked and waiting for batch submission to the payment process, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
nullable: true
methodType:
description: |
How an external refund was issued to a customer.
enum:
- ACH
- Cash
- Check
- CreditCard
- PayPal
- WireTransfer
- DebitCard
- CreditCardReferenceTransaction
- BankTransfer
- Other
type: string
number:
description: |
The unique identification number of the refund.
type: string
organizationLabel:
description: |
The organization that this object belongs to.
Note: This field is available only when the Multi-Org feature is enabled.
type: string
paymentId:
description: |
The ID of the payment that is refunded.
type: string
paymentMethodId:
description: |
The unique ID of the payment method that the customer used to make the refund.
type: string
nullable: true
paymentMethodSnapshotId:
description: |
The unique ID of the payment method snapshot, which is a copy of the particular payment method used in a transaction.
type: string
nullable: true
payoutId:
description: |
The payout ID of the refund from the gateway side.
type: string
nullable: true
reasonCode:
description: |
A code identifying the reason for the transaction.
type: string
referenceId:
description: |
The transaction ID returned by the payment gateway for an electronic refund. Use this field to reconcile refunds between your gateway and Zuora Payments.
type: string
nullable: true
refundDate:
description: |
The date when the refund takes effect, in `yyyy-mm-dd` format. For example, 2017-03-01.
format: date
type: string
refundTransactionTime:
description: |
The date and time when the refund was issued, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
nullable: true
secondRefundReferenceId:
description: |
The transaction ID returned by the payment gateway if there is an additional transaction for the refund. Use this field to reconcile payments between your gateway and Zuora Payments.
type: string
nullable: true
settledOn:
description: |
The date and time when the refund was settled in the payment processor, in `yyyy-mm-dd hh:mm:ss` format. This field is used by the Spectrum gateway only and not applicable to other gateways.
format: date-time
type: string
nullable: true
softDescriptor:
description: |
A payment gateway-specific field that maps Zuora to other gateways.
type: string
nullable: true
softDescriptorPhone:
description: |
A payment gateway-specific field that maps Zuora to other gateways.
type: string
nullable: true
status:
description: |
The status of the refund.
enum:
- Processed
- Canceled
- Error
- Processing
type: string
submittedOn:
description: |
The date and time when the refund was submitted, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
nullable: true
type:
description: |
The type of the refund.
enum:
- External
- Electronic
type: string
updatedById:
description: |
The ID of the Zuora user who last updated the refund.
type: string
updatedDate:
description: |
The date and time when the refund was last updated, in `yyyy-mm-dd hh:mm:ss` format. For example, 2017-03-02 15:36:10.
format: date-time
type: string
type: object
- $ref: '#/components/schemas/RefundObjectNSFields'
- $ref: '#/components/schemas/RefundObjectCustomFields'
title: refunds
PUTRefundType:
allOf:
- properties:
comment:
description: |
Comments about the refund.
maxLength: 255
minLength: 0
type: string
financeInformation:
description: |
Container for the finance information related to the refund.
properties:
bankAccountAccountingCode:
description: |
The accounting code that maps to a bank account in your accounting system.
maxLength: 100
minLength: 0
type: string
transferredToAccounting:
description: |
Whether the payment was transferred to an external accounting system. Use this field for integration with accounting systems, such as NetSuite.
enum:
- Processing
- 'Yes'
- 'No'
- Error
- Ignore
type: string
unappliedPaymentAccountingCode:
description: |
The accounting code for the unapplied payment.
maxLength: 100
minLength: 0
type: string
type: object
reasonCode:
description: |
A code identifying the reason for the transaction. The value must be an existing reason code or empty. If you do not specify a value, Zuora uses the default reason code.
type: string
referenceId:
description: |
The transaction ID returned by the payment gateway. Use this field to reconcile refunds between your gateway and Zuora Payments.
You can only update the reference ID for external refunds.
maxLength: 100
minLength: 0
type: string
type: object
- $ref: '#/components/schemas/RefundObjectNSFields'
- $ref: '#/components/schemas/RefundObjectCustomFields'
example:
reasonCode: Other
GETRefundType:
allOf:
- properties:
accountId:
description: |
The ID of the account associated with this refund. Zuora associates the refund automatically with the account from the associated payment or credit memo.
type: string
amount:
description: |
The total amount of the refund.
format: double
type: number
cancelledOn:
description: |
The date and time when the refund was cancelled, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
comment:
description: |
Comments about the refund.
type: string
nullable: true
createdById:
description: |
The ID of the Zuora user who created the refund.
type: string
createdDate:
description: |
The date and time when the refund was created, in `yyyy-mm-dd hh:mm:ss` format. For example, `2017-03-01 15:31:10`.
format: date-time
type: string
creditMemoId:
description: |
The ID of the credit memo that is refunded.
type: string
financeInformation:
description: |
Container for the finance information related to the refund.
properties:
bankAccountAccountingCode:
description: |
The accounting code that maps to a bank account in your accounting system.
type: string
bankAccountAccountingCodeType:
description: |
The type of the accounting code that maps to a bank account in your accounting system.
type: string
transferredToAccounting:
description: |
Whether the refund was transferred to an external accounting system. Use this field for integration with accounting systems, such as NetSuite.
enum:
- Processing
- 'Yes'
- 'No'
- Error
- Ignore
type: string
unappliedPaymentAccountingCode:
description: |
The accounting code for the unapplied payment.
type: string
unappliedPaymentAccountingCodeType:
description: |
The type of the accounting code for the unapplied payment.
type: string
type: object
gatewayId:
description: |
The ID of the gateway instance that processes the refund.
type: string
gatewayReconciliationReason:
description: |
The reason of gateway reconciliation.
type: string
gatewayReconciliationStatus:
description: |
The status of gateway reconciliation.
type: string
gatewayResponse:
description: |
The message returned from the payment gateway for the refund. This message is gateway-dependent.
type: string
gatewayResponseCode:
description: |
The code returned from the payment gateway for the refund. This code is gateway-dependent.
type: string
gatewayState:
description: |
The status of the refund in the gateway.
enum:
- MarkedForSubmission
- Submitted
- Settled
- NotSubmitted
- FailedToSettle
type: string
id:
description: |
The ID of the refund.
type: string
markedForSubmissionOn:
description: |
The date and time when a refund was marked and waiting for batch submission to the payment process, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
methodType:
description: |
How an external refund was issued to a customer.
enum:
- ACH
- Cash
- Check
- CreditCard
- PayPal
- WireTransfer
- DebitCard
- CreditCardReferenceTransaction
- BankTransfer
- Other
type: string
number:
description: |
The unique identification number of the refund.
type: string
organizationLabel:
description: |
The organization that this object belongs to.
Note: This field is available only when the Multi-Org feature is enabled.
type: string
paymentId:
description: |
The ID of the payment that is refunded.
type: string
paymentMethodId:
description: |
The unique ID of the payment method that the customer used to make the refund.
type: string
paymentMethodSnapshotId:
description: |
The unique ID of the payment method snapshot, which is a copy of the particular payment method used in a transaction.
type: string
payoutId:
description: |
The payout ID of the refund from the gateway side.
type: string
reasonCode:
description: |
A code identifying the reason for the transaction.
type: string
referenceId:
description: |
The transaction ID returned by the payment gateway for an electronic refund. Use this field to reconcile refunds between your gateway and Zuora Payments.
type: string
refundDate:
description: |
The date when the refund takes effect, in `yyyy-mm-dd` format. For example, `2017-03-01`.
format: date
type: string
refundTransactionTime:
description: |
The date and time when the refund was issued, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
secondRefundReferenceId:
description: |
The transaction ID returned by the payment gateway if there is an additional transaction for the refund. Use this field to reconcile payments between your gateway and Zuora Payments.
type: string
settledOn:
description: |
The date and time when the refund was settled in the payment processor, in `yyyy-mm-dd hh:mm:ss` format. This field is used by the Spectrum gateway only and not applicable to other gateways.
format: date-time
type: string
softDescriptor:
description: |
A payment gateway-specific field that maps Zuora to other gateways.
type: string
softDescriptorPhone:
description: |
A payment gateway-specific field that maps Zuora to other gateways.
type: string
status:
description: |
The status of the refund.
enum:
- Processed
- Canceled
- Error
- Processing
type: string
submittedOn:
description: |
The date and time when the refund was submitted, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
success:
description: Returns `true` if the request was processed successfully.
type: boolean
type:
description: |
The type of the refund.
enum:
- External
- Electronic
type: string
updatedById:
description: |
The ID of the Zuora user who last updated the refund.
type: string
updatedDate:
description: |
The date and time when the refund was last updated, in `yyyy-mm-dd hh:mm:ss` format. For example, 2017-03-02 15:36:10.
type: string
example: '2017-03-02 15:36:10'
type: object
- $ref: '#/components/schemas/RefundObjectNSFields'
- $ref: '#/components/schemas/RefundObjectCustomFields'
GETRefundPartCollectionType:
properties:
parts:
description: |
Container for refund parts.
items:
$ref: '#/components/schemas/RefundPartResponseTypewithSuccess'
type: array
success:
description: Returns `true` if the request was processed successfully.
type: boolean
type: object
RefundPartResponseTypewithSuccess:
properties:
amount:
description: |
The amount of the refund part.
format: double
type: number
createdById:
description: |
The ID of the Zuora user who created the refund part.
type: string
createdDate:
description: |
The date and time when the refund part was created, in `yyyy-mm-dd hh:mm:ss` format. For example, 2017-03-01 15:31:10.
format: date-time
type: string
creditMemoId:
description: |
The ID of the credit memo associated with the refund part.
type: string
id:
description: |
The ID of the refund part.
type: string
organizationLabel:
description: |
The organization that this object belongs to.
Note: This field is available only when the Multi-Org feature is enabled.
type: string
paymentId:
description: |
The ID of the payment associated with the refund part.
type: string
updatedById:
description: |
The ID of the Zuora user who last updated the refund part.
type: string
updatedDate:
description: |
The date and time when the refund part was last updated, in `yyyy-mm-dd hh:mm:ss` format. For example, 2017-03-02 15:36:10.
format: date-time
type: string
title: parts
type: object
RefundPartResponseType:
properties:
amount:
description: |
The amount of the refund part.
format: double
type: number
createdById:
description: |
The ID of the Zuora user who created the refund part.
type: string
createdDate:
description: |
The date and time when the refund part was created, in `yyyy-mm-dd hh:mm:ss` format. For example, 2017-03-01 15:31:10.
format: date-time
type: string
creditMemoId:
description: |
The ID of the credit memo associated with the refund part.
type: string
id:
description: |
The ID of the refund part.
type: string
organizationLabel:
description: |
The organization that this object belongs to.
Note: This field is available only when the Multi-Org feature is enabled.
type: string
paymentId:
description: |
The ID of the payment associated with the refund part.
type: string
success:
description: Returns `true` if the request was processed successfully.
type: boolean
updatedById:
description: |
The ID of the Zuora user who last updated the refund part.
type: string
updatedDate:
description: |
The date and time when the refund part was last updated, in `yyyy-mm-dd hh:mm:ss` format. For example, 2017-03-02 15:36:10.
format: date-time
type: string
type: object
GETRefundItemPartCollectionType:
properties:
itemParts:
description: |
Container for refund part items.
items:
$ref: '#/components/schemas/GETRefundItemPartTypewithSuccess'
type: array
nextPage:
description: |
URL to retrieve the next page of the response if it exists; otherwise absent.
format: URL
type: string
success:
description: Returns `true` if the request was processed successfully.
type: boolean
type: object
GETRefundItemPartTypewithSuccess:
properties:
amount:
description: |
The amount of the refund part item.
format: double
type: number
createdById:
description: |
The ID of the Zuora user who created the refund part item.
type: string
createdDate:
description: |
The date and time when the refund part item was created, in `yyyy-mm-dd hh:mm:ss` format. For example, 2017-03-01 15:31:10.
format: date-time
type: string
creditMemoItemId:
description: |
The ID of the credit memo item associated with the refund part item.
type: string
creditTaxItemId:
description: |
The ID of the credit memo taxation item associated with the refund part item.
type: string
id:
description: |
The ID of the refund part item.
type: string
organizationLabel:
description: |
The organization that this object belongs to.
Note: This field is available only when the Multi-Org feature is enabled.
type: string
updatedById:
description: |
The ID of the Zuora user who last updated the refund part item.
type: string
updatedDate:
description: |
The date and time when the refund part item was last updated, in `yyyy-mm-dd hh:mm:ss` format. For example, 2017-03-02 15:36:10.
format: date-time
type: string
title: itemParts
type: object
GETRefundItemPartType:
properties:
amount:
description: |
The amount of the refund part item.
format: double
type: number
createdById:
description: |
The ID of the Zuora user who created the refund part item.
type: string
createdDate:
description: |
The date and time when the refund part item was created, in `yyyy-mm-dd hh:mm:ss` format. For example, 2017-03-01 15:31:10.
format: date-time
type: string
creditMemoItemId:
description: |
The ID of the credit memo item associated with the refund part item.
type: string
creditTaxItemId:
description: |
The ID of the credit memo taxation item associated with the refund part item.
type: string
id:
description: |
The ID of the refund part item.
type: string
organizationLabel:
description: |
The organization that this object belongs to.
Note: This field is available only when the Multi-Org feature is enabled.
type: string
success:
description: Returns `true` if the request was processed successfully.
type: boolean
updatedById:
description: |
The ID of the Zuora user who last updated the refund part item.
type: string
updatedDate:
description: |
The date and time when the refund part item was last updated, in `yyyy-mm-dd hh:mm:ss` format. For example, 2017-03-02 15:36:10.
format: date-time
type: string
type: object
GETActiveInvoiceCycleResponse:
type: object
properties:
cycles:
type: array
items:
$ref: '#/components/schemas/GETInvoiceCycleElementResponse'
description: |
An array containing information of all active retry cycles for an invoice. See the schema and example for details.
example:
cycles:
- account_id: 2c92c0f96bd69165016bdccdd6ce2f29
invoice_id: 2c92c0f8778bf8cd017798168cb50e0b
payment_method_id: 2c92c0f9774f2b3e01775f6f06d87b61
currency: USD
status: Cycle Incomplete
current_attempt_number: 2
next_attempt: '2021-04-01T19:27:34.648Z'
customer_group: All Remaining Customers
attempts:
- attempt_number: 1
zuora_payment_id: 2c92c0867849d42301784bc9ca076c21
time_of_execution: '2021-03-19T18:42:20.103Z'
source: PR-00000371
cpr_generated: false
success: false
amount_collected: '0.0'
action_info:
action: Retry
retry_info:
next: '2021-04-01T19:27:34.648-09:00'
criteria: incremental_time
mapping_info:
label: Hard Decline
level: code
customer_group_id: 1
gateway_info:
id: 2c92c0f85e2d19af015e3a61d8947e5d
code: insufficient_funds
response: Your card has insufficient funds.
- attempt_number: 2
zuora_payment_id: 2c92c09c7849d3c101784bce0d0a06d5
time_of_execution: '2021-03-19T18:52:24.137Z'
source: PR-00000372
cpr_generated: true
success: false
amount_collected: '0.0'
action_info:
action: Retry
retry_info:
next: '2021-03-19T09:53:39.845-09:00'
criteria: incremental_time
mapping_info:
label: Hard Decline
level: code
customer_group_id: 1
gateway_info:
id: 2c92c0f85e2d19af015e3a61d8947e5d
code: insufficient_funds
response: Your card has insufficient funds.
GETInvoiceCycleElementResponse:
type: object
title: RetryCycle
properties:
account_id:
type: string
description: |
The ID of the customer account.
invoice_id:
type: string
description: |
The ID of the invoice.
payment_method_id:
type: string
description: |
The ID of the payment method.
currency:
type: string
description: |
The type of the currency used.
status:
type: string
description: |
The status of the retry cycle.
current_attempt_number:
type: number
description: |
The number of the current retry attempt.
next_attempt:
type: string
format: date-time
description: |
The date and time of the next retry attempt, in `yyyy-mm-dd hh:mm:ss` format.
customer_group:
type: string
description: |
The name of the customer group.
attempts:
type: array
description: |
An array containing information of the retry attempts that have been made. See the schema and example for details.
items:
$ref: '#/components/schemas/GETCycleElementAttemptResponse'
GETCycleElementAttemptResponse:
type: object
title: RetryAttempt
properties:
attempt_number:
type: number
description: |
The number of the retry attempt.
zuora_payment_id:
type: string
description: |
The ID of the payment in Zuora Payments.
time_of_execution:
type: string
format: date-time
description: |
The date and time when the retry attempt was made, in `yyyy-mm-dd hh:mm:ss` format.
source:
type: string
description: |
The number of the failed payment run.
cpr_generated:
type: boolean
description: |
Indicates whether the first retry attempt was generated by Configurable Payment Retry.
`true` for the cases of the first retry attempt generated by CPR and the second or later attempt.
`false` for the cases that the retry attempt was made by the payment run or an external source during retry cycles.
success:
type: boolean
description: |
Indicates whether the retry attempt is successful.
amount_collected:
type: number
description: |
The amount collected in this retry attempt.
action_info:
type: object
description: |
Information about the action of the retry attempt.
properties:
action:
type: string
description: |
The action taken in the retry attempt.
retry_info:
type: object
description: |
Information about the next retry attempt.
properties:
next:
type: string
format: date-time
description: |
The date and time of the next retry attempt as determined by `criteria`, in `yyyy-mm-dd hh:mm:ss` format.
criteria:
type: string
description: |
The criteria defined in the retry configuration in the CPR UI, to specify whether the next retry will occur in an incremental time or at a specific time or day.
mapping_info:
type: object
description: |
Information about the response code mapping for the retry attempt.
properties:
label:
type: string
description: |
The response code label, can be `Hard Decline`, `Soft Decline`, `System Error`, or custom labels.
level:
type: string
description: |
The response code level for the payment gateway, can be `Code` or `Description`.
customer_group_id:
type: number
description: |
The ID of the customer group.
gateway_info:
type: object
description: |
Information about the payment gateway.
properties:
id:
type: string
description: |
The ID of the payment gateway.
code:
type: string
description: |
The response code from the gateway.
response:
type: string
description: |
The response message from the gateway.
GETActiveDebitMemoCycleResponse:
type: object
properties:
cycles:
type: array
items:
$ref: '#/components/schemas/GETDebitMemoCycleElementResponse'
description: |
An array containing information of all active retry cycles for a debit memo. See the schema and example for details.
example:
cycles:
- account_id: 2c92c0f868e161e70168e25eb51d755f
debit_memo_id: 2c92c0fa7853052701785a38f3bb267f
payment_method_id: 2c92c0f8774f1afe01775f6e533c4c06
currency: USD
status: Cycle Incomplete
current_attempt_number: 2
next_attempt: '2021-04-01T10:22:57.464Z'
customer_group: All Remaining Customers
attempts:
- attempt_number: 1
zuora_payment_id: 2c92c085785305e201785a51af791979
time_of_execution: '2021-03-23T16:50:18.878Z'
source: PR-00000376
cpr_generated: false
success: false
amount_collected: '0.0'
action_info:
action: Retry
retry_info:
next: '2021-03-23T07:51:30.380-09:00'
criteria: incremental_time
mapping_info:
label: Hard Decline
level: code
customer_group_id: 1
gateway_info:
id: 2c92c0f85e2d19af015e3a61d8947e5d
code: insufficient_funds
response: Your card has insufficient funds.
- attempt_number: 2
zuora_payment_id: 2c92c0857881cf3e01788ee263b0331c
time_of_execution: '2021-04-01T19:21:55.207Z'
source: PR-00000380
cpr_generated: true
success: false
amount_collected: '0.0'
action_info:
action: Retry
retry_info:
next: '2021-04-01T10:22:57.464-09:00'
criteria: incremental_time
mapping_info:
label: Hard Decline
level: code
customer_group_id: 1
gateway_info:
id: 2c92c0f85e2d19af015e3a61d8947e5d
code: insufficient_funds
response: Your card has insufficient funds.
GETDebitMemoCycleElementResponse:
type: object
title: RetryCycle
properties:
account_id:
type: string
description: |
The ID of the customer account.
debit_memo_id:
type: string
description: |
The ID of the debit memo.
payment_method_id:
type: string
description: |
The ID of the payment method.
currency:
type: string
description: |
The type of the currency used.
status:
type: string
description: |
The status of the retry cycle.
current_attempt_number:
type: number
description: |
The number of the current retry attempt.
next_attempt:
type: string
format: date-time
description: |
The date and time of the next retry attempt, in `yyyy-mm-dd hh:mm:ss` format.
customer_group:
type: string
description: |
The name of the customer group.
attempts:
type: array
description: |
An array containing information of the retry attempts that have been made. See the schema and example for details.
items:
$ref: '#/components/schemas/GETCycleElementAttemptResponse'
GETActiveAccountCycleResponse:
type: object
properties:
cycles:
type: array
items:
$ref: '#/components/schemas/GETAccountCycleElementResponse'
description: |
An array containing information of all active retry cycles for an account. See the schema and example for details.
example:
cycles:
- account_id: 2c92c0f96bd69165016bdccdd6ce2f29
debit_memo_id: 2c92c0fb78532b0001785a38f6427976
payment_method_id: 2c92c0f9774f2b3e01775f6f06d87b61
currency: USD
status: Cycle Incomplete
current_attempt_number: 1
next_attempt: '2021-04-01T19:27:34.473Z'
customer_group: All Remaining Customers
attempts:
- attempt_number: 1
zuora_payment_id: 2c92c085785305e201785a5199a6192d
time_of_execution: '2021-03-23T16:50:18.878Z'
source: PR-00000376
cpr_generated: false
success: false
amount_collected: '0.0'
action_info:
action: Retry
retry_info:
next: '2021-03-23T07:51:27.521-09:00'
criteria: incremental_time
mapping_info:
label: Hard Decline
level: code
customer_group_id: 1
gateway_info:
id: 2c92c0f85e2d19af015e3a61d8947e5d
code: insufficient_funds
response: Your card has insufficient funds.
- account_id: 2c92c0f96bd69165016bdccdd6ce2f29
invoice_id: 2c92c0fa7853052701785a38c6622473
payment_method_id: 2c92c0f9774f2b3e01775f6f06d87b61
currency: USD
status: Cycle Incomplete
current_attempt_number: 1
next_attempt: '2021-04-01T19:27:34.436Z'
customer_group: All Remaining Customers
attempts:
- attempt_number: 1
zuora_payment_id: 2c92c085785305e201785a519d85193b
time_of_execution: '2021-03-23T16:50:18.878Z'
source: PR-00000376
cpr_generated: false
success: false
amount_collected: '0.0'
action_info:
action: Retry
retry_info:
next: '2021-03-23T07:51:28.161-09:00'
criteria: incremental_time
mapping_info:
label: Hard Decline
level: code
customer_group_id: 1
gateway_info:
id: 2c92c0f85e2d19af015e3a61d8947e5d
code: insufficient_funds
response: Your card has insufficient funds.
GETAccountCycleElementResponse:
type: object
title: RetryCycle
properties:
account_id:
type: string
description: |
The ID of the customer account.
invoice_id:
type: string
description: |
The ID of the invoice.
debit_memo_id:
type: string
description: |
The ID of the debit memo.
payment_method_id:
type: string
description: |
The ID of the payment method.
currency:
type: string
description: |
The type of the currency used.
status:
type: string
description: |
The status of the retry cycle.
current_attempt_number:
type: number
description: |
The number of the current retry attempt.
next_attempt:
type: string
format: date-time
description: |
The date and time of the next retry attempt, in `yyyy-mm-dd hh:mm:ss` format.
customer_group:
type: string
description: |
The name of the customer group.
attempts:
type: array
description: |
An array containing information of the retry attempts that have been made. See the schema and example for details.
items:
$ref: '#/components/schemas/GETCycleElementAttemptResponse'
GETInvoiceCycleHistoryResponse:
type: object
properties:
cycles:
type: array
items:
$ref: '#/components/schemas/GETInvoiceCycleElementResponse'
description: |
An array containing information of all completed retry cycles for an invoice. See the example for details.
example:
cycles:
- account_id: 2c92c0f96bd69165016bdcbf55ad5e62
invoice_id: 2c92c0fa7849b3ff01784bc5e8ee18b5
payment_method_id: 2c92c0f9774f2b3e01775f6cf2fb726a
currency: USD
status: Cycle Complete
current_attempt_number: 1
next_attempt: null
customer_group: Testing Group
attempts:
- attempt_number: 1
zuora_payment_id: 2c92c0867849d42301784bc9ce806c31
time_of_execution: '2021-04-01T19:11:21.639Z'
source: PR-00000370
cpr_generated: false
success: false
amount_collected: '0.0'
action_info:
action: Stop
retry_info: {}
mapping_info:
label: Hard Decline
level: code
customer_group_id: 5
gateway_info:
id: 2c92c0f85e2d19af015e3a61d8947e5d
code: insufficient_funds
response: Your card has insufficient funds.
- account_id: 2c92c0f96bd69165016bdcbf55ad5e62
invoice_id: 2c92c0fa7849b3ff01784bc5e8ee18b5
payment_method_id: 2c92c0f9774f2b3e01775f6cf2fb726a
currency: USD
status: Cycle Complete
current_attempt_number: 2
next_attempt: null
customer_group: All Remaining Customers
attempts:
- attempt_number: 1
zuora_payment_id: 2c92c0867849d42301784bc9ce806c31
time_of_execution: '2021-03-19T18:42:20.103Z'
source: PR-00000371
cpr_generated: false
success: false
amount_collected: '0.0'
action_info:
action: Retry
retry_info:
next: '2021-03-19T09:43:28.670-09:00'
criteria: incremental_time
mapping_info:
label: Hard Decline
level: code
customer_group_id: 1
gateway_info:
id: 2c92c0f85e2d19af015e3a61d8947e5d
code: insufficient_funds
response: Your card has insufficient funds.
- attempt_number: 2
zuora_payment_id: 2c92c09c7849d3c101784bcdfc010671
time_of_execution: '2021-03-19T18:52:24.137Z'
source: PR-00000372
cpr_generated: true
success: false
amount_collected: '0.0'
action_info:
action: Stop
retry_info: {}
mapping_info:
label: Hard Decline
level: code
customer_group_id: 1
gateway_info:
id: 2c92c0f85e2d19af015e3a61d8947e5d
code: insufficient_funds
response: Your card has insufficient funds.
GETDebitMemoCycleHistoryResponse:
type: object
properties:
cycles:
type: array
items:
$ref: '#/components/schemas/GETDebitMemoCycleElementResponse'
description: |
An array containing information of all completed retry cycles for a debit memo. See the example for details.
example:
cycles:
- account_id: 2c92c0f868e161e70168e25eb51d755f
debit_memo_id: 2c92c0fa7853052701785a38f3bb267f
payment_method_id: 2c92c0f8774f1afe01775f6e533c4c06
currency: USD
status: Cycle Complete
current_attempt_number: 2
next_attempt: null
customer_group: All Remaining Customers
attempts:
- attempt_number: 1
zuora_payment_id: 2c92c085785305e201785a51af791979
time_of_execution: '2021-03-23T16:50:18.878Z'
source: PR-00000376
cpr_generated: false
success: false
amount_collected: '0.0'
action_info:
action: Retry
retry_info:
next: '2021-03-23T07:51:30.380-09:00'
criteria: incremental_time
api_updated_retry_time: '2021-03-26T14:27:21.107-04:00'
mapping_info:
label: Hard Decline
level: code
customer_group_id: 1
gateway_info:
id: 2c92c0f85e2d19af015e3a61d8947e5d
code: insufficient_funds
response: Your card has insufficient funds.
- attempt_number: 2
zuora_payment_id: 2c92c0857881cf3e01788ee263b0331c
time_of_execution: '2021-04-01T19:21:55.207Z'
source: PR-00000378
cpr_generated: true
success: false
amount_collected: '0.0'
action_info:
action: Stop
retry_info: {}
mapping_info:
label: Hard Decline
level: code
customer_group_id: 1
gateway_info:
id: 2c92c0f85e2d19af015e3a61d8947e5d
code: insufficient_funds
response: Your card has insufficient funds.
GETAccountCycleHistoryResponse:
type: object
properties:
cycles:
type: array
items:
$ref: '#/components/schemas/GETAccountCycleElementResponse'
description: |
An array containing information of all completed retry cycles for an account. See the example for details.
example:
cycles:
- account_id: 2c92c0f96bd69165016bdcbf55ad5e62
invoice_id: 2c92c0fa7849b3ff01784bc5e8ee18b5
payment_method_id: 2c92c0f9774f2b3e01775f6cf2fb726a
currency: USD
status: Cycle Complete
current_attempt_number: 3
next_attempt: '2021-03-19T18:53:39.641Z'
customer_group: All Remaining Customers
attempts:
- attempt_number: 1
zuora_payment_id: 2c92c0867849d42301784bc9ce806c31
time_of_execution: '2021-03-19T18:42:20.103Z'
source: PR-00000371
cpr_generated: false
success: false
amount_collected: '0.0'
action_info:
action: Retry
retry_info:
next: '2021-03-19T09:43:28.670-09:00'
criteria: incremental_time
mapping_info:
label: Hard Decline
level: code
customer_group_id: 1
gateway_info:
id: 2c92c0f85e2d19af015e3a61d8947e5d
code: insufficient_funds
response: Your card has insufficient funds.
- attempt_number: 2
zuora_payment_id: 2c92c09c7849d3c101784bcdfc010671
time_of_execution: '2021-03-19T18:52:24.137Z'
source: PR-00000372
cpr_generated: true
success: false
amount_collected: '0.0'
action_info:
action: Stop
retry_info: {}
mapping_info:
label: Hard Decline
level: code
customer_group_id: 1
gateway_info:
id: 2c92c0f85e2d19af015e3a61d8947e5d
code: insufficient_funds
response: Your card has insufficient funds.
- account_id: 2c92c0f96bd69165016bdcbf55ad5e62
invoice_id: 2c92c0fb78532b0f01785a38cede190a
payment_method_id: 2c92c0f9774f2b3e01775f6cf2fb726a
currency: USD
status: Cycle Incomplete
current_attempt_number: 1
next_attempt: '2021-03-24T19:34:20.254Z'
customer_group: All Remaining Customers
attempts:
- attempt_number: 1
zuora_payment_id: 2c92c085785305e201785a51aae41969
time_of_execution: '2021-03-23T16:50:18.878Z'
source: PR-00000376
cpr_generated: false
success: false
amount_collected: '0.0'
action_info:
action: Retry
retry_info:
next: '2021-03-23T07:51:30.316-09:00'
criteria: incremental_time
mapping_info:
label: Hard Decline
level: code
customer_group_id: 1
gateway_info:
id: 2c92c0f85e2d19af015e3a61d8947e5d
code: insufficient_funds
response: Your card has insufficient funds.
GETBaselineMetricsResponse:
type: object
properties:
retry_success_rate:
type: number
description: |
The percentage of successful payment attempts for all customer groups on this Configurable Payment Retry instance so far.
Retry Success Rate = Number of successful retry payment attempts / Total number of retry payments attempted
Payment attempts here are any payment attempts executed by Configurable Payment Retry, excluding the initial payment run.
retry_success_rate_trend:
type: string
description: |
The trend of change in Retry Success Rate over the last 30 days.
document_success_rate:
type: number
description: |
The percentage of billing documents that are successfully collected, for all customer groups on this Configurable Payment Retry instance so far.
Document Success Rate = Number of billing documents collected / Total number of billing documents attempted
Billing documents collected are any invoices and debit memos that were paid through the payment attempt initiated by Configurable Payment Retry.
document_success_rate_trend:
type: string
description: |
The trend of change in Document Success Rate over the last 30 days.
average_days_outstanding:
type: number
description: |
The average number of days invoices and debit memos are unpaid before collection, for all customer groups on this Configurable Payment Retry instance so far.
average_days_outstanding_trend:
type: string
description: |
The trend of change in Average Days Outstanding over the last 30 days.
success:
type: boolean
description: |
Indicates whether the metrics are retrieved successfully.
If no data is loaded yet, a 200 response code will be returned with the success field set to `true`. All expected fields will be present but the value will be `null`.
example:
retry_success_rate: '11.90'
retry_success_rate_trend: down
document_success_rate: '13.54'
document_success_rate_trend: neutral
average_days_outstanding: '4.76'
average_days_outstanding_trend: up
success: true
GETAmountRecoveredResponse:
type: object
properties:
currency:
type: array
items:
type: object
description: |
An array containing the following information for each available currency.
If no payment of a given currency has been processed over the last 30 days, the currency will not appear in the array.
- The total amount recovered to date
- The amount recovered over the last 30 days
success:
type: boolean
description: |
Indicates whether the metrics are retrieved successfully.
If no data is loaded yet, a 200 response code will be returned with the success field set to `true`. All expected fields will be present but the value will be `null`.
example:
currency:
USD:
total_amount: '77515.21'
last_30_days: '1100.01'
EUR:
total_amount: '337.19'
last_30_days: '17.17'
CAD:
total_amount: '123954.10'
last_30_days: '5132.87'
success: true
GETDocumentSuccessRateByCustomerGroupResponse:
type: object
properties:
customer_groups:
type: array
items:
type: object
description: |
An array containing the Document Success Rate timeseries for each customer group represented by the customer group ID.
A timeseries over the past 6 months is present in the format of `*customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
description: |
Container for custom fields of an Accounting Code object.
title: accountingCodeFieldsCustom
type: object
POSTAccountingCodeType:
allOf:
- properties:
glAccountName:
description: |
Name of the account in your general ledger.
Field only available if you have Zuora Finance enabled. Maximum of 255 characters.
type: string
glAccountNumber:
description: |
Account number in your general ledger.
Field only available if you have Zuora Finance enabled. Maximum of 255 characters.
type: string
name:
description: |
Name of the accounting code.
Accounting code name must be unique. Maximum of 100 characters.
type: string
notes:
description: |
Maximum of 2,000 characters.
type: string
type:
description: |
If you want to create multiple accounting codes of the type `AccountsReceivable`, you need to have [Invoice Item Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement/C_Invoice_Item_Settlement) enabled and contact [Zuora Global Support](http://support.zuora.com) to access the Multiple AR Accounting Codes feature.
Note that `On-Account Receivable` is only available if you enable the Invoice Settlement feature.
enum:
- AccountsReceivable
- On-Account Receivable
- Cash
- OtherAssets
- CustomerCashOnAccount
- DeferredRevenue
- SalesTaxPayable
- OtherLiabilities
- SalesRevenue
- SalesDiscounts
- OtherRevenue
- OtherEquity
- BadDebt
- OtherExpenses
type: string
segmentConstantValues:
$ref: '#/components/schemas/SegmentConstantValuesCustomFields'
required:
- name
- type
type: object
- $ref: '#/components/schemas/AccountingCodeObjectCustomFields'
example:
name: CASH
type: Cash
POSTAccountingCodeResponseType:
properties:
id:
description: |
ID of the newly created accounting code.
type: string
success:
description: |
Returns `true` if the request was processed successfully.
type: boolean
type: object
GETAccountingCodeItemType:
allOf:
- properties:
category:
description: |
The category associated with the accounting code.
enum:
- Assets
- Liabilities
- Equity
- Revenue
- Expenses
type: string
createdBy:
description: |
The ID of the user who created the accounting code.
type: string
createdOn:
description: |
Date and time when the accounting code was created.
format: date-time
type: string
glAccountName:
description: |
Name of the account in your general ledger.
Field only available if you have Zuora Finance enabled.
type: string
glAccountNumber:
description: |
Account number in your general ledger.
Field only available if you have Zuora Finance enabled.
type: string
id:
description: |
ID of the accounting code.
type: string
name:
description: |
Name of the accounting code.
type: string
notes:
description: |
Any optional notes for the accounting code.
type: string
status:
description: |
The accounting code status.
enum:
- Active
- Inactive
type: string
success:
description: |
Returns `true` if the request was processed successfully.
type: boolean
type:
description: |
Accounting code type.
Note that `On-Account Receivable` is only available if you enable the Invoice Settlement feature.
enum:
- AccountsReceivable
- On-Account Receivable
- Cash
- OtherAssets
- CustomerCashOnAccount
- DeferredRevenue
- SalesTaxPayable
- OtherLiabilities
- SalesRevenue
- SalesDiscounts
- OtherRevenue
- OtherEquity
- BadDebt
- OtherExpenses
type: string
updatedBy:
description: |
The ID of the user who last updated the accounting code.
type: string
updatedOn:
description: |
Date and time when the accounting code was last updated.
format: date-time
type: string
segmentConstantValues:
$ref: '#/components/schemas/SegmentConstantValuesCustomFields'
type: object
- $ref: '#/components/schemas/AccountingCodeObjectCustomFields'
PUTAccountingCodeType:
allOf:
- properties:
glAccountName:
description: |
Name of the account in your general ledger.
Field only available if you have Zuora Finance enabled. Maximum of 255 characters.
type: string
glAccountNumber:
description: |
Account number in your general ledger.
Field only available if you have Zuora Finance enabled. Maximum of 255 characters.
type: string
name:
description: |
Name of the accounting code.
Accounting code name must be unique. Maximum of 100 characters.
type: string
notes:
description: |
Maximum of 2,000 characters.
type: string
type:
description: |
Accounting code type. You cannot change the type of an accounting code from `AccountsReceivable` to a different type.
Note that `On-Account Receivable` is only available if you enable the Invoice Settlement feature.
enum:
- AccountsReceivable
- On-Account Receivable
- Cash
- OtherAssets
- CustomerCashOnAccount
- DeferredRevenue
- SalesTaxPayable
- OtherLiabilities
- SalesRevenue
- SalesDiscounts
- OtherRevenue
- OtherEquity
- BadDebt
- OtherExpenses
type: string
segmentConstantValues:
$ref: '#/components/schemas/SegmentConstantValuesCustomFields'
type: object
- $ref: '#/components/schemas/AccountingCodeObjectCustomFields'
example:
notes: Details of the accounting code
GETAccountingPeriodsType:
properties:
accountingPeriods:
description: |
An array of all accounting periods on your tenant. The accounting periods are returned in ascending order of start date; that is, the latest period is returned first.
items:
$ref: '#/components/schemas/GETAccountingPeriodWithoutSuccessType'
type: array
nextPage:
description: |
URL to retrieve the next page of the response if it exists; otherwise absent.
format: URL
type: string
success:
description: |
Returns `true` if the request was processed successfully.
type: boolean
type: object
GETAccountingPeriodWithoutSuccessType:
allOf:
- properties:
createdBy:
description: |
ID of the user who created the accounting period.
type: string
createdOn:
description: |
Date and time when the accounting period was created.
format: date-time
type: string
endDate:
description: |
The end date of the accounting period.
format: date
type: string
fileIds:
description: |
File IDs of the reports available for the accounting period. You can retrieve the reports by specifying the file ID in a [Get Files](https://developer.zuora.com/api-references/api/operation/GET_Files) REST API call.
properties:
accountsReceivableAccountAgingDetailExportFileId:
description: |
File ID of the Accounts Receivable Aging Account Detail report.
type: string
accountsReceivableInvoiceAgingDetailExportFileId:
description: |
File ID of the Accounts Receivable Aging Invoice Detail report.
type: string
arRollForwardDetailExportFileId:
description: |
File ID of the Accounts Receivable Detail report.
type: string
fxRealizedGainAndLossDetailExportFileId:
description: |
File ID of the Realized Gain and Loss Detail report.
Returned only if you have Foreign Currency Conversion enabled.
type: string
fxUnrealizedGainAndLossDetailExportFileId:
description: |
File ID of the Unrealized Gain and Loss Detail report.
Returned only if you have Foreign Currency Conversion enabled
type: string
revenueDetailCsvFileId:
description: |
File ID of the Revenue Detail report in CSV format.
type: string
revenueDetailExcelFileId:
description: |
File ID of the Revenue Detail report in XLSX format.
type: string
unprocessedChargesFileId:
description: |
File ID of a report containing all unprocessed charges for the accounting period.
type: string
type: object
fiscalYear:
description: |
Fiscal year of the accounting period.
type: integer
fiscalQuarter:
description: Fiscal quarter of the accounting period.
type: integer
id:
description: |
ID of the accounting period.
type: string
name:
description: |
Name of the accounting period.
type: string
notes:
description: |
Any optional notes about the accounting period.
type: string
organizationLabels:
description: |
The organization(s) that the object belongs to.
Note: This field is available only when the Multi-Org feature is enabled.
items:
properties:
organizationId:
description: |
The organization ID.
type: string
organizationName:
description: |
The organization name.
type: string
type: object
type: array
runTrialBalanceEnd:
description: |
Date and time that the trial balance was completed. If the trial balance status is `Pending`, `Processing`, or `Error`, this field is `null`.
format: date-time
type: string
runTrialBalanceErrorMessage:
description: |
If trial balance status is Error, an error message is returned in this field.
type: string
runTrialBalanceStart:
description: |
Date and time that the trial balance was run. If the trial balance status is `Pending`, this field is `null`.
format: date-time
type: string
runTrialBalanceStatus:
description: |
Status of the trial balance for the accounting period. Possible values:
* `Pending`
* `Processing`
* `Completed`
* `Error`
type: string
startDate:
description: |
The start date of the accounting period.
format: date
type: string
status:
description: |
Status of the accounting period. Possible values:
* `Open`
* `PendingClose`
* `Closed`
type: string
updatedBy:
description: |
D of the user who last updated the accounting period.
type: string
updatedOn:
description: |
Date and time when the accounting period was last updated.
format: date-time
type: string
type: object
- $ref: '#/components/schemas/AccountingPeriodObjectCustomFields'
title: accountingPeriods
AccountingPeriodObjectCustomFields:
additionalProperties:
description: |
Custom fields of the Accounting Period object. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
description: |
Container for custom fields of an Accounting Period object.
title: accountingPeriodFieldsCustom
type: object
POSTAccountingPeriodType:
allOf:
- properties:
endDate:
description: |
The end date of the accounting period in yyyy-mm-dd format, for example, "2016-02-19".
format: date
type: string
fiscalYear:
description: |
Fiscal year of the accounting period in yyyy format, for example, "2016".
type: integer
fiscalQuarter:
description: Fiscal quarter of the accounting period. One number between 1 and 4.
type: integer
minimum: 1
maximum: 4
name:
description: |
Name of the accounting period.
Accounting period name must be unique. Maximum of 100 characters.
type: string
notes:
description: |
Notes about the accounting period.
Maximum of 255 characters.
type: string
organizationLabels:
description: |
The organization that the accounting period belongs to.
For each item in the array, either the `organizationId` or the `organizationName` field is required.
This field is only required when you have already turned on Multi-Org feature.
items:
properties:
organizationId:
description: |
The organization ID.
type: string
organizationName:
description: |
The organization name.
type: string
type: object
type: array
startDate:
description: |
The start date of the accounting period in yyyy-mm-dd format, for example, "2016-02-19".
format: date
type: string
required:
- name
- startDate
- endDate
- fiscalYear
type: object
- $ref: '#/components/schemas/AccountingPeriodObjectCustomFields'
example:
name: Jun 2016
fiscalYear: 2016
startDate: '2016-06-01'
endDate: '2016-06-30'
POSTAccountingPeriodResponseType:
properties:
id:
description: |
ID of the newly-created accounting period.
type: string
success:
description: |
Returns `true` if the request was processed successfully.
type: boolean
type: object
GETAccountingPeriodType:
allOf:
- properties:
createdBy:
description: |
ID of the user who created the accounting period.
type: string
createdOn:
description: |
Date and time when the accounting period was created.
format: date-time
type: string
endDate:
description: |
The end date of the accounting period.
format: date
type: string
fileIds:
description: |
File IDs of the reports available for the accounting period. You can retrieve the reports by specifying the file ID in a [Get Files](https://developer.zuora.com/api-references/api/operation/GET_Files) REST API call.
properties:
accountsReceivableAccountAgingDetailExportFileId:
description: |
File ID of the Accounts Receivable Aging Account Detail report.
type: string
accountsReceivableInvoiceAgingDetailExportFileId:
description: |
File ID of the Accounts Receivable Aging Invoice Detail report.
type: string
accountsReceivableDebitMemoAgingDetailExportFileId:
description: |
File ID of the Accounts Receivable Aging Debit Memo Detail report.
type: string
arRollForwardDetailExportFileId:
description: |
File ID of the Accounts Receivable Detail report.
type: string
fxRealizedGainAndLossDetailExportFileId:
description: |
File ID of the Realized Gain and Loss Detail report.
Returned only if you have Foreign Currency Conversion enabled.
type: string
fxUnrealizedGainAndLossDetailExportFileId:
description: |
File ID of the Unrealized Gain and Loss Detail report.
Returned only if you have Foreign Currency Conversion enabled
type: string
revenueDetailCsvFileId:
description: |
File ID of the Revenue Detail report in CSV format.
type: string
revenueDetailExcelFileId:
description: |
File ID of the Revenue Detail report in XLSX format.
type: string
unprocessedChargesFileId:
description: |
File ID of a report containing all unprocessed charges for the accounting period.
type: string
type: object
fiscalYear:
description: |
Fiscal year of the accounting period.
type: integer
fiscalQuarter:
description: Fiscal quarter of the accounting period.
type: integer
id:
description: |
ID of the accounting period.
type: string
name:
description: |
Name of the accounting period.
type: string
notes:
description: |
Any optional notes about the accounting period.
type: string
organizationLabels:
description: |
The organization(s) that the object belongs to.
Note: This field is available only when the Multi-Org feature is enabled.
items:
properties:
organizationId:
description: |
The organization ID.
type: string
organizationName:
description: |
The organization name.
type: string
type: object
type: array
runTrialBalanceEnd:
description: |
Date and time that the trial balance was completed. If the trial balance status is `Pending`, `Processing`, or `Error`, this field is `null`.
format: date-time
type: string
runTrialBalanceErrorMessage:
description: |
If trial balance status is Error, an error message is returned in this field.
type: string
runTrialBalanceStart:
description: |
Date and time that the trial balance was run. If the trial balance status is Pending, this field is null.
format: date-time
type: string
runTrialBalanceStatus:
description: |
Status of the trial balance for the accounting period. Possible values:
* `Pending`
* `Processing`
* `Completed`
* `Error`
type: string
startDate:
description: |
The start date of the accounting period.
format: date
type: string
status:
description: |
Status of the accounting period. Possible values:
* `Open`
* `PendingClose`
* `Closed`
type: string
success:
description: |
Returns `true` if the request was processed successfully.
type: boolean
updatedBy:
description: |
ID of the user who last updated the accounting period.
type: string
updatedOn:
description: |
Date and time when the accounting period was last updated.
format: date-time
type: string
type: object
- $ref: '#/components/schemas/AccountingPeriodObjectCustomFields'
PUTAccountingPeriodType:
allOf:
- properties:
endDate:
description: |
The end date of the accounting period in yyyy-mm-dd format, for example, "2016-02-19".
format: date
type: string
fiscalYear:
description: |
Fiscal year of the accounting period in yyyy format, for example, "2016".
type: integer
fiscalQuarter:
description: Fiscal quarter of the accounting period. One number between 1 and 4.
type: integer
minimum: 1
maximum: 4
name:
description: |
Name of the accounting period.
Accounting period name must be unique. Maximum of 100 characters.
type: string
notes:
description: |
Notes about the accounting period.
Maximum of 255 characters.
type: string
startDate:
description: |
The start date of the accounting period in yyyy-mm-dd format, for example, "2016-02-19".
format: date
type: string
type: object
- $ref: '#/components/schemas/AccountingPeriodObjectCustomFields'
example:
notes: Details of the accounting period
POSTJournalEntryType:
allOf:
- properties:
accountingPeriodName:
description: |
Name of the accounting period. The open-ended accounting period is named `Open-Ended`.
type: string
currency:
description: |
The type of currency used. Currency must be active.
type: string
journalEntryDate:
description: |
Date of the journal entry.
format: date
type: string
journalEntryItems:
description: |
Key name that represents the list of journal entry items.
items:
$ref: '#/components/schemas/POSTJournalEntryItemType'
type: array
notes:
description: |
The number associated with the revenue event.
Character limit: 2,000
type: string
organizationLabel:
description: |
Name of the organization that the journal entry belongs to.
This field is only required when you have already turned on Multi-Org feature.
type: string
segments:
description: |
List of segments that apply to the summary journal entry.
items:
$ref: '#/components/schemas/POSTJournalEntrySegmentType'
type: array
transferredToAccounting:
description: |
Status shows whether the journal entry has been transferred to an accounting system.
enum:
- 'No'
- Processing
- 'Yes'
- Error
- Ignore
type: string
required:
- journalEntryDate
- accountingPeriodName
- currency
- journalEntryItems
type: object
- $ref: '#/components/schemas/JournalEntryObjectCustomFields'
example:
accountingPeriodName: 2020/02
currency: USD
journalEntryDate: '2020-01-20'
journalEntryItems:
- accountingCodeName: Accounts Receivable
amount: 400.9
homeCurrencyAmount: 400.9
type: Credit
- accountingCodeName: Subscription Revenue
amount: 400.9
homeCurrencyAmount: 400.9
type: Debit
POSTJournalEntryResponseType:
properties:
journalEntryNumber:
description: |
Journal entry number in the format JE-00000001.
type: string
success:
description: |
Returns `true` if the request was processed successfully.
type: boolean
type: object
POSTJournalEntryItemType:
allOf:
- properties:
accountingCodeName:
description: |
Name of the accounting code.
type: string
accountingCodeType:
description: |
Accounting code type. This field is required if `accountingCodeName` is not unique.
Note that `On-Account Receivable` is only available if you enable the Invoice Settlement feature.
enum:
- AccountsReceivable
- On-Account Receivable
- Cash
- OtherAssets
- CustomerCashOnAccount
- DeferredRevenue
- SalesTaxPayable
- OtherLiabilities
- SalesRevenue
- SalesDiscounts
- OtherRevenue
- OtherEquity
- BadDebt
- OtherExpenses
type: string
amount:
description: |
Journal entry item amount in transaction currency.
format: decimal
type: string
homeCurrencyAmount:
description: |
Journal entry item amount in home currency.
This field is required if you have set your home currency for foreign currency conversion. Otherwise, do not pass this field.
format: decimal
type: string
type:
description: 'Type of journal entry item. '
enum:
- Credit
- Debit
type: string
required:
- accountingCodeName
- type
- amount
type: object
- $ref: '#/components/schemas/JournalEntryItemObjectCustomFields'
title: journalEntryItems
POSTJournalEntrySegmentType:
properties:
segmentName:
description: 'Name of segment. You must use the segment name that has already been specified in the default segment rule. In addition, segments need to be passed in the order where they were defined in the segmentation rule. If multiple segments are configured in the default rule, you need to specify all of them in order. '
type: string
segmentValue:
description: |
Value of segment in this summary journal entry.
type: string
required:
- segmentName
- segmentValue
title: segments
type: object
JournalEntryObjectCustomFields:
additionalProperties:
description: |
Custom fields of the Journal Entry object. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
description: |
Container for custom fields of a Journal Entry object.
title: journalEntryFieldsCustom
type: object
JournalEntryItemObjectCustomFields:
additionalProperties:
description: |
Custom fields of the Journal Entry Item object. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
description: |
Container for custom fields of a Journal Entry Item object.
title: journalEntryItemFieldsCustom
type: object
GETJournalEntriesInJournalRunType:
properties:
journalEntries:
description: |
Key name that represents the list of journal entries.
items:
$ref: '#/components/schemas/GETJournalEntryDetailTypeWithoutSuccess'
type: array
nextPage:
description: |
URL to retrieve the next page of the response if it exists; otherwise absent.
format: URL
type: string
success:
description: |
Returns `true` if the request was processed successfully.
type: boolean
type: object
GETJournalEntryDetailTypeWithoutSuccess:
allOf:
- properties:
accountingPeriodName:
description: |
Name of the accounting period that the journal entry belongs to.
type: string
aggregateCurrency:
description: |
Returns true if the journal entry is aggregating currencies. That is, if the journal entry was created when the `Aggregate transactions with different currencies during a JournalRun` setting was configured to "Yes". Otherwise, returns `false`.
type: boolean
currency:
description: |
Currency used.
type: string
homeCurrency:
description: |
Home currency used.
type: string
journalEntryDate:
description: |
Date of the journal entry.
format: date
type: string
journalEntryItems:
description: |
Key name that represents the list of journal entry items.
items:
$ref: '#/components/schemas/GETJournalEntryItemType'
type: array
notes:
description: |
Additional information about this record.
Character limit: 2,000
type: string
number:
description: |
Journal entry number in the format JE-00000001.
type: string
organizationLabel:
description: |
The organization that this object belongs to.
Note: This field is available only when the Multi-Org feature is enabled.
type: string
segments:
description: |
List of segments that apply to the summary journal entry.
items:
$ref: '#/components/schemas/GETJournalEntrySegmentType'
type: array
status:
description: 'Status of journal entry. '
enum:
- Created
- Cancelled
type: string
timePeriodEnd:
description: |
End date of time period included in the journal entry.
format: date
type: string
timePeriodStart:
description: |
Start date of time period included in the journal entry.
format: date
type: string
transactionType:
description: |
Transaction type of the transactions included in the summary journal entry.
type: string
transferDateTime:
description: |
Date and time that transferredToAccounting was changed to `Yes`. This field is returned only when transferredToAccounting is `Yes`. Otherwise, this field is `null`.
format: date-time
type: string
transferredBy:
description: |
User ID of the person who changed transferredToAccounting to `Yes`. This field is returned only when transferredToAccounting is `Yes`. Otherwise, this field is `null`.
type: string
transferredToAccounting:
description: 'Status shows whether the journal entry has been transferred to an accounting system. '
enum:
- 'No'
- Processing
- 'Yes'
- Error
- Ignore
type: string
type: object
- $ref: '#/components/schemas/JournalEntryObjectCustomFields'
title: journalEntries
GETJournalEntryItemType:
allOf:
- properties:
accountingCodeName:
description: |
Name of the accounting code.
type: string
accountingCodeType:
description: |
Accounting code type.
Note that `On-Account Receivable` is only available if you enable the Invoice Settlement feature.
enum:
- AccountsReceivable
- On-Account Receivable
- Cash
- OtherAssets
- CustomerCashOnAccount
- DeferredRevenue
- SalesTaxPayable
- OtherLiabilities
- SalesRevenue
- SalesDiscounts
- OtherRevenue
- OtherEquity
- BadDebt
- OtherExpenses
type: string
amount:
description: |
Journal entry item amount in transaction currency.
format: decimal
type: string
glAccountName:
description: |
The account number in the general ledger (GL) that corresponds to the accounting code.
type: string
glAccountNumber:
description: |
The account name in the general ledger (GL) that corresponds to the accounting code.
type: string
homeCurrencyAmount:
description: |
Journal entry item amount in home currency.
format: decimal
type: string
type:
description: 'Type of journal entry item. '
enum:
- Credit
- Debit
type: string
type: object
- $ref: '#/components/schemas/JournalEntryItemObjectCustomFields'
title: journalEntryItems
GETJournalEntrySegmentType:
properties:
segmentName:
description: |
Name of segment.
type: string
segmentValue:
description: |
Value of segment in this summary journal entry.
type: string
title: segments
type: object
GETJournalEntryDetailType:
allOf:
- properties:
accountingPeriodName:
description: |
Name of the accounting period that the journal entry belongs to.
type: string
aggregateCurrency:
description: |
Returns true if the journal entry is aggregating currencies. That is, if the journal entry was created when the `Aggregate transactions with different currencies during a Journal Run` setting was configured to `Yes`. Otherwise, returns `false`.
type: boolean
currency:
description: |
Currency used.
type: string
homeCurrency:
description: |
Home currency used.
type: string
journalEntryDate:
description: |
Date of the journal entry.
format: date
type: string
journalEntryItems:
description: |
Key name that represents the list of journal entry items.
items:
$ref: '#/components/schemas/GETJournalEntryItemType'
type: array
notes:
description: |
Additional information about this record.
Character limit: 2,000
type: string
number:
description: |
Journal entry number in the format JE-00000001.
type: string
organizationLabel:
description: |
The organization that this object belongs to.
Note: This field is available only when the Multi-Org feature is enabled.
type: string
segments:
description: |
List of segments that apply to the summary journal entry.
items:
$ref: '#/components/schemas/GETJournalEntrySegmentType'
type: array
status:
description: |
Status of journal entry.
enum:
- Created
- Cancelled
type: string
success:
description: |
Returns `true` if the request was processed successfully.
type: boolean
timePeriodEnd:
description: |
End date of time period included in the journal entry.
format: date
type: string
timePeriodStart:
description: |
Start date of time period included in the journal entry.
format: date
type: string
transactionType:
description: |
Transaction type of the transactions included in the summary journal entry.
type: string
transferDateTime:
description: |
Date and time that transferredToAccounting was changed to `Yes`. This field is returned only when transferredToAccounting is `Yes`. Otherwise, this field is `null`.
format: date-time
type: string
transferredBy:
description: |
User ID of the person who changed transferredToAccounting to `Yes`. This field is returned only when transferredToAccounting is `Yes`. Otherwise, this field is `null`.
type: string
transferredToAccounting:
description: 'Status shows whether the journal entry has been transferred to an accounting system. '
enum:
- 'No'
- Processing
- 'Yes'
- Error
- Ignore
type: string
type: object
- $ref: '#/components/schemas/JournalEntryObjectCustomFields'
PUTBasicSummaryJournalEntryType:
allOf:
- properties:
journalEntryItems:
description: |
Key name that represents the list of journal entry items.
items:
$ref: '#/components/schemas/PUTJournalEntryItemType'
type: array
notes:
description: |
Additional information about this record.
***Character limit:*** 2,000
type: string
transferredToAccounting:
description: |
Status shows whether the journal entry has been transferred to an accounting system.
This field cannot be changed after the summary journal entry has been canceled.
**Note:** The Zuora Finance ***Override Transferred to Accounting*** permission is required to change `transferredToAccounting` from `Yes` to any other value.
enum:
- 'No'
- Processing
- 'Yes'
- Error
- Ignore
type: string
type: object
- $ref: '#/components/schemas/JournalEntryObjectCustomFields'
example:
transferredToAccounting: 'Yes'
PUTJournalEntryItemType:
allOf:
- properties:
accountingCodeName:
description: |
Name of the accounting code.
If the Journal Entry Item has a blank accounting code, enter the empty string.
type: string
accountingCodeType:
description: |
Accounting code type.
Note that `On-Account Receivable` is only available if you enable the Invoice Settlement feature.
enum:
- AccountsReceivable
- On-Account Receivable
- Cash
- OtherAssets
- CustomerCashOnAccount
- DeferredRevenue
- SalesTaxPayable
- OtherLiabilities
- SalesRevenue
- SalesDiscounts
- OtherRevenue
- OtherEquity
- BadDebt
- OtherExpenses
type: string
type:
description: 'Type of journal entry item. '
enum:
- Credit
- Debit
type: string
required:
- accountingCodeName
- type
type: object
- $ref: '#/components/schemas/JournalEntryItemObjectCustomFields'
title: journalEntryItems
POSTJournalRunType:
example:
accountingPeriodName: Nov-2014
journalEntryDate: '2014-11-04'
transactionTypes:
- type: Invoice Item
- type: Revenue Event Item
properties:
accountingPeriodName:
description: |
Name of the accounting period.
This field determines the target start and end dates of the journal run.
Required if you do not include `targetStartDate` and `targetEndDate`.
type: string
journalEntryDate:
description: |
Date of the journal entry.
format: date
type: string
organizationLabels:
description: |
The organization that this run is created for.
For each item in the array, either the `organizationId` or the
`organizationName` field is required.
This field is only required when you have already turned on Multi-Org
feature.
properties:
organizationId:
description: |
The organization ID.
type: string
organizationName:
description: |
The organization name.
type: string
type: object
targetEndDate:
description: |
The target end date of the journal run.
If you include `accountingPeriodName`, the `targetEndDate` must be empty or the same as the end date of the accounting period specified in `accountingPeriodName`.
format: date
type: string
targetStartDate:
description: |
The target start date of the journal run.
Required if you include targetEndDate.
If you include `accountingPeriodName`, the `targetStartDate` must be empty or the same as the start date of the accounting period specified in `accountingPeriodName`.
format: date
type: string
transactionTypes:
description: |
Transaction types included in the journal run.
You can include one or more transaction types.
items:
$ref: '#/components/schemas/POSTJournalRunTransactionType'
type: array
required:
- transactionTypes
- journalEntryDate
type: object
POSTJournalRunResponseType:
properties:
journalRunNumber:
description: |
Journal run number.
type: string
success:
description: |
Returns `true` if the request was processed successfully.
type: boolean
type: object
POSTJournalRunTransactionType:
properties:
type:
description: |
Transaction type. Invoice Adjustment is deprecated on Production. Zuora recommends that you use the Invoice Item Adjustment instead.
If you enable the Invoice Settlement feature, Debit Memo Item, Credit Memo Item, and Credit Memo Application Item are available, Payment and Refund will be replaced by Payment Application and Refund Application.
If you enable both the Invoice Settlement feature and the Invoice Item Settlement feature, Payment and Refund will be replaced by Payment Application Item and Refund Application Item.
enum:
- Invoice Item
- Taxation Item
- Invoice Item Adjustment (Invoice)
- Invoice Item Adjustment (Tax)
- Invoice Adjustment
- Electronic Payment
- External Payment
- Electronic Refund
- External Refund
- Electronic Credit Balance Payment
- External Credit Balance Payment
- Electronic Credit Balance Refund
- External Credit Balance Refund
- Credit Balance Adjustment (Applied from Credit Balance)
- Credit Balance Adjustment (Transferred to Credit Balance)
- Revenue Event Item
- Debit Memo Item (Charge)
- Debit Memo Item (Tax)
- Credit Memo Item (Charge)
- Credit Memo Item (Tax)
- Credit Memo Application Item
- Electronic Payment Application
- External Payment Application
- Electronic Refund Application
- External Refund Application
- Electronic Payment Application Item
- External Payment Application Item
- Electronic Refund Application Item
- External Refund Application Item
type: string
required:
- type
title: transactionTypes
type: object
GETJournalRunType:
properties:
aggregateCurrency:
description: ''
type: boolean
executedOn:
description: |
Date and time the journal run was executed.
format: date-time
type: string
journalEntryDate:
description: |
Date of the journal entry.
format: date
type: string
number:
description: |
Journal run number.
type: string
organizationLabels:
description: |
The organization(s) that the object belongs to.
Note: This field is available only when the Multi-Org feature is enabled.
items:
properties:
organizationId:
description: |
The organization ID.
type: string
organizationName:
description: |
The organization name.
type: string
type: object
type: array
segmentationRuleName:
description: |
Name of GL segmentation rule used in the journal run.
type: string
status:
description: |
Status of the journal run.
enum:
- Pending
- Processing
- Completed
- Error
- CancelInprogress
- Cancelled
- DeleteInprogress
type: string
success:
description: |
Returns `true` if the request was processed successfully.
type: boolean
targetEndDate:
description: |
The target end date of the journal run.
format: date
type: string
targetStartDate:
description: |
The target start date of the journal run.
format: date
type: string
totalJournalEntryCount:
description: |
Total number of journal entries in the journal run.
format: int64
type: integer
transactionTypes:
description: |
Transaction types included in the journal run.
items:
$ref: '#/components/schemas/GETJournalRunTransactionType'
type: array
type: object
GETJournalRunTransactionType:
properties:
type:
description: |
Transaction type. Invoice Adjustment is deprecated on Production. Zuora recommends that you use the Invoice Item Adjustment instead.
If you enable the Invoice Settlement feature, Debit Memo Item, Credit Memo Item, and Credit Memo Application Item are available, Payment and Refund will be replaced by Payment Application and Refund Application.
If you enable both the Invoice Settlement feature and the Invoice Item Settlement feature, Payment and Refund will be replaced by Payment Application Item and Refund Application Item.
enum:
- Invoice Item
- Taxation Item
- Invoice Item Adjustment (Invoice)
- Invoice Item Adjustment (Tax)
- Invoice Adjustment
- Electronic Payment
- External Payment
- Electronic Refund
- External Refund
- Electronic Credit Balance Payment
- External Credit Balance Payment
- Electronic Credit Balance Refund
- External Credit Balance Refund
- Credit Balance Adjustment (Applied from Credit Balance)
- Credit Balance Adjustment (Transferred to Credit Balance)
- Revenue Event Item
- Debit Memo Item (Charge)
- Debit Memo Item (Tax)
- Credit Memo Item (Charge)
- Credit Memo Item (Tax)
- Credit Memo Application Item
- Electronic Payment Application
- External Payment Application
- Electronic Refund Application
- External Refund Application
- Electronic Payment Application Item
- External Payment Application Item
- Electronic Refund Application Item
- External Refund Application Item
type: string
title: transactionTypes
type: object
POSTMassUpdateResponseType:
properties:
bulkKey:
description: |
String of 32 characters that identifies the mass action. The bulkKey is generated before the mass action is processed. You can use the bulkKey to Get the Mass Action Result.
type: string
success:
description: |
Returns `true` if the request was processed successfully.
type: boolean
type: object
GETMassUpdateType:
properties:
actionType:
description: |
Type of mass action.
type: string
endedOn:
description: |
Date and time that the mass action was completed. The format is `yyyy-MM-dd hh:mm:ss`.
format: date-time
type: string
errorCount:
description: |
Total number of failed records.
This field is updated in real time. When the mass action **status** is Processing, this field returns the number of records that have failed so far. When the mass action **status** is Pending, this field is null.
type: string
inputSize:
description: |
Size of the input file in bytes.
format: int64
type: integer
outputSize:
description: |
Size of the response file in bytes.
format: int64
type: integer
outputType:
description: |
Type of output for the response file. The following table describes the output type.
| Output Type | Description |
|----------------|-------------------------------------|
| (url:.csv.zip) | URL pointing to a zipped .csv file. |
type: string
outputURL:
description: |
URL to download the response file. The response file is a zipped .csv file.
The response file is identical to the file you uploaded to perform the mass action, with additional columns providing information about the outcome of each record.
This field only returns a value when the mass action **status** is Completed or Stopped. Otherwise, this field is null.
type: string
processedCount:
description: |
Total number of processed records. This field is equal to the sum of `errorCount` and `successCount`.
This field is updated in real time. When the mass action **status** is Processing, this field returns the number of records that have been processed so far. When the mass action **status** is Pending, this field is null.
type: string
startedOn:
description: |
Date and time that Zuora started processing the mass action. The format is `yyyy-MM-dd hh:mm:ss`.
format: date-time
type: string
status:
description: |
Status of the mass action. The following table describes the mass action statuses.
| Status | Description |
|------------|----------------------------------------------------------------------------|
| Pending | Mass action has not yet started being processed. |
| Processing | Mass action is in progress. |
| Stopping | Mass action is in the process of stopping, but has not yet stopped. |
| Stopped | Mass action has stopped. |
| Completed | Mass action was successfully completed. There may still be failed records. |
| Failed | Mass action failed. No records are processed. No response file is created. |
type: string
success:
description: |
Returns `true` if the request was processed successfully.
type: boolean
successCount:
description: |
Total number of successful records.
This field is updated in real time. When the mass action **status** is Processing, this field returns the number of records that have succeeded so far. When the mass action **status** is Pending, this field is null.
type: string
totalCount:
description: |
Total number of records in the uploaded mass action file.
When the mass action **status** is Pending, this field is null.
type: string
uploadedBy:
description: |
Email of the person who uploaded the mass action file.
type: string
uploadedOn:
description: |
Date and time that the mass action file was uploaded. The format is `yyyy-MM-dd hh:mm:ss`.
format: date-time
type: string
type: object
ExpandedAccount:
properties:
id:
type: string
description: |
The unique identifier of the account.
createdById:
type: string
description: |
The unique identifier of the user who created the account.
createdDate:
type: string
format: date-time
description: |
The date and time when the account was created.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the account.
updatedDate:
type: string
format: date-time
description: |
The date and time when the account was last updated.
accountNumber:
type: string
description: |
The account number that identifies the account.
additionalEmailAddresses:
type: string
description: |
An additional email addresse to receive email notifications.
allowInvoiceEdit:
type: boolean
description: |
Indicates whether associated invoices can be edited.
default: false
autoPay:
type: boolean
description: |
Indicates whether future payments are automatically collected when they are due
during a payment run.
balance:
type: number
format: double
description: |
The customer's total invoice balance minus credit balance.
batch:
type: string
description: |
The alias name given to a batch. A string of 50 characters or less.
bcdSettingOption:
description: |
Bill cycle day setting option. Indicates whether the account’s bill cycle day is managed manually or automatically.
- `ManualSet`: The bill cycle day is explicitly set to a specific day of the month (1–31).
- `AutoSet`: The bill cycle day is automatically determined by Zuora. The bill cycle day is assigned when the first subscription is created for the account.
This field is system-derived and read-only. Its value is automatically determined based on the `billCycleDay` field.
type: string
enum:
- ManualSet
- AutoSet
billCycleDay:
type: integer
format: int64
description: |
Billing cycle day (BCD), the day of the month when a bill run
generates invoices for the account.
billToId:
type: string
description: |
The unique identifier of the bill-to contact associated with the account.
communicationProfileId:
type: string
description: |
The unique identifier of the communication profile that Zuora uses when sending notifications to the account's contacts.
creditBalance:
type: number
format: double
description: |
The current credit balance on the account.
crmId:
description: |
External identifier of the account in a CRM system.
maxLength: 100
type: string
currency:
type: string
description: |
A currency defined in the web-based UI administrative settings.
customerServiceRepName:
description: |
Name of the account's customer service representative, if applicable.
maxLength: 50
type: string
defaultPaymentMethodId:
type: string
description: |
ID of the default payment method for the account.
eInvoiceProfileId:
type: string
description: |
ID of the e-invoice profile for this account.
**Note**: This field is available only if you have the E-Invoicing feature in **Early Adopter** phase enabled.
invoiceDeliveryPrefsEmail:
description: |
Indicates whether the customer wants to receive invoices through email.
type: boolean
invoiceDeliveryPrefsPrint:
description: |
Whether the customer wants to receive printed invoices, such as through postal mail.
type: boolean
invoiceTemplateId:
description: |
Invoice template ID, configured in Billing Settings in the Zuora UI.
type: string
lastInvoiceDate:
type: string
format: date
description: |
Date of the most recent invoice for the account; null if no invoice has ever been generated.
lastMetricsUpdate:
description: |
The date and time when account metrics are last updated, if the account is a partner account.
**Note**:
- This field is available only if you have the Reseller Account feature enabled.
- If you ever set the `partnerAccount` field to `true` for an account, the value of `lastMetricsUpdate` field is the time when the account metrics are last updated.
format: date-time
type: string
name:
type: string
description: |
The name of the account.
notes:
type: string
description: |
A string of up to 65,535 characters.
organizationId:
type: string
description: |
The unique identifier of the organization to which the account belongs.
parentId:
description: |
Identifier of the parent customer account for this Account object. The
length is 32 characters. Use this field if you have Customer Hierarchy enabled.
type: string
partnerAccount:
type: boolean
description: |
Whether the customer account is a partner, distributor, or reseller.
**Note**: This field is available only if you have the Reseller Account feature enabled.
paymentMethodCascadingConsent:
type: boolean
description: |
`true` indicates the consent from your customer to use the Cascading Payment Method feature was collected.
`false` indicates the consent was not collected and the Cascading Payment Method feature is not enabled.
purchaseOrderNumber:
type: string
description: |
The purchase order number provided by your customer for services,
products, or both purchased.
salesRepName:
type: string
description: |
Name of the account's sales representative, if applicable.
sequenceSetId:
type: string
nullable: true
description: |
The ID of the billing document sequence set to assign to the customer account.
The billing documents to generate for this account will adopt the prefix and starting document number configured in the sequence set.
If a customer account has no assigned billing document sequence set, billing documents generated for this account adopt the prefix and starting document number from the default sequence set.
shipToId:
type: string
description: |
The unique identifier of the ship-to contact associated with the account.
soldToId:
type: string
description: |
The unique identifier of the sold-to contact associated with the account.
status:
description: |
The account status.
type: string
enum:
- Active
- Draft
- Canceled
taxCompanyCode:
type: string
description: |
Unique code that identifies a company account in Avalara.
**Note:** This feature is in Limited Availability. If you wish to have access to the feature, submit a request at [Zuora Global Support](https://support.zuora.com).
maxLength: 50
taxExemptCertificateID:
type: string
description: |
ID of the customer tax exemption certificate. Applicable if you use Zuora Tax or Connect tax engines.
maxLength: 32
taxExemptCertificateType:
type: string
description: |
Type of tax exemption certificate that the customer holds. Applicable if you use Zuora Tax or Connect tax engines.
maxLength: 32
taxExemptDescription:
type: string
description: |
Description of the tax exemption certificate that the customer holds.
Applicable if you use Zuora Tax or Connect tax engines.
maxLength: 500
taxExemptEffectiveDate:
type: string
format: date
description: |
Date when the customer tax exemption starts, in `YYYY-MM-DD` format. Applicable if you use Zuora Tax or Connect tax engines.
taxExemptEntityUseCode:
type: string
description: |
A unique entity use code to apply exemptions in Avalara AvaTax. See Exempt Transactions for more details.
maxLength: 64
taxExemptExpirationDate:
type: string
format: date
description: |
Date when the customer tax exemption expires, in `YYYY-MM-DD` format. Applicable if you use Zuora Tax or Connect tax engines.
taxExemptIssuingJurisdiction:
type: string
description: |
Jurisdiction in which the customer tax exemption certificate was issued.
maxLength: 32
taxExemptStatus:
type: string
default: 'No'
description: |
Status of the account tax exemption. Applicable if you use Zuora Tax or Connect tax engines. Required if you use Zuora Tax.
enum:
- 'No'
- 'Yes'
- PendingVerification
totalInvoiceBalance:
type: number
description: |
Total balance of all posted invoices.
format: double
unappliedBalance:
type: number
description: |
Total unapplied balance in this currency.
vATId:
type: string
description: EU Value Added Tax ID.
mrr:
type: number
description: |
Monthly recurring revenue for the account.
totalDebitMemoBalance:
type: number
description: |
Total balance of all posted debit memos.
format: double
unappliedCreditMemoAmount:
type: number
description: |
The total unapplied amount of all posted credit memos in this currency.
format: double
creditMemoTemplateId:
type: string
description: |
ID of the credit memo template that is used to generate credit memos for the account.
debitMemoTemplateId:
type: string
description: |
ID of the debit memo template that is used to generate debit memos for the account.
paymentGateway:
type: string
description: |
The name of the payment gateway instance. If null or left unassigned,
the account will use the default gateway.
paymentTerm:
type: string
description: |
A payment-terms indicator defined in the web-based UI administrative
settings, for example, `Net 30`.
billTo:
$ref: '#/components/schemas/ExpandedContact'
shipTo:
$ref: '#/components/schemas/ExpandedContact'
soldTo:
$ref: '#/components/schemas/ExpandedContact'
defaultPaymentMethod:
$ref: '#/components/schemas/NestedPaymentMethodOnExpand'
subscriptions:
type: array
items:
$ref: '#/components/schemas/NestedSubscriptionOnExpand'
payments:
type: array
items:
$ref: '#/components/schemas/NestedPaymentOnExpand'
refunds:
type: array
items:
$ref: '#/components/schemas/NestedRefundOnExpand'
creditMemos:
type: array
items:
$ref: '#/components/schemas/NestedCreditMemoOnExpand'
debitMemos:
type: array
items:
$ref: '#/components/schemas/NestedDebitMemoOnExpand'
invoices:
type: array
items:
$ref: '#/components/schemas/NestedInvoiceOnExpand'
usages:
type: array
items:
$ref: '#/components/schemas/NestedUsageOnExpand'
paymentMethods:
type: array
items:
$ref: '#/components/schemas/NestedPaymentMethodOnExpand'
additionalProperties:
type: object
description: |
Custom fields of the Account object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryAccountResponse
CommonOQErrorResponse:
properties:
reasons:
description: |
The container of the error code and message. This field is available only if the `success` field is `false`.
items:
properties:
code:
description: |
The error code of response.
type: integer
message:
description: |
The detail information of the error response
type: string
type: object
type: array
requestId:
description: |
The unique identifier of the request.
format: uuid
maxLength: 36
minLength: 36
type: object
ExpandedContact:
properties:
id:
type: string
description: |
The unique identifier of the contact.
createdById:
type: string
description: |
The unique identifier of the user who created the contact.
createdDate:
type: string
format: date-time
description: |
The date and time when the contact was created.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the contact.
updatedDate:
type: string
format: date-time
description: |
The date and time when the contact was last updated.
accountId:
description: |
The ID of the account associated with the contact.
type: string
address1:
description: |
The first line of the contact's address, which is often a street address or business name.
maxLength: 255
type: string
address2:
description: |
The second line of the contact's address.
maxLength: 255
type: string
asBillTo:
type: boolean
description: |
Indicates whether the contact can be specified as a bill-to contact.
asShipTo:
type: boolean
description: |
Indicates whether the contact can be specified as a ship-to contact.
asSoldTo:
type: boolean
description: |
Indicates whether the contact can be specified as a sold-to contact.
city:
description: |
The city of the contact's address.
maxLength: 40
type: string
country:
description: |
The country of the contact's address.
maxLength: 64
type: string
county:
description: |
The county. May optionally be used by Zuora Tax to calculate county tax.
maxLength: 32
type: string
fax:
description: |
The contact's fax number.
maxLength: 40
type: string
description:
description: |
A description for the contact.
maxLength: 100
type: string
firstName:
description: |
The contact's first name.
maxLength: 100
type: string
homePhone:
description: |
The contact's home phone number.
maxLength: 40
type: string
lastName:
description: |
The contact's last name.
maxLength: 100
type: string
mobilePhone:
description: |
The mobile phone number of the contact.
maxLength: 100
type: string
nickname:
description: |
A nickname for the contact.
maxLength: 100
type: string
otherPhone:
description: |
An additional phone number for the contact.
maxLength: 40
type: string
otherPhoneType:
description: |
The type of the additional phone number.
enum:
- Work
- Mobile
- Home
- Other
type: string
personalEmail:
description: |
The contact's personal email address.
maxLength: 80
type: string
state:
description: |
The state or province of the contact's address.
maxLength: 40
type: string
postalCode:
description: |
ZIP code or other postal code of the contact's address.
maxLength: 20
type: string
taxRegion:
description: |
If using Zuora Tax, a region string as optionally defined in your tax rules.
maxLength: 32
type: string
workEmail:
description: |
The contact's business email address.
maxLength: 80
type: string
workPhone:
description: |
The contact's business phone number.
maxLength: 40
type: string
additionalProperties:
type: object
description: |
Custom fields of the Contact object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryContactResponse
NestedPaymentMethodOnExpand:
properties:
id:
type: string
description: |
The unique identifier of the payment method.
createdById:
type: string
description: |
The unique identifier of the user who created the payment method.
createdDate:
type: string
format: date-time
description: |
The time that the payment method gets created in the system, in the
`YYYY-MM-DD HH:MM:SS` format.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the payment method.
updatedDate:
type: string
format: date-time
description: |
The time that the payment method gets updated in the system, in the
`YYYY-MM-DD HH:MM:SS` format.
accountId:
type: string
description: |
The unique identifier of the account that the payment method is
associated with.
achAbaCode:
type: string
description: |
The nine-digit routing number or ABA number used by banks. This field is only required if the `type` field is set to `ACH`.
achAccountName:
type: string
description: |
The name of the account holder, which can be either a person or a company. This field is only required if the `type` field is set to `ACH`.
achAccountNumberMask:
description: |
The masked bank account number associated with the ACH payment method. This field is only required if the `type` field is set to `ACH`.
type: string
achAccountType:
type: string
description: |
The type of bank account associated with the ACH payment method. This field is only required if the `type` field is set to `ACH`.
When creating an ACH payment method on Adyen, this field is required by Zuora but it is not required by Adyen. To create the ACH payment method successfully, specify a real value for this field if you can. If it is not possible to get the real value for it, specify any of the allowed values as a dummy value, `Checking` preferably.
enum:
- BusinessChecking
- Checking
- Saving
achAddress1:
type: string
description: |
First address line for the ACH payment method.
maxLength: 255
achAddress2:
type: string
description: |
Second address line for the ACH payment method.
maxLength: 255
achBankName:
type: string
description: |
The name of the bank where the ACH payment account is held.
When creating an ACH payment method on Adyen, this field is required by Zuora but it is not required by Adyen. To create the ACH payment method successfully, specify a real value for this field if you can. If it is not possible to get the real value for it, specify a dummy value.
maxLength: 70
achCity:
type: string
description: |
City for the ACH payment method.
It is recommended to provide the city and country information when creating a payment method. The information will be used to process payments. If the information is not provided during payment method creation, the city and country data will be missing during payment processing.
maxLength: 40
achCountry:
description: |
Country for the ACH payment method. Must be a valid country name or abbreviation.
See View countries or regions for the list of supported country names and abbreviations.
It is recommended to provide the city and country information when creating a payment method. The information will be used to process payments. If the information is not provided during payment method creation, the city and country data will be missing during payment processing.
type: string
achPostalCode:
type: string
description: |
Zip code or postal code for the ACH payment method.
maxLength: 20
achState:
type: string
description: |
State for the ACH payment method. Must be a valid subregion (state or province) name or code. For more information, see View subregions of a specific country or region.
active:
type: boolean
description: |
Indicates whether the payment method type is active. This field is for Zuora internal use and does not impact customer integration or use cases.
isSystem:
type: boolean
description: |
Indicates whether the payment method is a system-generated payment method. This field is for Zuora internal use and does not impact customer integration or use cases.
bankBranchCode:
type: string
description: |
The branch code of the bank used for Direct Debit.
bankCheckDigit:
description: The check digit in the international bank account number, which confirms the validity of the account. Applicable to direct debit payment methods.
type: string
bankCity:
type: string
description: The city of the direct debit bank.
bankCode:
type: string
description: |
The sort code or number that identifies the bank. This is also known as the sort code.
bankIdentificationNumber:
type: string
description: The first six or eight digits of the payment method's number, such as the credit card number or account number. Banks use this number to identify a payment method.
bankName:
type: string
description: The name of the direct debit bank.
bankPostalCode:
type: string
description: The zip code or postal code of the direct debit bank.
bankStreetName:
type: string
description: The name of the street of the direct debit bank.
bankStreetNumber:
type: string
description: The number of the direct debit bank.
bankTransferAccountName:
type: string
description: The name on the direct debit bank account.
bankTransferAccountNumberMask:
type: string
description: |
This is a masked displayable version of the bank account number, used for
security purposes. For example: `XXXXXXXXX54321`.
bankTransferAccountType:
type: string
description: |
The type of the customer's bank account. Applicable to direct debit
payment methods.
bankTransferType:
description: |
Specifies the type of direct debit transfer. The value of this field is dependent on the country of the user.
Possible Values:
* `AutomatischIncasso` (NL)
* `LastschriftDE` (Germany)
* `LastschriftAT` (Austria)
* `DemandeDePrelevement` (FR)
* `DirectDebitUK` (UK)
* `Domicil` (Belgium)
* `LastschriftCH` (CH)
* `RID` (Italy)
* `OrdenDeDomiciliacion` (Spain)
* `Autogiro` (Sweden)
* `Betalingsservice` (Denmark)
enum:
- AutomatischIncasso
- LastschriftDE
- LastschriftAT
- DemandeDePrelevement
- DirectDebitUK
- Domicil
- LastschriftCH
- RID
- OrdenDeDomiciliacion
- Autogiro
- Betalingsservice
type: string
businessIdentificationCode:
type: string
description: |
The business identification code for Swiss direct payment methods that use
the Global Collect payment gateway. Only applicable to direct debit
payment methods in Switzerland with Global Collect.
city:
description: |
The city of the customer's address. Applicable to debit payment methods.
type: string
country:
type: string
description: The two-letter country code of the customer's address. Applicable to direct debit payment methods.
creditCardAddress1:
type: string
description: |
The first line of the card holder's address, which is often a street
address or business name. Applicable to credit card and direct debit
payment methods.
creditCardAddress2:
type: string
description: |
The second line of the card holder's address. Applicable to credit card
and direct debit payment methods.
creditCardCity:
type: string
description: |
The city of the card holder's address. Applicable to credit card and
direct debit payment methods.
creditCardCountry:
description: |
The country where the credit card holder stays.
When creating a payment method through a translated UI or Payment Page, a country name in a translated language might be selected.
Regardless of the country texts selected when creating the payment method, only the supported country name returns in this field.
For a complete list of supported country names, see View countries or regions.
Internationalization is not supported for the API field value.
type: string
creditCardExpirationMonth:
type: integer
format: int32
description: |
One or two digits expiration month.
minimum: 1
maximum: 12
creditCardExpirationYear:
type: integer
format: int32
description: |
Four-digit expiration year.
creditCardHolderName:
type: string
description: |
The full name of the credit card holder.
creditCardMaskNumber:
description: |
The masked credit card number, such as `*********1112`.
type: string
creditCardPostalCode:
type: string
description: |
The postal code for the address of the credit card holder.
creditCardState:
type: string
description: |
The state where the credit card holder stays.
creditCardType:
description: |
The type of the credit card or debit card.
Possible values include `Visa`, `MasterCard`, `AmericanExpress`, `Discover`, `JCB`, and `Diners`. For more information about credit card types supported by different payment gateways, see [Supported Payment Gateways](https://knowledgecenter.zuora.com/CB_Billing/M_Payment_Gateways/Supported_Payment_Gateways).
**Note:** This field is only returned for the Credit Card and Debit Card payment types.
type: string
deviceSessionId:
description: |
The session ID of the user when the `PaymentMethod` was created or updated.
type: string
existingMandate:
description: |
Indicates whether the mandate is an existing mandate.
enum:
- 'Yes'
- 'No'
type: string
email:
description: |
The email address of the payment method holder.
type: string
firstName:
type: string
description: |
The customer's first name. Only applicable to direct debit payment methods.
iBAN:
type: string
description: |
The International Bank Account Number used to create the SEPA payment method. The value is masked.
iPAddress:
type: string
description: |
The IP address of the user when the payment method was created or updated.
identityNumber:
type: string
description: |
The identity number of the account holder or the cardholder.
companyName:
type: string
description: |
The name of the company.
isCompany:
type: boolean
description: |
Whether the customer account is a company.
lastFailedSaleTransactionDate:
type: string
format: date
description: |
The date of the last failed attempt to collect payment with this payment
method.
lastName:
type: string
description: |
The customer's last name. Only applicable to direct debit payment methods.
lastTransactionDateTime:
type: string
description: |
The date and time of the most recent transaction.
format: date-time
lastTransactionStatus:
type: string
description: The status of the most recent transaction.
mandateCreationDate:
description: |
The date on which the mandate was created.
format: date
type: string
mandateId:
description: |
The mandate ID.
type: string
mandateReason:
description: |
The reason of the mandate from the gateway side.
type: string
mandateReceived:
type: string
description: |
Indicates whether the mandate is received from the gateway.
enum:
- 'Yes'
- 'No'
mandateStatus:
type: string
description: |
The status of the mandate from the gateway side.
mandateUpdateDate:
type: string
format: date
description: |
The date on which the mandate was updated.
maxConsecutivePaymentFailures:
type: integer
format: int32
description: |
The number of allowable consecutive failures Zuora attempts with the payment method before stopping.
name:
type: string
description: |
The name of the payment method.
numConsecutiveFailures:
type: integer
format: int32
description: |
The number of consecutive failed payments for this payment method. It is reset to `0` upon successful payment.
paymentMethodStatus:
type: string
description: |
The status of the payment method.
enum:
- Active
- Closed
- Scrubbed
paymentRetryWindow:
type: integer
format: int32
description: |
The retry interval setting, which prevents making a payment attempt if the last failed attempt was within the last specified number of hours.
paypalBaid:
type: string
description: |
ID of a PayPal billing agreement.
example: I-1TJ3GAGG82Y9
paypalEmail:
type: string
description: |
Email address associated with the PayPal payment method.
paypalPreapprovalKey:
type: string
description: |
The PayPal preapproval key.
paypalType:
type: string
description: |
The type of the PayPal payment method.
phone:
type: string
description: |
The phone number that the account holder registered with the bank. This
field is used for credit card validation when passing to a gateway.
postalCode:
type: string
description: |
The zip code of the customer's address. Only applicable to direct debit
payment methods.
secondTokenId:
description: |
A gateway unique identifier that replaces sensitive payment method data.
**Note:** This field is only returned for the Credit Card Reference Transaction payment type.
type: string
state:
type: string
description: |
The state of the customer's address. Only applicable to direct debit
payment methods.
streetName:
type: string
description: |
The street name of the customer's address. Only applicable to direct debit
payment methods.
streetNumber:
type: string
description: |
The street number of the customer's address. Only applicable to direct
debit payment methods.
tokenId:
type: string
description: |
A gateway unique identifier that replaces sensitive payment method data or
represents a gateway's unique customer profile. Applicable to CC Reference
Transaction payment methods.
totalNumberOfErrorPayments:
type: integer
format: int32
description: The number of error payments that used this payment method.
totalNumberOfProcessedPayments:
type: integer
format: int32
description: The number of successful payments that used this payment method.
type:
type: string
description: |
The type of the payment method. For example, `CreditCard`.
useDefaultRetryRule:
type: boolean
description: |
Indicates whether this payment method uses the default retry rules configured in the Zuora Payments settings.
methodReferenceId:
type: string
description: |
The identification reference of the custom payment method.
This field should be mapped to a field name defined in the `fields` array for the purpose of being used as a filter in reporting tools such as Payment Method Data Source Exports and Data Query.
userReferenceId:
type: string
description: |
The identification reference of the user or customer account.
This field should be mapped to a field name defined in the `fields` array for the purpose of being used as a filter in reporting tools such as Data Source Exports and Data Query.
subType:
type: string
description: |
The identification reference indicating the subtype of the custom payment method.
This field should be mapped to a field name defined in the `fields` array for the purpose of being used as a filter in reporting tools such as Data Source Exports and Data Query.
methodSpecificData:
type: string
description: |
Other method-specific data of the payment method.
cardBrand:
description: |
The card brand, such as `Visa` and `MasterCard`.
type: string
cardClass:
description: |
The type of the card.
type: string
enum:
- ChargeCard
- Credit
- Debit
- DeferredDebit
- Prepaid
cardIssuingBank:
type: string
description: |
The issuer bank of the card, such as `JPMORGAN CHASE BANK N.A.`.
cardIssuingCountry:
type: string
description: |
The issuing country code of the card, such as `US`.
cardProductType:
type: string
description: |
The product type of the card.
enum:
- Commercial_or_Corporate_Card
- Consumer_Card
account:
type: object
description: |
The account to which the payment method belongs.
additionalProperties:
type: object
description: |
Custom fields of the Payment Method object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryPaymentMethodResponse
NestedSubscriptionOnExpand:
properties:
id:
type: string
description: |
The unique identifier of the subscription.
createdById:
type: string
description: |
The unique identifier of the user who created the subscription.
createdDate:
type: string
format: date-time
description: |
The date and time when the subscription was created in the Zuora
system, in the `yyyy-mm-dd hh:mm:ss` format.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the subscription.
updatedDate:
type: string
format: date-time
description: |
The date and time when the subscription was last updated, in the `yyyy-mm-dd hh:mm:ss` format.
accountId:
type: string
description: The ID of the account associated with this subscription.
autoRenew:
type: boolean
description: |
If `true`, the subscription automatically renews at the end of the
term.
default: false
cancelledDate:
type: string
format: date
description: |
The date on which the subscription was canceled.
contractAcceptanceDate:
type: string
format: date
description: |
The date when the customer accepts the contract, in the `yyyy-mm-dd` format.
If this field is not set:
- If the `serviceActivationDate` field is not set, the value of this
field is set to be the contract effective date.
- If the `serviceActivationDate` field is set, the value of this field
is set to be the service activation date.
The billing trigger dates must follow this rule:
contractEffectiveDate <= serviceActivationDate <=
contractAcceptanceDate
contractEffectiveDate:
type: string
format: date
description: |
The date when the subscription is activated, in the `yyyy-mm-dd` format.
You must specify a Service Activation date if the Customer Acceptance
date is set. If the Customer Acceptance date is not set, the value of
the `serviceActivationDate` field defaults to be the Contract
Effective Date.
The billing trigger dates must follow this rule:
contractEffectiveDate <= serviceActivationDate <=
contractAcceptanceDate
creatorAccountId:
type: string
description: |
The ID of the account that created the subscription. This field is
automatically populated with the ID of the account that creates the
subscription.
**Note**: This field is not available for single version subscriptions.
creatorInvoiceOwnerId:
type: string
description: |
The account ID that owns the invoices associated with the subscription or the amended subscription.
**Note**: This field is not available for single version subscriptions.
currentTerm:
type: integer
format: int64
description: |
The length of the period for the current subscription term.
currentTermPeriodType:
type: string
description: |
The period type for the current subscription term.
enum:
- Month
- Year
- Day
- Week
default: Month
initialTerm:
type: integer
format: int64
description: |
The length of the period for the initial subscription term.
initialTermPeriodType:
type: string
description: |
The period type for the first subscription term.
enum:
- Month
- Year
- Day
- Week
default: Month
invoiceOwnerId:
type: string
description: |
The account ID that owns the invoices associated with the subscription.
isInvoiceSeparate:
type: boolean
default: false
description: |
Determines if the subscription is invoiced separately.
If `true`, then all charges for this subscription are collected into the subscription's own invoice.
isSingleVersioned:
type: boolean
description: |
If `true`, the subscription is a single version subscription.
name:
type: string
description: |
The name of the subscription.
notes:
type: string
description: |
Additional information about the subscription.
maxLength: 65535
originalCreatedDate:
type: string
description: |
The date when the subscription was originally created.
This value is the same as the `createdDate` value until the subscription is amended.
originalId:
type: string
description: |
The original rate plan charge ID. Only available for update
subscription.
**Note**: This field is not available for single version subscriptions.
previousSubscriptionId:
type: string
description: |
The ID of the previous subscription. This field is only available if
the subscription is a renewal subscription.
**Note**: This field is not available for single version subscriptions.
renewalSetting:
type: string
description: |
Specifies whether a termed subscription will remain `TERMED` or change to `EVERGREEN` when it is renewed.
enum:
- RENEW_WITH_SPECIFIC_TERM
- RENEW_TO_EVERGREEN
default: RENEW_WITH_SPECIFIC_TERM
renewalTerm:
type: integer
format: int64
description: |
The length of the period for the subscription renewal term.
renewalTermPeriodType:
type: string
description: |
The period type for the subscription renewal term.
enum:
- Month
- Year
- Day
- Week
default: Month
revision:
type: string
description: |
An auto-generated decimal value uniquely tagged with a subscription.
The value always contains one decimal place, for example, the revision
of a new subscription is 1.0. If a further version of the subscription
is created, the revision value will be increased by 1. Also, the
revision value is always incremental regardless of deletion of
subscription versions.
serviceActivationDate:
type: string
format: date
description: |
The date on which the services or products within a subscription have been activated and access has been provided to the customer, in the `yyyy-mm-dd` format.
status:
type: string
description: |
Subscription status.
enum:
- Draft
- Pending Activation
- Pending Acceptance
- Active
- Cancelled
- Suspended
isLatestVersion:
description: |
If `true`, the current subscription object is the latest version.
**Note**: This field is not available for single version subscriptions.
type: boolean
subscriptionEndDate:
type: string
format: date
description: |
The date when the subscription term ends, where the subscription ends
at midnight the day before.
For example, if the `subscriptionEndDate` is 12/31/2016, the
subscriptions ends at midnight (00:00:00 hours) on 12/30/2016.
This date is the same as the term end date or the cancelation date, as
appropriate.
subscriptionStartDate:
type: string
format: date
description: |
Date the subscription becomes effective.
subscriptionVersionAmendmentId:
type: string
description: |
The ID of the amendment made to this subscription version.
**Note**: This field is not available for single version subscriptions.
termEndDate:
type: string
format: date
description: |
Date the subscription term ends. If the subscription is evergreen,
this is null or is the cancellation date (if one has been set).
termStartDate:
type: string
format: date
description: |
Date the subscription term begins. If this is a renewal subscription,
this date is different from the subscription start date.
termType:
type: string
description: |
The type of the subscription term.
enum:
- TERMED
- EVERGREEN
version:
type: integer
format: int64
description: This is the subscription version automatically generated by Zuora Billing. Each order or amendment creates a new version of the subscription, which incorporates the changes made in the order or amendment.
cMRR:
type: number
description: |
Monthly recurring revenue of the subscription.
billToContactSnapshotId:
type: string
description: |
The ID of the bill-to contact snapshot.
billToContactId:
type: string
description: |
The ID of the bill-to contact for the subscription.
invoiceTemplateId:
type: string
description: |
The ID of the invoice template associated with the subscription.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request or you select **Default Template from Account** for this field during subscription creation, the value of this field is automatically set to `null` in the response body.
sequenceSetId:
description: |
The ID of the sequence set associated with the subscription.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request or you select **Default Set from Account** for this field during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
nullable: true
shipToContactId:
type: string
description: |
The ID of the ship-to contact for the subscription.
shipToContactSnapshotId:
type: string
description: |
The ID of the ship-to contact snapshot.
soldToContactId:
type: string
description: |
The ID of the sold-to contact for the subscription.
soldToContactSnapshotId:
type: string
description: |
The ID of the sold-to contact snapshot.
externallyManagedBy:
type: string
description: |
An enum field on the Subscription object to indicate the name of a
third-party store. This field is used to represent subscriptions created
through third-party stores.
enum:
- Amazon
- Apple
- Google
- Roku
lastBookingDate:
description: |
The last booking date of the subscription object. This field is
writable only when the subscription is newly created as a first
version subscription. You can override the date value when creating a
subscription through the Subscribe and Amend API or the subscription
creation UI (non-Orders). Otherwise, the default value `today` is set
per the user's timezone. The value of this field is as follows:
* For a new subscription created by the [Subscribe and Amend
APIs](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Orders_Harmonization/Orders_Migration_Guidance#Subscribe_and_Amend_APIs_to_Migrate),
this field has the value of the subscription creation date.
* For a subscription changed by an amendment, this field has the value
of the amendment booking date.
* For a subscription created or changed by an order, this field has
the value of the order date.
format: date
type: string
invoiceScheduleId:
type: string
description: |
The ID of the invoice schedule associated with the subscription.
If multiple invoice schedules are created for different terms of a
subscription, this field stores the latest invoice schedule.
**Note**: This field is available only if you have the Billing Schedule feature enabled.
cancelReason:
type: string
description: |
The reason for a subscription cancellation copied from the
`changeReason` field of a Cancel Subscription order action.
This field contains valid value only if a subscription is cancelled
through the Orders UI or API. Otherwise, the value for this field will
always be `null`.
prepayment:
type: boolean
description: |
Whether the subscription is prepaid.
currency:
description: |
The currency of the subscription.
**Note**: This field is available only if you have the Multiple Currencies feature enabled.
type: string
orderId:
description: |
The ID of the order associated with the subscription.
**Note**: This field is available only for orders that exist after the end of June 2023.
type: string
rampId:
type: string
description: |
The ID of the ramp object associated with the subscription.
**Note**: This field is available only if you have the Ramp feature enabled.
paymentTerm:
type: string
description: |
Name of the payment term associated with the account. For example,
"Net 30". The payment term determines the due dates of invoices.
quoteNumber__QT:
type: string
description: |
The unique identifier of the Quote. This field is used in Zuora data
sources to report on Subscription metrics. If the subscription originated
from Zuora Quotes, the value is populated with the value from Zuora
Quotes.
maxLength: 32
quoteType__QT:
description: |
The Quote type that represents the subscription lifecycle stage such as
New, Amendment, Renew or Cancel. This field is used in Zuora data sources
to report on Subscription metrics. If the subscription originated from
Zuora Quotes, the value is populated with the value from Zuora Quotes.
maxLength: 32
type: string
quoteBusinessType__QT:
type: string
description: |
The specific identifier for the type of business transaction the Quote
represents such as New, Upsell, Downsell, Renewal or Churn. This field is
used in Zuora data sources to report on Subscription metrics. If the
subscription originated from Zuora Quotes, the value is populated with the
value from Zuora Quotes.
maxLength: 32
opportunityName__QT:
type: string
description: |
The unique identifier of the Opportunity. This field is used in Zuora data
sources to report on Subscription metrics. If the subscription originated
from Zuora Quotes, the value is populated with the value from Zuora
Quotes.
maxLength: 100
opportunityCloseDate__QT:
type: string
format: date
cpqBundleJsonId__QT:
description: |
The Bundle product structures from Zuora Quotes if you utilize Bundling in Salesforce. Do not change the value in this field.
maxLength: 32
type: string
account:
type: object
description: |
The subscription owner account associated with the subscription.
invoiceOwner:
type: object
description: |
The invoice owner account associated with the subscription.
billToContact:
type: object
description: |
The bill-to contact who pays the billing documents for this subscription.
invoiceItems:
type: array
items:
type: object
description: |
The invoice items associated with the subscription.
ratePlans:
type: array
items:
type: object
description: |
The rate plans associated with the subscription.
additionalProperties:
type: object
description: |
Custom fields of the Subscription object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QuerySubscriptionResponse
NestedPaymentOnExpand:
properties:
id:
type: string
description: |
The unique identifier of the payment.
createdById:
type: string
description: |
The unique identifier of the user who created the payment.
createdDate:
type: string
format: date-time
description: |
The time that the payment gets created in the system, in the
`YYYY-MM-DD HH:MM:SS` format.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the payment.
updatedDate:
type: string
format: date-time
description: |
The time that the payment gets updated in the system, in the
`YYYY-MM-DD HH:MM:SS` format.
accountId:
description: |
The ID of the customer account that the payment is for.
type: string
accountingCode:
type: string
description: |
The accounting code for the charge. Accounting codes group
transactions that contain similar accounting attributes.
amount:
description: |
The total amount of the payment.
format: double
type: number
appliedAmount:
description: |
The applied amount of the payment.
format: double
type: number
authTransactionId:
description: |
The authorization transaction ID from the payment gateway.
type: string
appliedCreditBalanceAmount:
type: number
description: |
The amount of the payment to apply to a credit balance.
bankIdentificationNumber:
type: string
description: |
The first six or eight digits of the credit card or debit card used for the payment, when applicable.
Use this field to reconcile payments between the gateway and merchant banks.
cancelledOn:
type: string
description: |
The date when the payment was canceled.
format: date-time
comment:
type: string
description: |
Comments about the payment.
nullable: true
currency:
description: |
When Standalone Payment is not enabled, the `currency` of the payment must be the same as the payment currency defined in the customer account settings through Zuora UI.
When Standalone Payment is enabled and `standalone` is `true`, the `currency` of the standalone payment can be different from the payment currency defined in the customer account settings. The amount will not be summed up to the account balance or key metrics regardless of currency.
type: string
example: USD
effectiveDate:
type: string
format: date
description: |
The date and time when the payment takes effect, in `yyyy-mm-dd hh:mm:ss` format.
gatewayOrderId:
description: |
A merchant-specified natural key value that can be passed to the electronic payment gateway when a payment is created.
type: string
gatewayReconciliationReason:
description: |
The reason of gateway reconciliation.
type: string
gatewayReconciliationStatus:
description: |
The status of gateway reconciliation.
type: string
gatewayResponse:
description: |
The message returned from the payment gateway for the payment. This message is gateway-dependent.
type: string
gatewayResponseCode:
description: |
The code returned from the payment gateway for the payment. This code is gateway-dependent.
type: string
gatewayState:
description: |
The status of the payment in the gateway; use for reconciliation.
enum:
- MarkedForSubmission
- Submitted
- Settled
- NotSubmitted
- FailedToSettle
type: string
gatewayTransactionState:
type: string
isStandalone:
type: boolean
description: |
Indicates whether the payment is a standalone payment. A standalone
payment is a payment that is not associated with any invoice or
subscription.
markedForSubmissionOn:
type: string
format: date-time
description: |
The date and time when a charge was marked and waiting for batch
submission to the payment process, in `yyyy-mm-dd hh:mm:ss` format.
paymentMethodId:
type: string
description: |
The unique ID of the payment method that the customer used to make the payment.
paymentMethodSnapshotId:
type: string
description: |
The unique ID of the payment method snapshot which is a copy of the particular Payment Method used in a transaction.
paymentOptionId:
type: string
description: |
ID of the paymentOption object, which describe the transactional level rules for processing payments.
paymentNumber:
type: string
description: |
The unique identification number of a payment.
example: P-00000028.
payoutId:
type: string
description: |
The payout ID of the payment from the gateway side.
prepayment:
description: |
Indicates whether the payment is used as a reserved payment. See [Prepaid Cash with Drawdown](https://knowledgecenter.zuora.com/Zuora_Billing/Billing_and_Invoicing/JA_Advanced_Consumption_Billing/Prepaid_Cash_with_Drawdown) for more information.
type: boolean
referencedPaymentID:
type: string
description: |
The ID of a referenced payment.
referenceId:
description: |
The transaction ID returned by the payment gateway. Use this field to reconcile payments between your gateway and Zuora Payments.
type: string
refundAmount:
type: number
description: |
The amount of the payment that is refunded.
format: double
secondPaymentReferenceId:
type: string
description: |
The transaction ID returned by the payment gateway if there is an additional transaction for the payment. Use this field to reconcile payments between your gateway and Zuora Payments.
settledOn:
type: string
format: date-time
description: |
The date and time when the payment was settled in the payment processor, in `yyyy-mm-dd hh:mm:ss` format. This field is used by the Spectrum gateway only and not applicable to other gateways.
softDescriptor:
type: string
description: |
A payment gateway-specific field that maps to Zuora for the gateways, Orbital, Vantiv and Verifi.
softDescriptorPhone:
type: string
description: |
A payment gateway-specific field that maps to Zuora for the gateways, Orbital, Vantiv and Verifi.
source:
type: string
description: |
Indicates how the payment was created, whether through API, manually, import, or payment run.
enum:
- PaymentRun
- Import
- Manually
- API
sourceName:
type: string
description: |
Name of the source. It can be a payment run number or a file name.
status:
description: |
The status of the payment.
enum:
- Draft
- Processing
- Processed
- Error
- Canceled
- Posted
type: string
submittedOn:
description: |
The date and time when the payment was submitted, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
type:
description: |
The type of the payment.
enum:
- External
- Electronic
type: string
transferredToAccounting:
description: |
Whether the payment was transferred to an external accounting system. Use this field for integration with accounting systems, such as NetSuite.
enum:
- Processing
- 'Yes'
- 'No'
- Error
- Ignore
type: string
transactionSource:
type: string
description: |
Payment transaction source used to differentiate the transaction source in Stored Credential Transaction framework.
- `C_Unscheduled`: Cardholder-initiated transaction (CIT) that does not occur on scheduled or regularly occurring dates.
- `M_Recurring`: Merchant-initiated transaction (MIT) that occurs at regular intervals.
- `M_Unscheduled`: Merchant-initiated transaction (MIT) that does not occur on scheduled or regularly occurring dates.
- `M_MOTO`: Mail Order Telephone Order (MOTO) payment transaction. This option is only available for credit card payments on Stripe v2. See [Overview of Stripe payment gateway integration](https://knowledgecenter.zuora.com/Zuora_Collect/Payment_gateway_integrations/Supported_payment_gateways/Stripe_Payment_Gateway/A_Overview_of_Stripe_payment_gateway_integration) for more information.
enum:
- C_Unscheduled
- M_Recurring
- M_Unscheduled
- M_MOTO
unappliedAmount:
type: number
description: |
The unapplied amount of the payment.
lastEmailDateTime:
type: string
description: |
The date and time when the last email was sent to the customer for the payment.
gateway:
type: string
description: |
Name of the gateway instance that processes the payment.
account:
type: object
description: |
The account associated with the payment.
paymentMethod:
type: object
description: |
The payment method used for this payment.
paymentApplications:
type: array
items:
type: object
description: |
The payment applications associated with the payment.
additionalProperties:
type: object
description: |
Custom fields of the Payment object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryPaymentResponse
NestedRefundOnExpand:
properties:
id:
type: string
description: |
The unique identifier of the refund.
createdById:
type: string
description: |
The unique identifier of the user who created the refund.
createdDate:
type: string
format: date-time
description: |
The date and time when the refund was created.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the refund.
updatedDate:
type: string
format: date-time
description: |
The date and time when the refund was last updated.
accountId:
description: |
The ID of the account associated with this refund. Zuora associates the refund automatically with the account from the associated payment or credit memo.
type: string
amount:
description: |
The total amount of the refund.
format: double
type: number
cancelledOn:
description: |
The date and time when the refund was cancelled, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
comment:
description: |
Comments about the refund.
type: string
nullable: true
paymentMethodSnapshotId:
type: string
description: |
The unique ID of the payment method snapshot which is a copy of the particular payment method used in a transaction.
accountingCode:
type: string
description: |
The accounting code that maps to this refund transaction in your accounting
system.
currency:
type: string
description: |
The currency of the refund.
gatewayReconciliationReason:
description: |
The reason of gateway reconciliation.
type: string
gatewayReconciliationStatus:
description: |
The status of gateway reconciliation.
type: string
gatewayResponse:
description: |
The message returned from the payment gateway for the refund. This
message is gateway-dependent.
type: string
gatewayResponseCode:
description: |
The code returned from the payment gateway for the refund. This code
is gateway-dependent.
type: string
gatewayState:
description: |
The status of the refund in the gateway.
enum:
- MarkedForSubmission
- Submitted
- Settled
- NotSubmitted
- FailedToSettle
type: string
markedForSubmissionOn:
description: |
The date and time when a refund was marked and waiting for batch submission to the payment process, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
methodType:
description: |
How an external refund was issued to a customer.
enum:
- ACH
- Cash
- Check
- CreditCard
- PayPal
- WireTransfer
- DebitCard
- CreditCardReferenceTransaction
- BankTransfer
- Other
type: string
paymentMethodId:
type: string
description: |
The unique ID of the payment method that the customer used to make the refund.
payoutId:
type: string
description: |
The payout ID of the refund from the gateway side.
reasonCode:
type: string
description: |
A code identifying the reason for the transaction.
refundNumber:
type: string
description: |
The number of the refund.
referenceID:
description: |
The transaction ID returned by the payment gateway for an electronic refund. Use this field to reconcile refunds between your gateway and Zuora Payments.
type: string
refundDate:
description: |
The date when the refund takes effect, in `yyyy-mm-dd` format. For example, 2017-03-01.
format: date
type: string
refundTransactionTime:
description: |
The date and time when the refund was issued, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
sourceType:
type: string
description: |
Specifies whether the refund is a refund payment or a credit balance.
enum:
- Payment
- CreditBalance
- CreditMemo
secondRefundReferenceId:
description: |
The transaction ID returned by the payment gateway if there is an additional transaction for the refund. Use this field to reconcile payments between your gateway and Zuora Payments.
type: string
settledOn:
description: |
The date and time when the refund was settled in the payment processor, in `yyyy-mm-dd hh:mm:ss` format. This field is used by the Spectrum gateway only and not applicable to other gateways.
format: date-time
type: string
softDescriptor:
description: |
A payment gateway-specific field that maps Zuora to other gateways.
type: string
softDescriptorPhone:
description: |
A payment gateway-specific field that maps Zuora to other gateways.
type: string
status:
description: |
The status of the refund.
enum:
- Processed
- Canceled
- Error
- Processing
type: string
submittedOn:
type: string
description: |
The date and time when the refund was submitted, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
transferredToAccounting:
description: |
Whether the refund was transferred to an external accounting system. Use this field for integration with accounting systems, such as NetSuite.
enum:
- Processing
- 'Yes'
- 'No'
- Error
- Ignore
type: string
type:
type: string
description: |
The type of the refund.
enum:
- External
- Electronic
associatedTransactionNumber:
type: string
description: |
The number of the associated transactions, such as payments.
gateway:
type: string
description: |
The gateway that processed the original payment. A gateway is an online service provider that connects an online shopping cart to a payment processor.
Zuora uses this same gateway for the corresponding refund.
If this payment gateway is no longer active, then the electronic refund fails.
account:
type: object
description: |
The account associated with the refund.
paymentMethod:
type: object
description: |
The payment method to which the refund is returned.
refundApplications:
type: array
items:
type: object
description: |
The refund applications associated with the refund.
additionalProperties:
type: object
description: |
Custom fields of the Refund object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryRefundResponse
NestedCreditMemoOnExpand:
properties:
id:
type: string
description: |
The unique identifier of the credit memo.
createdById:
type: string
description: |
The unique identifier of the user who created the credit memo.
createdDate:
type: string
format: date-time
description: |
The date and time when the credit memo was created.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the credit memo.
updatedDate:
type: string
format: date-time
description: |
The date and time when the credit memo was last updated.
appliedAmount:
description: |
The applied amount of the credit memo.
format: double
type: number
balance:
type: number
description: |
The remaining balance of credit memo.
billToContactId:
description: |
The ID of the bill-to contact associated with the credit memo.
The value of this field is `null` if you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled.
type: string
billToContactSnapshotId:
description: |
The ID of the bill-to contact snapshot associated with the credit memo.
The value of this field is `null` if the bill rule [Preserve snapshot of bill-to and sold-to contacts when billing documents are posted](https://knowledgecenter.zuora.com/Zuora_Billing/Billing_and_Invoicing/Billing_Settings/Define_Billing_Rules#Preserve_snapshot_of_bill-to_and_sold-to_contacts_when_billing_documents_are_posted) is disabled.
type: string
cancelledById:
description: |
The ID of the Zuora user who cancelled the credit memo.
type: string
nullable: true
cancelledOn:
description: |
The date and time when the credit memo was cancelled, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
nullable: true
comment:
description: |
Comments about the credit memo.
type: string
nullable: true
currency:
description: |
The currency of the credit memo.
**Note:** By default, the currency on a billing document matches the default currency set on the associated account.
However, Zuora now offers a Multiple Currencies feature to support different currencies for billing documents, allowing flexibility beyond the account-level currency.
For more information, see Multiple Currency.
type: string
nullable: true
discountAmount:
type: number
description: |
The amount of the discount on the credit memo.
einvoiceErrorCode:
description: |
The error code returned when the e-invoice file status is `Failed`. This code can either be a Zuora-generated error code or one returned by a third-party e-invoicing service provider.
**Note**: This field is available only if you have the E-Invoicing feature in **Early Adopter** phase enabled.
type: string
einvoiceErrorMessage:
description: |
The error message returned when the e-invoice file status is `Failed`. This message can either be a Zuora-generated error message or one returned by a third-party e-invoicing service provider.
**Note**: This field is available only if you have the E-Invoicing feature in **Early Adopter** phase enabled.
type: string
einvoiceFileId:
description: |
The ID of the e-invoice file generated for the credit memo.
**Note**: This field is available only if you have the E-Invoicing feature in **Early Adopter** phase enabled.
type: string
einvoiceStatus:
description: |
The status of the e-invoice file generation for the credit memo.
- If e-invoice file generation succeeds, this field is either `Generated` or `Success`, and both the error code and message are empty, and the `eInvoiceFileId` field stores the ID of the generated e-invoice file.
- If a failure occurs during e-invoice file generation, this field is `Failed` and an error code and an error message are returned respectively in the `einvoiceErrorCode` and `einvoiceErrorMessage` fields.
- If e-invoice file generation conditionally succeeds, this field is `ConditionalSuccess` and an error code and an error message are returned respectively in the `einvoiceErrorCode` and `einvoiceErrorMessage` fields.
- If the e-invoice file has been approved by the tax authority, this field is `ApprovedByAuthority`. The next status will be either `Success` or `Rejected`.
- If the e-invoice file has been rejected by the government, this field is `Rejected`. You cannot resend this e-invoice; you must create a new invoice instead.
**Note**: This field is available only if you have the E-Invoicing feature in **Early Adopter** phase enabled.
enum:
- Processing
- Generated
- Success
- Failed
- ConditionalSuccess
- ApprovedByAuthority
- Rejected
type: string
excludeFromAutoApplyRules:
description: |
Whether the credit memo is excluded from the rule of automatically applying credit memos to invoices.
type: boolean
exchangeRateDate:
type: string
format: date
description: |
The date of the exchange rate used. The date is in `yyyy-mm-dd` format.
Corresponds to the value specified in the Provider Exchange Rate Date column in the Import Foreign Exchange Rates template when you uploaded the rates through the Mass Updater.
autoApplyUponPosting:
description: |
Whether the credit memo automatically applies to the invoice upon
posting.
type: boolean
memoDate:
type: string
format: date
description: |
The date when the credit memo takes effect, in `yyyy-mm-dd` format.
For example, `2024-01-01`.
memoNumber:
description: |
The unique identification number of the credit memo.
type: string
postedById:
description: |
The ID of the Zuora user who posted the credit memo.
type: string
postedOn:
description: |
The date and time when the credit memo was posted, in
`yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
reasonCode:
description: |
A code identifying the reason for the transaction. The value
must be an existing reason code or empty.
type: string
refundAmount:
description: |
The amount of the refund on the credit memo.
format: double
type: number
revenueImpacting:
description: |
Indicates whether this write off operation impacts the revenue. If `revenueImpacting` = `Yes`, the deferred revenue accounting code will be automatically selected from the associated invoice.
If `revenueImpacting` = `No`, users can select an accounting code such as bad-debt expense accounting code for the write off operation.
enum:
- 'Yes'
- 'No'
default: 'Yes'
type: string
reversed:
description: |
Whether the credit memo is reversed.
type: boolean
sequenceSetId:
description: |
The ID of the sequence set associated with the credit memo.
The value of this field is `null` if you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled.
type: string
nullable: true
source:
description: |
The source of the credit memo.
Possible values:
- `BillRun`: The credit memo is generated by a bill run.
- `API`: The credit memo is created by calling the [Invoice and collect](https://developer.zuora.com/api-references/api/operation/POST_TransactionInvoicePayment) operation, or by calling the Orders, Order Line Items, or Fulfillments API operations.
- `ApiSubscribe`: The credit memo is created by calling the [Create subscription](https://developer.zuora.com/api-references/api/operation/POST_Subscription) and [Create account](https://developer.zuora.com/api-references/api/operation/POST_Account) operation.
- `ApiAmend`: The credit memo is created by calling the [Update subscription](https://developer.zuora.com/api-references/api/operation/PUT_Subscription) operation.
- `AdhocFromPrpc`: The credit memo is created from a product rate plan charge through the Zuora UI or by calling the [Create a credit memo from a charge](https://developer.zuora.com/api-references/api/operation/POST_CreditMemoFromPrpc) operation.
- `AdhocFromInvoice`: The credit memo is created from an invoice or created by reversing an invoice. You can create a credit memo from an invoice through the Zuora UI or by calling the [Create credit memo from invoice](https://developer.zuora.com/api-references/api/operation/POST_CreditMemoFromInvoice) operation. You can create a credit memo by reversing an invoice through the Zuora UI or by calling the [Reverse invoice](https://developer.zuora.com/api-references/api/operation/PUT_ReverseInvoice) operation.
type: string
enum:
- BillRun
- API
- ApiSubscribe
- ApiAmend
- AdhocFromPrpc
- AdhocFromInvoice
sourceId:
description: |
The ID of the credit memo source.
If a credit memo is generated from a bill run, the value is the
number of the corresponding bill run. Otherwise, the value is
`null`.
type: string
sourceType:
description: |
The type of the credit memo source.
enum:
- Subscription
- Standalone
- Invoice
- Order
- CreditMemo
- Consolidation
type: string
status:
description: |
The status of the credit memo.
enum:
- Draft
- Posted
- Canceled
- Error
- PendingForTax
- Generating
- CancelInProgress
type: string
targetDate:
description: |
The target date for the credit memo, in `yyyy-mm-dd` format. For example, `2024-01-01`.
format: date
type: string
taxAmount:
description: |
The amount of taxation.
format: double
type: number
taxMessage:
description: |
The message about the status of tax calculation related to the credit memo. If tax calculation fails in one credit memo, this field displays the reason for the failure.
type: string
nullable: true
taxStatus:
description: |
The status of tax calculation related to the credit memo.
**Note**: This field is only applicable to tax calculation by third-party tax engines. Also, the `Voided` status indicates that the tax transaction is successfully canceled on the tax vendor's side. If a tax transaction was successfully committed to the third-party tax engine but the invoice failed to post, Zuora automatically detects the issue and voids the tax transaction on the vendor's side.
enum:
- Complete
- Error
- UnknownError
- DuplicateDoc
- InvalidRequest
- InvalidResponse
- TaxEngineError
- ConcurrentModify
- InternalServerError
- TaxCodeTemplateError
- Voided
type: string
shipToContactSnapshotId:
description: |
The ID of the ship-to contact snapshot associated with the
credit memo.
**Note**: If you have the Flexible Billing Attributes feature
disabled, the value of this field is `null`.
type: string
soldToContactSnapshotId:
description: |
The ID of the sold-to contact snapshot associated with the
credit memo.
**Note**: If you have the Flexible Billing Attributes feature
disabled, the value of this field is `null`.
type: string
taxAutoCalculation:
default: true
description: |
Whether to automatically calculate taxes in the credit memo.
type: boolean
totalAmount:
type: number
format: double
description: |
The total amount of the credit memo, including taxes.
totalAmountWithoutTax:
type: number
format: double
description: |
The total amount of the credit memo, excluding taxes.
totalTaxExemptAmount:
description: |
The calculated tax amount excluded due to the exemption.
format: double
type: number
transferredToAccounting:
description: |
Whether the credit memo was transferred to an external
accounting system. This field is used for integration with
accounting systems such as NetSuite.
enum:
- Processing
- 'Yes'
- 'No'
- Error
- Ignore
type: string
invoiceId:
description: |
The ID of a referred invoice.
type: string
accountId:
description: |
The ID of the customer account associated with the credit memo.
type: string
account:
type: object
description: |
The account associated with the credit memo.
billToContact:
type: object
description: |
The bill-to contact on the account.
creditMemoItems:
type: array
items:
type: object
description: |
The credit memo items on the current credit memo.
creditMemoApplications:
type: array
items:
type: object
description: |
The credit memo applications associated with the current credit memo.
additionalProperties:
type: object
description: |
Custom fields of the Credit Memo object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryCreditMemoResponse
NestedDebitMemoOnExpand:
properties:
id:
type: string
description: |
The unique identifier of the debit memo.
createdById:
type: string
description: |
The unique identifier of the user who created the debit memo.
createdDate:
type: string
format: date-time
description: |
The date and time when the debit memo was created.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the debit memo.
updatedDate:
type: string
format: date-time
description: |
The date and time when the debit memo was last updated.
autoPay:
description: |
Whether debit memos are automatically picked up for processing in the
corresponding payment run.
By default, debit memos are automatically picked up for processing in
the corresponding payment run.
type: boolean
creditMemoId:
type: string
description: |
The ID of the credit memo from which the debit memo was created.
nullable: true
balance:
type: number
description: |
The remaining balance of debit memo.
billToContactId:
description: |
The ID of the bill-to contact associated with the debit memo.
The value of this field is `null` if you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled.
type: string
billToContactSnapshotId:
description: |
The ID of the bill-to contact snapshot associated with the debit memo.
The value of this field is `null` if the bill rule [Preserve snapshot of bill-to and sold-to contacts when billing documents are posted](https://knowledgecenter.zuora.com/Zuora_Billing/Billing_and_Invoicing/Billing_Settings/Define_Billing_Rules#Preserve_snapshot_of_bill-to_and_sold-to_contacts_when_billing_documents_are_posted) is disabled.
type: string
cancelledById:
description: |
The ID of the Zuora user who cancelled the debit memo.
type: string
nullable: true
cancelledOn:
description: |
The date and time when the debit memo was cancelled, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
nullable: true
comments:
description: |
Comments about the debit memo.
type: string
currency:
description: |
The currency of the debit memo.
**Note:** By default, the currency on a billing document matches the default currency set on the associated account.
However, Zuora now offers a Multiple Currencies feature to support different currencies for billing documents, allowing flexibility beyond the account-level currency.
For more information, see Multiple Currency.
type: string
nullable: true
discountAmount:
type: number
description: |
The amount of the discount on the debit memo.
dueDate:
type: string
format: date
description: |
The date by which the payment for the debit memo is due, in
`yyyy-mm-dd` format.
einvoiceErrorCode:
description: |
The error code returned when the e-invoice file status is `Failed`. This code can either be a Zuora-generated error code or one returned by a third-party e-invoicing service provider.
**Note**: This field is available only if you have the E-Invoicing feature in **Early Adopter** phase enabled.
type: string
einvoiceErrorMessage:
description: |
The error message returned when the e-invoice file status is `Failed`. This message can either be a Zuora-generated error message or one returned by a third-party e-invoicing service provider.
**Note**: This field is available only if you have the E-Invoicing feature in **Early Adopter** phase enabled.
type: string
einvoiceFileId:
description: |
The ID of the e-invoice file generated for the debit memo.
**Note**: This field is available only if you have the E-Invoicing feature in **Early Adopter** phase enabled.
type: string
einvoiceStatus:
description: |
The status of the e-invoice file generation for the credit memo.
- If e-invoice file generation succeeds, this field is either `Generated` or `Success`, and both the error code and message are empty, and the `eInvoiceFileId` field stores the ID of the generated e-invoice file.
- If a failure occurs during e-invoice file generation, this field is `Failed` and an error code and an error message are returned respectively in the `einvoiceErrorCode` and `einvoiceErrorMessage` fields.
- If e-invoice file generation conditionally succeeds, this field is `ConditionalSuccess` and an error code and an error message are returned respectively in the `einvoiceErrorCode` and `einvoiceErrorMessage` fields.
- If the e-invoice file has been approved by the tax authority, this field is `ApprovedByAuthority`. The next status will be either `Success` or `Rejected`.
- If the e-invoice file has been rejected by the government, this field is `Rejected`. You cannot resend this e-invoice; you must create a new invoice instead.
**Note**: This field is available only if you have the E-Invoicing feature in **Early Adopter** phase enabled.
enum:
- Processing
- Generated
- Success
- Failed
- ConditionalSuccess
- ApprovedByAuthority
- Rejected
type: string
exchangeRateDate:
type: string
format: date
description: |
The date of the exchange rate used. The date is in `yyyy-mm-dd` format.
Corresponds to the value specified in the Provider Exchange Rate Date column in the Import Foreign Exchange Rates template when you uploaded the rates through the Mass Updater.
memoDate:
type: string
format: date
description: |
The date when the debit memo takes effect, in `yyyy-mm-dd` format.
For example, `2024-01-01`.
memoNumber:
description: |
The unique identification number of the debit memo.
type: string
postedById:
description: |
The ID of the Zuora user who posted the debit memo.
type: string
postedOn:
description: |
The date and time when the debit memo was posted, in
`yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
reasonCode:
description: |
A code identifying the reason for the transaction. The value
must be an existing reason code or empty.
type: string
sequenceSetId:
description: |
The ID of the sequence set associated with the debit memo.
The value of this field is `null` if you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled.
type: string
nullable: true
source:
description: |
The source of the debit memo.
Possible values:
- `BillRun`: The debit memo is generated by a bill run.
- `API`
- `ApiSubscribe`: The debit memo is created by calling the [Create subscription](https://developer.zuora.com/api-references/api/operation/POST_Subscription) and [Create account](https://developer.zuora.com/api-references/api/operation/POST_Account) operation.
- `ApiAmend`: The debit memo is created by calling the [Update subscription](https://developer.zuora.com/api-references/api/operation/PUT_Subscription) operation.
- `AdhocFromPrpc`: The debit memo is created from a product rate plan charge through the Zuora UI or by calling the [Create a debit memo from a charge](https://developer.zuora.com/api-references/api/operation/POST_DebitMemoFromPrpc/) operation.
- `AdhocFromInvoice`: The debit memo is created from an invoice or created by reversing an invoice. You can create a debit memo from an invoice through the Zuora UI or by calling the [Create a debit memo from an invoice](https://developer.zuora.com/api-references/api/operation/POST_DebitMemoFromInvoice/) operation.
type: string
enum:
- BillRun
- API
- ApiSubscribe
- ApiAmend
- AdhocFromPrpc
- AdhocFromInvoice
sourceId:
description: |
The ID of the debit memo source.
If a debit memo is generated from a bill run, the value is the
number of the corresponding bill run. Otherwise, the value is
`null`.
type: string
sourceType:
description: |
The type of the debit memo source.
enum:
- Subscription
- Standalone
- Order
- Consolidation
- Invoice
- CreditMemo
type: string
status:
description: |
The status of the debit memo.
enum:
- Draft
- Posted
- Canceled
- Error
- PendingForTax
- Generating
- CancelInProgress
type: string
targetDate:
description: |
The target date for the debit memo, in `yyyy-mm-dd` format. For example, `2024-01-01`.
format: date
type: string
taxAmount:
description: |
The amount of taxation.
format: double
type: number
taxMessage:
description: |
The message about the status of tax calculation related to the
debit memo. If tax calculation fails in one debit memo, this
field displays the reason for the failure.
type: string
nullable: true
taxStatus:
description: |
The status of tax calculation related to the debit memo.
**Note**: This field is only applicable to tax calculation by
third-party tax engines. Also, the `Voided` status indicates that the tax transaction is successfully canceled on the tax vendor's side.
If a tax transaction was successfully committed to the third-party tax engine but the invoice failed to post, Zuora automatically detects
the issue and voids the tax transaction on the vendor's side.
enum:
- Complete
- Error
- UnknownError
- DuplicateDoc
- InvalidRequest
- InvalidResponse
- TaxEngineError
- ConcurrentModify
- InternalServerError
- TaxCodeTemplateError
- Voided
type: string
shipToContactSnapshotId:
description: |
The ID of the ship-to contact snapshot associated with the
debit memo.
**Note**: If you have the Flexible Billing Attributes feature
disabled, the value of this field is `null`.
type: string
soldToContactSnapshotId:
description: |
The ID of the sold-to contact snapshot associated with the
debit memo.
**Note**: If you have the Flexible Billing Attributes feature
disabled, the value of this field is `null`.
type: string
taxAutoCalculation:
default: true
description: |
Whether to automatically calculate taxes in the debit memo.
type: boolean
totalAmount:
type: number
format: double
description: |
The total amount of the debit memo, including taxes.
totalAmountWithoutTax:
type: number
format: double
description: |
The total amount of the debit memo, excluding taxes.
totalTaxExemptAmount:
description: |
The calculated tax amount excluded due to the exemption.
format: double
type: number
transferredToAccounting:
description: |
Whether the debit memo was transferred to an external
accounting system. This field is used for integration with
accounting systems such as NetSuite.
enum:
- Processing
- 'Yes'
- 'No'
- Error
- Ignore
type: string
invoiceId:
description: |
The ID of a referred invoice.
type: string
accountId:
description: |
The ID of the customer account associated with the debit memo.
type: string
paymentTerm:
type: string
description: |
The name of the payment term assoicated with the debit memo.
The value of this field is `null` if you have the [Flexible Billing
Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes)
feature disabled.
account:
type: object
description: |
The account associated with the debit memo.
billToContact:
type: object
description: |
The bill-to contact associated with the debit memo.
debitMemoItems:
type: array
items:
type: object
description: |
The debit memo items associated with the debit memo.
additionalProperties:
type: object
description: |
Custom fields of the Debit Memo object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryDebitMemoResponse
NestedInvoiceOnExpand:
properties:
id:
type: string
description: |
The unique identifier of the invoice.
createdById:
type: string
description: |
The unique identifier of the user who created the invoice.
createdDate:
type: string
format: date-time
description: |
The time that the invoice gets created in the system, in the
`YYYY-MM-DD HH:MM:SS` format.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the invoice.
updatedDate:
type: string
format: date-time
description: |
The time that the invoice gets updated in the system, in the
`YYYY-MM-DD HH:MM:SS` format.
accountId:
description: |
The ID of the customer account associated with the invoice.
type: string
adjustmentAmount:
description: |
The amount of the invoice adjustments associated with the invoice.
format: double
type: number
amount:
description: |
The total amount of the invoice.
format: double
type: number
amountWithoutTax:
description: |
The invoice amount excluding tax.
format: double
type: number
autoPay:
description: |
Whether invoices are automatically picked up for processing in the corresponding payment run.
type: boolean
balance:
description: |
The remaining balance of the invoice after all payments, adjustments, and refunds are applied.
type: number
format: double
billToContactId:
description: |
The ID of the bill-to contact associated with the invoice.
type: string
billToContactSnapshotId:
description: |
The ID of the bill-to contact snapshot associated with the invoice.
type: string
comments:
type: string
description: |
Comments about the invoice.
creditBalanceAdjustmentAmount:
description: |
The currency amount of the adjustment applied to the customer's credit balance.
**Note:** This field is only available if you have the Credit Balance feature enabled and the Invoice Settlement feature disabled.
format: double
type: number
creditMemoAmount:
description: |
The currency amount of all credit memos applied to this invoice.
**Note:** This field is only available if you have [Invoice Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement) 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.
format: double
type: number
currency:
description: |
The currency of the invoice.
**Note:** By default, the currency on a billing document matches the default currency set on the associated account.
However, Zuora now offers a Multiple Currencies feature to support different currencies for billing documents, allowing flexibility beyond the account-level currency.
For more information, see Multiple Currency.
nullable: true
type: string
dueDate:
type: string
format: date
description: |
The date by which the payment for this invoice is due, in `yyyy-mm-dd` format.
includesOneTime:
description: |
Specifies whether the invoice includes one-time charges.
type: boolean
includesRecurring:
description: |
Specifies whether the invoice includes recurring charges.
type: boolean
includesUsage:
description: |
Specifies whether the invoice includes usage charges.
type: boolean
invoiceDate:
description: |
The date that appears on the invoice being created.
format: date
type: string
invoiceNumber:
description: |
The unique identification number of the invoice.
type: string
lastEmailSentDate:
description: |
The date when the invoice was last emailed.
type: string
organizationId:
type: string
description: |
ID of the organization this object belongs to.
paymentAmount:
description: |
The amount of payments applied to the invoice.
format: double
type: number
postedBy:
description: |
The user ID of the person who moved the invoice to Posted status.
type: string
postedDate:
description: |
The date when the invoice was posted.
format: date-time
type: string
refundAmount:
description: |
Specifies the amount of a refund that was applied against an earlier payment on the invoice.
format: double
type: number
sequenceSetId:
description: |
The ID of the sequence set associated with the invoice.
type: string
communicationProfileId:
description: |
The ID of the communication profile associated with the invoice.
type: string
nullable: true
shipToContactId:
description: |
The ID of the ship-to contact associated with the invoice.
type: string
shipToContactSnapshotId:
description: |
The ID of the ship-to contact snapshot associated with the invoice.
type: string
soldToContactId:
description: |
The ID of the sold-to contact associated with the invoice.
type: string
soldToContactSnapshotId:
description: |
The ID of the sold-to contact snapshot associated with the invoice.
type: string
source:
description: |
The source of the invoice.
enum:
- BillRun
- API
- ApiSubscribe
- ApiAmend
type: string
sourceId:
description: |
The ID of the invoice source.
If an invoice is generated from a bill run, the value is the number of the corresponding bill run.Otherwise, the value is `null`.
type: string
reversed:
type: boolean
description: |
Whether the invoice is reversed.
sourceType:
description: |
The type of the invoice source.
enum:
- Subscription
- Standalone
- Order
- Consolidation
type: string
status:
description: |
The status of the invoice.
enum:
- Draft
- Posted
type: string
targetDate:
description: |
This date is used to determine which charges are to be billed. All charges that are to be billed on this date or prior will be included in this bill run.
format: date
type: string
taxAmount:
description: |
The amount of taxation.
format: double
type: number
taxExemptAmount:
description: |
The calculated tax amount excluded due to the exemption.
format: double
type: number
taxMessage:
description: |
The message that the tax engine return if it calculates the taxes of this invoice fails.
type: string
nullable: true
taxStatus:
description: |
The status that the tax engine return after it calculates the taxes of this invoice.
**Note:** The `Voided` status indicates that the tax transaction is successfully canceled on the tax vendor's side. If a tax transaction was successfully committed to the third-party tax engine but the invoice failed to post, Zuora automatically detects the issue and voids the tax transaction on the vendor's side.
enum:
- Complete
- Error
- UnknownError
- DuplicateDoc
- InvalidRequest
- InvalidResponse
- TaxEngineError
- ConcurrentModify
- InternalServerError
- TaxCodeTemplateError
- Voided
type: string
templateId:
description: |
The ID of the invoice template.
- If you have the Flexible Billing Attributes feature enabled, the value of this field depends on the configuration of the invoice template.
- If you specify an invoice template at the subscription level, the value of this field is automatically populated from the corresponding subscription.
- If you do not specify any invoice template at the subscription level, the value of this field is automatically populated from the corresponding account.
- If you have the Flexible Billing Attributes feature disabled, the value of this field is `null`.
type: string
transferredToAccounting:
description: |
Whether the invoice was transferred to an external accounting system.
enum:
- Processing
- Error
- Ignore
- 'Yes'
- 'No'
type: string
eInvoiceStatus:
description: |
It could be Processing, RetrieveTimeOut, Generated, Success, ConditionalSuccess, ApprovedByAuthority, Failed, or Rejected. If it’s Failed, it will have an error code and message. If it’s Generated or Success, both error code and message are empty, and eInvoiceFileId stores the file id of e-invoice.
enum:
- Processing
- RetrieveTimeOut
- Generated
- Success
- Failed
- ConditionalSuccess
- ApprovedByAuthority
- Rejected
type: string
eInvoiceFileId:
type: string
description: |
The ID of the e-invoice file.
eInvoiceErrorCode:
type: string
description: |
The error code when status is `Failed`. This code can either be a Zuora-generated error code or one returned by a third-party e-invoice vendor.
eInvoiceErrorMessage:
type: string
description: |
The error message when status is "Failed". This message can either be a Zuora-generated error code or one returned by a third-party e-invoice vendor.
paymentLink:
type: string
description: |
A link to the Payment Link page where the customer can pay the invoice.
The link is generated only if the invoice is posted after enabling the Payment Link feature on your tenant.
**Note**: The Payment Link feature is in the Early Adopter phase.
You can enable the Payment Link feature through a self-service configuration in the **Manage Features** setting for Zuora Payments.
paymentTerm:
type: string
description: |
The payment term associated with the invoice. For
example, `Net 30`. The payment term determines the due dates of
invoices.
account:
type: object
description: |
The account associated with the invoice.
billToContact:
type: object
description: |
The bill-to contact who pays the invoice.
additionalProperties:
type: object
description: |
Custom fields of the Invoice object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryInvoiceResponse
NestedUsageOnExpand:
properties:
id:
type: string
description: |
The unique identifier of the usage.
createdById:
type: string
description: |
The unique identifier of the user who created the usage.
createdDate:
type: string
format: date-time
description: |
The date and time when the usage was created.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the usage.
updatedDate:
type: string
format: date-time
description: |
The date and time when the usage was last updated.
accountId:
type: string
description: |
The ID of the customer account associated with the usage.
accountNumber:
type: string
description: |
The number of the customer account associated with the usage.
ratePlanChargeId:
type: string
description: |
ID of the rate plan charge that pays for this usage.
endDateTime:
type: string
description: |
End date of the time period in which usage is tracked. Zuora uses
this field value to determine the usage date.
format: date-time
productRatePlanChargeId:
type: string
description: |
The product rate plan charge number that you use for a dynamic usage charge.
quantity:
type: number
description: |
Number of units used.
rbeStatus:
type: string
description: |
Indicates if the rating and billing engine (RBE) processed usage data for an invoice.
enum:
- Importing
- Pending
- Processed
sourceType:
type: string
description: |
Indicates if the usage records were imported from the web-based UI or the API.
enum:
- API
- Import
startDateTime:
description: |
Start date of the time period in which usage is tracked. Zuora uses
this field value to determine the usage date.
format: date-time
type: string
subscriptionId:
type: string
description: |
The original ID of the subscription that contains the fees related to the usage data.
submissionDateTime:
type: string
format: date-time
description: |
The date and time when the usage was submitted.
uOM:
type: string
description: |
The units to measure usage. Units of measure are configured in the web-based UI. Your values depend on your configuration in **Billing Settings**.
description:
type: string
description: |
A description of the usage record.
importId:
type: string
description: |
The unique identifier of the import.
uniqueKey:
description: |
a customer-defined specific identifier of a usage record.
**Note**: This field is only available if you have the [Prepaid with
Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown)
feature or the Unbilled Usage feature enabled. See [Upload usage record with unique
key](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Prepaid_balance_transactions#Upload_usage_record_with_unique_key)
for more information.
type: string
fileId:
description: |
File ID of the uploaded usage records file. You can use this file ID with [Get files](https://developer.zuora.com/api-references/api/operation/GET_Files) to download the file.
type: string
fileName:
type: string
description: |
The name of the import file when the usage record is imported from the file.
account:
type: object
description: |
The account associated with the usage.
additionalProperties:
type: object
description: |
Custom fields of the Usage object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryUsageResponse
ExpandedAmendment:
properties:
id:
type: string
description: |
The unique identifier of the amendment.
createdById:
type: string
description: |
The unique identifier of the user who created the amendment.
createdDate:
type: string
format: date-time
description: |
The time that the amendment gets created in the system, in the
`YYYY-MM-DD HH:MM:SS` format.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the amendment.
updatedDate:
type: string
format: date-time
description: |
The time that the amendment gets updated in the system, in the
`YYYY-MM-DD HH:MM:SS` format.
autoRenew:
type: boolean
description: |
Indicates whether the amendment is automatically renewed.
code:
type: string
description: |
The amendment code.
contractEffectiveDate:
type: string
format: date
description: |
The date when the amendment becomes effective for billing purposes,
as `yyyy-mm-dd`.
currentTerm:
type: integer
format: int64
description: |
The length of the period for the current subscription term.
currentTermPeriodType:
type: string
description: |
The period type for the current subscription term.
enum:
- Month
- Year
- Day
- Week
customerAcceptanceDate:
type: string
format: date
description: |
The date when the customer accepts the amendment changes to
the subscription, as `yyyy-mm-dd`.
description:
type: string
description: |
Description of the amendment.
effectiveDate:
type: string
format: date
description: |
The date when the amendment changes take effective.
effectivePolicy:
type: string
description: |
Effective Policy for the subscription.
The value depends on the following conditions:
* If the rate plan change (from old to new) is an upgrade, the effective policy is `EffectiveImmediately` by default.
* If the rate plan change (from old to new) is a downgrade, the effective policy is `EffectiveEndOfBillingPeriod` by default.
* Otherwise, the effective policy is `SpecificDate` by default.
**Note:** This feature is in the **Early Adopter** phase. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available. If you want to join this early adopter program, submit a request at [Zuora Global Support](http://support.zuora.com/).
enum:
- EffectiveImmediately
- EffectiveEndOfBillingPeriod
- SpecificDate
name:
type: string
description: |
The name of the amendment.
newRatePlanId:
type: string
description: |
The ID of the rate plan charge on which amendment is made. Only
the Add or Update amendment returns a new rate plan ID.
removedRatePlanId:
type: string
description: |
The ID of the rate plan charge that is removed from the subscription. Only
the Remove Product amendment returns a removed rate plan ID.
renewalSetting:
type: string
description: |
Specifies whether a termed subscription will remain termed or change to evergreen when it is renewed.
enum:
- RENEW_WITH_SPECIFIC_TERM
- RENEW_TO_EVERGREEN
renewalTerm:
description: |
The term of renewal for the amended subscription.
format: int64
type: integer
renewalTermPeriodType:
description: |
The period type for the subscription renewal term.
type: string
enum:
- Month
- Year
- Day
- Week
resumeDate:
description: |
The date when the subscription resumption takes effect, as `yyyy-mm-dd`.
**Note:** This feature is in **Limited Availability**. If you wish to have access to the feature, submit a request at [Zuora Global Support](http://support.zuora.com/).
format: date
type: string
serviceActivationDate:
type: string
format: date
description: |
The date when service is activated, as `yyyy-mm-dd`.
specificUpdateDate:
type: string
format: date
description: |
The date when the Update Product amendment takes effect.
Only for the Update Product amendments if there is already
a future-dated Update Product amendment on the subscription.
status:
type: string
description: |
The status of the amendment.
enum:
- Draft
- Pending Activation
- Pending Acceptance
- Completed
subscriptionId:
type: string
description: |
The ID of the subscription based on which the amendment is created.
suspendDate:
type: string
description: |
The date when the subscription suspension takes effect, as `yyyy-mm-dd`.
**Note:** This feature is in **Limited Availability**. If you wish to have access to the feature, submit a request at [Zuora Global Support](http://support.zuora.com/).
format: date
termStartDate:
type: string
format: date
description: |
The date when the new terms and conditions take effect.
termType:
type: string
description: |
Indicates if the subscription is termed or evergreen.
enum:
- TERMED
- EVERGREEN
type:
description: |
Type of the amendment.
type: string
enum:
- Cancellation
- NewProduct
- OwnerTransfer
- RemoveProduct
- Renewal
- UpdateProduct
- TermsAndConditions
- ChangePlan
- Composite
subType:
type: string
description: |
The sub type for the change plan order action.
If this field was not set by user, the field is automatically generated by the system according to the following rules:
When the old and new rate plans are within the same Grading catalog group:
* If the grade of new plan is greater than that of the old plan, this is an "Upgrade".
* If the grade of new plan is less than that of the old plan, this is a "Downgrade".
* If the grade of new plan equals that of the old plan, this is a "Crossgrade".
When the old and new rate plans are not in the same Grading catalog group, or either has no group, this is "PlanChanged".
enum:
- Upgrade
- Downgrade
- Crossgrade
- PlanChanged
bookingDate:
type: string
format: date
additionalProperties:
type: object
description: |
Custom fields of the Amendment object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryAmendmentResponse
ExpandedBillingRun:
properties:
id:
type: string
description: |
The unique identifier of the bill run.
createdById:
type: string
description: |
The unique identifier of the user who created the bill run.
createdDate:
type: string
format: date-time
description: |
The date and time when the bill run was created.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the bill run.
updatedDate:
type: string
format: date-time
description: |
The date and time when the bill run was last updated.
billingRunNumber:
type: string
description: |
The number of the bill run.
billingRunType:
type: string
description: |
The type of the bill run.
- You can use this field only if the Catch-Up Bill Run feature is
enabled.
- You must specify this field to create a catch up bill run.
enum:
- Regular
- CatchUp
default: Regular
endDate:
type: string
format: date-time
description: |
The end date and time when the bill run completes.
errorMessage:
type: string
description: |
The error message generated by a failed billing run.
executedDate:
type: string
format: date-time
description: |
The date and time when the bill run was executed.
invoiceDate:
type: string
format: date
description: |
The date that appears on the invoice being created, in the `yyyy-mm-dd` format.
The value cannot fall in a closed accounting period.
name:
type: string
description: |
The name of the bill run.
numberOfAccounts:
type: integer
format: int64
description: |
The number of accounts included in this bill run processing.
numberOfInvoices:
type: integer
format: int64
description: |
The number of invoices generated from this bill run.
numberOfCreditMemos:
type: integer
format: int64
description: |
The number of credit memos generated from this bill run.
postedDate:
type: string
format: date-time
description: |
The date when the bill run was posted.
startDate:
type: string
format: date-time
description: |
The start date and time of the bill run.
status:
description: |
The status of the bill run.
enum:
- Pending
- Processing
- Completed
- Error
- Canceled
- Posted
- PostInProgress
- CancelInProgress
- RemoveInProgress
- Paused
type: string
targetDate:
type: string
format: date
description: |
The target date for this bill run, only valid for ad-hoc bill runs.
targetType:
type: string
description: |
The target type for this bill run.
enum:
- SingleAccount
- AllAccount
totalTime:
type: integer
format: int64
description: |
The total time in milliseconds for the bill run to complete.
accountId:
type: string
description: |
The unique identifier of the account included in the bill run.
batches:
description: |
The batch of accounts for this bill run, this field can not exist with
`billRunFilters` together.
**Values:** `AllBatches` or an array of `Batch`*n* where *n* is a
number between 1 and 50, for example, `Batch7`.
items:
type: string
type: array
billCycleDay:
description: |
The day of the bill cycle. This field is only valid when `batches` is
specified.
**Values:**
- `AllBillCycleDays` or one of numbers 1 - 31 for an ad-hoc bill run
- `AllBillCycleDays`, one of numbers 1 - 31, or `AsRunDay` for a scheduled bill run
type: string
enum:
- AllBillCycleDays
- AsRunDay
noEmailForZeroAmountInvoice:
description: |
Whether to suppress emails for invoices with zero total amount
generated in this bill run after the bill run is complete.
type: boolean
autoEmail:
description: |
Whether to automatically send emails after Auto-Post is complete.
type: boolean
autoPost:
description: |
Whether to automatically post the bill run after the bill run is created.
type: boolean
autoRenewal:
description: |
Whether to automatically renew auto-renew subscriptions that are up for renewal.
type: boolean
invoicesEmailed:
type: boolean
description: |
Whether the invoices have been emailed after the bill run is complete.
lastEmailSentTime:
type: string
format: date-time
description: |
The date and time when the last email was sent.
targetDateOffSet:
type: integer
format: int32
description: |
The offset compared to bill run execution date, only valid for scheduled bill runs.
invoiceDateOffSet:
type: integer
format: int32
description: |
The offset compared to bill run execution date, only valid for scheduled bill runs.
chargeTypeToExclude:
description: |
The types of the charges to be excluded from the generation of billing
documents.
enum:
- OneTime
- Recurring
- Usage
type: string
scheduledExecutionTime:
description: |
The scheduled execution time for a bill run.
format: date-time
type: string
repeatType:
description: |
The repeat type of the bill run.
enum:
- None
- Daily
- Weekly
- Monthly
type: string
repeatFrom:
description: |
The start date of the scheduled bill run.
format: date
type: string
repeatTo:
description: |
The end date of of the scheduled bill run.
format: date
type: string
runTime:
type: integer
format: int32
description: |
The scheduled run time (hour) of day.
maximum: 23
minimum: 0
timeZone:
type: string
description: |
Timezone of the scheduled bill run.
monthlyOnDay:
type: string
description: |
The repeat day in a month.
weeklyOnDay:
description: |
The repeat day in a week.
enum:
- Mon
- Tue
- Wed
- Thu
- Fri
- Sat
- Sun
type: string
includeSubscriptions:
default: true
description: |
Indicates whether to bill subscriptions in the bill run.
type: boolean
includeOrderLineItems:
default: true
description: |
Indicates whether to bill order line items in the bill run.
type: boolean
additionalProperties:
type: object
description: |
Custom fields of the Bill Run object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryBillingRunResponse
ExpandedCreditMemo:
properties:
id:
type: string
description: |
The unique identifier of the credit memo.
createdById:
type: string
description: |
The unique identifier of the user who created the credit memo.
createdDate:
type: string
format: date-time
description: |
The date and time when the credit memo was created.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the credit memo.
updatedDate:
type: string
format: date-time
description: |
The date and time when the credit memo was last updated.
appliedAmount:
description: |
The applied amount of the credit memo.
format: double
type: number
balance:
type: number
description: |
The remaining balance of credit memo.
billToContactId:
description: |
The ID of the bill-to contact associated with the credit memo.
The value of this field is `null` if you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled.
type: string
billToContactSnapshotId:
description: |
The ID of the bill-to contact snapshot associated with the credit memo.
The value of this field is `null` if the bill rule [Preserve snapshot of bill-to and sold-to contacts when billing documents are posted](https://knowledgecenter.zuora.com/Zuora_Billing/Billing_and_Invoicing/Billing_Settings/Define_Billing_Rules#Preserve_snapshot_of_bill-to_and_sold-to_contacts_when_billing_documents_are_posted) is disabled.
type: string
cancelledById:
description: |
The ID of the Zuora user who cancelled the credit memo.
type: string
nullable: true
cancelledOn:
description: |
The date and time when the credit memo was cancelled, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
nullable: true
comment:
description: |
Comments about the credit memo.
type: string
nullable: true
currency:
description: |
The currency of the credit memo.
**Note:** By default, the currency on a billing document matches the default currency set on the associated account.
However, Zuora now offers a Multiple Currencies feature to support different currencies for billing documents, allowing flexibility beyond the account-level currency.
For more information, see Multiple Currency.
type: string
nullable: true
example: USD
discountAmount:
type: number
description: |
The amount of the discount on the credit memo.
einvoiceErrorCode:
description: |
The error code returned when the e-invoice file status is `Failed`. This code can either be a Zuora-generated error code or one returned by a third-party e-invoicing service provider.
**Note**: This field is available only if you have the E-Invoicing feature in **Early Adopter** phase enabled.
type: string
einvoiceErrorMessage:
description: |
The error message returned when the e-invoice file status is `Failed`. This message can either be a Zuora-generated error message or one returned by a third-party e-invoicing service provider.
**Note**: This field is available only if you have the E-Invoicing feature in **Early Adopter** phase enabled.
type: string
einvoiceFileId:
description: |
The ID of the e-invoice file generated for the credit memo.
**Note**: This field is available only if you have the E-Invoicing feature in **Early Adopter** phase enabled.
type: string
einvoiceStatus:
description: |
The status of the e-invoice file generation for the credit memo.
- If e-invoice file generation succeeds, this field is either `Generated` or `Success`, and both the error code and message are empty, and the `eInvoiceFileId` field stores the ID of the generated e-invoice file.
- If the responses from tax vendors such as Sovos or Avalara are
taking too long, this field becomes `RetrieveTimeOut`. Once the
vendor responds successfully, you can use the 'Resync E-Invoice Status'
action to update the status automatically. You can view these updates
in System Health telemetry.
- If a failure occurs during e-invoice file generation, this field is `Failed` and an error code and an error message are returned respectively in the `einvoiceErrorCode` and `einvoiceErrorMessage` fields.
- If e-invoice file generation conditionally succeeds, this field is `ConditionalSuccess` and an error code and an error message are returned respectively in the `einvoiceErrorCode` and `einvoiceErrorMessage` fields.
- If the e-invoice file has been approved by the tax authority, this field is `ApprovedByAuthority`. The next status will be either `Success` or `Rejected`.
- If the e-invoice file has been rejected by the government, this field is `Rejected`. You cannot resend this e-invoice; you must create a new invoice instead.
**Note**: This field is available only if you have the E-Invoicing feature in **Early Adopter** phase enabled.
enum:
- Processing
- RetrieveTimeOut
- Generated
- Success
- Failed
- ConditionalSuccess
- ApprovedByAuthority
- Rejected
type: string
excludeFromAutoApplyRules:
description: |
Whether the credit memo is excluded from the rule of automatically applying credit memos to invoices.
type: boolean
exchangeRateDate:
type: string
format: date
description: |
The date of the exchange rate used. The date is in `yyyy-mm-dd` format.
Corresponds to the value specified in the Provider Exchange Rate Date column in the Import Foreign Exchange Rates template when you uploaded the rates through the Mass Updater.
autoApplyUponPosting:
description: |
Whether the credit memo automatically applies to the invoice upon
posting.
type: boolean
memoDate:
type: string
format: date
description: |
The date when the credit memo takes effect, in `yyyy-mm-dd` format.
For example, `2024-01-01`.
memoNumber:
description: |
The unique identification number of the credit memo.
type: string
postedById:
description: |
The ID of the Zuora user who posted the credit memo.
type: string
postedOn:
description: |
The date and time when the credit memo was posted, in
`yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
reasonCode:
description: |
A code identifying the reason for the transaction. The value
must be an existing reason code or empty.
type: string
refundAmount:
description: |
The amount of the refund on the credit memo.
format: double
type: number
reversed:
description: |
Whether the credit memo is reversed.
type: boolean
revenueImpacting:
description: |
Indicates whether this write off operation impacts the revenue. If `revenueImpacting` = `Yes`, the deferred revenue accounting code will be automatically selected from the associated invoice
If `revenueImpacting` = `No`, users can select an accounting code such as bad-debt expense accounting code for the write off operation.
enum:
- 'Yes'
- 'No'
default: 'Yes'
type: string
sequenceSetId:
description: |
The ID of the sequence set associated with the credit memo.
The value of this field is `null` if you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled.
type: string
nullable: true
source:
description: |
The source of the credit memo.
Possible values:
- `BillRun`: The credit memo is generated by a bill run.
- `API`: The credit memo is created by calling the [Invoice and collect](https://developer.zuora.com/api-references/api/operation/POST_TransactionInvoicePayment) operation, or by calling the Orders, Order Line Items, or Fulfillments API operations.
- `ApiSubscribe`: The credit memo is created by calling the [Create subscription](https://developer.zuora.com/api-references/api/operation/POST_Subscription) and [Create account](https://developer.zuora.com/api-references/api/operation/POST_Account) operation.
- `ApiAmend`: The credit memo is created by calling the [Update subscription](https://developer.zuora.com/api-references/api/operation/PUT_Subscription) operation.
- `AdhocFromPrpc`: The credit memo is created from a product rate plan charge through the Zuora UI or by calling the [Create a credit memo from a charge](https://developer.zuora.com/api-references/api/operation/POST_CreditMemoFromPrpc) operation.
- `AdhocFromInvoice`: The credit memo is created from an invoice or created by reversing an invoice. You can create a credit memo from an invoice through the Zuora UI or by calling the [Create credit memo from invoice](https://developer.zuora.com/api-references/api/operation/POST_CreditMemoFromInvoice) operation. You can create a credit memo by reversing an invoice through the Zuora UI or by calling the [Reverse invoice](https://developer.zuora.com/api-references/api/operation/PUT_ReverseInvoice) operation.
type: string
enum:
- BillRun
- API
- ApiSubscribe
- ApiAmend
- AdhocFromPrpc
- AdhocFromInvoice
sourceId:
description: |
The ID of the credit memo source.
If a credit memo is generated from a bill run, the value is the
number of the corresponding bill run. Otherwise, the value is
`null`.
type: string
sourceType:
description: |
The type of the credit memo source.
enum:
- Subscription
- Standalone
- Invoice
- Order
- CreditMemo
- Consolidation
type: string
status:
description: |
The status of the credit memo.
enum:
- Draft
- Posted
- Canceled
- Error
- PendingForTax
- Generating
- CancelInProgress
type: string
targetDate:
description: |
The target date for the credit memo, in `yyyy-mm-dd` format. For example, `2024-01-01`.
format: date
type: string
taxAmount:
description: |
The amount of taxation.
format: double
type: number
taxMessage:
description: |
The message about the status of tax calculation related to the credit memo. If tax calculation fails in one credit memo, this field displays the reason for the failure.
type: string
nullable: true
taxStatus:
description: |
The status of tax calculation related to the credit memo.
**Note**: This field is only applicable to tax calculation by third-party tax engines. Also, the `Voided` status indicates that the tax transaction is successfully canceled on the tax vendor's side. If a tax transaction was successfully committed to the third-party tax engine but the invoice failed to post, Zuora automatically detects the issue and voids the tax transaction on the vendor's side.
enum:
- Complete
- Error
- UnknownError
- DuplicateDoc
- InvalidRequest
- InvalidResponse
- TaxEngineError
- ConcurrentModify
- InternalServerError
- TaxCodeTemplateError
- Voided
type: string
shipToContactSnapshotId:
description: |
The ID of the ship-to contact snapshot associated with the
credit memo.
**Note**: If you have the Flexible Billing Attributes feature
disabled, the value of this field is `null`.
type: string
soldToContactSnapshotId:
description: |
The ID of the sold-to contact snapshot associated with the
credit memo.
**Note**: If you have the Flexible Billing Attributes feature
disabled, the value of this field is `null`.
type: string
taxAutoCalculation:
default: true
description: |
Whether to automatically calculate taxes in the credit memo.
type: boolean
totalAmount:
type: number
format: double
description: |
The total amount of the credit memo, including taxes.
totalAmountWithoutTax:
type: number
format: double
description: |
The total amount of the credit memo, excluding taxes.
totalTaxExemptAmount:
description: |
The calculated tax amount excluded due to the exemption.
format: double
type: number
transferredToAccounting:
description: |
Whether the credit memo was transferred to an external
accounting system. This field is used for integration with
accounting systems such as NetSuite.
enum:
- Processing
- 'Yes'
- 'No'
- Error
- Ignore
type: string
invoiceId:
description: |
The ID of a referred invoice.
type: string
accountId:
description: |
The ID of the customer account associated with the credit memo.
type: string
account:
$ref: '#/components/schemas/NestedAccountOnExpand'
billToContact:
$ref: '#/components/schemas/ExpandedContact'
creditMemoItems:
type: array
items:
$ref: '#/components/schemas/NestedCreditMemoItemOnExpand'
creditMemoApplications:
type: array
items:
$ref: '#/components/schemas/NestedCreditMemoApplicationOnExpand'
billToContactSnapshot:
$ref: '#/components/schemas/NestedContactSnapshotOnExpand'
soldToContactSnapshot:
$ref: '#/components/schemas/NestedContactSnapshotOnExpand'
shipToContactSnapshot:
$ref: '#/components/schemas/NestedContactSnapshotOnExpand'
additionalProperties:
type: object
description: |
Custom fields of the Credit Memo object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryCreditMemoResponse
NestedAccountOnExpand:
properties:
id:
type: string
description: |
The unique identifier of the account.
createdById:
type: string
description: |
The unique identifier of the user who created the account.
createdDate:
type: string
format: date-time
description: |
The date and time when the account was created.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the account.
updatedDate:
type: string
format: date-time
description: |
The date and time when the account was last updated.
accountNumber:
type: string
description: |
The account number that identifies the account.
additionalEmailAddresses:
type: string
description: |
An additional email address to receive email notifications.
allowInvoiceEdit:
type: boolean
description: |
Indicates whether associated invoices can be edited.
default: false
autoPay:
type: boolean
description: |
Indicates whether future payments are automatically collected when they are due
during a payment run.
balance:
type: number
format: double
description: |
The customer's total invoice balance minus credit balance.
batch:
type: string
description: |
The alias name given to a batch. A string of 50 characters or less.
bcdSettingOption:
type: string
description: |
The billing cycle day setting option for the account.
enum:
- ManualSet
- AutoSet
billCycleDay:
type: integer
format: int64
description: |
Billing cycle day (BCD), the day of the month when a bill run
generates invoices for the account.
billToId:
type: string
description: |
The unique identifier of the bill-to contact associated with the account.
communicationProfileId:
type: string
description: |
The unique identifier of the communication profile that Zuora uses when sending notifications to the account's contacts.
creditBalance:
type: number
format: double
description: |
The current credit balance on the account.
crmId:
description: |
External identifier of the account in a CRM system.
maxLength: 100
type: string
currency:
type: string
description: |
A currency defined in the web-based UI administrative settings.
customerServiceRepName:
description: |
Name of the account's customer service representative, if applicable.
maxLength: 50
type: string
defaultPaymentMethodId:
type: string
description: |
ID of the default payment method for the account.
eInvoiceProfileId:
type: string
description: |
ID of the e-invoice profile for this account.
**Note**: This field is available only if you have the E-Invoicing feature in **Early Adopter** phase enabled.
invoiceDeliveryPrefsEmail:
description: |
Indicates whether the customer wants to receive invoices through email.
type: boolean
invoiceDeliveryPrefsPrint:
description: |
Whether the customer wants to receive printed invoices, such as through postal mail.
type: boolean
invoiceTemplateId:
description: |
Invoice template ID, configured in Billing Settings in the Zuora UI.
type: string
lastInvoiceDate:
type: string
format: date
description: |
Date of the most recent invoice for the account; null if no invoice has ever been generated.
lastMetricsUpdate:
description: |
The date and time when account metrics are last updated, if the account is a partner account.
**Note**:
- This field is available only if you have the Reseller Account feature enabled.
- If you ever set the `partnerAccount` field to `true` for an account, the value of `lastMetricsUpdate` field is the time when the account metrics are last updated.
format: date-time
type: string
name:
type: string
description: |
The name of the account.
notes:
type: string
description: |
A string of up to 65,535 characters.
organizationId:
type: string
description: |
The unique identifier of the organization to which the account belongs.
parentId:
description: |
Identifier of the parent customer account for this Account object. The
length is 32 characters. Use this field if you have Customer Hierarchy enabled.
type: string
partnerAccount:
type: boolean
description: |
Whether the customer account is a partner, distributor, or reseller.
**Note**: This field is available only if you have the Reseller Account feature enabled.
paymentMethodCascadingConsent:
type: boolean
description: |
`true` indicates the consent from your customer to use the Cascading Payment Method feature was collected.
`false` indicates the consent was not collected and the Cascading Payment Method feature is not enabled.
purchaseOrderNumber:
type: string
description: |
The purchase order number provided by your customer for services,
products, or both purchased.
salesRepName:
type: string
description: |
Name of the account's sales representative, if applicable.
sequenceSetId:
type: string
nullable: true
description: |
The ID of the billing document sequence set to assign to the customer account.
The billing documents to generate for this account will adopt the prefix and starting document number configured in the sequence set.
If a customer account has no assigned billing document sequence set, billing documents generated for this account adopt the prefix and starting document number from the default sequence set.
shipToId:
type: string
description: |
The unique identifier of the ship-to contact associated with the account.
soldToId:
type: string
description: |
The unique identifier of the sold-to contact associated with the account.
status:
description: |
The account status.
type: string
enum:
- Active
- Draft
- Canceled
taxCompanyCode:
type: string
description: |
Unique code that identifies a company account in Avalara.
**Note:** This feature is in Limited Availability. If you wish to have access to the feature, submit a request at [Zuora Global Support](https://support.zuora.com).
maxLength: 50
taxExemptCertificateID:
type: string
description: |
ID of the customer tax exemption certificate. Applicable if you use Zuora Tax or Connect tax engines.
maxLength: 32
taxExemptCertificateType:
type: string
description: |
Type of tax exemption certificate that the customer holds. Applicable if you use Zuora Tax or Connect tax engines.
maxLength: 32
taxExemptDescription:
type: string
description: |
Description of the tax exemption certificate that the customer holds.
Applicable if you use Zuora Tax or Connect tax engines.
maxLength: 500
taxExemptEffectiveDate:
type: string
format: date
description: |
Date when the customer tax exemption starts, in `YYYY-MM-DD` format. Applicable if you use Zuora Tax or Connect tax engines.
taxExemptEntityUseCode:
type: string
description: |
A unique entity use code to apply exemptions in Avalara AvaTax. See Exempt Transactions for more details.
maxLength: 64
taxExemptExpirationDate:
type: string
format: date
description: |
Date when the customer tax exemption expires, in `YYYY-MM-DD` format. Applicable if you use Zuora Tax or Connect tax engines.
taxExemptIssuingJurisdiction:
type: string
description: |
Jurisdiction in which the customer tax exemption certificate was issued.
maxLength: 32
taxExemptStatus:
type: string
default: 'No'
description: |
Status of the account tax exemption. Applicable if you use Zuora Tax or Connect tax engines. Required if you use Zuora Tax.
enum:
- 'No'
- 'Yes'
- PendingVerification
totalInvoiceBalance:
type: number
description: |
Total balance of all posted invoices.
format: double
unappliedBalance:
type: number
description: |
Total unapplied balance in this currency.
vATId:
type: string
description: EU Value Added Tax ID.
mrr:
type: number
description: |
Monthly recurring revenue for the account.
totalDebitMemoBalance:
type: number
description: |
Total balance of all posted debit memos.
format: double
unappliedCreditMemoAmount:
type: number
description: |
The total unapplied amount of all posted credit memos in this currency.
format: double
creditMemoTemplateId:
type: string
description: |
ID of the credit memo template that is used to generate credit memos for the account.
debitMemoTemplateId:
type: string
description: |
ID of the debit memo template that is used to generate debit memos for the account.
paymentGateway:
type: string
description: |
The name of the payment gateway instance. If null or left unassigned,
the account will use the default gateway.
paymentTerm:
type: string
description: |
A payment-terms indicator defined in the web-based UI administrative
settings, for example, `Net 30`.
billTo:
type: object
description: |
The bill-to contact on this account.
shipTo:
type: object
description: |
The ship-to contact on the account.
soldTo:
type: object
description: |
The sold-to contact on the account.
defaultPaymentMethod:
type: object
description: |
The default payment method associated with the account.
subscriptions:
type: array
items:
type: object
description: |
The subscriptions associated with the account.
payments:
type: array
items:
type: object
description: |
The payments associated with the account.
refunds:
type: array
items:
type: object
description: |
The refunds associated with the account.
creditMemos:
type: array
items:
type: object
description: |
The credit memos associated with the account.
debitMemos:
type: array
items:
type: object
description: |
The debit memos associated with the account.
invoices:
type: array
items:
type: object
description: |
The invoices associated with the account.
usages:
type: array
items:
type: object
description: |
The usage records associated with the account.
paymentMethods:
type: array
items:
type: object
description: |
The payment methods associated with the account.
additionalProperties:
type: object
description: |
Custom fields of the Account object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryAccountResponse
NestedCreditMemoItemOnExpand:
properties:
id:
type: string
description: |
The unique identifier of the credit memo item.
createdById:
type: string
description: |
The unique identifier of the user who created the credit memo item.
createdDate:
type: string
format: date-time
description: |
The date and time when the credit memo item was created.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the credit memo item.
updatedDate:
type: string
format: date-time
description: |
The date and time when the credit memo item was last updated.
amount:
type: number
description: |
The amount of the credit memo item. For tax-inclusive credit memo
items, the amount indicates the credit memo item amount including tax.
For tax-exclusive credit memo items, the amount indicates the credit
memo item amount excluding tax.
amountWithoutTax:
description: |
The credit memo item amount excluding tax.
format: double
type: number
appliedToItemId:
description: |
The unique ID of the credit memo item that the discount charge is applied to.
type: string
appliedToOthersAmount:
type: number
description: |
The amount of the credit memo that is applied to other credit memo
items.
beAppliedByOthersAmount:
type: number
chargeDate:
type: string
description: |
The date when the credit memo item is charged, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
description:
description: |
The description of the credit memo item.
**Note**: This field is only available if you set the `Zuora-Version` request header to `257.0` or later [available versions](https://developer.zuora.com/api-references/api/overview/#section/API-Versions/Minor-Version).
type: string
excludeItemBillingFromRevenueAccounting:
description: |
The flag to exclude the credit memo item from revenue accounting.
**Note**: This field is only available if you have the Billing - Revenue Integration feature enabled.
type: boolean
fulfillmentId:
description: |
The reference ID of the fulfillment associated with the credit memo item.
type: string
invoiceScheduleId:
description: |
The ID of the invoice schedule associated with the credit memo item.
**Note**: This field is available only if you have the Billing Schedule feature enabled.
type: string
invoiceScheduleItemId:
description: |
The ID of the invoice schedule item associated with the credit memo item. The credit memo item is generated during the processing of the invoice schedule item.
**Note**: This field is available only if you have the Billing Schedule feature enabled.
type: string
itemShipToContactId:
description: |
The ID of the ship-to contact associated with the credit memo item.
**Note**: If you have the Flexible Billing Attributes feature disabled, the value of this field is `null`.
type: string
itemSoldToContactId:
description: |
The ID of the sold-to contact associated with the credit memo item.
**Note**: If you have the Flexible Billing Attributes feature disabled, the value of this field is `null`.
type: string
itemSoldToContactSnapshotId:
description: |
The ID of the sold-to contact snapshot associated with the credit memo item.
**Note**: If you have the Flexible Billing Attributes feature disabled, the value of this field is `null`.
type: string
itemType:
type: string
description: |
The type of the credit memo item.
orderLineItemId:
type: string
description: |
The ID of the order line item associated with the credit memo item, if applicable.
processingType:
description: |
The type of the charge for the credit memo item.
- `0`: Charge - `1`: Discount
type: string
enum:
- '0'
- '1'
quantity:
description: |
The number of units for the credit memo item.
format: double
type: number
purchaseOrderNumber:
type: string
description: |
The purchase order number associated the credit memo item.
creditFromItemSource:
description: |
The type of the credit from item.
enum:
- InvoiceItem
- CreditMemoItem
type: string
creditFromItemId:
type: string
description: |
The ID of the credit from item.
reflectDiscountInNetAmount:
type: boolean
default: false
description: |
When you apply percentage discounts to either of the following charges, you need to set the `reflectDiscountInNetAmount` field on your discount charge to `true`, to enable calculating and displaying the net amount of the following charges in Zuora Revenue.
* delivery pricing charge
* prepayment charge
* drawdown charge
Note the following:
* If you are an Order to Revenue customer, when you set the `reflectDiscountInNetAmount` field to `true`, you must also set the `excludeItemBillingFromRevenueAccounting` field to `true`.
* If you are a Billing - Revenue Integration customer, you must set the `reflectDiscountInNetAmount` field to `false`, otherwise an error will be returned. Billing - Revenue Integration does not support discounts on the preceding charges.
* If you are a Zuora Billing customer who does not enable the Order to Revenue or Billing - Revenue Integration feature, when you apply percentage discounts to the preceding charges, you also need to set the `reflectDiscountInNetAmount` field to `true`.
serviceEndDate:
description: |
The service end date of the credit memo item.
format: date
type: string
serviceStartDate:
description: |
The service start date of the credit memo item.
format: date
type: string
sku:
description: |
The SKU for the product associated with the credit memo item.
type: string
sourceItemType:
description: |
The type of the source item.
- If a credit memo is not created from an invoice or a product rate plan charge or a return order line item, the value of this field is `SubscriptionComponent`.
- If a credit memo is created from an invoice, the value of this field is `InvoiceDetail`.
- If a credit memo is created from a product rate plan charge, the value of this field is `ProductRatePlanCharge`.
- If a credit memo is created from a return order line item, the value of this field is `OrderLineItem`.
enum:
- SubscriptionComponent
- InvoiceDetail
- ProductRatePlanCharge
- OrderLineItem
type: string
subscriptionId:
description: |
The ID of the subscription associated with the credit memo item.
type: string
taxMode:
description: |
The tax mode of the credit memo item, indicating whether the amount of the credit memo item includes tax.
enum:
- TaxExclusive
- TaxInclusive
type: string
chargeName:
type: string
description: |
The name of the charge associated with the credit memo item.
chargeNumber:
type: string
description: |
The number of the product rate plan charge that the credit memo is created from.
commitmentChargeSegmentNumber:
type: string
commitmentChargeNumber:
type: string
taxAmount:
description: |
The amount of the tax applied to the credit memo item.
format: double
type: number
taxCodeName:
type: string
description: |
The tax code identifies which tax rules and tax rates to apply to a specific credit memo item.
taxExemptAmount:
type: number
description: |
The calculated tax amount excluded due to the exemption.
unappliedAmount:
description: |
The unapplied amount of the credit memo item.
format: double
type: number
unitOfMeasure:
description: |
The units to measure usage.
type: string
unitPrice:
description: |
The per-unit price of the credit memo item.
format: double
type: number
subscriptionNumber:
type: string
description: |
The number of the subscription associated with the credit memo item.
invoiceItemId:
type: string
description: |
The ID of the invoice item associated with the credit memo item.
productRatePlanChargeId:
type: string
description: |
The ID of the product rate plan charge that the credit memo is created
from.
ratePlanChargeId:
type: string
description: |
The ID of the rate plan charge associated with the credit memo item.
revenueRecognitionRuleName:
type: string
description: |
The name of the revenue recognition rule governing the revenue schedule.
revenueImpacting:
description: |
Indicates whether this write off operation impacts the revenue. If `revenueImpacting` = `Yes`, the deferred revenue accounting code will be automatically selected from the associated invoice.
If `revenueImpacting` = `No`, users can select an accounting code such as bad-debt expense accounting code for the write off operation.
enum:
- 'Yes'
- 'No'
default: 'Yes'
type: string
creditMemoId:
type: string
description: |
The ID of the credit memo to which this credit memo item belongs.
numberOfDeliveries:
description: |
The number of deliveries dedicated to the Delivery Pricing charges. The value might be different, as follows:
- For the credit memo generated by a bill run, this field has a value.
- For the credit memo generated from an invoice, this field is blank.
**Note**: This field is available only if you have the Delivery Pricing feature enabled.
type: number
recognizedRevenueAccountingCodeId:
type: string
description: |
The Recognized Revenue accounting code for the credit memo item.
accountReceivableAccountingCodeId:
type: string
description: |
The Account Receivable accounting code for the credit memo item.
onAccountAccountingCodeId:
type: string
description: |
The On Account accounting code for the credit memo item.
deferredRevenueAccountingCodeId:
type: string
description: |
The Deferred Revenue accounting code for the credit memo item.
journalEntryId:
type: string
description: |
The ID of the journal entry that corresponds to this transaction.
shipToContactSnapshotId:
description: |
The ID of the ship-to contact snapshot associated with the credit memo.
type: string
soldToContactSnapshotId:
description: |
The ID of the sold-to contact snapshot associated with the credit memo.
type: string
billToContactSnapshotId:
description: |
The ID of the bill-to contact snapshot associated with the credit memo.
type: string
subscription:
type: object
description: |
The subscription associated with the credit memo item.
ratePlanCharge:
type: object
description: |
The rate plan charge associated with the credit memo item.
additionalProperties:
type: object
description: |
Custom fields of the Credit Memo Item object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryCreditMemoItemResponse
NestedCreditMemoApplicationOnExpand:
properties:
id:
type: string
description: |
The unique identifier of the credit memo application.
createdById:
type: string
description: |
The unique identifier of the user who created the credit memo application.
createdDate:
type: string
format: date-time
description: |
The date and time when the credit memo application was created.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the credit memo application.
updatedDate:
type: string
format: date-time
description: |
The date and time when the credit memo application was last updated.
amount:
type: number
format: double
description: |
The application amount of the credit memo.
effectiveDate:
type: string
format: date
description: |
The date when the credit memo application becomes effective.
creditMemoId:
type: string
description: |
The ID of the credit memo associated with the credit memo application.
accountId:
type: string
description: |
The ID of the customer account associated with the credit memo.
applicationGroupId:
type: string
description: |
The ID of the application group to which this credit memo application belongs.
debitMemoId:
type: string
description: |
The ID of the debit memo to which the credit memo is applied.
invoiceId:
type: string
description: |
The ID of the invoice to which the credit memo is applied.
creditMemo:
type: object
description: |
The credit memo associated with the credit memo application.
type: object
title: QueryCreditMemoApplicationResponse
additionalProperties: false
NestedContactSnapshotOnExpand:
properties:
id:
type: string
description: |
The unique identifier of the contact snapshot.
createdById:
type: string
description: |
The unique identifier of the user who created the snapshot.
createdDate:
type: string
format: date-time
description: |
The date and time when the contact snapshot was created.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the snapshot.
updatedDate:
type: string
format: date-time
description: |
The date and time when the contact snapshot was last updated.
accountId:
type: string
description: |
The unique identifier of the associated billing account.
contactId:
type: string
description: |
The unique identifier of the original contact.
firstName:
type: string
description: |
The first name of the contact.
lastName:
type: string
description: |
The last name of the contact.
nickName:
type: string
description: |
The nickname of the contact.
address1:
type: string
description: |
The first line of the address.
address2:
type: string
description: |
The second line of the address.
city:
type: string
description: |
The city of the contact's address.
state:
type: string
description: |
The state or province of the contact's address.
postalCode:
type: string
description: |
The postal or ZIP code.
county:
type: string
description: |
The county or region of the contact.
country:
type: string
description: |
The county or region of the contact.
taxRegion:
type: string
description: |
The tax region applicable to the contact.
description:
type: string
description: |
The free-form description of the contact snapshot.
homePhone:
type: string
description: |
The home phone number.
otherPhone:
type: string
description: |
Any other phone number.
otherPhoneType:
type: string
description: |
The type of the other phone number.
fax:
type: string
description: |
The fax number.
personalEmail:
type: string
description: |
The personal email address.
workEmail:
type: string
description: |
The personal email address.
deleted:
type: boolean
description: |
Indicates whether the contact snapshot is marked as deleted.
additionalProperties:
type: object
description: |
Custom fields of the ContactSnapshot object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryContactSnapshotResponse
ExpandedCreditMemoApplication:
properties:
id:
type: string
description: |
The unique identifier of the credit memo application.
createdById:
type: string
description: |
The unique identifier of the user who created the credit memo application.
createdDate:
type: string
format: date-time
description: |
The date and time when the credit memo application was created.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the credit memo application.
updatedDate:
type: string
format: date-time
description: |
The date and time when the credit memo application was last updated.
amount:
type: number
format: double
description: |
The application amount of the credit memo.
effectiveDate:
type: string
format: date
description: |
The date when the credit memo application becomes effective.
creditMemoId:
type: string
description: |
The ID of the credit memo associated with the credit memo application.
accountId:
type: string
description: |
The ID of the customer account associated with the credit memo.
applicationGroupId:
type: string
description: |
The ID of the application group to which this credit memo application belongs.
debitMemoId:
type: string
description: |
The ID of the debit memo to which the credit memo is applied.
invoiceId:
type: string
description: |
The ID of the invoice to which the credit memo is applied.
creditMemo:
$ref: '#/components/schemas/NestedCreditMemoOnExpand'
type: object
title: QueryCreditMemoApplicationResponse
additionalProperties: false
ExpandedCreditMemoItem:
properties:
id:
type: string
description: |
The unique identifier of the credit memo item.
createdById:
type: string
description: |
The unique identifier of the user who created the credit memo item.
createdDate:
type: string
format: date-time
description: |
The date and time when the credit memo item was created.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the credit memo item.
updatedDate:
type: string
format: date-time
description: |
The date and time when the credit memo item was last updated.
amount:
type: number
description: |
The amount of the credit memo item. For tax-inclusive credit memo
items, the amount indicates the credit memo item amount including tax.
For tax-exclusive credit memo items, the amount indicates the credit
memo item amount excluding tax.
amountWithoutTax:
description: |
The credit memo item amount excluding tax.
format: double
type: number
appliedToItemId:
description: |
The unique ID of the credit memo item that the discount charge is applied to.
type: string
appliedToOthersAmount:
type: number
description: |
The amount of the credit memo that is applied to other credit memo
items.
beAppliedByOthersAmount:
type: number
chargeDate:
type: string
description: |
The date when the credit memo item is charged, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
description:
description: |
The description of the credit memo item.
**Note**: This field is only available if you set the `Zuora-Version` request header to `257.0` or later [available versions](https://developer.zuora.com/api-references/api/overview/#section/API-Versions/Minor-Version).
type: string
excludeItemBillingFromRevenueAccounting:
description: |
The flag to exclude the credit memo item from revenue accounting.
**Note**: This field is only available if you have the Billing - Revenue Integration feature enabled.
type: boolean
fulfillmentId:
description: |
The reference ID of the fulfillment associated with the credit memo item.
type: string
invoiceScheduleId:
description: |
The ID of the invoice schedule associated with the credit memo item.
**Note**: This field is available only if you have the Billing Schedule feature enabled.
type: string
invoiceScheduleItemId:
description: |
The ID of the invoice schedule item associated with the credit memo item. The credit memo item is generated during the processing of the invoice schedule item.
**Note**: This field is available only if you have the Billing Schedule feature enabled.
type: string
itemShipToContactId:
description: |
The ID of the ship-to contact associated with the credit memo item.
**Note**: If you have the Flexible Billing Attributes feature disabled, the value of this field is `null`.
type: string
itemSoldToContactId:
description: |
The ID of the sold-to contact associated with the credit memo item.
**Note**: If you have the Flexible Billing Attributes feature disabled, the value of this field is `null`.
type: string
itemSoldToContactSnapshotId:
description: |
The ID of the sold-to contact snapshot associated with the credit memo item.
**Note**: If you have the Flexible Billing Attributes feature disabled, the value of this field is `null`.
type: string
itemType:
type: string
description: |
The type of the credit memo item.
orderLineItemId:
type: string
description: |
The ID of the order line item associated with the credit memo item, if applicable.
processingType:
description: |
The type of the charge for the credit memo item.
- `0`: Charge - `1`: Discount
type: string
enum:
- '0'
- '1'
revenueImpacting:
description: |
Indicates whether this write off operation impacts the revenue. If `revenueImpacting` = `Yes`, the deferred revenue accounting code will be automatically selected from the associated invoice.
If `revenueImpacting` = `No`, users can select an accounting code such as bad-debt expense accounting code for the write off operation.
enum:
- 'Yes'
- 'No'
default: 'Yes'
type: string
quantity:
description: |
The number of units for the credit memo item.
format: double
type: number
purchaseOrderNumber:
type: string
description: |
The purchase order number associated the credit memo item.
creditFromItemSource:
description: |
The type of the credit from item.
enum:
- InvoiceItem
- CreditMemoItem
type: string
creditFromItemId:
type: string
description: |
The ID of the credit from item.
reflectDiscountInNetAmount:
type: boolean
default: false
description: |
When you apply percentage discounts to either of the following charges, you need to set the `reflectDiscountInNetAmount` field on your discount charge to `true`, to enable calculating and displaying the net amount of the following charges in Zuora Revenue.
* delivery pricing charge
* prepayment charge
* drawdown charge
Note the following:
* If you are an Order to Revenue customer, when you set the `reflectDiscountInNetAmount` field to `true`, you must also set the `excludeItemBillingFromRevenueAccounting` field to `true`.
* If you are a Billing - Revenue Integration customer, you must set the `reflectDiscountInNetAmount` field to `false`, otherwise an error will be returned. Billing - Revenue Integration does not support discounts on the preceding charges.
* If you are a Zuora Billing customer who does not enable the Order to Revenue or Billing - Revenue Integration feature, when you apply percentage discounts to the preceding charges, you also need to set the `reflectDiscountInNetAmount` field to `true`.
serviceEndDate:
description: |
The service end date of the credit memo item.
format: date
type: string
serviceStartDate:
description: |
The service start date of the credit memo item.
format: date
type: string
sku:
description: |
The SKU for the product associated with the credit memo item.
type: string
sourceItemType:
description: |
The type of the source item.
- If a credit memo is not created from an invoice or a product rate plan charge or a return order line item, the value of this field is `SubscriptionComponent`.
- If a credit memo is created from an invoice, the value of this field is `InvoiceDetail`.
- If a credit memo is created from a product rate plan charge, the value of this field is `ProductRatePlanCharge`.
- If a credit memo is created from a return order line item, the value of this field is `OrderLineItem`.
enum:
- SubscriptionComponent
- InvoiceDetail
- ProductRatePlanCharge
- OrderLineItem
type: string
subscriptionId:
description: |
The ID of the subscription associated with the credit memo item.
type: string
taxMode:
description: |
The tax mode of the credit memo item, indicating whether the amount of the credit memo item includes tax.
enum:
- TaxExclusive
- TaxInclusive
type: string
chargeName:
type: string
description: |
The name of the charge associated with the credit memo item.
chargeNumber:
type: string
description: |
The number of the product rate plan charge that the credit memo is created from.
commitmentChargeSegmentNumber:
type: string
commitmentChargeNumber:
type: string
taxAmount:
description: |
The amount of the tax applied to the credit memo item.
format: double
type: number
taxCodeName:
type: string
description: |
The tax code identifies which tax rules and tax rates to apply to a specific credit memo item.
taxExemptAmount:
type: number
description: |
The calculated tax amount excluded due to the exemption.
unappliedAmount:
description: |
The unapplied amount of the credit memo item.
format: double
type: number
unitOfMeasure:
description: |
The units to measure usage.
type: string
unitPrice:
description: |
The per-unit price of the credit memo item.
format: double
type: number
subscriptionNumber:
type: string
description: |
The number of the subscription associated with the credit memo item.
invoiceItemId:
type: string
description: |
The ID of the invoice item associated with the credit memo item.
productRatePlanChargeId:
type: string
description: |
The ID of the product rate plan charge that the credit memo is created
from.
ratePlanChargeId:
type: string
description: |
The ID of the rate plan charge associated with the credit memo item.
revenueRecognitionRuleName:
type: string
description: |
The name of the revenue recognition rule governing the revenue schedule.
creditMemoId:
type: string
description: |
The ID of the credit memo to which this credit memo item belongs.
numberOfDeliveries:
description: |
The number of deliveries dedicated to the Delivery Pricing charges. The value might be different, as follows:
- For the credit memo generated by a bill run, this field has a value.
- For the credit memo generated from an invoice, this field is blank.
**Note**: This field is available only if you have the Delivery Pricing feature enabled.
type: number
recognizedRevenueAccountingCodeId:
type: string
description: |
The Recognized Revenue accounting code for the credit memo item.
accountReceivableAccountingCodeId:
type: string
description: |
The Account Receivable accounting code for the credit memo item.
onAccountAccountingCodeId:
type: string
description: |
The On Account accounting code for the credit memo item.
deferredRevenueAccountingCodeId:
type: string
description: |
The Deferred Revenue accounting code for the credit memo item.
journalEntryId:
type: string
description: |
The ID of the journal entry that corresponds to this credit memo item.
shipToContactSnapshotId:
description: |
The ID of the ship-to contact snapshot associated with the credit memo.
type: string
soldToContactSnapshotId:
description: |
The ID of the sold-to contact snapshot associated with the credit memo.
type: string
billToContactSnapshotId:
description: |
The ID of the bill-to contact snapshot associated with the credit memo.
type: string
subscription:
$ref: '#/components/schemas/NestedSubscriptionOnExpand'
ratePlanCharge:
$ref: '#/components/schemas/NestedRatePlanChargeOnExpand'
subscriptionOwner:
$ref: '#/components/schemas/NestedAccountOnExpand'
creditTaxationItems:
$ref: '#/components/schemas/NestedCreditTaxationItemOnExpand'
additionalProperties:
type: object
description: |
Custom fields of the Credit Memo Item object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryCreditMemoItemResponse
NestedRatePlanChargeOnExpand:
properties:
id:
type: string
description: |
The unique identifier of the rate plan charge.
createdById:
type: string
description: |
The unique identifier of the user who created the rate plan charge.
createdDate:
type: string
format: date-time
description: |
The date and time when the rate plan charge was created.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the rate plan charge.
updatedDate:
type: string
format: date-time
description: |
The date and time when the rate plan charge was last updated.
ratePlanId:
type: string
description: |
The unique identifier of the rate plan to which this rate plan charge belongs.
productRatePlanChargeId:
type: string
description: |
The unique identifier of the product rate plan charge associated with this product rate plan charge.
accountingCode:
description: |
The accounting code for the charge. Accounting codes group transactions that contain similar accounting attributes.
**Values**: inherited from `ProductRatePlanCharge.AccountingCode`
**Note**: This value changes if `ProductRatePlanCharge.AccountingCode` is updated. The values of `UpdatedById` and `UpdatedDate` for the `RatePlanCharge` do not change when `ProductRatePlanCharge.AccountingCode` is updated.
type: string
applyDiscountTo:
description: |
Specifies the type of charges a specific discount applies to.
**Values**: inherited from `ProductRatePlanCharge.ApplyDiscountTo`
type: string
billCycleDay:
type: integer
format: int64
description: |
Indicates the charge's billing cycle day (BCD), which is when bill runs generate invoices for charges associated with the product rate plan charge or the account.
**Values**: inherited from `ProductRatePlanCharge.BillCycleDay`
billCycleType:
type: string
description: |
Specifies how to determine the billing day for the charge.\n\
**Values**: inherited from `ProductRatePlanCharge.BillCycleType`
**Note:** You can override the value inherited from the Product Rate Plan Charge, but only when creating a new subscription or a New Product amendment.
billingPeriod:
type: string
description: |
Allows billing period to be overridden on rate plan charge.
**Values**: **inherited from `ProductRatePlanCharge.BillingPeriod`
**Note:** You can override the value inherited from the Product Rate Plan Charge, but only when creating a new subscription or a New Product amendment.
billingPeriodAlignment:
type: string
description: |
Aligns charges within the same subscription if multiple charges begin on different dates.
**Values**: inherited from `ProductRatePlanCharge.BillingPeriodAlignment`
billingTiming:
type: string
description: |
The billing timing for the charge. You can choose to bill in advance or in arrears for recurring charge types. This field is not used in one-time or usage based charge types.
**Note:** You can override the value inherited from the Product Rate Plan Charge when a subscription has a recurring charge type.
enum:
- In Advance
- In Arrears
chargedThroughDate:
type: string
format: date
description: |
The date through which a customer has been billed for the charge.
maxLength: 29
chargeModel:
type: string
description: |
Determines how to evaluate charges. Charge models must be individually activated in the web-based UI.
**Values**: inherited from `ProductRatePlanCharge.ChargeModel`
chargeNumber:
description: |
A unique number that identifies the charge. This number is returned as a string.
**Values**: one of the following:
- automatically generated if left `null`
- a unique number of 50 characters or fewer
type: string
chargeType:
type: string
description: |
Specifies the type of charge.
**Values**: inherited from `ProductRatePlanCharge.ChargeType`
description:
type: string
description: |
A description of the rate plan charge.
discountLevel:
type: string
description: |
Application scope of the discount charge. For example, if the value of this field is `subscription` and the value of the `applyDiscountTo` field is `RECURRING`, the discount charge applies to all recurring charges in the same subscription as the discount charge.
enum:
- rateplan
- subscription
- account
dMRC:
type: number
description: |
A delta monthly recurring charge is the change in monthly
recurring revenue caused by an amendment or a new subscription.
**Values**: automatically generated
drawdownRate:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
The [conversion rate](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_drawdown_charge#UOM_Conversion) between Usage UOM and Drawdown UOM for a [drawdown charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_drawdown_charge). Must be a positive number (>0).
type: number
dTCV:
type: number
description: |
After an Amendment, the change in the total contract value (TCV) amount for this charge, compared with its previous value.
**Values**: automatically generated
effectiveEndDate:
type: string
format: date
description: |
Start date when the rate plan charge becomes active, as `yyyy-mm-dd`.
effectiveStartDate:
type: string
format: date
description: |
Final date the rate plan is active, as `yyyy-mm-dd`.
endDateCondition:
description: |
Condition for the charge to become inactive.
- If the value of this field is `FixedPeriod`, the charge is active for a predefined duration based on the value of the `upToPeriodsType` and `upToPeriods` fields.
- If the value of this field is `SpecificEndDate`, use the `specificEndDate` field to specify the date when the charge becomes inactive.
enum:
- SubscriptionEnd
- FixedPeriod
- SpecificEndDate
- OneTime
type: string
excludeItemBillingFromRevenueAccounting:
default: false
description: |
The flag to exclude rate plan charge related invoice items, invoice item adjustments, credit memo items, and debit memo items from revenue accounting.
If both the following features are enabled in your tenant, you must ensure the `excludeItemBillingFromRevenueAccounting` field is set consistently for a prepayment charge and the corresponding drawdown charge. In addition, if the `excludeItemBookingFromRevenueAccounting` field in an Create Subscription or Add Product order action is set to `false`, you must also set the `excludeItemBillingFromRevenueAccounting` field in this order action to `false`.
* Prepaid with Drawdown
* Unbilled Usage
**Note**: This field is only available if you have the Order to Revenue or [Zuora Billing - Revenue Integration](https://knowledgecenter.zuora.com/Zuora_Revenue/Zuora_Billing_-_Revenue_Integration) feature enabled.
type: boolean
excludeItemBookingFromRevenueAccounting:
default: false
description: |
The flag to exclude rate plan charges from revenue accounting.
If both the following features are enabled in your tenant, you must ensure the `excludeItemBookingFromRevenueAccounting` field is set consistently for a prepayment charge and the corresponding drawdown charge.
* Prepaid with Drawdown
* Unbilled Usage
**Note**: This field is only available if you have the Order to Revenue or [Zuora Billing - Revenue Integration](https://knowledgecenter.zuora.com/Zuora_Revenue/Zuora_Billing_-_Revenue_Integration) feature enabled.
type: boolean
invoiceScheduleId:
type: string
description: |
The unique identifier of the invoice schedule associated with the subscription.
isLastSegment:
type: boolean
description: |
Indicates if the segment of the rate plan charge is the most recent segment. **Values**: automatically generated.
isPrepaid:
type: boolean
description: |
**Note**: This field is only available if you have the [Prepaid with
Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown)
feature enabled.
Indicates whether this charge is a prepayment (topup) charge or a
drawdown charge.
isRollover:
type: boolean
description: |
**Note**: This field is only available if you have the Prepaid with Drawdown feature enabled.
It determines whether the rollover fields are needed.
rolloverPeriods:
type: integer
format: int64
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
This field defines the number of rollover periods, it is restricted to 3.
rolloverPeriodLength:
type: integer
format: int32
nullable: true
description: |
**Note**: This field is only available if you have the [Prepaid with
Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown)
feature enabled.
Use this field when you want to set the rollover fund's period length shorter than the prepayment charge's validity period. In this case, you must set the `rolloverPeriods` field to 1. For example, you can define the rollover fund's period length as 5 months, shorter than the prepayment charge's validity period: a year.
rolloverApply:
type: string
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
This field defines the priority of rollover, which is either first or last.
enum:
- ApplyFirst
- ApplyLast
isProcessed:
type: boolean
description: |
Indicates whether the rate plan charge has been processed.
listPriceBase:
type: string
description: |
The list price base for the product rate plan charge.
enum:
- Per Billing Period
- Per Month
- Per Week
- Per Year
- Per Specific Months
specificListPriceBase:
type: integer
format: int32
description: |
The number of months for the list price base of the charge. This field is required if you set the value of the `ListPriceBase` field to `Per Specific Months`.
**Notes**:
- This field is available only if you have the Annual List Price feature enabled.
- The value of this field is `null` if you do not set the value of the `ListPriceBase` field to `Per Specific Months`.
maximum: 200
minimum: 1
nullable: true
priceUpsellQuantityStacked:
type: boolean
commitmentType:
description: |
**Note**: This field is only available if you have the Unbilled Usage feature enabled.
To use this field, you must set the `X-Zuora-WSDL-Version` request header to `133` or higher. Otherwise, an error occurs.
This field defines the type of commitment. A prepaid charge can be `UNIT` or `CURRENCY`. A minimum commitment(in-arrears) charge can only be `CURRENCY` type. For topup(recurring or one-time) charges, this field indicates what type of funds are created.
* If UNIT, it will create a fund with given prepaidUom.
* If CURRENCY, it will create a fund with the currency amount calculated in list price.
For drawdown(usage) charges, this field indicates what type of funds are drawdown from that created from topup charges.
enum:
- UNIT
- CURRENCY
type: string
isCommitted:
type: boolean
description: |
Indicates whether the rate plan charge is commited.
mRR:
type: number
description: |
Monthly recurring revenue (MRR) is the amount of recurring
charges in a given month. The MRR calculation doesn't include one-time
charges nor usage charges. **Values**: automatically
generated
name:
type: string
maxLength: 100
description: |
The name of the rate plan charge. **Values**: automatically generated
numberOfPeriods:
type: integer
format: int64
description: |
Specifies the number of periods to use when calculating charges in an overage smoothing charge model. **Values**: inherited from `ProductRatePlanCharge.NumberOfPeriod`.
originalId:
type: string
maxLength: 32
description: |
The original ID of the rate plan charge. **Values**: automatically generated.
overageCalculationOption:
type: string
maxLength: 20
description: |
Determines when to calculate overage charges. If the value of the SmoothingMode field is null (not specified and not inherited from ProductRatePlanCharge.SmoothingMode), the value of this field is ignored.
**Values**: inherited from `ProductRatePlanCharge.OverageCalculationOption`.
overageUnusedUnitsCreditOption:
type: string
maxLength: 20
description: |
Determines whether to credit the customer with unused units of usage. **Values**: inherited from `ProductRatePlanCharge.OverageUnusedUnitsCreditOption`.
prepaidOperationType:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
The type of this charge. It is either a prepayment (topup) charge or a drawdown charge.
enum:
- topup
- drawdown
- null
type: string
nullable: true
prepaidQuantity:
type: number
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
The number of units included in a [prepayment charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge). Must be a positive number (>0).
nullable: true
prepaidTotalQuantity:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
The total amount of units that end customers can use during a validity period when they subscribe to a [prepayment charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge).
type: number
nullable: true
priceChangeOption:
type: string
description: |
Applies an automatic price change when a termed subscription is renewed.
**Values**: one of the following:
- `NoChange` (default)
- `SpecificPercentageValue`
- `UseLatestProductCatalogPricing`
priceIncreasePercentage:
type: number
format: double
description: |
Specifies the percentage to increase or decrease the price of renewed subscriptions. **Values**: a decimal value between -100 and 100.
processedThroughDate:
type: string
format: date
maxLength: 29
description: |
The date until when charges have been processed. When billing in arrears, such as usage, this field value is the the same as the `ChargedThroughDate` value. This date is the earliest date when a charge can be amended.
**Values**: automatically generated.
prorationOption:
type: string
description: |
Determines how to prorate charges when a subscription is created or amended.
quantity:
type: number
description: |
The default quantity of units, such as the number of authors in a hosted wiki service. Valid for all charge models except for Flat Fee pricing. **Values**: a valid quantity value.
numberOfDeliveries:
type: number
description: |
Number of deliveries in the billing period for the charge segment.
The `numberOfDeliveries` is used for the Delivery Pricing charge model only.
**Note**: The Delivery Pricing charge model is in the **Early Adopter** phase. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available. To manage and access this feature through the self-service interface, see [Enable billing features by yourself](https://knowledgecenter.zuora.com/Zuora_Billing/Bill_your_customers/Billing_Settings/Manage_Features) in the Knowledge Center. You can check **Delivery Pricing** in **Billing Settings** > **Enable Charge Types / Models**.
ratingGroup:
type: string
description: |
A rating group based on which usage records are rated. Only applicable to Usage charges.
Possible values:
- `ByBillingPeriod`: The rating is based on all the usages in a billing period.
- `ByUsageStartDate`: The rating is based on all the usages on the same usage start date.
- `ByUsageRecord`: The rating is based on each usage record.
- `ByUsageUpload`: The rating is based on all the usages in a uploaded usage file (`.xls` or `.csv`).
- `ByGroupId`: The rating is based on all the usages in a custom group.
For more information, see [Usage rating by group](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Usage/Usage_Rating_by_Group).
enum:
- ByBillingPeriod
- ByUsageStartDate
- ByUsageRecord
- ByUsageUpload
- ByGroupId
revenueRecognitionRuleName:
type: string
description: |
Specifies the Revenue Recognition Rule that you want the Rate Plan Charge to use. This field can be updated when **Status** is `Draft`.
By default, the Revenue Recognition Rule is inherited from the Product Rate Plan Charge. For Amend calls, you can use this field only for NewProduct amendments.
For Update calls, you can use this field only to update subscriptions in draft status. Note that if you use this field to specify a Revenue Recognition Rule for the Rate Plan Charge,
the rule will remain as specified even if you later change the rule used by the corresponding Product Rate Plan Charge.
**Values**: inherited from `ProductRatePlanCharge.RevenueRecognitionRuleName` or the name of an active Revenue Recognition Rule
**Note**: Unless overridden, this value changes if `ProductRatePlanCharge.RevenueRecognitionRuleName` is updated.
The values of `UpdatedById` and `UpdatedDate` for the `RatePlanCharge` do not change when `ProductRatePlanCharge.RevenueRecognitionRuleName` is updated.
revenueRecognitionTiming:
description: |
Specifies the type of revenue recognition timing.
Predefined options are listed as enum values in this API Reference. Other options might also be avaliable depending on the revenue recognition policy configuration in the Zuora Billing UI.
**Note**: This field is only available if you have the Order to Revenue feature enabled.
maxLength: 200
type: string
enum:
- Upon Billing Document Posting Date
- Upon Order Activation Date
revenueAmortizationMethod:
description: |
Specifies the type of revenue amortization method.
Predefined options are listed as enum values in this API Reference. Other options might also be avaliable depending on the revenue recognition policy configuration in the Zuora Billing UI.
**Note**: This field is only available if you have the Order to Revenue feature enabled.
maxLength: 200
type: string
enum:
- Immediate
- Ratable Using Start And End Dates
revRecCode:
type: string
maxLength: 70
description: |
Associates this product rate plan charge with a specific revenue recognition code.
**Values**: inherited from `ProductRatePlanCharge.RevRecCode` or a valid revenue recognition code
**Note**: Unless overridden, this value changes if `ProductRatePlanCharge.RevRecCode` is updated. The values of `UpdatedById` and `UpdatedDate` for the `RatePlanCharge` do not change when `ProductRatePlanCharge.RevRecCode` is updated.
revRecTriggerCondition:
type: string
maxLength: 22
description: |
Specifies when revenue recognition begins.
**Values**: inherited from `ProductRatePlanCharge.RevRecTriggerCondition` or one of the following:
- `ContractEffectiveDate`
- `ServiceActivationDate`
- `CustomerAcceptanceDate`
Note: Unless overridden, this value changes if `ProductRatePlanCharge.RevRecTriggerCondition` is updated. The values of `UpdatedById` and `UpdatedDate` for the `RatePlanCharge` do not change when `ProductRatePlanCharge.RevRecTriggerCondition` is updated.
segment:
type: integer
format: int32
description: |
The identifying number of the subscription rate plan segment. Segments are numbered sequentially, starting with 1.
**Values**: automatically generated
specificBillingPeriod:
type: integer
format: int64
description: |
Customizes the number of months or weeks for the charges billing period. This field is required if you set the value of the BillingPeriod field to `Specific Months` or `Specific Weeks`.
**Values**: inherited from `ProductRatePlanCharge.BillingPeriod`
**Note:** You can override the value inherited from the Product Rate Plan Charge, but only when creating a new subscription or a New Product amendment.
specificEndDate:
type: string
format: date
description: |
The specific date on which the charge ends, in `yyyy-mm-dd` format.
**Note**:
- This field is only applicable when the `EndDateCondition` field is set to `SpecificEndDate`.
- If the subscription ends before the specific end date, the charge ends when the subscription ends. But if the subscription end date is subsequently changed through a Renewal, or Terms and Conditions amendment, the charge will end on the specific end date.
tCV:
description: |2-
The total contract value (TCV) is the value of a single rate plan charge in a subscription over the lifetime of the subscription. This value does not represent all charges on the subscription. The TCV includes recurring charges and one-time charges, but it doesn't include usage charge.
**Values**: automatically generated
format: double
type: number
triggerDate:
description: |
The date when the charge becomes effective and billing begins, in `yyyy-mm-dd` format. This field is required if the `TriggerEvent` field value is `SpecificDate`.
format: date
type: string
triggerEvent:
description: |
Specifies when to start billing the customer for the charge.
**Note: **This field can be passed through the Subscribe and Amend calls and will override the default value set on the Product Rate Plan Charge.
**Values**: inherited from `ProductRatePlanCharge.TriggerEvent` and can be one of the following values:
- `ContractEffective` is the date when the subscription's contract goes into effect and the charge is ready to be billed.
- `ServiceActivation` is when the services or products for a subscription have been activated and the customers have access.
- `CustomerAcceptance` is when the customer accepts the services or products for a subscription.
- `SpecificDate` is valid only on the RatePlanCharge.
type: string
maxLength: 18
uOM:
description: |
Specifies the units to measure usage.
**Values**: inherited from `ProductRatePlanCharge.UOM`
type: string
maxLength: 25
upToPeriods:
type: integer
format: int64
description: |
Specifies the length of the period during which the charge is active. If this period ends before the subscription ends, the charge ends when this period ends.
**Values**: inherited from `ProductRatePlanCharge.UpToPeriods` **Note**:
- You must use this field together with the `UpToPeriodsType` field to specify the time period. This field is only applicable only when the `EndDateCondition` field is set to `FixedPeriod`.
- You can override the value inherited from the Product Rate Plan Charge, but only when creating a new subscription or a New Product amendment.
- Use this field to override the value in `ProductRatePlanCharge.UpToPeriod`.
- If you override the value in this field, enter a whole number between 0 and 65535, exclusive.
- If the subscription end date is subsequently changed through a Renewal, or Terms and Conditions amendment, the charge end date will change accordingly up to the original period end.
upToPeriodsType:
type: string
description: |
The period type used to define when the charge ends. This field can be updated when **Status** is `Draft`.
**Note**:
- You must use this field together with the `UpToPeriods` field to specify the time period.
- This field is only applicable only when the `EndDateCondition` field is set to `FixedPeriod`.
enum:
- Billing Periods
- Days
- Weeks
- Months
- Years
default: Billing Periods
version:
type: integer
format: int64
description: |
The version of the rate plan charge. Each time a charge is amended, Zuora creates a new version of the rate plan charge. **Values**: automatically generated.
weeklyBillCycleDay:
description: |
Specifies which day of the week as the bill cycle day (BCD) for the charge.
type: string
enum:
- Sunday
- Monday
- Tuesday
- Wednesday
- Thursday
- Friday
- Saturday
subscriptionId:
type: string
description: |
The unique identifier of the subscription to which the rate plan charge belongs.
subscriptionOwnerId:
type: string
description: |
ID of the account that owns the subscription.
invoiceOwnerId:
type: string
description: |
ID of the account that will pay the billing documents for the subscription.
originalOrderDate:
type: string
format: date
description: |
The date when the rate plan charge is created through an order or amendment. This field is to standardize the booking date information to increase audit ability and traceability of data between Zuora Billing and Zuora Revenue. It is mapped as the booking date for a sales order line in Zuora Revenue.
amendedByOrderOn:
type: string
format: date
description: |
The date when the rate plan charge is amended through an order
or amendment. This field is to standardize the booking date
information to increase audit ability and traceability of data
between Zuora Billing and Zuora Revenue. It is mapped as the
booking date for a sale order line in Zuora Revenue.
validityPeriodType:
type: string
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
The period in which the prepayment units are valid to use as defined in a [prepayment charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge).
enum:
- SUBSCRIPTION_TERM
- ANNUAL
- SEMI_ANNUAL
- QUARTER
- MONTH
creditOption:
type: string
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
The way to calculate credit. See [Credit Option](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge#Credit_Option) for more information.
enum:
- TimeBased
- ConsumptionBased
- FullCreditBack
applyToBillingPeriodPartially:
type: boolean
description: |
Allow the discount duration to be aligned with the billing period partially.
**Note**: You must enable the [Enhanced Discounts](https://knowledgecenter.zuora.com/Zuora_Billing/Build_products_and_prices/Basic_concepts_and_terms/B_Charge_Models/D_Manage_Enhanced_Discount) feature to access this field.
productChargeDefinitionId:
type: string
description: |
The unique ID of the product charge definition.
accountReceivableAccountingCodeId:
description: |
ID of the accountReceivableAccountingCode of a standalone charge.
**Note:** This field is available when the Standalone Orders, Zuora Finance, and Invoice Settlement features are enabled.
type: string
deferredRevenueAccountingCodeId:
description: |
ID of the deferredRevenueAccountingCode of a standalone charge.
**Note:** This field is available when the Standalone Orders and Zuora Finance features are enabled.
type: string
recognizedRevenueAccountingCodeId:
description: |
ID of the recognizedRevenueAccountingCode of a standalone charge.
**Note:** This field is available when the Standalone Orders and Zuora Finance features are enabled.
type: string
prepaidUOM:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
Unit of measurement for a [prepayment charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge).
type: string
drawdownUom:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
Unit of measurement for a [drawdown charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_drawdown_charge).
type: string
ratePlan:
type: object
description: |
The rate plan to which this charge belongs.
productRatePlanCharge:
type: object
description: |
The product rate plan charge associated with this rate plan charge.
salesPrice:
type: number
description: |
The sales price associated with the rate plan charge expressed as a decimal.
**Notes**:
- This field is only available to subscriptions that are created through orders and exist after 2023-01-10.
- This field applies to the following charge models, and the values vary with the charge models:
- Flat fee: the value equals the value of the `price` field.
- Per unit: the value equals `price` multiplied by `quantity`.
- Fixed amount discount: the value equals the value of the `discountAmount` field.
- Volume: The calculation of the tier price is dependent on whether the price format is the flat fee or per unit.
- Tiered: The calculation of the tier price is dependent on whether the price format is the flat fee or per unit.
taxable:
type: boolean
description: |
Indicates whether the rate plan charge is taxable.
reverted:
type: boolean
description: |
Indicates whether the rate plan charge has been reverted.
reflectDiscountInNetAmount:
type: boolean
description: |
Indicates whether the discount is reflected in the net amount.
additionalProperties:
type: object
description: |
Custom fields of the Rate Plan Charge object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryRatePlanChargeResponse
NestedCreditTaxationItemOnExpand:
properties:
appliedAmount:
description: |
The applied amount of the taxation item.
format: double
type: number
axemptAmount:
description: |
The calculated tax amount excluded due to the exemption.
format: double
type: number
jurisdiction:
description: |
The jurisdiction that applies the tax or VAT. This value is typically a state, province, county, or city.
type: string
locationCode:
description: |
The identifier for the location based on the value of the `taxCode` field.
type: string
name:
description: |
The name of the taxation item.
type: string
refundAmount:
description: |
The amount of the refund on the taxation item.
format: double
type: number
taxAmount:
description: |
The amount of taxation.
format: double
type: number
taxCode:
description: |
The tax code identifies which tax rules and tax rates to apply to a specific credit memo.
type: string
taxCodeDescription:
description: |
The description of the tax code.
type: string
taxDate:
description: |
The date that the tax is applied to the credit memo, in yyyy-mm-dd format.
type: string
format: date
taxMode:
description: |
The tax mode of the credit memo, indicating whether the amount of the credit memo includes tax.
enum:
- TaxExclusive
- TaxInclusive
type: string
taxRate:
description: |
The tax rate applied to the credit memo.
format: decimal
type: string
taxRateDescription:
description: |
The description of the tax rate.
type: string
taxRateType:
description: |
The type of the tax rate.
enum:
- Percentage
- FlatFee
type: string
unappliedAmount:
description: |
The unapplied amount of the taxation item.
format: double
type: number
creditMemoItemId:
description: |
The ID of the credit memo item.
type: string
taxableItemSnapshotId:
type: string
description: |
The unique identifier of the taxable item snapshot.
id:
type: string
description: |
The unique identifier of the taxation item.
createdById:
type: string
description: |
The unique identifier of the user who created the taxation item.
createdDate:
type: string
format: date-time
description: |
The date and time when the taxation item was created in the Zuora
system, in the `yyyy-mm-dd hh:mm:ss` format.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the taxation item.
updatedDate:
type: string
format: date-time
description: |
The date and time when the taxation item was last updated, in the `yyyy-mm-dd hh:mm:ss` format.
accountReceivableAccountingCodeId:
type: string
description: |
The accounting code for Account Receivable.
type: object
title: QueryCreditTaxationItemResponse
ExpandedDailyConsumptionSummary:
properties:
id:
type: string
description: The unique identifier of the daily consumption summary.
originChargeId:
type: string
description: The unique identifier of the charge.
chargeSegmentNumber:
type: integer
format: int32
description: |
The charge segment number.
fundId:
type: string
description: |
The unique identifier of the fund.
dailyConsumptionAmount:
type: number
description: |
The daily consumption amount.
dailyTotalQuantity:
type: number
description: |
The total quantity consumed daily.
transactionDate:
type: string
format: date
description: |
The date of the transaction.
ratingResultId:
type: string
description: |
The unique identifier of the rating result.
dailyGroupSummaryId:
type: string
description: |
The unique identifier of the daily group summary.
createdById:
type: string
description: |
The unique identifier of the user who created the daily consumption summary.
createdDate:
type: string
format: date-time
description: |
The date and time when the daily consumption summary was created.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the daily consumption summary.
updatedDate:
type: string
format: date-time
description: |
The date and time when the daily consumption summary was last updated.
drawdownOriginChargeId:
type: string
description: |
The unique identifier of the original drawdown charge.
drawdownChargeSegmentNumber:
type: integer
format: int32
description: |
The charge segment number of the drawdown charge.
drawdownRecognizedRevenueGlAccountNumber:
type: string
description: |
The GL account number of the recognized revenue for the drawdown charge.
drawdownAdjustmentRevenueGlAccountNumber:
type: string
description: |
The GL account number of the adjusted revenue for the drawdown charge.
usageChargeName:
type: string
description: |
The name of the usage charge.
usageChargeNumber:
type: string
description: |
The number of the usage charge.
type: object
title: QueryDailyConsumptionSummaryResponse
ExpandedDebitMemo:
properties:
id:
type: string
description: |
The unique identifier of the debit memo.
createdById:
type: string
description: |
The unique identifier of the user who created the debit memo.
createdDate:
type: string
format: date-time
description: |
The date and time when the debit memo was created.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the debit memo.
updatedDate:
type: string
format: date-time
description: |
The date and time when the debit memo was last updated.
autoPay:
description: |
Whether debit memos are automatically picked up for processing in the
corresponding payment run.
By default, debit memos are automatically picked up for processing in
the corresponding payment run.
type: boolean
creditMemoId:
type: string
description: |
The ID of the credit memo from which the debit memo was created.
nullable: true
balance:
type: number
description: |
The remaining balance of debit memo.
billToContactId:
description: |
The ID of the bill-to contact associated with the debit memo.
The value of this field is `null` if you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled.
type: string
billToContactSnapshotId:
description: |
The ID of the bill-to contact snapshot associated with the debit memo.
The value of this field is `null` if the bill rule [Preserve snapshot of bill-to and sold-to contacts when billing documents are posted](https://knowledgecenter.zuora.com/Zuora_Billing/Billing_and_Invoicing/Billing_Settings/Define_Billing_Rules#Preserve_snapshot_of_bill-to_and_sold-to_contacts_when_billing_documents_are_posted) is disabled.
type: string
cancelledById:
description: |
The ID of the Zuora user who cancelled the debit memo.
type: string
nullable: true
cancelledOn:
description: |
The date and time when the debit memo was cancelled, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
nullable: true
comments:
description: |
Comments about the debit memo.
type: string
currency:
description: |
The currency of the debit memo.
**Note:** By default, the currency on a billing document matches the default currency set on the associated account.
However, Zuora now offers a Multiple Currencies feature to support different currencies for billing documents, allowing flexibility beyond the account-level currency.
For more information, see Multiple Currency.
type: string
nullable: true
discountAmount:
type: number
description: |
The amount of the discount on the debit memo.
dueDate:
type: string
format: date
description: |
The date by which the payment for the debit memo is due, in
`yyyy-mm-dd` format.
einvoiceErrorCode:
description: |
The error code returned when the e-invoice file status is `Failed`. This code can either be a Zuora-generated error code or one returned by a third-party e-invoicing service provider.
**Note**: This field is available only if you have the E-Invoicing feature in **Early Adopter** phase enabled.
type: string
einvoiceErrorMessage:
description: |
The error message returned when the e-invoice file status is `Failed`. This message can either be a Zuora-generated error message or one returned by a third-party e-invoicing service provider.
**Note**: This field is available only if you have the E-Invoicing feature in **Early Adopter** phase enabled.
type: string
einvoiceFileId:
description: |
The ID of the e-invoice file generated for the debit memo.
**Note**: This field is available only if you have the E-Invoicing feature in **Early Adopter** phase enabled.
type: string
einvoiceStatus:
description: |
The status of the e-invoice file generation for the credit memo.
- If e-invoice file generation succeeds, this field is either `Generated` or `Success`, and both the error code and message are empty, and the `eInvoiceFileId` field stores the ID of the generated e-invoice file.
- If the responses from tax vendors such as Sovos or Avalara are
taking too long, this field becomes `RetrieveTimeOut`. Once the
vendor responds successfully, you can use the 'Resync E-Invoice Status'
action to update the status automatically. You can view these updates
in System Health telemetry.
- If a failure occurs during e-invoice file generation, this field is `Failed` and an error code and an error message are returned respectively in the `einvoiceErrorCode` and `einvoiceErrorMessage` fields.
- If e-invoice file generation conditionally succeeds, this field is
`ConditionalSuccess` and an error code and an error message are
returned respectively in the `einvoiceErrorCode` and `einvoiceErrorMessage` fields.
- If the e-invoice file has been approved by the tax authority, this
field is `ApprovedByAuthority`. The next status will be either
`Success` or `Rejected`.
- If the e-invoice file has been rejected by the government, this field
is `Rejected`. You cannot resend this e-invoice; you must create a
new invoice instead.
**Note**: This field is available only if you have the E-Invoicing feature in **Early Adopter** phase enabled.
enum:
- Processing
- RetrieveTimeOut
- Generated
- Success
- Failed
- ConditionalSuccess
- ApprovedByAuthority
- Rejected
type: string
exchangeRateDate:
type: string
format: date
description: |
The date of the exchange rate used. The date is in `yyyy-mm-dd` format.
Corresponds to the value specified in the Provider Exchange Rate Date column in the Import Foreign Exchange Rates template when you uploaded the rates through the Mass Updater.
memoDate:
type: string
format: date
description: |
The date when the debit memo takes effect, in `yyyy-mm-dd` format.
For example, `2024-01-01`.
memoNumber:
description: |
The unique identification number of the debit memo.
type: string
postedById:
description: |
The ID of the Zuora user who posted the debit memo.
type: string
postedOn:
description: |
The date and time when the debit memo was posted, in
`yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
reasonCode:
description: |
A code identifying the reason for the transaction. The value
must be an existing reason code or empty.
type: string
sequenceSetId:
description: |
The ID of the sequence set associated with the debit memo.
The value of this field is `null` if you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled.
type: string
nullable: true
source:
description: |
The source of the debit memo.
Possible values:
- `BillRun`: The debit memo is generated by a bill run.
- `API`
- `ApiSubscribe`: The debit memo is created by calling the [Create subscription](https://developer.zuora.com/api-references/api/operation/POST_Subscription) and [Create account](https://developer.zuora.com/api-references/api/operation/POST_Account) operation.
- `ApiAmend`: The debit memo is created by calling the [Update subscription](https://developer.zuora.com/api-references/api/operation/PUT_Subscription) operation.
- `AdhocFromPrpc`: The debit memo is created from a product rate plan charge through the Zuora UI or by calling the [Create a debit memo from a charge](https://developer.zuora.com/api-references/api/operation/POST_DebitMemoFromPrpc/) operation.
- `AdhocFromInvoice`: The debit memo is created from an invoice or created by reversing an invoice. You can create a debit memo from an invoice through the Zuora UI or by calling the [Create a debit memo from an invoice](https://developer.zuora.com/api-references/api/operation/POST_DebitMemoFromInvoice/) operation.
type: string
enum:
- BillRun
- API
- ApiSubscribe
- ApiAmend
- AdhocFromPrpc
- AdhocFromInvoice
sourceId:
description: |
The ID of the debit memo source.
If a debit memo is generated from a bill run, the value is the
number of the corresponding bill run. Otherwise, the value is
`null`.
type: string
sourceType:
description: |
The type of the debit memo source.
enum:
- Subscription
- Standalone
- Order
- Consolidation
- Invoice
- CreditMemo
type: string
status:
description: |
The status of the debit memo.
enum:
- Draft
- Posted
- Canceled
- Error
- PendingForTax
- Generating
- CancelInProgress
type: string
targetDate:
description: |
The target date for the debit memo, in `yyyy-mm-dd` format. For example, `2024-01-01`.
format: date
type: string
taxAmount:
description: |
The amount of taxation.
format: double
type: number
taxMessage:
description: |
The message about the status of tax calculation related to the
debit memo. If tax calculation fails in one debit memo, this
field displays the reason for the failure.
type: string
nullable: true
taxStatus:
description: |
The status of tax calculation related to the debit memo.
**Note**: This field is only applicable to tax calculation by
third-party tax engines. Also, the `Voided` status indicates that the tax transaction is successfully canceled on the tax vendor's side.
If a tax transaction was successfully committed to the third-party tax engine but the invoice failed to post, Zuora automatically detects
the issue and voids the tax transaction on the vendor's side.
enum:
- Complete
- Error
- UnknownError
- DuplicateDoc
- InvalidRequest
- InvalidResponse
- TaxEngineError
- ConcurrentModify
- InternalServerError
- TaxCodeTemplateError
- Voided
type: string
shipToContactSnapshotId:
description: |
The ID of the ship-to contact snapshot associated with the
debit memo.
**Note**: If you have the Flexible Billing Attributes feature
disabled, the value of this field is `null`.
type: string
soldToContactSnapshotId:
description: |
The ID of the sold-to contact snapshot associated with the
debit memo.
**Note**: If you have the Flexible Billing Attributes feature
disabled, the value of this field is `null`.
type: string
taxAutoCalculation:
default: true
description: |
Whether to automatically calculate taxes in the debit memo.
type: boolean
totalAmount:
type: number
format: double
description: |
The total amount of the debit memo, including taxes.
totalAmountWithoutTax:
type: number
format: double
description: |
The total amount of the debit memo, excluding taxes.
totalTaxExemptAmount:
description: |
The calculated tax amount excluded due to the exemption.
format: double
type: number
transferredToAccounting:
description: |
Whether the debit memo was transferred to an external
accounting system. This field is used for integration with
accounting systems such as NetSuite.
enum:
- Processing
- 'Yes'
- 'No'
- Error
- Ignore
type: string
invoiceId:
description: |
The ID of a referred invoice.
type: string
accountId:
description: |
The ID of the customer account associated with the debit memo.
type: string
paymentTerm:
type: string
description: |
The name of the payment term assoicated with the debit memo.
The value of this field is `null` if you have the [Flexible Billing
Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes)
feature disabled.
account:
$ref: '#/components/schemas/NestedAccountOnExpand'
billToContact:
$ref: '#/components/schemas/ExpandedContact'
debitMemoItems:
type: array
items:
$ref: '#/components/schemas/NestedDebitMemoItemOnExpand'
billToContactSnapshot:
$ref: '#/components/schemas/NestedContactSnapshotOnExpand'
soldToContactSnapshot:
$ref: '#/components/schemas/NestedContactSnapshotOnExpand'
shipToContactSnapshot:
$ref: '#/components/schemas/NestedContactSnapshotOnExpand'
additionalProperties:
type: object
description: |
Custom fields of the Debit Memo object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryDebitMemoResponse
NestedDebitMemoItemOnExpand:
properties:
id:
type: string
description: |
The unique identifier of the debit memo item.
createdById:
type: string
description: |
The unique identifier of the user who created the debit memo item.
createdDate:
type: string
format: date-time
description: |
The date and time when the debit memo item was created.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the debit memo item.
updatedDate:
type: string
format: date-time
description: |
The date and time when the debit memo item was last updated.
amount:
description: |
The amount of the debit memo item. For tax-inclusive debit memo items, the amount indicates the debit memo item amount including tax. For tax-exclusive debit memo items, the amount indicates the debit memo item amount excluding tax.
format: double
type: number
amountWithoutTax:
description: |
The debit memo item amount excluding tax.
format: double
type: number
appliedToItemId:
type: string
description: |
The parent debit memo item that this debit memo items is applied to if this item is discount.
appliedToOthersAmount:
type: number
beAppliedByOthersAmount:
type: number
chargeDate:
type: string
description: |
The date when the debit memo item is charged, in `yyyy-mm-dd hh:mm:ss`
format.
format: date-time
creditMemoItemId:
type: string
excludeItemBillingFromRevenueAccounting:
description: |
The flag to exclude the debit memo item from revenue accounting.
**Note**: This field is only available if you have the Billing - Revenue Integration feature enabled.
type: boolean
description:
type: string
description: |
The description of the debit memo item.
itemShipToContactId:
description: |
The ID of the ship-to contact associated with the debit memo item.
**Note**: If you have the Flexible Billing Attributes feature disabled, the value of this field is `null`.
itemSoldToContactId:
description: |
The ID of the sold-to contact associated with the debit memo item.
**Note**: If you have the Flexible Billing Attributes feature disabled, the value of this field is `null`.
type: string
itemSoldToContactSnapshotId:
description: |
The ID of the sold-to contact snapshot associated with the debit memo item.
**Note**: If you have the Flexible Billing Attributes feature disabled, the value of this field is `null`.
type: string
processingType:
description: |
The type of the charge for the debit memo item.
- `0`: charge - `1`: discount
type: string
enum:
- '0'
- '1'
quantity:
description: |
The number of units for the debit memo item.
format: double
type: number
reflectDiscountInNetAmount:
type: boolean
default: false
description: |
When you apply percentage discounts to either of the following charges, you need to set the `reflectDiscountInNetAmount` field on your discount charge to `true`, to enable calculating and displaying the net amount of the following charges in Zuora Revenue.
* delivery pricing charge
* prepayment charge
* drawdown charge
Note the following:
* If you are an Order to Revenue customer, when you set the `reflectDiscountInNetAmount` field to `true`, you must also set the `excludeItemBillingFromRevenueAccounting` field to `true`.
* If you are a Billing - Revenue Integration customer, you must set the `reflectDiscountInNetAmount` field to `false`, otherwise an error will be returned. Billing - Revenue Integration does not support discounts on the preceding charges.
* If you are a Zuora Billing customer who does not enable the Order to Revenue or Billing - Revenue Integration feature, when you apply percentage discounts to the preceding charges, you also need to set the `reflectDiscountInNetAmount` field to `true`.
serviceEndDate:
description: |
The end date of the service period associated with this debit memo item. Service ends one second before the date specified in this field.
format: date
type: string
serviceStartDate:
description: |
The start date of the service period associated with this debit memo item. If the associated charge is a one-time fee, this date is the date of that charge.
format: date
type: string
sku:
type: string
description: |
The SKU for the product associated with the debit memo item.
sourceItemType:
description: |
The type of the source item.
enum:
- CreditMemoItem
- SubscriptionComponent
- InvoiceDetail
- ProductRatePlanCharge
type: string
chargeName:
type: string
description: |
The name of the charge associated with the debit memo item.
chargeNumber:
type: string
description: |
The number of the charge associated with the debit memo item.
taxAmount:
type: number
description: |
The amount of tax on this debit memo.
format: double
taxCodeName:
type: string
description: |
Name of the tax code identifies which tax rules and tax rates to apply to a specific debit memo item.
taxExemptAmount:
type: number
description: |
The calculated tax amount excluded due to the exemption.
format: double
taxMode:
description: |
The tax mode of the debit memo item, indicating whether the amount of the debit memo item includes tax.
enum:
- TaxExclusive
- TaxInclusive
type: string
unitOfMeasure:
description: |
The units to measure usage.
type: string
unitPrice:
description: |
The per-unit price of the debit memo item.
format: double
type: number
subscriptionId:
type: string
description: |
The ID of the subscription associated with the debit memo item.
subscriptionNumber:
type: string
description: |
The number of the subscription associated with the debit memo item.
invoiceItemId:
type: string
description: |
The ID of the invoice item associated with the debit memo item.
productRatePlanChargeId:
type: string
description: |
The ID of the product rate plan charge based on which the debit memo item is created.
ratePlanChargeId:
type: string
description: |
The ID of the rate plan charge associated with the debit memo item.
debitMemoId:
type: string
description: |
The ID of the debit memo to which this debit memo item belongs.
balance:
type: number
description: |
The balance of the debit memo item.
format: double
recognizedRevenueAccountingCodeId:
type: string
description: |
The Recognized Revenue accounting code for the credit memo item.
accountReceivableAccountingCodeId:
type: string
description: |
The Account Receivable accounting code for the credit memo item.
deferredRevenueAccountingCodeId:
type: string
description: |
The Deferred Revenue accounting code for the credit memo item.
journalEntryId:
type: string
description: |
The ID of the journal entry that corresponds to this transaction.
soldToContactSnapshotId:
description: |
The ID of the sold-to contact snapshot associated with the credit memo.
type: string
billToContactSnapshotId:
description: |
The ID of the bill-to contact snapshot associated with the credit memo.
type: string
subscription:
type: object
description: |
The subscription associated with the debit memo item.
ratePlanCharge:
type: object
description: |
The rate plan charge associated with the debit memo item.
additionalProperties:
type: object
description: |
Custom fields of the Debit Memo Item object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryDebitMemoItemResponse
ExpandedDebitMemoItem:
properties:
id:
type: string
description: |
The unique identifier of the debit memo item.
createdById:
type: string
description: |
The unique identifier of the user who created the debit memo item.
createdDate:
type: string
format: date-time
description: |
The date and time when the debit memo item was created.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the debit memo item.
updatedDate:
type: string
format: date-time
description: |
The date and time when the debit memo item was last updated.
amount:
description: |
The amount of the debit memo item. For tax-inclusive debit memo items, the amount indicates the debit memo item amount including tax. For tax-exclusive debit memo items, the amount indicates the debit memo item amount excluding tax.
format: double
type: number
amountWithoutTax:
description: |
The debit memo item amount excluding tax.
format: double
type: number
appliedToItemId:
type: string
description: |
The parent debit memo item that this debit memo items is applied to if this item is discount.
appliedToOthersAmount:
type: number
beAppliedByOthersAmount:
type: number
chargeDate:
type: string
description: |
The date when the debit memo item is charged, in `yyyy-mm-dd hh:mm:ss`
format.
format: date-time
creditMemoItemId:
type: string
excludeItemBillingFromRevenueAccounting:
description: |
The flag to exclude the debit memo item from revenue accounting.
**Note**: This field is only available if you have the Billing - Revenue Integration feature enabled.
type: boolean
description:
type: string
description: |
The description of the debit memo item.
itemShipToContactId:
description: |
The ID of the ship-to contact associated with the debit memo item.
**Note**: If you have the Flexible Billing Attributes feature disabled, the value of this field is `null`.
type: string
itemSoldToContactId:
description: |
The ID of the sold-to contact associated with the debit memo item.
**Note**: If you have the Flexible Billing Attributes feature disabled, the value of this field is `null`.
type: string
itemSoldToContactSnapshotId:
description: |
The ID of the sold-to contact snapshot associated with the debit memo item.
**Note**: If you have the Flexible Billing Attributes feature disabled, the value of this field is `null`.
type: string
processingType:
description: |
The type of the charge for the debit memo item.
- `0`: charge - `1`: discount
type: string
enum:
- '0'
- '1'
quantity:
description: |
The number of units for the debit memo item.
format: double
type: number
reflectDiscountInNetAmount:
type: boolean
default: false
description: |
When you apply percentage discounts to either of the following charges, you need to set the `reflectDiscountInNetAmount` field on your discount charge to `true`, to enable calculating and displaying the net amount of the following charges in Zuora Revenue.
* delivery pricing charge
* prepayment charge
* drawdown charge
Note the following:
* If you are an Order to Revenue customer, when you set the `reflectDiscountInNetAmount` field to `true`, you must also set the `excludeItemBillingFromRevenueAccounting` field to `true`.
* If you are a Billing - Revenue Integration customer, you must set the `reflectDiscountInNetAmount` field to `false`, otherwise an error will be returned. Billing - Revenue Integration does not support discounts on the preceding charges.
* If you are a Zuora Billing customer who does not enable the Order to Revenue or Billing - Revenue Integration feature, when you apply percentage discounts to the preceding charges, you also need to set the `reflectDiscountInNetAmount` field to `true`.
serviceEndDate:
description: |
The end date of the service period associated with this debit memo item. Service ends one second before the date specified in this field.
format: date
type: string
serviceStartDate:
description: |
The start date of the service period associated with this debit memo item. If the associated charge is a one-time fee, this date is the date of that charge.
format: date
type: string
sku:
type: string
description: |
The SKU for the product associated with the debit memo item.
sourceItemType:
description: |
The type of the source item.
enum:
- CreditMemoItem
- SubscriptionComponent
- InvoiceDetail
- ProductRatePlanCharge
type: string
chargeName:
type: string
description: |
The name of the charge associated with the debit memo item.
chargeNumber:
type: string
description: |
The number of the charge associated with the debit memo item.
taxAmount:
type: number
description: |
The amount of tax on this debit memo.
format: double
taxCodeName:
type: string
description: |
Name of the tax code identifies which tax rules and tax rates to apply to a specific debit memo item.
taxExemptAmount:
type: number
description: |
The calculated tax amount excluded due to the exemption.
format: double
taxMode:
description: |
The tax mode of the debit memo item, indicating whether the amount of the debit memo item includes tax.
enum:
- TaxExclusive
- TaxInclusive
type: string
unitOfMeasure:
description: |
The units to measure usage.
type: string
unitPrice:
description: |
The per-unit price of the debit memo item.
format: double
type: number
subscriptionId:
type: string
description: |
The ID of the subscription associated with the debit memo item.
subscriptionNumber:
type: string
description: |
The number of the subscription associated with the debit memo item.
invoiceItemId:
type: string
description: |
The ID of the invoice item associated with the debit memo item.
productRatePlanChargeId:
type: string
description: |
The ID of the product rate plan charge based on which the debit memo item is created.
ratePlanChargeId:
type: string
description: |
The ID of the rate plan charge associated with the debit memo item.
debitMemoId:
type: string
description: |
The ID of the debit memo to which this debit memo item belongs.
balance:
type: number
description: |
The balance of the debit memo item.
format: double
recognizedRevenueAccountingCodeId:
type: string
description: |
The Recognized Revenue accounting code for the debit memo item.
accountReceivableAccountingCodeId:
type: string
description: |
The Account Receivable accounting code for the debit memo item.
deferredRevenueAccountingCodeId:
type: string
description: |
The Deferred Revenue accounting code for the debit memo item.
journalEntryId:
type: string
description: |
The ID of the journal entry that corresponds to this debit memo item.
shipToContactSnapshotId:
description: |
The ID of the ship-to contact snapshot associated with the debit memo.
type: string
soldToContactSnapshotId:
description: |
The ID of the sold-to contact snapshot associated with the debit memo.
type: string
billToContactSnapshotId:
description: |
The ID of the bill-to contact snapshot associated with the debit memo.
type: string
subscription:
$ref: '#/components/schemas/NestedSubscriptionOnExpand'
ratePlanCharge:
$ref: '#/components/schemas/NestedRatePlanChargeOnExpand'
subscriptionOwner:
$ref: '#/components/schemas/NestedAccountOnExpand'
debitTaxationItems:
$ref: '#/components/schemas/NestedDebitTaxationItemOnExpand'
additionalProperties:
type: object
description: |
Custom fields of the Debit Memo Item object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryDebitMemoItemResponse
NestedDebitTaxationItemOnExpand:
properties:
balance:
description: |
The balance of the taxation item.
format: double
type: number
creditAmount:
description: |
The amount of credit memos applied to the debit memo.
format: double
type: number
exemptAmount:
description: |
The calculated tax amount excluded due to the exemption.
format: double
type: number
jurisdiction:
description: |
The jurisdiction that applies the tax or VAT. This value is typically a state, province, county, or city.
type: string
locationCode:
description: |
The identifier for the location based on the value of the `taxCode` field.
type: string
name:
description: |
The name of the taxation item.
type: string
paymentAmount:
description: |
The amount of payments applied to the debit memo.
format: double
type: number
taxAmount:
description: |
The amount of taxation.
format: double
type: number
taxCode:
description: |
The tax code identifies which tax rules and tax rates to apply to a specific debit memo.
type: string
taxCodeDescription:
description: |
The description of the tax code.
type: string
taxDate:
description: |
The date that the tax is applied to the debit memo, in yyyy-mm-dd format.
type: string
format: date
taxMode:
description: |
The tax mode of the debit memo, indicating whether the amount of the debit memo includes tax.
enum:
- TaxExclusive
- TaxInclusive
type: string
taxRate:
description: |
The tax rate applied to the debit memo.
format: decimal
type: string
taxRateDescription:
description: |
The description of the tax rate.
type: string
taxRateType:
description: |
The type of the tax rate.
enum:
- Percentage
- FlatFee
type: string
debitMemoItemId:
description: |
The ID of the debit memo item.
type: string
taxableItemSnapshotId:
type: string
description: |
The unique identifier of the taxable item snapshot.
taxationItemId:
description: |
The Id of the taxation item.
type: string
id:
type: string
description: |
The unique identifier of the taxation item.
createdById:
type: string
description: |
The unique identifier of the user who created the taxation item.
createdDate:
type: string
format: date-time
description: |
The date and time when the taxation item was created in the Zuora
system, in the `yyyy-mm-dd hh:mm:ss` format.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the taxation item.
updatedDate:
type: string
format: date-time
description: |
The date and time when the taxation item was last updated, in the `yyyy-mm-dd hh:mm:ss` format.
accountReceivableAccountingCodeId:
type: string
description: |
The accounting code for Account Receivable.
type: object
title: QueryDebitTaxationItemResponse
ExpandedDeliveryAdjustment:
properties:
id:
type: string
description: |
The unique identifier of the delivery adjustment.
createdById:
type: string
description: |
The unique identifier of the user who created the delivery adjustment.
createdDate:
type: string
format: date-time
description: |
The date and time when the delivery adjustment was created.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the delivery adjustment.
updatedDate:
type: string
format: date-time
description: |
The date and time when the delivery adjustment was last updated.
adjustmentNumber:
type: string
description: |
The system-generated delivery adjustment number.
creditMemoNumber:
type: string
description: |
Number of the credit memo generated for the delivery adjustment.
debitMemoNumber:
description: |
The Debit Memo generated to write off the Credit Memo for the delivery adjustment.
type: string
creditMemoId:
type: string
description: |
The ID of the credit memo generated for the delivery adjustment.
segmentId:
type: string
description: |
The ID of the segment on the subscription for which the delivery adjustment is created.
chargeId:
type: string
description: |
The charge ID in the subscription for which the delivery
adjustment is created.
chargeNumber:
description: |
The charge number in the subscription for which the delivery
adjustment is created.
type: string
subscriptionId:
type: string
description: |
The ID of the subscription for which the delivery
adjustment is created.
subscriptionNumber:
description: |
The number of the subscription for which the delivery adjustment is created.
type: string
originalSubId:
type: string
description: |
The original subscription ID.
status:
description: |
The status of the delivery adjustment.
type: string
enum:
- Billed
- Cancelled
numberOfDeliveries:
description: |
The total number of all delivery adjustments.
type: number
amountPerUnit:
type: number
description: |
The actual charged amount per unit for the delivery adjustment.
amount:
description: |
The amount of the delivery adjustment.
type: number
date:
type: string
description: |
The delivery adjustment date, in `yyyy-mm-dd` format.
format: date
deliveryDay:
type: string
description: |
The delivery adjustment day of the week.
reason:
description: |
The reason for the delivery adjustment.
type: string
type:
type: string
description: |
The type of delivery adjustment.
enum:
- DeliveryCredit
accountId:
type: string
description: |
The ID of the account who owns the delivery adjustment.
invoiceOwnerAccountId:
type: string
description: |
The account ID of the invoice owner who owns the delivery adjustment.
accountingCode:
type: string
description: |
The accounting code associated with the delivery adjustment.
deferredAccountingCode:
type: string
description: |
The accounting code for the deferred revenue, such as Monthly Recurring Liability.
**Note**: For the credit memo generated by the delivery adjustment, if this field is not specified, the value inherits from the subscription rate plan charge.
recognizedRevenueAccountingCode:
type: string
description: |
The accounting code for the recognized revenue, such as Monthly
Recurring Charges or Overage Charges.
**Note**: For the credit memo generated by the delivery adjustment, if this field is not specified, the value inherits from the subscription rate plan charge.
revenueRecognitionRuleName:
description: |
The name of the revenue recognition rule governing the revenue
schedule.
**Note**: For the credit memo generated by the delivery adjustment, if this field is not specified, the value inherits from the subscription rate plan charge.
type: string
billingDate:
description: |
The billing date is same as the delivery date of the delivery adjustment, in `yyyy-mm-dd` format.
format: date
type: string
additionalProperties:
type: object
description: |
Custom fields of the Delivery Adjustment object. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryDeliveryAdjustmentResponse
ExpandedFulfillment:
properties:
id:
type: string
description: |
The unique identifier of the fulfillment.
createdById:
type: string
description: |
The unique identifier of the user who created the fulfillment.
createdDate:
type: string
format: date-time
description: |
The date and time when the fulfillment was created.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the fulfillment.
updatedDate:
type: string
format: date-time
description: |
The date and time when the fulfillment was last updated.
orderLineItemId:
type: string
description: |
ID of the order line item.
fulfillmentNumber:
description: The sytem generated number for the fulfillment.
type: string
fulfillmentType:
description: |
The type of the fulfillment.
enum:
- Delivery
- Return
type: string
fulfillmentDate:
description: |
The date of the fulfillment.
format: date
type: string
quantity:
description: |
The quantity of the fulfillment.
type: number
state:
description: |
The state of the fulfillment. See Order Line Item states, Order states, and state transitions for more information.
enum:
- Executing
- Booked
- SentToBilling
- Complete
- Cancelled
type: string
trackingNumber:
description: |
The tracking number of the fulfillment.
type: string
billTargetDate:
description: |
The target date for the fulfillment to be picked up by bill run for billing.
format: date
type: string
description:
description: The description of the fulfillment.
type: string
carrier:
description: |
The carrier of the fulfillment. The available values can be managed in the Fulfillment Settings page under Billing Settings.
type: string
fulfillmentLocation:
description: |
The location of the fulfillment. The available values can be managed in the Fulfillment Settings page under Billing Settings.
type: string
fulfillmentSystem:
description: |
The system of the fulfillment. The available values can be managed in the Fulfillment Settings page under Billing Settings.
type: string
externalId:
description: |
The external ID of the fulfillment.
type: string
excludeItemBookingFromRevenueAccounting:
description: |
The flag to exclude fulfillment item from revenue accounting.
**Note**: This field is only available if you have the Order to Revenue or Zuora Billing - Revenue Integration feature enabled.
type: boolean
excludeItemBillingFromRevenueAccounting:
description: |
The flag to exclude fulfillment item from revenue accounting.
**Note**: This field is only available if you have the Order to Revenue or Zuora Billing - Revenue Integration feature enabled.
type: boolean
additionalProperties:
type: object
description: |
Custom fields of the Fulfillment object. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryFulfillmentResponse
ExpandedInvoice:
properties:
id:
type: string
description: |
The unique identifier of the invoice.
createdById:
type: string
description: |
The unique identifier of the user who created the invoice.
createdDate:
type: string
format: date-time
description: |
The time that the invoice gets created in the system, in the
`YYYY-MM-DD HH:MM:SS` format.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the invoice.
updatedDate:
type: string
format: date-time
description: |
The time that the invoice gets updated in the system, in the
`YYYY-MM-DD HH:MM:SS` format.
accountId:
description: |
The ID of the customer account associated with the invoice.
type: string
adjustmentAmount:
description: |
The amount of the invoice adjustments associated with the invoice.
format: double
type: number
amount:
description: |
The total amount of the invoice.
format: double
type: number
amountWithoutTax:
description: |
The invoice amount excluding tax.
format: double
type: number
autoPay:
description: |
Whether invoices are automatically picked up for processing in the corresponding payment run.
type: boolean
balance:
description: |
The remaining balance of the invoice after all payments, adjustments, and refunds are applied.
type: number
format: double
billToContactId:
description: |
The ID of the bill-to contact associated with the invoice.
type: string
billToContactSnapshotId:
description: |
The ID of the bill-to contact snapshot associated with the invoice.
type: string
comments:
type: string
description: |
Comments about the invoice.
creditBalanceAdjustmentAmount:
description: |
The currency amount of the adjustment applied to the customer's credit balance.
**Note:** This field is only available if you have the Credit Balance feature enabled and the Invoice Settlement feature disabled.
format: double
type: number
creditMemoAmount:
description: |
The currency amount of all credit memos applied to this invoice.
**Note:** This field is only available if you have [Invoice Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement) 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.
format: double
type: number
currency:
description: |
The currency of the invoice.
**Note:** By default, the currency on a billing document matches the default currency set on the associated account.
However, Zuora now offers a Multiple Currencies feature to support different currencies for billing documents, allowing flexibility beyond the account-level currency.
For more information, see Multiple Currency.
nullable: true
type: string
dueDate:
type: string
format: date
description: |
The date by which the payment for this invoice is due, in `yyyy-mm-dd` format.
includesOneTime:
description: |
Specifies whether the invoice includes one-time charges.
type: boolean
includesRecurring:
description: |
Specifies whether the invoice includes recurring charges.
type: boolean
includesUsage:
description: |
Specifies whether the invoice includes usage charges.
type: boolean
invoiceDate:
description: |
The date that appears on the invoice being created.
format: date
type: string
invoiceNumber:
description: |
The unique identification number of the invoice.
type: string
lastEmailSentDate:
description: |
The date when the invoice was last emailed.
type: string
organizationId:
type: string
description: |
ID of the organization this object belongs to.
paymentAmount:
description: |
The amount of payments applied to the invoice.
format: double
type: number
postedBy:
description: |
The user ID of the person who moved the invoice to Posted status.
type: string
postedDate:
description: |
The date when the invoice was posted.
format: date-time
type: string
refundAmount:
description: |
Specifies the amount of a refund that was applied against an earlier payment on the invoice.
format: double
type: number
sequenceSetId:
description: |
The ID of the sequence set associated with the invoice.
type: string
nullable: true
communicationProfileId:
description: |
The ID of the communication profile associated with the invoice.
type: string
nullable: true
shipToContactId:
description: |
The ID of the ship-to contact associated with the invoice.
type: string
shipToContactSnapshotId:
description: |
The ID of the ship-to contact snapshot associated with the invoice.
type: string
soldToContactId:
description: |
The ID of the sold-to contact associated with the invoice.
type: string
soldToContactSnapshotId:
description: |
The ID of the sold-to contact snapshot associated with the invoice.
type: string
source:
description: |
The source of the invoice.
enum:
- BillRun
- API
- ApiSubscribe
- ApiAmend
type: string
sourceId:
description: |
The ID of the invoice source.
If an invoice is generated from a bill run, the value is the number of the corresponding bill run.Otherwise, the value is `null`.
type: string
reversed:
type: boolean
description: |
Whether the invoice is reversed.
sourceType:
description: |
The type of the invoice source.
enum:
- Subscription
- Standalone
- Order
- Consolidation
type: string
status:
description: |
The status of the invoice.
enum:
- Draft
- Posted
type: string
targetDate:
description: |
This date is used to determine which charges are to be billed. All charges that are to be billed on this date or prior will be included in this bill run.
format: date
type: string
taxAmount:
description: |
The amount of taxation.
format: double
type: number
taxExemptAmount:
description: |
The calculated tax amount excluded due to the exemption.
format: double
type: number
taxMessage:
description: |
The message that the tax engine return if it calculates the taxes of this invoice fails.
type: string
nullable: true
taxStatus:
description: |
The status that the tax engine return after it calculates the taxes of this invoice. Also, the `Voided` status indicates that the tax transaction is successfully canceled on the tax vendor's side. If a tax transaction was successfully committed to the third-party tax engine but the invoice failed to post, Zuora automatically detects the issue and voids the tax transaction on the vendor's side.
enum:
- Complete
- Error
- UnknownError
- DuplicateDoc
- InvalidRequest
- InvalidResponse
- TaxEngineError
- ConcurrentModify
- InternalServerError
- TaxCodeTemplateError
- Voided
type: string
templateId:
description: |
The ID of the invoice template.
- If you have the Flexible Billing Attributes feature enabled, the value of this field depends on the configuration of the invoice template.
- If you specify an invoice template at the subscription level, the value of this field is automatically populated from the corresponding subscription.
- If you do not specify any invoice template at the subscription level, the value of this field is automatically populated from the corresponding account.
- If you have the Flexible Billing Attributes feature disabled, the value of this field is `null`.
type: string
transferredToAccounting:
description: |
Whether the invoice was transferred to an external accounting system.
enum:
- Processing
- Error
- Ignore
- 'Yes'
- 'No'
type: string
eInvoiceStatus:
description: |
It could be Processing, RetrieveTimeOut, Generated, Success, ConditionalSuccess, ApprovedByAuthority, Failed, and Rejected. If it’s Failed, it will have an error code and message. If it’s Generated or Success, both error code and message are empty, and eInvoiceFileId stores the file id of e-invoice.
enum:
- Processing
- RetrieveTimeOut
- Generated
- Success
- Failed
- ConditionalSuccess
- ApprovedByAuthority
- Rejected
type: string
eInvoiceFileId:
type: string
description: |
The ID of the e-invoice file.
eInvoiceErrorCode:
type: string
description: |
The error code when status is `Failed`. This code can either be a Zuora-generated error code or one returned by a third-party e-invoice vendor.
eInvoiceErrorMessage:
type: string
description: |
The error message when status is "Failed". This message can either be a Zuora-generated error code or one returned by a third-party e-invoice vendor.
paymentLink:
type: string
description: |
A link to the Payment Link page where the customer can pay the invoice.
The link is generated only if the invoice is posted after enabling the Payment Link feature on your tenant.
**Note**: The Payment Link feature is in the Early Adopter phase.
You can enable the Payment Link feature through a self-service configuration in the **Manage Features** setting for Zuora Payments.
paymentTerm:
type: string
description: |
The payment term associated with the invoice. The payment term determines the due dates of
invoices.
example: Net 30
account:
$ref: '#/components/schemas/NestedAccountOnExpand'
billToContact:
$ref: '#/components/schemas/ExpandedContact'
invoiceItems:
type: array
items:
$ref: '#/components/schemas/NestedInvoiceItemOnExpand'
billToContactSnapshot:
$ref: '#/components/schemas/NestedContactSnapshotOnExpand'
soldToContactSnapshot:
$ref: '#/components/schemas/NestedContactSnapshotOnExpand'
shipToContactSnapshot:
$ref: '#/components/schemas/NestedContactSnapshotOnExpand'
additionalProperties:
type: object
description: |
Custom fields of the Invoice object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryInvoiceResponse
NestedInvoiceItemOnExpand:
properties:
id:
type: string
description: |
The unique identifier of the invoice item.
createdById:
type: string
description: |
The unique identifier of the user who created the invoice item.
createdDate:
type: string
format: date-time
description: |
The date and time when the invoice item was created.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the invoice item.
updatedDate:
type: string
format: date-time
description: |
The date and time when the invoice item was last updated.
invoiceId:
type: string
description: |
The unique identifier of the invoice to which this invoice item belongs.
invoiceScheduleId:
description: |
The ID of the invoice schedule associated with the rate plan charge on the subscription.
**Note**: This field is available only if you have the Billing Schedule feature enabled.
type: string
invoiceScheduleItemId:
type: string
description: |
The ID of the invoice schedule item that generates this invoice item.
**Note**: This field is available only if you have the Billing Schedule feature enabled.
ratePlanChargeId:
type: string
description: |
The ID of the rate plan charge associated with the invoice item.
accountingCode:
description: The accounting code associated with the invoice item.
type: string
appliedToInvoiceItemId:
description: |
The unique ID of the invoice item that the discount charge is applied
to.
type: string
chargeAmount:
description: |
The amount of the charge.
**Note**: This amount does not include taxes regardless if the charge's tax mode is inclusive or exclusive. This is the discount amount actually applied when the invoice item is a discount charge.
format: double
type: number
chargeDate:
description: |
The date when the invoice item is charged, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
chargeName:
description: The name of the charge.
type: string
chargeNumber:
type: string
description: |
Number of the charge.
commitmentChargeNumber:
type: string
commitmentChargeSegmentNumber:
type: string
description:
description: The description of the invoice item.
type: string
discountAmount:
type: number
description: |
The amount of the discount.
excludeItemBillingFromRevenueAccounting:
type: boolean
description: |
The flag to exclude the invoice item from revenue accounting.
**Note**: This field is only available if you have the Billing - Revenue Integration feature enabled.
fulfillmentId:
type: string
description: |
The reference ID of the fulfillment associated with the invoice item.
itemShipToContactId:
type: string
description: |
The ID of the ship-to contact associated with the invoice item.
**Note**: If you have the Flexible Billing Attributes feature disabled, the value of this field is `null`.
itemSoldToContactId:
type: string
description: |
The ID of the sold-to contact associated with the invoice item.
**Note**: If you have the Flexible Billing Attributes feature disabled, the value of this field is `null`.
itemSoldToContactSnapshotId:
type: string
description: |
The ID of the sold-to contact snapshot associated with the invoice item.
**Note**: If you have the Flexible Billing Attributes feature disabled, the value of this field is `null`.
processingType:
type: string
description: |
The kind of the charge for the invoice item.
- `0`: charge
- `1`: discount
- `2`: prepayment
- `3`: tax
enum:
- '0'
- '1'
- '2'
- '3'
quantity:
type: number
description: |
The quantity of this item, in the configured unit of measure for the
charge.
reflectDiscountInNetAmount:
type: boolean
default: false
description: |
When you apply percentage discounts to either of the following charges, you need to set the `reflectDiscountInNetAmount` field on your discount charge to `true`, to enable calculating and displaying the net amount of the following charges in Zuora Revenue.
* delivery pricing charge
* prepayment charge
* drawdown charge
Note the following:
* If you are an Order to Revenue customer, when you set the `reflectDiscountInNetAmount` field to `true`, you must also set the `excludeItemBillingFromRevenueAccounting` field to `true`.
* If you are a Billing - Revenue Integration customer, you must set the `reflectDiscountInNetAmount` field to `false`, otherwise an error will be returned. Billing - Revenue Integration does not support discounts on the preceding charges.
* If you are a Zuora Billing customer who does not enable the Order to Revenue or Billing - Revenue Integration feature, when you apply percentage discounts to the preceding charges, you also need to set the `reflectDiscountInNetAmount` field to `true`.
revRecStartDate:
type: string
format: date
serviceEndDate:
description: |
The end date of the service period for this item, i.e., the last day
of the service period, as _yyyy-mm-dd_.
format: date
type: string
serviceStartDate:
description: |
The start date of the service period for this item, as _yyyy-mm-dd_.
For a one-time fee item, the date of the charge.
format: date
type: string
sKU:
type: string
description: |
The SKU of the product associated with the invoice item.
sourceItemType:
description: |
The type of the source item.
enum:
- SubscriptionComponent
- Rounding
- ProductRatePlanCharge
- None
- OrderLineItem
type: string
subscriptionId:
type: string
description: |
ID of the subscription associated with the invoice item.
subscriptionNumber:
type: string
description: |
Number of the subscription associated with the invoice item.
taxAmount:
description: |
The amount of tax applied to the charge.
format: double
type: number
taxCode:
description: |
The tax code of the invoice item.
**Note** Only when taxation feature is enabled, this field can be presented.
type: string
taxExemptAmount:
type: number
taxMode:
description: |
The tax mode of the invoice item, indicating whether the amount of the invoice item includes tax.
enum:
- TaxExclusive
- TaxInclusive
type: string
unitPrice:
description: |
The per-unit price of the invoice item.
**Note**: For discount charges, this represents the discount percentage (for percentage-based discounts) or the discount amount (for fixed-amount discounts).
format: double
type: number
uOM:
type: string
description: |
The unit of measure (UOM) that is configured in **Settings > Billing** for the product rate plan charge.
balance:
type: number
description: |
The balance of the invoice item.
**Note**: This field is only available if you have the Invoice Settlement feature enabled.
numberOfDeliveries:
type: number
description: |
The number of deliveries dedicated to the Delivery Pricing charges.
**Note**: This field is available only if you have the Delivery Pricing feature enabled.
accountReceivableAccountingCodeId:
type: string
description: |
ID of the account receivable accounting code associated with the invoice item.
**Note:** This field is only available if you have Zuora Finance enabled.
recognizedRevenueAccountingCodeId:
type: string
description: |
ID of the recognized revenue accounting code associated with the invoice item.
**Note:** This field is only available if you have Zuora Finance enabled.
deferredRevenueAccountingCodeId:
description: |
ID of the deferred revenue accounting code associated with the invoice item.
**Note:** This field is only available if you have Zuora Finance enabled.
type: string
contractAssetAccountingCodeId:
description: |
ID of the accounting code for contract asset.
**Note**: This field is only available if you have the Billing - Revenue Integration feature enabled.
type: string
contractLiabilityAccountingCodeId:
type: string
description: |
ID of the accounting code for contract liability.
**Note**: This field is only available if you have the Billing - Revenue Integration feature enabled.
contractRecognizedRevenueAccountingCodeId:
description: |
ID of the accounting code for contract recognized revenue.
**Note**: This field is only available if you have the Billing - Revenue Integration feature enabled.
type: string
unbilledReceivablesAccountingCodeId:
type: string
adjustmentRevenueAccountingCodeId:
description: |
The accounting code for adjustment revenue.
**Note**: This field is only available if you have the Billing - Revenue Integration feature enabled.
type: string
adjustmentLiabilityAccountingCodeId:
description: |
ID of the accounting code for adjustment liability.
**Note**: This field is only available if you have the Billing - Revenue Integration feature enabled.
type: string
journalEntryId:
type: string
description: |
The ID of the journal entry that corresponds to this invoice item.
accountId:
type: string
description: |
The ID of the account associated with the invoice item.
billToContactSnapshotId:
description: |
The ID of the bill-to contact snapshot associated with the invoice.
type: string
shipToContactSnapshotId:
description: |
The ID of the ship-to contact snapshot associated with the invoice.
type: string
soldToContactSnapshotId:
description: |
The ID of the sold-to contact snapshot associated with the invoice.
type: string
parentAccountId:
type: string
description: |
The parent account of the account associated with the invoice.
**Note**: This field is available only if you have Customer Hierarchy enabled for your tenant.
billToContactId:
type: string
description: |
The ID of the bill-to contact associated with the invoice.
shipToContactId:
type: string
description: |
The ID of the ship-to contact associated with the invoice.
soldToContactId:
type: string
description: |
The ID of the sold-to contact associated with the invoice.
defaultPaymentMethodId:
type: string
description: |
The ID of the default payment method on the associated account.
ratePlanId:
type: string
description: |
The ID of the rate plan that the invoice is created from.
amendmentId:
type: string
description: |
The ID of the amendment associated with the subscription.
**Note**: This field is available only if you do not have Orders enabled for your tenant.
productRatePlanChargeId:
description: |
The ID of the product rate plan charge that the invoice item is created from.
type: string
productRatePlanId:
description: |
The ID of the product rate plan that the invoice item is created from.
type: string
productId:
description: |
The ID of the product that the invoice item is created from.
type: string
bookingReference:
type: string
description: |
The booking reference of the invoice item.
itemType:
type: string
description: |
The type of the invoice item.
purchaseOrderNumber:
description: |
The purchase order number associated with the invoice item.
type: string
revRecCode:
description: |
The revenue recognition code.
type: string
revRecTriggerCondition:
description: |
The date when revenue recognition is triggered.
enum:
- ContractEffectiveDate
- ServiceActivationDate
- CustomerAcceptanceDate
type: string
revenueRecognitionRuleName:
description: |
The revenue recognition rule of the invoice item.
**Note:** This field is only available if you have Zuora Finance enabled.
type: string
subscriptionOwnerId:
description: |
The ID of the subscription owner associated with the invoice item.
type: string
orderLineItemId:
description: |
The reference ID of the oder line item associated with the invoice item.
type: string
invoice:
type: object
description: |
The invoices to which the invoice item belongs.
subscription:
type: object
description: |
The invoice to which the invoice item belongs.
ratePlanCharge:
type: object
description: |
The rate plan charge associated with the invoice item.
orderLineItem:
type: object
description: |
The order line item associated with the invoice item.
additionalProperties:
type: object
description: |
Custom fields of the Invoice Item object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryInvoiceItemResponse
ExpandedInvoiceItem:
properties:
id:
type: string
description: |
The unique identifier of the invoice item.
createdById:
type: string
description: |
The unique identifier of the user who created the invoice item.
createdDate:
type: string
format: date-time
description: |
The date and time when the invoice item was created.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the invoice item.
updatedDate:
type: string
format: date-time
description: |
The date and time when the invoice item was last updated.
invoiceId:
type: string
description: |
The unique identifier of the invoice to which this invoice item belongs.
invoiceScheduleId:
description: |
The ID of the invoice schedule associated with the rate plan charge on the subscription.
**Note**: This field is available only if you have the Billing Schedule feature enabled.
type: string
invoiceScheduleItemId:
type: string
description: |
The ID of the invoice schedule item that generates this invoice item.
**Note**: This field is available only if you have the Billing Schedule feature enabled.
ratePlanChargeId:
type: string
description: |
The ID of the rate plan charge associated with the invoice item.
accountingCode:
description: The accounting code associated with the invoice item.
type: string
appliedToInvoiceItemId:
description: |
The unique ID of the invoice item that the discount charge is applied
to.
type: string
chargeAmount:
description: |
The amount of the charge.
**Note**: This amount does not include taxes regardless if the charge's tax mode is inclusive or exclusive. This is the discount amount actually applied when the invoice item is a discount charge.
format: double
type: number
chargeDate:
description: |
The date when the invoice item is charged, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
chargeName:
description: The name of the charge.
type: string
chargeNumber:
type: string
description: |
Number of the charge.
commitmentChargeNumber:
type: string
commitmentChargeSegmentNumber:
type: string
description:
description: The description of the invoice item.
type: string
discountAmount:
type: number
description: |
The amount of the discount.
excludeItemBillingFromRevenueAccounting:
type: boolean
description: |
The flag to exclude the invoice item from revenue accounting.
**Note**: This field is only available if you have the Billing - Revenue Integration feature enabled.
fulfillmentId:
type: string
description: |
The reference ID of the fulfillment associated with the invoice item.
itemShipToContactId:
type: string
description: |
The ID of the ship-to contact associated with the invoice item.
**Note**: If you have the Flexible Billing Attributes feature disabled, the value of this field is `null`.
itemSoldToContactId:
type: string
description: |
The ID of the sold-to contact associated with the invoice item.
**Note**: If you have the Flexible Billing Attributes feature disabled, the value of this field is `null`.
itemSoldToContactSnapshotId:
type: string
description: |
The ID of the sold-to contact snapshot associated with the invoice item.
**Note**: If you have the Flexible Billing Attributes feature disabled, the value of this field is `null`.
processingType:
type: string
description: |
The kind of the charge for the invoice item.
- `0`: charge
- `1`: discount
- `2`: prepayment
- `3`: tax
enum:
- '0'
- '1'
- '2'
- '3'
quantity:
type: number
description: |
The quantity of this item, in the configured unit of measure for the
charge.
reflectDiscountInNetAmount:
type: boolean
default: false
description: |
When you apply percentage discounts to either of the following charges, you need to set the `reflectDiscountInNetAmount` field on your discount charge to `true`, to enable calculating and displaying the net amount of the following charges in Zuora Revenue.
* delivery pricing charge
* prepayment charge
* drawdown charge
Note the following:
* If you are an Order to Revenue customer, when you set the `reflectDiscountInNetAmount` field to `true`, you must also set the `excludeItemBillingFromRevenueAccounting` field to `true`.
* If you are a Billing - Revenue Integration customer, you must set the `reflectDiscountInNetAmount` field to `false`, otherwise an error will be returned. Billing - Revenue Integration does not support discounts on the preceding charges.
* If you are a Zuora Billing customer who does not enable the Order to Revenue or Billing - Revenue Integration feature, when you apply percentage discounts to the preceding charges, you also need to set the `reflectDiscountInNetAmount` field to `true`.
revRecStartDate:
type: string
format: date
serviceEndDate:
description: |
The end date of the service period for this item, i.e., the last day
of the service period, as _yyyy-mm-dd_.
format: date
type: string
serviceStartDate:
description: |
The start date of the service period for this item, as _yyyy-mm-dd_.
For a one-time fee item, the date of the charge.
format: date
type: string
sKU:
type: string
description: |
The SKU of the product associated with the invoice item.
sourceItemType:
description: |
The type of the source item.
enum:
- SubscriptionComponent
- Rounding
- ProductRatePlanCharge
- None
- OrderLineItem
type: string
subscriptionId:
type: string
description: |
ID of the subscription associated with the invoice item.
subscriptionNumber:
type: string
description: |
Number of the subscription associated with the invoice item.
taxAmount:
description: |
The amount of tax applied to the charge.
format: double
type: number
taxCode:
description: |
The tax code of the invoice item.
**Note** Only when taxation feature is enabled, this field can be presented.
type: string
taxExemptAmount:
type: number
taxMode:
description: |
The tax mode of the invoice item, indicating whether the amount of the invoice item includes tax.
enum:
- TaxExclusive
- TaxInclusive
type: string
unitPrice:
description: |
The per-unit price of the invoice item.
**Note**: For discount charges, this represents the discount percentage (for percentage-based discounts)
or the discount amount (for fixed-amount discounts).
format: double
type: number
uOM:
type: string
description: |
The unit of measure (UOM) that is configured in **Settings > Billing** for the product rate plan charge.
balance:
type: number
description: |
The balance of the invoice item.
**Note**: This field is only available if you have the Invoice Settlement feature enabled.
numberOfDeliveries:
type: number
description: |
The number of deliveries dedicated to the Delivery Pricing charges.
**Note**: This field is available only if you have the Delivery Pricing feature enabled.
accountReceivableAccountingCodeId:
type: string
description: |
ID of the account receivable accounting code associated with the invoice item.
**Note:** This field is only available if you have Zuora Finance enabled.
recognizedRevenueAccountingCodeId:
type: string
description: |
ID of the recognized revenue accounting code associated with the invoice item.
**Note:** This field is only available if you have Zuora Finance enabled.
deferredRevenueAccountingCodeId:
description: |
ID of the deferred revenue accounting code associated with the invoice item.
**Note:** This field is only available if you have Zuora Finance enabled.
type: string
contractAssetAccountingCodeId:
description: |
ID of the accounting code for contract asset.
**Note**: This field is only available if you have the Billing - Revenue Integration feature enabled.
type: string
contractLiabilityAccountingCodeId:
type: string
description: |
ID of the accounting code for contract liability.
**Note**: This field is only available if you have the Billing - Revenue Integration feature enabled.
contractRecognizedRevenueAccountingCodeId:
description: |
ID of the accounting code for contract recognized revenue.
**Note**: This field is only available if you have the Billing - Revenue Integration feature enabled.
type: string
unbilledReceivablesAccountingCodeId:
type: string
adjustmentRevenueAccountingCodeId:
description: |
The accounting code for adjustment revenue.
**Note**: This field is only available if you have the Billing - Revenue Integration feature enabled.
type: string
adjustmentLiabilityAccountingCodeId:
description: |
ID of the accounting code for adjustment liability.
**Note**: This field is only available if you have the Billing - Revenue Integration feature enabled.
type: string
journalEntryId:
type: string
description: |
The ID of the journal entry that corresponds to this invoice item.
accountId:
type: string
description: |
The ID of the account associated with the invoice item.
billToContactSnapshotId:
description: |
The ID of the bill-to contact snapshot associated with the invoice.
type: string
shipToContactSnapshotId:
description: |
The ID of the ship-to contact snapshot associated with the invoice.
type: string
soldToContactSnapshotId:
description: |
The ID of the sold-to contact snapshot associated with the invoice.
type: string
parentAccountId:
type: string
description: |
The parent account of the account associated with the invoice.
**Note**: This field is available only if you have Customer Hierarchy enabled for your tenant.
billToContactId:
type: string
description: |
The ID of the bill-to contact associated with the invoice.
shipToContactId:
type: string
description: |
The ID of the ship-to contact associated with the invoice.
soldToContactId:
type: string
description: |
The ID of the sold-to contact associated with the invoice.
defaultPaymentMethodId:
type: string
description: |
The ID of the default payment method on the associated account.
ratePlanId:
type: string
description: |
The ID of the rate plan that the invoice is created from.
amendmentId:
type: string
description: |
The ID of the amendment associated with the subscription.
**Note**: This field is available only if you do not have Orders enabled for your tenant.
productRatePlanChargeId:
description: |
The ID of the product rate plan charge that the invoice item is created from.
type: string
productRatePlanId:
description: |
The ID of the product rate plan that the invoice item is created from.
type: string
productId:
description: |
The ID of the product that the invoice item is created from.
type: string
bookingReference:
type: string
description: |
The booking reference of the invoice item.
itemType:
type: string
description: |
The type of the invoice item.
purchaseOrderNumber:
description: |
The purchase order number associated with the invoice item.
type: string
revRecCode:
description: |
The revenue recognition code.
type: string
revRecTriggerCondition:
description: |
The date when revenue recognition is triggered.
enum:
- ContractEffectiveDate
- ServiceActivationDate
- CustomerAcceptanceDate
type: string
revenueRecognitionRuleName:
description: |
The revenue recognition rule of the invoice item.
**Note:** This field is only available if you have Zuora Finance enabled.
type: string
orderLineItemId:
description: |
The reference ID of the oder line item associated with the invoice item.
type: string
subscriptionOwnerId:
description: |
The ID of the subscription owner associated with the invoice item.
type: string
invoice:
$ref: '#/components/schemas/NestedInvoiceOnExpand'
subscription:
$ref: '#/components/schemas/NestedSubscriptionOnExpand'
taxationItems:
type: array
items:
$ref: '#/components/schemas/ExpandedTaxationItem'
ratePlanCharge:
$ref: '#/components/schemas/NestedRatePlanChargeOnExpand'
orderLineItem:
$ref: '#/components/schemas/NestedOrderLineItemOnExpand'
subscriptionOwner:
$ref: '#/components/schemas/NestedAccountOnExpand'
additionalProperties:
type: object
description: |
Custom fields of the Invoice Item object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryInvoiceItemResponse
ExpandedTaxationItem:
properties:
id:
type: string
description: |
The unique identifier of the taxation item.
createdById:
type: string
description: |
The unique identifier of the user who created the taxation item.
createdDate:
type: string
format: date-time
description: |
The date and time when the taxation item was created in the Zuora
system, in the `yyyy-mm-dd hh:mm:ss` format.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the taxation item.
updatedDate:
type: string
format: date-time
description: |
The date and time when the taxation item was last updated, in the `yyyy-mm-dd hh:mm:ss` format.
creditAmount:
type: number
description: |
The amount of credit memos applied to the taxation item.
format: double
accountingCode:
type: string
description: |
The accounting code that maps to the taxation item in your accounting system.
exemptAmount:
type: number
description: |
The calculated tax amount excluded due to the exemption.
format: double
invoiceItemId:
type: string
description: |
The unique identifier of the invoice item to which the taxation item belongs.
jurisdiction:
type: string
description: |
The jurisdiction that applies the tax or VAT. This value is typically
a state, province, county, or city.
locationCode:
type: string
description: |
The identifier for the location based on the value of the `taxCode` field.
name:
type: string
description: |
The name of the taxation item.
paymentAmount:
type: number
description: |
The amount of payment applied to the invoice or debit memo.
format: double
taxAmount:
type: number
description: |
The amount of the tax applied to the billing document.
format: double
taxAmountUnrounded:
type: number
description: |
The amount of the tax applied to the billing document before rounding.
countryCode:
type: string
description: |
The code of country to which the taxation item.
taxCodeDescription:
type: string
description: |
The description of the tax code.
customerCode:
type: string
description: |
The customer code. This field is only available if you are using one of the Vertex Tax Connector apps.
exemptCertificate:
type: string
description: |
The tax exemption certificate that the customer holds. Applicable if you use Zuora Tax or Connect tax engines.
sellerRegistration:
type: string
description: |
Your seller registration code. This field is only available if you are using the OneSource Determination app.
taxDescription:
type: string
description: |
The description of the tax.
taxRuleId:
type: string
description: |
The unique identifier of the tax rule.
taxCode:
type: string
description: |
The tax code identifies which tax rules and tax rates to apply to a
specific billing document.
taxMode:
type: string
description: |
The mode of the tax.
enum:
- TaxExclusive
- TaxInclusive
taxDate:
type: string
format: date
description: |
The date when the tax is applied to the billing document.
taxRate:
type: number
description: |
The tax rate applied to the billing document.
format: double
taxRateDescription:
type: string
description: |
The description of the tax rate.
taxRateType:
type: string
description: |
The type of the tax rate applied to the billing document.
enum:
- Percentage
- FlatFee
balance:
type: number
description: |
The remaining balance on the taxation item.
journalEntryId:
type: string
description: |
The ID of the journal entry that corresponds to this transaction.
salesTaxPayableAccountingCodeId:
type: string
description: |
The accounting code for Sales Tax Payable.
accountReceivableAccountingCodeId:
type: string
description: |
The accounting code for Account Receivable.
taxableItemSnapshotId:
type: string
description: |
The unique identifier of the taxable item snapshot.
periodEndDate:
type: string
format: date
description: |
The end date of the period to which the taxation item belongs.
periodStartDate:
type: string
format: date
description: |
The start date of the period to which the taxation item belongs.
taxableAmount:
type: number
format: double
description: |
The taxable amount of the taxation item.
additionalProperties:
type: object
description: |
Custom fields of the Taxation Item object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryTaxationItemResponse
NestedOrderLineItemOnExpand:
properties:
id:
type: string
description: |
The unique identifier of the order line item.
createdById:
type: string
description: |
The unique identifier of the user who created the order line item.
createdDate:
type: string
format: date-time
description: |
The time that the order line item gets created in the system, in the
`YYYY-MM-DD HH:MM:SS` format.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the order line item.
updatedDate:
type: string
format: date-time
description: |
The date and time when the order line item was last updated.
accountingCode:
type: string
description: |
The accountingCode for the Order Line Item (OLI).
You can update this field only for a sales OLI and only when the sales OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
nullable: true
billTargetDate:
description: |
The target date for the Order Line Item (OLI) to be picked up by bill run for generating billing documents.
To generate billing documents for an OLI, you must set this field and set the `itemState` field to `SentToBilling`.
You can update this field for a sales or return OLI only when the OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
format: date
type: string
amountPerUnit:
type: number
description: |
The actual charged amount per unit for the Order Line Item (OLI).
You can update this field only for a sales OLI and only when the sales OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
description:
description: |
The description of the Order Line Item.
type: string
amount:
type: number
description: |
The total amount for the Order Line Item (OLI).
amountWithoutTax:
type: number
description: |
The total amount for the Order Line Item (OLI) excluding tax.
itemName:
description: |
The name of the Order Line Item (OLI).
You can update this field for a sales or return OLI only when the OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
type: string
itemNumber:
description: |
The number for the Order Line Item (OLI).
You can update this field for a sales or return OLI only when the OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
type: string
itemState:
description: |
The state of the Order Line Item (OLI). See [State transitions for an order, order line item, and fulfillment](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Order_Line_Items/AB_Order_Line_Item_States_and_Order_States) for more information.
To generate invoice for an OLI, you must set this field to `SentToBilling` and set the `billTargetDate` field .
You can update this field for a sales or return OLI only when the OLI is in the `Executing` or 'Booked' or `SentToBilling`state (when the `itemState` field is set as `Executing` or `SentToBilling`).
enum:
- Executing
- Booked
- SentToBilling
- Complete
- Cancelled
type: string
itemType:
description: |
The type of the Order Line Item (OLI).
You can update this field only for a sales OLI and only when the sales OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
enum:
- Product
- Fee
- Services
type: string
listPricePerUnit:
description: |
The list price per unit for the Order Line Item (OLI).
You can update this field only for a sales OLI and only when the sales OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
type: number
listPrice:
description: |
The extended list price for an order line item, calculated by the formula:
listPrice = listPricePerUnit * quantity
type: number
orderId:
type: string
description: |
The ID of the order that the order line item belongs to.
productCode:
description: |
The product code for the Order Line Item (OLI).
You can update this field only for a sales OLI and only when the sales OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
type: string
purchaseOrderNumber:
description: |
Used by customers to specify the Purchase Order Number provided by the buyer.
You can update this field only for a sales OLI and only when the sales OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
type: string
quantity:
description: |
The quantity of units, such as the number of authors in a hosted wiki service.
You can update this field for a sales or return OLI only when the OLI in the `Executing` state (when the `itemState` field is set as `Executing`).
type: number
revenueRecognitionRule:
type: string
description: |
The Revenue Recognition rule for the Order Line Item.
productRatePlanChargeId:
description: |
ID of a Product Rate Plan Charge. Only one-time charges are supported.
type: string
billToId:
description: |
The ID of a contact that belongs to the billing account of the order line item. Use this field to assign an existing account as the bill-to contact of an order line item.
type: string
billToSnapshotId:
description: |
The snapshot of the ID for an account used as the bill-to contact of an order line item. This field is used to store the original information about the account, in case the information about the account is changed after the creation of the order line item. The `billToSnapshotId` field is exposed while retrieving the order line item details.
type: string
shipTo:
description: |
The ID of a contact that belongs to the owner acount or billing account of the order line item. Use this field to assign an existing account as the ship-to contact of an order line item.
type: string
shipToSnapshotId:
description: |
The snapshot of the ID for an account used as the ship-to contact of an order line item. This field is used to store the original information about the account, in case the information about the account is changed after the creation of the order line item. The `shipToSnapshotId` field is exposed while retrieving the order line item details.
type: string
soldTo:
description: |
The ID of a contact that belongs to the owner acount or billing account of the order line item. Use this field to assign an existing account as the sold-to contact of an order line item.
type: string
soldToSnapshotId:
description: |
The snapshot of the ID for an account used as the sold-to contact of an order line item. This field is used to store the original information about the account, in case the information about the account is changed after the creation of the order line item. The `soldToSnapshotId` field is exposed while retrieving the order line item details.
type: string
soldToOrderContactId:
type: string
description: |
The ID of the sold-to contact for the order.
ownerAccountId:
description: |
The account ID of the owner of the order line item.
type: string
invoiceOwnerAccountId:
description: |
The account ID of the invoice owner of the order line item.
type: string
taxCode:
description: |
The tax code for the Order Line Item (OLI).
You can update this field only for a sales OLI and only when the sales OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
type: string
taxMode:
description: |
The tax mode for the Order Line Item (OLI).
You can update this field only for a sales OLI and only when the sales OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
enum:
- TaxInclusive
- TaxExclusive
type: string
transactionDate:
type: string
format: date
description: |
The date when the transaction occurs.
uOM:
description: |
Specifies the units to measure usage.
You can update this field only for a sales OLI and only when the sales OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
type: string
relatedSubscriptionNumber:
description: |
This field is used to relate an order line item to an subscription.
You can update this field only for a sales OLI and only when the sales OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
type: string
transactionEndDate:
description: |
The date a transaction is completed. The default value of this field is the transaction start date. Also, the value of this field should always equal or be later than the value of the `transactionStartDate` field.
You can update this field for a sales or return OLI only when the OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
format: date
type: string
transactionStartDate:
description: |
The date a transaction starts. The default value of this field is the order date.
You can update this field for a sales or return OLI only when the OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
format: date
type: string
excludeItemBillingFromRevenueAccounting:
type: boolean
description: |
Indicates whether to exclude the related invoice items, invoice item adjustments, credit memo items, and debit memo items from revenue accounting.
**Note**: This field is only available if you have the Order to Revenue or Billing - Revenue Integration feature enabled.
excludeItemBookingFromRevenueAccounting:
type: boolean
description: |
Indicates whether to exclude the related rate plan charges and order line items from revenue accounting.
**Note**: This field is only available if you have the Order to Revenue or Billing - Revenue Integration feature enabled.
originalOrderDate:
type: string
format: date
description: |
The date of the original sale order for a return order line item.
amendedByOrderOn:
type: string
format: date
description: |
The date of the amended order for a return order line item.
itemCategory:
default: Sales
description: |
The category of the Order Line Item, to indicate a product sale or return.
enum:
- Sales
- Return
type: string
originalOrderId:
description: |
The ID of the original sale order for a return order line item.
type: string
originalOrderLineItemId:
description: |
The ID of the original sale order line item for a return order line item.
type: string
originalOrderLineItemNumber:
description: |
The number of the original sale order line item for a return order line item.
type: string
originalOrderNumber:
description: |
The number of the original sale order for a return order line item.
type: string
quantityAvailableForReturn:
description: |
The quantity that can be returned for an order line item.
type: number
quantityFulfilled:
description: |
The fulfilled quantity for an order line item.
type: number
quantityPendingFulfillment:
description: |
The quantity to fulfill for an order line item.
type: number
requiresFulfillment:
description: |
The flag to show whether fulfillment is needed or not. It's derived from billing rule of the Order Line Item.
type: boolean
billingRule:
description: |
The billing rule of the Order Line Item.
enum:
- TriggerWithoutFulfillment
- TriggerAsFulfillmentOccurs
type: string
inlineDiscountPerUnit:
description: |
This field is used in accordance with the `inlineDiscountType` field, in the following manner:
* If the `inlineDiscountType` field is set as `Percentage`, this field specifies the discount percentage for each unit of the order line item. For exmaple, if you specify `5` in this field, the discount percentage is 5%.
* If the `inlineDiscountType` field is set as `FixedAmount`, this field specifies the discount amount on each unit of the order line item. For exmaple, if you specify `10` in this field, the discount amount on each unit of the order line item is 10.
Once you set the `inlineDiscountType`, `inlineDiscountPerUnit`, and `listPricePerUnit` fields, the system will automatically generate the `amountPerUnit` field. You shall not set the `amountPerUnit` field by yourself.
type: number
inlineDiscountType:
description: |
This field is used to specify the inline discount type, which can be `Percentage`, `FixedAmount`, or `None`. The default value is `Percentage`.
This field is used together with the `inlineDiscountPerUnit` field to specify inline discounts for order line items. The inline discount is applied to the list price of an order line item.
Once you set the `inlineDiscountType`, `inlineDiscountPerUnit`, and `listPricePerUnit` fields, the system will automatically generate the `amountPerUnit` field. You shall not set the `amountPerUnit` field by yourself.
enum:
- Percentage
- FixedAmount
- None
type: string
discount:
type: number
description: |
This field shows the total discount amount that is applied to an order line item after the `inlineDiscountType`, `inlineDiscountPerUnit` and `quantity` fields are set.
The inline discount is applied to the list price of an order line item.
recognizedRevenueAccountingCodeId:
type: string
description: |
The recognized revenue accounting code for the Order Line Item.
deferredRevenueAccountingCodeId:
description: |
The deferred revenue accounting code for the Order Line Item.
type: string
contractAssetAccountingCode:
description: |
The accounting code on the Order Line Item object for customers using [Zuora Billing - Revenue Integration](https://knowledgecenter.zuora.com/Zuora_Revenue/Zuora_Billing_-_Revenue_Integration).
type: string
contractLiabilityAccountingCode:
description: |
The accounting code on the Order Line Item object for customers using [Zuora Billing - Revenue Integration](https://knowledgecenter.zuora.com/Zuora_Revenue/Zuora_Billing_-_Revenue_Integration).
type: string
contractRecognizedRevenueAccountingCodeId:
description: |
The accounting code on the Order Line Item object for customers using [Zuora Billing - Revenue Integration](https://knowledgecenter.zuora.com/Zuora_Revenue/Zuora_Billing_-_Revenue_Integration).
type: string
unbilledReceivablesAccountingCodeId:
description: |
The accounting code on the Order Line Item object for customers using [Zuora Billing - Revenue Integration](https://knowledgecenter.zuora.com/Zuora_Revenue/Zuora_Billing_-_Revenue_Integration).
type: string
adjustmentRevenueAccountingCodeId:
description: |
The accounting code on the Order Line Item object for customers using [Zuora Billing - Revenue Integration](https://knowledgecenter.zuora.com/Zuora_Revenue/Zuora_Billing_-_Revenue_Integration).
type: string
adjustmentLiabilityAccountingCodeId:
description: |
The accounting code on the Order Line Item object for customers using [Zuora Billing - Revenue Integration](https://knowledgecenter.zuora.com/Zuora_Revenue/Zuora_Billing_-_Revenue_Integration).
type: string
invoiceItems:
type: array
items:
type: object
description: The invoice item associated with the order line item.
additionalProperties:
type: object
description: |
Custom fields of the Order Line Item object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryOrderLineItemResponse
ExpandedInvoiceSchedule:
properties:
id:
type: string
description: |
The unique identifier of the invoice schedule.
createdById:
type: string
description: |
The unique identifier of the user who created the invoice schedule.
createdDate:
type: string
format: date-time
description: |
The date and time when the invoice schedule was created.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the invoice schedule.
updatedDate:
type: string
format: date-time
description: |
The date and time when the invoice schedule was last updated.
totalAmount:
type: number
description: |
The total amount that needs to be billed during the processing of the invoice schedule.
The value of this field keeps unchanged once invoice schedule items are created.
actualAmount:
type: number
description: |
The actual amount that needs to be billed during the processing of the invoice schedule.
By default, the actual amount is the same as the total amount. Even if order changes occur like Remove Product or Cancel Subscription, the value of the `totalAmount` field keeps unchanged. The value of the `actualAmount` field reflects the actual amount to be billed.
billedAmount:
type: number
description: |
The amount that has been billed during the processing of the invoice schedule.
unbilledAmount:
type: number
description: |
The amount that is waiting to be billed during the processing of the invoice schedule.
nextRunDate:
type: string
format: date
description: |
The run date of the next execution of invoice schedule. By default, the next run date is the same as run date of next pending invoice schedule item.
It can be overwritten with a different date other than the default value. When the invoice schedule has completed the execution, the next run date is null.
number:
type: string
description: |
The sequence number of the invoice schedule.
notes:
type: string
maxLength: 255
description: |
Comments on the invoice schedule.
accountId:
type: string
description: |
The ID of the customer account that the invoice schedule belongs to.
status:
type: string
description: |
The status of the invoice schedule.
enum:
- Pending
- PartiallyProcessed
- Paused
- FullyProcessed
additionalSubscriptionsToBill:
type: string
description: |
A list of the numbers of the subscriptions that need to be billed together with the invoice schedule.
One invoice schedule can have at most 600 additional subscriptions.
currency:
type: string
description: |
The currency of the billing documents generated during the processing of the invoice schedule.
**Note**:
- This field is available only if you have the Multiple Currencies feature enabled.
- If you have the Multiple Currencies feature disabled, the corresponding account's default currency is always used.
invoiceScheduleItems:
type: array
items:
$ref: '#/components/schemas/NestedInvoiceScheduleItemOnExpand'
invoiceScheduleBookings:
type: array
items:
$ref: '#/components/schemas/NestedInvoiceScheduleBookingOnExpand'
ratePlanCharges:
type: array
items:
$ref: '#/components/schemas/NestedRatePlanChargeOnExpand'
additionalProperties:
type: object
description: |
Custom fields of the Invoice Schedule object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryInvoiceScheduleResponse
NestedInvoiceScheduleItemOnExpand:
properties:
id:
type: string
description: |
The unique identifier of the invoice schedule item.
createdById:
type: string
description: |
The unique identifier of the user who created the invoice schedule item.
createdDate:
type: string
format: date-time
description: |
The date and time when the invoice schedule item was created.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the invoice schedule item.
updatedDate:
type: string
format: date-time
description: |
The date and time when the invoice schedule item was last updated.
amount:
type: string
format: number
description: |
The amount of the invoice generated during the processing of the invoice schedule item.
You can only specify either the `amount` field or `percentage` field in one request.
- If you choose to specify the `amount` field in the request, `null` is returned as the value of the `percentage` field in the corresponding response.
- If you choose to specify the `percentage` field in the request, the value of the `amount` field returned in the corresponding response is calculated based on the percentage of the total amount.
The value of this field keeps unchanged once invoice schedule items are created.
percentage:
type: number
description: |
The percentage of the total amount to be billed during the processing of the invoice schedule item.
You can only specify either the `amount` field or `percentage` field in one request.
- If you choose to specify the `amount` field in the request, `null` is returned as the value of the `percentage` field in the corresponding response.
- If you choose to specify the `percentage` field in the request, the value of the `amount` field returned in the corresponding response is calculated based on the percentage of the total amount.
actualAmount:
type: string
format: number
description: |
The actual amount that needs to be billed during the processing of the invoice schedule item.
By default, the actual amount is the same as the total amount. Even if order changes occur like Remove Product or Cancel Subscription, the value of the `amount` field keeps unchanged. The value of the `actualAmount` field reflects the actual amount to be billed.
runDate:
type: string
format: date
description: |
The date in the tenant's time zone when the invoice schedule item is processed to generate an invoice.
invoiceScheduleId:
type: string
description: |
The ID of the invoice schedule that the invoice schedule item belongs to.
invoiceId:
type: string
description: |
The ID of the invoice that is generated during the processing of the invoice schedule item.
creditMemoId:
type: string
description: |
The ID of the credit memo that is generated during the processing of the invoice schedule item.
status:
type: string
description: |
The status of the invoice schedule item.
enum:
- Pending
- Executing
- Processed
name:
type: string
maxLength: 100
description: |
The name of the invoice schedule item.
sequenceNumber:
type: string
description: |
The sequence number of the invoice schedule item.
targetDateForAdditionalSubscriptions:
type: string
format: date
description: |
The date in the tenant's time zone used by the invoice schedule to determine which fixed-period regular charges to be billed together with the invoice schedule item.
The regular charges must come from the subscriptions specified in the `additionalSubscriptionsToBill` field on the associated invoice schedule.
additionalProperties:
type: object
description: |
Custom fields of the Invoice Schedule Item object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryInvoiceScheduleItemResponse
NestedInvoiceScheduleBookingOnExpand:
properties:
id:
type: string
description: |
The unique identifier of the invoice schedule booking.
createdById:
type: string
description: |
The unique identifier of the user who created the invoice schedule booking.
createdDate:
type: string
format: date-time
description: |
The date and time when the invoice schedule booking was created.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the invoice schedule booking.
updatedDate:
type: string
format: date-time
description: |
The date and time when the invoice schedule booking was last updated.
invoiceScheduleId:
type: string
description: |
The ID of the invoice schedule that the invoice schedule booking belongs to.
orderId:
type: string
description: |
The ID of the order associated with the invoice schedule.
orderNumber:
type: string
description: |
The number of the order associated with the invoice schedule.
subscriptionId:
type: string
description: |
The ID of the subscription contained in the order associated with the invoice schedule.
subscriptionNumber:
type: string
description: |
The number of the subscription contained in the order associated with the invoice schedule.
chargeNumbers:
type: string
description: |
A list of charges in the subscription that are chosen to be included in the invoice schedule.
type: object
title: QueryInvoiceScheduleBookingResponse
ExpandedOrderAction:
properties:
id:
type: string
description: |
The unique identifier of the order action.
createdById:
type: string
description: |
The unique identifier of the user who created the order action.
createdDate:
type: string
format: date-time
description: |
The time that the order action gets created in the system, in the
`YYYY-MM-DD HH:MM:SS` format.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the order action.
updatedDate:
type: string
format: date-time
description: |
The date and time when the order action was last updated.
contractEffectiveDate:
type: string
format: date
description: |
Effective contract date for this subscription, as yyyy-mm-dd.
customerAcceptanceDate:
type: string
format: date
description: |
The date on which the services or products within a subscription have been accepted by the customer, as yyyy-mm-dd.
type:
description: |
Type of the order action.
**Note**: The change plan type of order action is supported for the Order to Revenue feature. However, it is currently not supported for the Billing - Revenue Integration feature. When Billing - Revenue Integration is enabled, the change plan type of order action will no longer be applicable in Zuora Billing.
enum:
- CreateSubscription
- TermsAndConditions
- AddProduct
- UpdateProduct
- RemoveProduct
- RenewSubscription
- CancelSubscription
- OwnerTransfer
- Suspend
- Resume
- ChangePlan
type: string
sequence:
type: integer
format: int32
description: |
The sequence of the order actions processed in the order.
subscriptionVersionAmendmentId:
type: string
description: |
The unique identifier of the amendment that changes the version of the subscription.
orderId:
type: string
description: |
The unique identifier of the order that the order action belongs to.
subscriptionId:
type: string
description: |
The unique identifier of the subscription associated with the order action.
subscriptionNumber:
type: string
description: |
The number of the subscription associated with the order action.
serviceActivationDate:
type: string
format: date
description: |
The date on which the services or products within a subscription have been activated and access has been provided to the customer, as yyyy-mm-dd.
autoRenew:
type: boolean
description: |
If `true`, the subscription automatically renews at the end of the term.
default: false
renewSetting:
description: |
Specifies whether a termed subscription will remain termed or change to evergreen when it is renewed.
type: string
enum:
- RENEW_WITH_SPECIFIC_TERM
- RENEW_TO_EVERGREEN
default: RENEW_WITH_SPECIFIC_TERM
renewalTerm:
type: integer
format: int64
description: |
The length of the period for the subscription renewal term.
default: 0
renewalTermPeriodType:
description: |
The period type for the subscription renewal term.
This field is used with the `renewalTerm` field to specify the subscription renewal term.
type: string
enum:
- Month
- Year
- Day
- Week
default: Month
termStartDate:
type: string
format: date
description: |
The date on which the subscription term begins, as `yyyy-mm-dd`. If this is a renewal subscription, this date is different from the subscription start date.
termType:
type: string
enum:
- TERMED
- EVERGREEN
description: |
The type of the subscription term.
currentTerm:
type: integer
format: int64
description: |
The length of the period for the current subscription term.
currentTermPeriodType:
description: |
The period type for the current subscription term.
type: string
enum:
- Month
- Year
- Day
- Week
default: Month
suspendDate:
type: string
format: date
description: |
The date when subscription suspension takes effect, in the `yyyy-mm-dd` format.
resumeDate:
type: string
format: date
description: |
The resume date when the resumption takes effect.
cancellationEffectiveDate:
type: string
format: date
description: |
Date when the cancellation takes effect, in the `yyyy-mm-dd` format. Used only if `cancellationPolicy` is `SpecificDate`. It should not be earlier than the subscription contract-effective date, later than the subscription term-end date, or within a period for which the customer has been invoiced.
cancellationPolicy:
type: string
description: |
Cancellation method.
enum:
- EndOfCurrentTerm
- EndOfLastInvoicePeriod
- SpecificDate
paymentTerm:
description: |
The name of the payment term associated with the subscription. For
example, `Net 30`. The payment term determines the due dates of invoices.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request or you select **Default Term from Account** for this field during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
billToContactId:
description: |
The ID of the bill-to contact associated with the subscription.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request or you select **Default Contact from Account** for this field during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
invoiceTemplateId:
description: |
The ID of the invoice template associated with the subscription.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request or you select **Default Template from Account** for this field during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
sequenceSetId:
description: |
The ID of the sequence set associated with the subscription.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request or you select **Default Set from Account** for this field during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
nullable: true
shipToContactId:
description: |
The ID of the ship-to contact associated with the subscription.
type: string
soldToContactId:
description: |
The ID of the sold-to contact associated with the subscription.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request or you select **Default Contact from Account** for this field during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
clearingExistingPaymentTerm:
default: false
description: |
Whether to clear the existing payment term at the subscription level. This field is mutually exclusive with the `paymentTerm` field.
**Note**: If you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
type: boolean
clearingExistingBillToContact:
default: false
description: |
Whether to clear the existing bill-to contact ID at the subscription level. This field is mutually exclusive with the `billToContactId` field.
**Note**: If you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
type: boolean
clearingExistingInvoiceTemplate:
default: false
description: |
Whether to clear the existing invoice template ID at the subscription level. This field is mutually exclusive with the `invoiceTemplateId` field.
**Note**: If you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
type: boolean
clearingExistingSequenceSet:
default: false
description: |
Whether to clear the existing sequence set ID at the subscription level. This field is mutually exclusive with the `sequenceSetId` field.
**Note**: If you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
type: boolean
clearingExistingShipToContact:
default: false
description: |
Whether to clear the existing ship-to contact ID at the subscription level. This field is mutually exclusive with the `shipToContactId` field.
**Note**: If you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
type: boolean
clearingExistingSoldToContact:
default: false
description: |
Whether to clear the existing sold-to contact ID at the subscription level. This field is mutually exclusive with the `soldToContactId` field.
**Note**: If you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
type: boolean
communicationProfileId:
description: |
The ID of the communication profile associated with the subscription.
**Note**: This field is available in the request body only if you have the Flexible Billing Attributes
feature turned on. The value is `null` in the response body without this feature turned on.
type: string
nullable: true
clearingExistingCommunicationProfile:
default: false
description: |
Whether to clear the existing communication profile at the subscription
level. This field is mutually exclusive with the `communicationProfileId` field.
type: boolean
subType:
description: |
The sub type for the change plan order action.
If this field was not set by user, the field is automatically generated by the system according to the following rules:
When the old and new rate plans are within the same Grading catalog group:
* If the grade of new plan is greater than that of the old plan, this is an "Upgrade".
* If the grade of new plan is less than that of the old plan, this is a "Downgrade".
* If the grade of new plan equals that of the old plan, this is a "Crossgrade".
When the old and new rate plans are not in the same Grading catalog group, or either has no group, this is "PlanChanged".
enum:
- Upgrade
- Downgrade
- Crossgrade
- PlanChanged
type: string
effectivePolicy:
description: |
The default value for the `effectivePolicy` field is as follows:
* If the rate plan change (from old to new) is an upgrade, the effective policy is `EffectiveImmediately` by default.
* If the rate plan change (from old to new) is a downgrade, the effective policy is `EffectiveEndOfBillingPeriod` by default.
* Otherwise, the effective policy is `SpecificDate` by default.
**Notes**:
* When setting this field to `EffectiveEndOfBillingPeriod`, you cannot set the billing trigger dates for the subscription as the system will automatically set the trigger dates to the end of billing period.
* When setting this field to `SpecificDate`, you must also set the `contractEffectiveDate` field.
enum:
- EffectiveImmediately
- EffectiveEndOfBillingPeriod
- SpecificDate
type: string
subscription:
$ref: '#/components/schemas/NestedSubscriptionOnExpand'
order:
$ref: '#/components/schemas/NestedOrderOnExpand'
additionalProperties:
type: object
description: |
Custom fields of the Order Action object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryOrderActionResponse
NestedOrderOnExpand:
properties:
id:
type: string
description: |
The unique identifier of the order.
createdById:
type: string
description: |
The unique identifier of the user who created the order.
createdDate:
type: string
format: date-time
description: |
The time that the order gets created in the system, in the
`YYYY-MM-DD HH:MM:SS` format.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the order.
updatedDate:
type: string
format: date-time
description: |
The date and time when the order was last updated.
description:
type: string
description: |
The description of the order.
orderDate:
type: string
format: date
description: |
The date when the order is signed. All the order actions under this
order will use this order date as the contract effective date if no
additinal contractEffectiveDate is provided.
orderNumber:
type: string
description: |
The unique identifier of the order.
accountId:
type: string
description: |
The unique identifier of the customer account associated with the
order.
status:
type: string
description: |
The status of the order. If the order contains any `Pending
Activation` or `Pending Acceptance` subscription, the order status
will be `Pending`; If the order is in draft status, the order status
will be `Draft`; otherwise the order status is `Completed`.
The available order statuses are as follow:
- `Draft`: The order is in draft status.
- `Pending`: The order is in pending status.
- `Completed`: The order is in completed status.
- `Cancelled`: The draft or scheduled order is cancelled.
- `Scheduled`: The order is in scheduled status and it is only valid
if the Scheduled Orders feature is enabled.
- `Executing`: The scheduled order is executed by a scheduler and it
is only valid if the Scheduled Orders feature is enabled.
- `Failed`: The scheduled order has failed.
**Note**: To manage and access the Scheduled Orders feature from the self-service
interface, see Enable billing features by yourself.
enum:
- Draft
- Pending
- Completed
- Cancelled
- Scheduled
- Executing
- Failed
state:
type: string
description: |
The state of the bill-to address. The value is a valid subregion (state
or province) name or code. For more information, see View subregions of a specific country or region.
createdByMigration:
type: boolean
description: |
Indicates whether the order is created by migration.
category:
type: string
invoiceScheduleId:
type: string
description: |
The unique identifier of the invoice schedule associated with the
order.
scheduledDate:
type: string
format: date
description: |
The date for the order scheduled.
scheduledDatePolicy:
description: Date policy of the scheduled order.
enum:
- SpecificDate
type: string
errorCode:
type: string
description: |
The error code of the error response.
errorMessage:
type: string
description: |
The error message of the error response.
response:
type: string
account:
$ref: '#/components/schemas/NestedAccountOnExpand'
orderLineItems:
type: array
items:
$ref: '#/components/schemas/NestedOrderLineItemOnExpand'
orderActions:
type: array
items:
$ref: '#/components/schemas/NestedOrderActionOnExpand'
additionalProperties:
type: object
description: |
Custom fields of the Order object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryOrdersResponse
NestedOrderActionOnExpand:
properties:
id:
type: string
description: |
The unique identifier of the order action.
createdById:
type: string
description: |
The unique identifier of the user who created the order action.
createdDate:
type: string
format: date-time
description: |
The time that the order action gets created in the system, in the
`YYYY-MM-DD HH:MM:SS` format.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the order action.
updatedDate:
type: string
format: date-time
description: |
The date and time when the order action was last updated.
contractEffectiveDate:
type: string
format: date
description: |
Effective contract date for this subscription, as yyyy-mm-dd.
customerAcceptanceDate:
type: string
format: date
description: |
The date on which the services or products within a subscription have been accepted by the customer, as yyyy-mm-dd.
type:
description: |
Type of the order action.
**Note**: The change plan type of order action is supported for the Order to Revenue feature. However, it is currently not supported for the Billing - Revenue Integration feature. When Billing - Revenue Integration is enabled, the change plan type of order action will no longer be applicable in Zuora Billing.
enum:
- CreateSubscription
- TermsAndConditions
- AddProduct
- UpdateProduct
- RemoveProduct
- RenewSubscription
- CancelSubscription
- OwnerTransfer
- Suspend
- Resume
- ChangePlan
type: string
sequence:
type: integer
format: int32
description: |
The sequence of the order actions processed in the order.
subscriptionVersionAmendmentId:
type: string
description: |
The unique identifier of the amendment that changes the version of the subscription.
orderId:
type: string
description: |
The unique identifier of the order that the order action belongs to.
subscriptionId:
type: string
description: |
The unique identifier of the subscription associated with the order action.
subscriptionNumber:
type: string
description: |
The number of the subscription associated with the order action.
serviceActivationDate:
type: string
format: date
description: |
The date on which the services or products within a subscription have been activated and access has been provided to the customer, as yyyy-mm-dd.
autoRenew:
type: boolean
description: |
If `true`, the subscription automatically renews at the end of the term.
default: false
renewSetting:
description: |
Specifies whether a termed subscription will remain termed or change to evergreen when it is renewed.
type: string
enum:
- RENEW_WITH_SPECIFIC_TERM
- RENEW_TO_EVERGREEN
default: RENEW_WITH_SPECIFIC_TERM
renewalTerm:
type: integer
format: int64
description: |
The length of the period for the subscription renewal term.
default: 0
renewalTermPeriodType:
description: |
The period type for the subscription renewal term.
This field is used with the `renewalTerm` field to specify the subscription renewal term.
type: string
enum:
- Month
- Year
- Day
- Week
default: Month
termStartDate:
type: string
format: date
description: |
The date on which the subscription term begins, as `yyyy-mm-dd`. If this is a renewal subscription, this date is different from the subscription start date.
termType:
type: string
enum:
- TERMED
- EVERGREEN
description: |
The type of the subscription term.
currentTerm:
type: integer
format: int64
description: |
The length of the period for the current subscription term.
currentTermPeriodType:
description: |
The period type for the current subscription term.
type: string
enum:
- Month
- Year
- Day
- Week
default: Month
suspendDate:
type: string
format: date
description: |
The date when subscription suspension takes effect, in the `yyyy-mm-dd` format.
resumeDate:
type: string
format: date
description: |
The resume date when the resumption takes effect.
cancellationEffectiveDate:
type: string
format: date
description: |
Date when the cancellation takes effect, in the `yyyy-mm-dd` format. Used only if `cancellationPolicy` is `SpecificDate`. It should not be earlier than the subscription contract-effective date, later than the subscription term-end date, or within a period for which the customer has been invoiced.
cancellationPolicy:
type: string
description: |
Cancellation method.
enum:
- EndOfCurrentTerm
- EndOfLastInvoicePeriod
- SpecificDate
paymentTerm:
description: |
The name of the payment term associated with the subscription. For
example, `Net 30`. The payment term determines the due dates of invoices.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request or you select **Default Term from Account** for this field during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
billToContactId:
description: |
The ID of the bill-to contact associated with the subscription.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request or you select **Default Contact from Account** for this field during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
invoiceTemplateId:
description: |
The ID of the invoice template associated with the subscription.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request or you select **Default Template from Account** for this field during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
sequenceSetId:
description: |
The ID of the sequence set associated with the subscription.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request or you select **Default Set from Account** for this field during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
shipToContactId:
description: |
The ID of the ship-to contact associated with the subscription.
type: string
soldToContactId:
description: |
The ID of the sold-to contact associated with the subscription.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request or you select **Default Contact from Account** for this field during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
clearingExistingPaymentTerm:
default: false
description: |
Whether to clear the existing payment term at the subscription level. This field is mutually exclusive with the `paymentTerm` field.
**Note**: If you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
type: boolean
clearingExistingBillToContact:
default: false
description: |
Whether to clear the existing bill-to contact ID at the subscription level. This field is mutually exclusive with the `billToContactId` field.
**Note**: If you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
type: boolean
clearingExistingInvoiceTemplate:
default: false
description: |
Whether to clear the existing invoice template ID at the subscription level. This field is mutually exclusive with the `invoiceTemplateId` field.
**Note**: If you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
type: boolean
clearingExistingSequenceSet:
default: false
description: |
Whether to clear the existing sequence set ID at the subscription level. This field is mutually exclusive with the `sequenceSetId` field.
**Note**: If you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
type: boolean
clearingExistingShipToContact:
default: false
description: |
Whether to clear the existing ship-to contact ID at the subscription level. This field is mutually exclusive with the `shipToContactId` field.
**Note**: If you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
type: boolean
clearingExistingSoldToContact:
default: false
description: |
Whether to clear the existing sold-to contact ID at the subscription level. This field is mutually exclusive with the `soldToContactId` field.
**Note**: If you have the [Flexible Billing Attributes](https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/flexible-billing/flexible-billing-attributes/overview-of-flexible-billing-attributes) feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
type: boolean
communicationProfileId:
description: |
The ID of the communication profile associated with the subscription.
**Note**: This field is available in the request body only if you have the Flexible Billing Attributes
feature turned on. The value is `null` in the response body without this feature turned on.
type: string
nullable: true
clearingExistingCommunicationProfile:
default: false
description: |
Whether to clear the existing communication profile at the subscription
level. This field is mutually exclusive with the `communicationProfileId` field.
type: boolean
subType:
description: |
The sub type for the change plan order action.
If this field was not set by user, the field is automatically generated by the system according to the following rules:
When the old and new rate plans are within the same Grading catalog group:
* If the grade of new plan is greater than that of the old plan, this is an "Upgrade".
* If the grade of new plan is less than that of the old plan, this is a "Downgrade".
* If the grade of new plan equals that of the old plan, this is a "Crossgrade".
When the old and new rate plans are not in the same Grading catalog group, or either has no group, this is "PlanChanged".
enum:
- Upgrade
- Downgrade
- Crossgrade
- PlanChanged
type: string
effectivePolicy:
description: |
The default value for the `effectivePolicy` field is as follows:
* If the rate plan change (from old to new) is an upgrade, the effective policy is `EffectiveImmediately` by default.
* If the rate plan change (from old to new) is a downgrade, the effective policy is `EffectiveEndOfBillingPeriod` by default.
* Otherwise, the effective policy is `SpecificDate` by default.
**Notes**:
* When setting this field to `EffectiveEndOfBillingPeriod`, you cannot set the billing trigger dates for the subscription as the system will automatically set the trigger dates to the end of billing period.
* When setting this field to `SpecificDate`, you must also set the `contractEffectiveDate` field.
enum:
- EffectiveImmediately
- EffectiveEndOfBillingPeriod
- SpecificDate
type: string
subscription:
type: object
description: |
The subscription associated with this order action.
**Note**: For draft and scheduled orders, information on the subscription, rate plan, and rate plan charges is not available nor displayed until the following conditions are met:
- A scheduled order is executed and its status is changed to `completed`.
- A draft order is activated and its status is changed to `pending` or `completed`.
For example, if an order is in the `scheduled` or `draft` status, information on the subscription, rate plan, and rate plan charges is not displayed.
additionalProperties:
type: object
description: |
Custom fields of the Order Action object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryOrderActionResponse
ExpandedOrderLineItem:
properties:
id:
type: string
description: |
The unique identifier of the order line item.
createdById:
type: string
description: |
The unique identifier of the user who created the order line item.
createdDate:
type: string
format: date-time
description: |
The time that the order line item gets created in the system, in the
`YYYY-MM-DD HH:MM:SS` format.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the order line item.
updatedDate:
type: string
format: date-time
description: |
The date and time when the order line item was last updated.
accountingCode:
type: string
description: |
The accountingCode for the Order Line Item (OLI).
You can update this field only for a sales OLI and only when the sales OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
nullable: true
billTargetDate:
description: |
The target date for the Order Line Item (OLI) to be picked up by bill run for generating billing documents.
To generate billing documents for an OLI, you must set this field and set the `itemState` field to `SentToBilling`.
You can update this field for a sales or return OLI only when the OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
format: date
type: string
amountPerUnit:
type: number
description: |
The actual charged amount per unit for the Order Line Item (OLI).
You can update this field only for a sales OLI and only when the sales OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
description:
description: |
The description of the Order Line Item.
type: string
amount:
type: number
description: |
The total amount for the Order Line Item (OLI).
amountWithoutTax:
type: number
description: |
The total amount for the Order Line Item (OLI) excluding tax.
itemName:
description: |
The name of the Order Line Item (OLI).
You can update this field for a sales or return OLI only when the OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
type: string
itemNumber:
description: |
The number for the Order Line Item (OLI).
You can update this field for a sales or return OLI only when the OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
type: string
itemState:
description: |
The state of the Order Line Item (OLI). See [State transitions for an order, order line item, and fulfillment](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Order_Line_Items/AB_Order_Line_Item_States_and_Order_States) for more information.
To generate invoice for an OLI, you must set this field to `SentToBilling` and set the `billTargetDate` field .
You can update this field for a sales or return OLI only when the OLI is in the `Executing` or 'Booked' or `SentToBilling`state (when the `itemState` field is set as `Executing` or `SentToBilling`).
enum:
- Executing
- Booked
- SentToBilling
- Complete
- Cancelled
type: string
itemType:
description: |
The type of the Order Line Item (OLI).
You can update this field only for a sales OLI and only when the sales OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
enum:
- Product
- Fee
- Services
type: string
listPricePerUnit:
description: |
The list price per unit for the Order Line Item (OLI).
You can update this field only for a sales OLI and only when the sales OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
type: number
listPrice:
description: |
The extended list price for an order line item, calculated by the formula:
listPrice = listPricePerUnit * quantity
type: number
orderId:
type: string
description: |
The ID of the order that the order line item belongs to.
productCode:
description: |
The product code for the Order Line Item (OLI).
You can update this field only for a sales OLI and only when the sales OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
type: string
purchaseOrderNumber:
description: |
Used by customers to specify the Purchase Order Number provided by the buyer.
You can update this field only for a sales OLI and only when the sales OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
type: string
quantity:
description: |
The quantity of units, such as the number of authors in a hosted wiki service.
You can update this field for a sales or return OLI only when the OLI in the `Executing` state (when the `itemState` field is set as `Executing`).
type: number
revenueRecognitionRule:
type: string
description: |
The Revenue Recognition rule for the Order Line Item.
productRatePlanChargeId:
description: |
ID of a Product Rate Plan Charge. Only one-time charges are supported.
type: string
billToId:
description: |
The ID of a contact that belongs to the billing account of the order line item. Use this field to assign an existing account as the bill-to contact of an order line item.
type: string
billToSnapshotId:
description: |
The snapshot of the ID for an account used as the bill-to contact of an order line item. This field is used to store the original information about the account, in case the information about the account is changed after the creation of the order line item. The `billToSnapshotId` field is exposed while retrieving the order line item details.
type: string
shipTo:
description: |
The ID of a contact that belongs to the owner acount or billing account of the order line item. Use this field to assign an existing account as the ship-to contact of an order line item.
type: string
shipToSnapshotId:
description: |
The snapshot of the ID for an account used as the ship-to contact of an order line item. This field is used to store the original information about the account, in case the information about the account is changed after the creation of the order line item. The `shipToSnapshotId` field is exposed while retrieving the order line item details.
type: string
soldTo:
description: |
The ID of a contact that belongs to the owner acount or billing account of the order line item. Use this field to assign an existing account as the sold-to contact of an order line item.
type: string
soldToSnapshotId:
description: |
The snapshot of the ID for an account used as the sold-to contact of an order line item. This field is used to store the original information about the account, in case the information about the account is changed after the creation of the order line item. The `soldToSnapshotId` field is exposed while retrieving the order line item details.
type: string
soldToOrderContactId:
type: string
description: |
The ID of the sold-to contact for the order.
ownerAccountId:
description: |
The account ID of the owner of the order line item.
type: string
invoiceOwnerAccountId:
description: |
The account ID of the invoice owner of the order line item.
type: string
taxCode:
description: |
The tax code for the Order Line Item (OLI).
You can update this field only for a sales OLI and only when the sales OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
type: string
taxMode:
description: |
The tax mode for the Order Line Item (OLI).
You can update this field only for a sales OLI and only when the sales OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
enum:
- TaxInclusive
- TaxExclusive
type: string
transactionDate:
type: string
format: date
description: |
The date when the transaction occurs.
uOM:
description: |
Specifies the units to measure usage.
You can update this field only for a sales OLI and only when the sales OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
type: string
relatedSubscriptionNumber:
description: |
This field is used to relate an order line item to an subscription.
You can update this field only for a sales OLI and only when the sales OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
type: string
transactionEndDate:
description: |
The date a transaction is completed. The default value of this field is the transaction start date. Also, the value of this field should always equal or be later than the value of the `transactionStartDate` field.
You can update this field for a sales or return OLI only when the OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
format: date
type: string
transactionStartDate:
description: |
The date a transaction starts. The default value of this field is the order date.
You can update this field for a sales or return OLI only when the OLI is in the `Executing` state (when the `itemState` field is set as `Executing`).
format: date
type: string
excludeItemBillingFromRevenueAccounting:
type: boolean
description: |
Indicates whether to exclude the related invoice items, invoice item adjustments, credit memo items, and debit memo items from revenue accounting.
**Note**: This field is only available if you have the Order to Revenue or Billing - Revenue Integration feature enabled.
excludeItemBookingFromRevenueAccounting:
type: boolean
description: |
Indicates whether to exclude the related rate plan charges and order line items from revenue accounting.
**Note**: This field is only available if you have the Order to Revenue or Billing - Revenue Integration feature enabled.
originalOrderDate:
type: string
format: date
description: |
The date of the original sale order for a return order line item.
amendedByOrderOn:
type: string
format: date
description: |
The date of the amended order for a return order line item.
itemCategory:
default: Sales
description: |
The category of the Order Line Item, to indicate a product sale or return.
enum:
- Sales
- Return
type: string
originalOrderId:
description: |
The ID of the original sale order for a return order line item.
type: string
originalOrderLineItemId:
description: |
The ID of the original sale order line item for a return order line item.
type: string
originalOrderLineItemNumber:
description: |
The number of the original sale order line item for a return order line item.
type: string
originalOrderNumber:
description: |
The number of the original sale order for a return order line item.
type: string
quantityAvailableForReturn:
description: |
The quantity that can be returned for an order line item.
type: number
quantityFulfilled:
description: |
The fulfilled quantity for an order line item.
type: number
quantityPendingFulfillment:
description: |
The quantity to fulfill for an order line item.
type: number
requiresFulfillment:
description: |
The flag to show whether fulfillment is needed or not. It's derived from billing rule of the Order Line Item.
type: boolean
billingRule:
description: |
The billing rule of the Order Line Item.
enum:
- TriggerWithoutFulfillment
- TriggerAsFulfillmentOccurs
type: string
inlineDiscountPerUnit:
description: |
This field is used in accordance with the `inlineDiscountType` field, in the following manner:
* If the `inlineDiscountType` field is set as `Percentage`, this field specifies the discount percentage for each unit of the order line item. For exmaple, if you specify `5` in this field, the discount percentage is 5%.
* If the `inlineDiscountType` field is set as `FixedAmount`, this field specifies the discount amount on each unit of the order line item. For exmaple, if you specify `10` in this field, the discount amount on each unit of the order line item is 10.
Once you set the `inlineDiscountType`, `inlineDiscountPerUnit`, and `listPricePerUnit` fields, the system will automatically generate the `amountPerUnit` field. You shall not set the `amountPerUnit` field by yourself.
type: number
inlineDiscountType:
description: |
This field is used to specify the inline discount type, which can be `Percentage`, `FixedAmount`, or `None`. The default value is `Percentage`.
This field is used together with the `inlineDiscountPerUnit` field to specify inline discounts for order line items. The inline discount is applied to the list price of an order line item.
Once you set the `inlineDiscountType`, `inlineDiscountPerUnit`, and `listPricePerUnit` fields, the system will automatically generate the `amountPerUnit` field. You shall not set the `amountPerUnit` field by yourself.
enum:
- Percentage
- FixedAmount
- None
type: string
discount:
type: number
description: |
This field shows the total discount amount that is applied to an order line item after the `inlineDiscountType`, `inlineDiscountPerUnit` and `quantity` fields are set.
The inline discount is applied to the list price of an order line item.
recognizedRevenueAccountingCodeId:
type: string
description: |
The recognized revenue accounting code for the Order Line Item.
deferredRevenueAccountingCodeId:
description: |
The deferred revenue accounting code for the Order Line Item.
type: string
contractAssetAccountingCode:
description: |
The accounting code on the Order Line Item object for customers using [Zuora Billing - Revenue Integration](https://knowledgecenter.zuora.com/Zuora_Revenue/Zuora_Billing_-_Revenue_Integration).
type: string
contractLiabilityAccountingCode:
description: |
The accounting code on the Order Line Item object for customers using [Zuora Billing - Revenue Integration](https://knowledgecenter.zuora.com/Zuora_Revenue/Zuora_Billing_-_Revenue_Integration).
type: string
contractRecognizedRevenueAccountingCodeId:
description: |
The accounting code on the Order Line Item object for customers using [Zuora Billing - Revenue Integration](https://knowledgecenter.zuora.com/Zuora_Revenue/Zuora_Billing_-_Revenue_Integration).
type: string
unbilledReceivablesAccountingCodeId:
description: |
The accounting code on the Order Line Item object for customers using [Zuora Billing - Revenue Integration](https://knowledgecenter.zuora.com/Zuora_Revenue/Zuora_Billing_-_Revenue_Integration).
type: string
adjustmentRevenueAccountingCodeId:
description: |
The accounting code on the Order Line Item object for customers using [Zuora Billing - Revenue Integration](https://knowledgecenter.zuora.com/Zuora_Revenue/Zuora_Billing_-_Revenue_Integration).
type: string
adjustmentLiabilityAccountingCodeId:
description: |
The accounting code on the Order Line Item object for customers using [Zuora Billing - Revenue Integration](https://knowledgecenter.zuora.com/Zuora_Revenue/Zuora_Billing_-_Revenue_Integration).
type: string
invoiceItems:
type: array
items:
$ref: '#/components/schemas/NestedInvoiceItemOnExpand'
additionalProperties:
type: object
description: |
Custom fields of the Order Line Item object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryOrderLineItemResponse
ExpandedOrders:
properties:
id:
type: string
description: |
The unique identifier of the order.
createdById:
type: string
description: |
The unique identifier of the user who created the order.
createdDate:
type: string
format: date-time
description: |
The time that the order gets created in the system, in the
`YYYY-MM-DD HH:MM:SS` format.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the order.
updatedDate:
type: string
format: date-time
description: |
The date and time when the order was last updated.
description:
type: string
description: |
The description of the order.
orderDate:
type: string
format: date
description: |
The date when the order is signed. All the order actions under this
order will use this order date as the contract effective date if no
additinal contractEffectiveDate is provided.
orderNumber:
type: string
description: |
The unique identifier of the order.
accountId:
type: string
description: |
The unique identifier of the customer account associated with the
order.
status:
type: string
description: |
The status of the order. If the order contains any `Pending
Activation` or `Pending Acceptance` subscription, the order status
will be `Pending`; If the order is in draft status, the order status
will be `Draft`; otherwise the order status is `Completed`.
The available order statuses are as follow:
- `Draft`: The order is in draft status.
- `Pending`: The order is in pending status.
- `Completed`: The order is in completed status.
- `Cancelled`: The draft or scheduled order is cancelled.
- `Scheduled`: The order is in scheduled status and it is only valid
if the Scheduled Orders feature is enabled.
- `Executing`: The scheduled order is executed by a scheduler and it
is only valid if the Scheduled Orders feature is enabled.
- `Failed`: The scheduled order has failed.
**Note**: To manage and access the Scheduled Orders feature from the self-service
interface, see Enable billing features by yourself.
enum:
- Draft
- Pending
- Completed
- Cancelled
- Scheduled
- Executing
- Failed
state:
type: string
description: |
The state of the bill-to address. The value is a valid subregion (state
or province) name or code. For more information, see View subregions of a specific country or region.
createdByMigration:
type: boolean
description: |
Indicates whether the order is created by migration.
category:
type: string
invoiceScheduleId:
type: string
description: |
The unique identifier of the invoice schedule associated with the
order.
scheduledDate:
type: string
format: date
description: |
The date for the order scheduled.
scheduledDatePolicy:
description: Date policy of the scheduled order.
enum:
- SpecificDate
type: string
errorCode:
type: string
description: |
The error code of the error response.
errorMessage:
type: string
description: |
The error message of the error response.
response:
type: string
account:
$ref: '#/components/schemas/NestedAccountOnExpand'
orderLineItems:
type: array
items:
$ref: '#/components/schemas/NestedOrderLineItemOnExpand'
orderActions:
type: array
items:
$ref: '#/components/schemas/NestedOrderActionOnExpand'
additionalProperties:
type: object
description: |
Custom fields of the Order object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See [Manage Custom Fields](https://knowledgecenter.zuora.com/BB_Introducing_Z_Business/Manage_Custom_Fields) for more information.
type: object
title: QueryOrdersResponse
ExpandedPayment:
properties:
id:
type: string
description: |
The unique identifier of the payment.
createdById:
type: string
description: |
The unique identifier of the user who created the payment.
createdDate:
type: string
format: date-time
description: |
The time that the payment gets created in the system, in the
`YYYY-MM-DD HH:MM:SS` format.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the payment.
updatedDate:
type: string
format: date-time
description: |
The time that the payment gets updated in the system, in the
`YYYY-MM-DD HH:MM:SS` format.
accountId:
description: |
The ID of the customer account that the payment is for.
type: string
accountingCode:
type: string
description: |
The accounting code for the charge. Accounting codes group
transactions that contain similar accounting attributes.
amount:
description: |
The total amount of the payment.
format: double
type: number
appliedAmount:
description: |
The applied amount of the payment.
format: double
type: number
authTransactionId:
description: |
The authorization transaction ID from the payment gateway.
type: string
appliedCreditBalanceAmount:
type: number
description: |
The amount of the payment to apply to a credit balance.
bankIdentificationNumber:
type: string
description: |
The first six or eight digits of the credit card or debit card used for the payment, when applicable.
Use this field to reconcile payments between the gateway and merchant banks.
cancelledOn:
type: string
description: |
The date when the payment was canceled.
format: date-time
comment:
type: string
description: |
Comments about the payment.
nullable: true
currency:
description: |
When Standalone Payment is not enabled, the `currency` of the payment must be the same as the payment currency defined in the customer account settings through Zuora UI.
When Standalone Payment is enabled and `standalone` is `true`, the `currency` of the standalone payment can be different from the payment currency defined in the customer account settings. The amount will not be summed up to the account balance or key metrics regardless of currency.
type: string
example: USD
effectiveDate:
type: string
format: date
description: |
The date and time when the payment takes effect, in `yyyy-mm-dd hh:mm:ss` format.
gatewayOrderId:
description: |
A merchant-specified natural key value that can be passed to the electronic payment gateway when a payment is created.
type: string
gatewayReconciliationReason:
description: |
The reason of gateway reconciliation.
type: string
gatewayReconciliationStatus:
description: |
The status of gateway reconciliation.
type: string
gatewayResponse:
description: |
The message returned from the payment gateway for the payment. This message is gateway-dependent.
type: string
gatewayResponseCode:
description: |
The code returned from the payment gateway for the payment. This code is gateway-dependent.
type: string
gatewayState:
description: |
The status of the payment in the gateway; use for reconciliation.
enum:
- MarkedForSubmission
- Submitted
- Settled
- NotSubmitted
- FailedToSettle
type: string
gatewayTransactionState:
type: string
isStandalone:
type: boolean
description: |
Indicates whether the payment is a standalone payment. A standalone
payment is a payment that is not associated with any invoice or
subscription.
markedForSubmissionOn:
type: string
format: date-time
description: |
The date and time when a charge was marked and waiting for batch
submission to the payment process, in `yyyy-mm-dd hh:mm:ss` format.
paymentMethodId:
type: string
description: |
The unique ID of the payment method that the customer used to make the payment.
paymentMethodSnapshotId:
type: string
description: |
The unique ID of the payment method snapshot which is a copy of the particular Payment Method used in a transaction.
paymentOptionId:
type: string
description: |
ID of the paymentOption object, which describe the transactional level rules for processing payments.
paymentNumber:
type: string
description: |
The unique identification number of a payment.
example: P-00000028.
payoutId:
type: string
description: |
The payout ID of the payment from the gateway side.
prepayment:
description: |
Indicates whether the payment is used as a reserved payment. See [Prepaid Cash with Drawdown](https://knowledgecenter.zuora.com/Zuora_Billing/Billing_and_Invoicing/JA_Advanced_Consumption_Billing/Prepaid_Cash_with_Drawdown) for more information.
type: boolean
referencedPaymentID:
type: string
description: |
The ID of a referenced payment.
referenceId:
description: |
The transaction ID returned by the payment gateway. Use this field to reconcile payments between your gateway and Zuora Payments.
type: string
refundAmount:
type: number
description: |
The amount of the payment that is refunded.
format: double
secondPaymentReferenceId:
type: string
description: |
The transaction ID returned by the payment gateway if there is an additional transaction for the payment. Use this field to reconcile payments between your gateway and Zuora Payments.
settledOn:
type: string
format: date-time
description: |
The date and time when the payment was settled in the payment processor, in `yyyy-mm-dd hh:mm:ss` format. This field is used by the Spectrum gateway only and not applicable to other gateways.
softDescriptor:
type: string
description: |
A payment gateway-specific field that maps to Zuora for the gateways, Orbital, Vantiv and Verifi.
softDescriptorPhone:
type: string
description: |
A payment gateway-specific field that maps to Zuora for the gateways, Orbital, Vantiv and Verifi.
source:
type: string
description: |
Indicates how the payment was created, whether through API, manually, import, or payment run.
enum:
- PaymentRun
- Import
- Manually
- API
sourceName:
type: string
description: |
Name of the source. It can be a payment run number or a file name.
status:
description: |
The status of the payment.
enum:
- Draft
- Processing
- Processed
- Error
- Canceled
- Posted
type: string
submittedOn:
description: |
The date and time when the payment was submitted, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
type:
description: |
The type of the payment.
enum:
- External
- Electronic
type: string
transferredToAccounting:
description: |
Whether the payment was transferred to an external accounting system. Use this field for integration with accounting systems, such as NetSuite.
enum:
- Processing
- 'Yes'
- 'No'
- Error
- Ignore
type: string
transactionSource:
type: string
description: |
Payment transaction source used to differentiate the transaction source in Stored Credential Transaction framework.
- `C_Unscheduled`: Cardholder-initiated transaction (CIT) that does not occur on scheduled or regularly occurring dates.
- `M_Recurring`: Merchant-initiated transaction (MIT) that occurs at regular intervals.
- `M_Unscheduled`: Merchant-initiated transaction (MIT) that does not occur on scheduled or regularly occurring dates.
- `M_MOTO`: Mail Order Telephone Order (MOTO) payment transaction. This option is only available for credit card payments on Stripe v2. See [Overview of Stripe payment gateway integration](https://knowledgecenter.zuora.com/Zuora_Collect/Payment_gateway_integrations/Supported_payment_gateways/Stripe_Payment_Gateway/A_Overview_of_Stripe_payment_gateway_integration) for more information.
enum:
- C_Unscheduled
- M_Recurring
- M_Unscheduled
- M_MOTO
unappliedAmount:
type: number
description: |
The unapplied amount of the payment.
lastEmailDateTime:
type: string
description: |
The date and time when the last email was sent to the customer for the payment.
gateway:
type: string
description: |
Name of the gateway instance that processes the payment.
account:
$ref: '#/components/schemas/NestedAccountOnExpand'
paymentMethod:
$ref: '#/components/schemas/NestedPaymentMethodOnExpand'
paymentApplications:
type: array
items:
$ref: '#/components/schemas/ExpandedPaymentApplication'
additionalProperties:
type: object
description: |
Custom fields of the Payment object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryPaymentResponse
ExpandedPaymentApplication:
properties:
id:
type: string
description: |
The unique identifier of the payment application.
createdById:
type: string
description: |
The unique identifier of the user who created the payment application.
createdDate:
type: string
format: date-time
description: |
The date and time when the payment application was created.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the payment application.
updatedDate:
type: string
format: date-time
description: |
The date and time when the payment application was last updated.
applyAmount:
type: number
format: double
description: |
The applied amount of the payment.
effectiveDate:
type: string
format: date
description: |
The date when the payment application takes effect, in `yyyy-mm-dd` format.
The effective date is later than or equal to the maximum effective date of the payment.
paymentApplicationStatus:
type: string
description: |
The status of the payment application.
enum:
- Processing
- Processed
- Cancelled
accountId:
type: string
description: |
The ID of the customer account associated with the payment application.
paymentId:
type: string
description: |
The unique ID of the created payment.
example: 4028905f5a87c0ff015a87eb6b75007f
invoiceId:
type: string
description: |
The ID of the invoice to which the payment is applied.
applicationGroupId:
type: string
description: |
The ID of the application group to which this payment application belongs.
debitMemoId:
type: string
description: |
The ID of the debit memo to which the payment is applied.
billingDocumentOwnerId:
type: string
description: |
The ID of the billing document owner.
accountReceivableAccountingCodeId:
type: string
description: |
The accountReceivableAccountingCode of a standalone charge.
**Note:** This field is available when the Standalone Orders, Zuora Finance, and Invoice Settlement features are enabled.
unappliedPaymentAccountingCodeId:
type: string
description: |
The accounting code for the unapplied payment.
cashAccountingCodeId:
type: string
description: |
The accounting code for cash payments.
journalEntryId:
type: string
description: |
The ID of the journal entry that corresponds to this transaction.
payment:
$ref: '#/components/schemas/NestedPaymentOnExpand'
type: object
title: QueryPaymentApplicationResponse
additionalProperties: false
ExpandedPaymentMethod:
properties:
id:
type: string
description: |
The unique identifier of the payment method.
createdById:
type: string
description: |
The unique identifier of the user who created the payment method.
createdDate:
type: string
format: date-time
description: |
The time that the payment method gets created in the system, in the
`YYYY-MM-DD HH:MM:SS` format.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the payment method.
updatedDate:
type: string
format: date-time
description: |
The time that the payment method gets updated in the system, in the
`YYYY-MM-DD HH:MM:SS` format.
accountId:
type: string
description: |
The unique identifier of the account that the payment method is
associated with.
achAbaCode:
type: string
description: |
The nine-digit routing number or ABA number used by banks. This field is only required if the `type` field is set to `ACH`.
achAccountName:
type: string
description: |
The name of the account holder, which can be either a person or a company. This field is only required if the `type` field is set to `ACH`.
achAccountNumberMask:
description: |
The masked bank account number associated with the ACH payment method. This field is only required if the `type` field is set to `ACH`.
type: string
achAccountType:
type: string
description: |
The type of bank account associated with the ACH payment method. This field is only required if the `type` field is set to `ACH`.
When creating an ACH payment method on Adyen, this field is required by Zuora but it is not required by Adyen. To create the ACH payment method successfully, specify a real value for this field if you can. If it is not possible to get the real value for it, specify any of the allowed values as a dummy value, `Checking` preferably.
enum:
- BusinessChecking
- Checking
- Saving
achAddress1:
type: string
description: |
First address line for the ACH payment method.
maxLength: 255
achAddress2:
type: string
description: |
Second address line for the ACH payment method.
maxLength: 255
achBankName:
type: string
description: |
The name of the bank where the ACH payment account is held.
When creating an ACH payment method on Adyen, this field is required by Zuora but it is not required by Adyen. To create the ACH payment method successfully, specify a real value for this field if you can. If it is not possible to get the real value for it, specify a dummy value.
maxLength: 70
achCity:
type: string
description: |
City for the ACH payment method.
It is recommended to provide the city and country information when creating a payment method. The information will be used to process payments. If the information is not provided during payment method creation, the city and country data will be missing during payment processing.
maxLength: 40
achCountry:
description: |
Country for the ACH payment method. Must be a valid country name or abbreviation.
See View countries or regions for the list of supported country names and abbreviations.
It is recommended to provide the city and country information when creating a payment method. The information will be used to process payments. If the information is not provided during payment method creation, the city and country data will be missing during payment processing.
type: string
achPostalCode:
type: string
description: |
Zip code or postal code for the ACH payment method.
maxLength: 20
achState:
type: string
description: |
State for the ACH payment method. Must be a valid subregion (state or province) name or code. For more information, see View subregions of a specific country or region.
active:
type: boolean
description: |
Indicates whether the payment method type is active. This field is for Zuora internal use and does not impact customer integration or use cases.
isSystem:
type: boolean
description: |
Indicates whether the payment method is a system-generated payment method. This field is for Zuora internal use and does not impact customer integration or use cases.
accountVerificationService:
description: |
Displays the name of the service provider. For example, Plaid.
type: string
accountVerificationStatus:
description: |
Displays the status of the account.
**Note:**
- `Active` - Access token is active.
- `Expired` - Access token has expired and must be linked again.
- `Expiring` - Access token will expire in few days(7 days for Plaid) and must be linked again
- `Inactive` - The end customer has revoked the account pemission. The end customer can login again and select the same method for the access token to be linked again.
enum:
- Active
- Expired
- Expiring
- Inactive
type: string
bankBranchCode:
type: string
description: |
The branch code of the bank used for Direct Debit.
bankCheckDigit:
description: The check digit in the international bank account number, which confirms the validity of the account. Applicable to direct debit payment methods.
type: string
bankCity:
type: string
description: The city of the direct debit bank.
bankCode:
type: string
description: |
The sort code or number that identifies the bank. This is also known as the sort code.
bankIdentificationNumber:
type: string
description: The first six or eight digits of the payment method's number, such as the credit card number or account number. Banks use this number to identify a payment method.
bankName:
type: string
description: The name of the direct debit bank.
bankPostalCode:
type: string
description: The zip code or postal code of the direct debit bank.
bankStreetName:
type: string
description: The name of the street of the direct debit bank.
bankStreetNumber:
type: string
description: The number of the direct debit bank.
bankTransferAccountName:
type: string
description: The name on the direct debit bank account.
bankTransferAccountNumberMask:
type: string
description: |
This is a masked displayable version of the bank account number, used for
security purposes. For example: `XXXXXXXXX54321`.
bankTransferAccountType:
type: string
description: |
The type of the customer's bank account. Applicable to direct debit
payment methods.
bankTransferType:
description: |
Specifies the type of direct debit transfer. The value of this field is dependent on the country of the user.
Possible Values:
* `AutomatischIncasso` (NL)
* `LastschriftDE` (Germany)
* `LastschriftAT` (Austria)
* `DemandeDePrelevement` (FR)
* `DirectDebitUK` (UK)
* `Domicil` (Belgium)
* `LastschriftCH` (CH)
* `RID` (Italy)
* `OrdenDeDomiciliacion` (Spain)
* `Autogiro` (Sweden)
* `Betalingsservice` (Denmark)
enum:
- AutomatischIncasso
- LastschriftDE
- LastschriftAT
- DemandeDePrelevement
- DirectDebitUK
- Domicil
- LastschriftCH
- RID
- OrdenDeDomiciliacion
- Autogiro
- Betalingsservice
type: string
businessIdentificationCode:
type: string
description: |
The business identification code for Swiss direct payment methods that use
the Global Collect payment gateway. Only applicable to direct debit
payment methods in Switzerland with Global Collect.
city:
description: |
The city of the customer's address. Applicable to debit payment methods.
type: string
country:
type: string
description: The two-letter country code of the customer's address. Applicable to direct debit payment methods.
creditCardAddress1:
type: string
description: |
The first line of the card holder's address, which is often a street
address or business name. Applicable to credit card and direct debit
payment methods.
creditCardAddress2:
type: string
description: |
The second line of the card holder's address. Applicable to credit card
and direct debit payment methods.
creditCardCity:
type: string
description: |
The city of the card holder's address. Applicable to credit card and
direct debit payment methods.
creditCardCountry:
description: |
The country where the credit card holder stays.
When creating a payment method through a translated UI or Payment Page, a country name in a translated language might be selected.
Regardless of the country texts selected when creating the payment method, only the supported country name returns in this field.
For a complete list of supported country names, see View countries or regions.
Internationalization is not supported for the API field value.
type: string
creditCardExpirationMonth:
type: integer
format: int32
description: |
One or two digits expiration month.
minimum: 1
maximum: 12
creditCardExpirationYear:
type: integer
format: int32
description: |
Four-digit expiration year.
creditCardHolderName:
type: string
description: |
The full name of the credit card holder.
creditCardMaskNumber:
description: |
The masked credit card number, such as `*********1112`.
type: string
creditCardPostalCode:
type: string
description: |
The postal code for the address of the credit card holder.
creditCardState:
type: string
description: |
The state where the credit card holder stays.
creditCardType:
description: |
The type of the credit card or debit card.
Possible values include `Visa`, `MasterCard`, `AmericanExpress`, `Discover`, `JCB`, and `Diners`. For more information about credit card types supported by different payment gateways, see [Supported Payment Gateways](https://knowledgecenter.zuora.com/CB_Billing/M_Payment_Gateways/Supported_Payment_Gateways).
**Note:** This field is only returned for the Credit Card and Debit Card payment types.
type: string
deviceSessionId:
description: |
The session ID of the user when the `PaymentMethod` was created or updated.
type: string
existingMandate:
description: |
Indicates whether the mandate is an existing mandate.
enum:
- 'Yes'
- 'No'
type: string
email:
description: |
The email address of the payment method holder.
type: string
firstName:
type: string
description: |
The customer's first name. Only applicable to direct debit payment methods.
iBAN:
type: string
description: |
The International Bank Account Number used to create the SEPA payment method. The value is masked.
iPAddress:
type: string
description: |
The IP address of the user when the payment method was created or updated.
identityNumber:
type: string
description: |
The identity number of the account holder or the cardholder.
companyName:
type: string
description: |
The name of the company.
isCompany:
type: boolean
description: |
Whether the customer account is a company.
lastFailedSaleTransactionDate:
type: string
format: date
description: |
The date of the last failed attempt to collect payment with this payment
method.
lastName:
type: string
description: |
The customer's last name. Only applicable to direct debit payment methods.
lastTransactionDateTime:
type: string
description: |
The date and time of the most recent transaction.
format: date-time
lastTransactionStatus:
type: string
description: The status of the most recent transaction.
mandateCreationDate:
description: |
The date on which the mandate was created.
format: date
type: string
mandateId:
description: |
The mandate ID.
type: string
mandateReason:
description: |
The reason of the mandate from the gateway side.
type: string
mandateReceived:
type: string
description: |
Indicates whether the mandate is received from the gateway.
enum:
- 'Yes'
- 'No'
mandateStatus:
type: string
description: |
The status of the mandate from the gateway side.
mandateUpdateDate:
type: string
format: date
description: |
The date on which the mandate was updated.
maxConsecutivePaymentFailures:
type: integer
format: int32
description: |
The number of allowable consecutive failures Zuora attempts with the payment method before stopping.
name:
type: string
description: |
The name of the payment method.
numConsecutiveFailures:
type: integer
format: int32
description: |
The number of consecutive failed payments for this payment method. It is reset to `0` upon successful payment.
paymentMethodStatus:
type: string
description: |
The status of the payment method.
enum:
- Active
- Closed
- Scrubbed
paymentRetryWindow:
type: integer
format: int32
description: |
The retry interval setting, which prevents making a payment attempt if the last failed attempt was within the last specified number of hours.
paypalBaid:
type: string
description: |
ID of a PayPal billing agreement.
example: I-1TJ3GAGG82Y9
paypalEmail:
type: string
description: |
Email address associated with the PayPal payment method.
paypalPreapprovalKey:
type: string
description: |
The PayPal preapproval key.
paypalType:
type: string
description: |
The type of the PayPal payment method.
phone:
type: string
description: |
The phone number that the account holder registered with the bank. This
field is used for credit card validation when passing to a gateway.
postalCode:
type: string
description: |
The zip code of the customer's address. Only applicable to direct debit
payment methods.
secondTokenId:
description: |
A gateway unique identifier that replaces sensitive payment method data.
**Note:** This field is only returned for the Credit Card Reference Transaction payment type.
type: string
state:
type: string
description: |
The state of the customer's address. Only applicable to direct debit
payment methods.
streetName:
type: string
description: |
The street name of the customer's address. Only applicable to direct debit
payment methods.
streetNumber:
type: string
description: |
The street number of the customer's address. Only applicable to direct
debit payment methods.
tokenId:
type: string
description: |
A gateway unique identifier that replaces sensitive payment method data or
represents a gateway's unique customer profile. Applicable to CC Reference
Transaction payment methods.
totalNumberOfErrorPayments:
type: integer
format: int32
description: The number of error payments that used this payment method.
totalNumberOfProcessedPayments:
type: integer
format: int32
description: The number of successful payments that used this payment method.
type:
type: string
description: |
The type of the payment method. For example, `CreditCard`.
useDefaultRetryRule:
type: boolean
description: |
Indicates whether this payment method uses the default retry rules configured in the Zuora Payments settings.
methodReferenceId:
type: string
description: |
The identification reference of the custom payment method.
This field should be mapped to a field name defined in the `fields` array for the purpose of being used as a filter in reporting tools such as Payment Method Data Source Exports and Data Query.
userReferenceId:
type: string
description: |
The identification reference of the user or customer account.
This field should be mapped to a field name defined in the `fields` array for the purpose of being used as a filter in reporting tools such as Data Source Exports and Data Query.
subType:
type: string
description: |
The identification reference indicating the subtype of the custom payment method.
This field should be mapped to a field name defined in the `fields` array for the purpose of being used as a filter in reporting tools such as Data Source Exports and Data Query.
methodSpecificData:
type: string
description: |
Other method-specific data of the payment method.
cardBrand:
description: |
The card brand, such as `Visa` and `MasterCard`.
type: string
cardClass:
description: |
The type of the card.
type: string
enum:
- ChargeCard
- Credit
- Debit
- DeferredDebit
- Prepaid
cardIssuingBank:
type: string
description: |
The issuer bank of the card, such as `JPMORGAN CHASE BANK N.A.`.
cardIssuingCountry:
type: string
description: |
The issuing country code of the card, such as `US`.
cardProductType:
type: string
description: |
The product type of the card.
enum:
- Commercial_or_Corporate_Card
- Consumer_Card
account:
$ref: '#/components/schemas/NestedAccountOnExpand'
additionalProperties:
type: object
description: |
Custom fields of the Payment Method object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryPaymentMethodResponse
ExpandedPaymentMethodSnapshot:
properties:
id:
type: string
description: |
The unique identifier of the payment method snapshot.
createdById:
type: string
description: |
The unique identifier of the user who created the payment method snapshot.
createdDate:
type: string
format: date-time
description: |
The time that the payment method snapshot gets created in the system, in the
`YYYY-MM-DD HH:MM:SS` format.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the payment method snapshot.
updatedDate:
type: string
format: date-time
description: |
The time that the payment method snapshot gets updated in the system, in the
`YYYY-MM-DD HH:MM:SS` format.
accountId:
type: string
description: |
The unique identifier of the account that the payment method snapshot is
associated with.
achAbaCode:
type: string
description: |
The nine-digit routing number or ABA number used by banks. This field is only required if the `type` field is set to `ACH`.
achAccountName:
type: string
description: |
The name of the account holder, which can be either a person or a company. This field is only required if the `type` field is set to `ACH`.
achAccountNumberMask:
description: |
The masked bank account number associated with the ACH payment method. This field is only required if the `type` field is set to `ACH`.
type: string
achAccountType:
type: string
description: |
The type of bank account associated with the ACH payment method. This field is only required if the `type` field is set to `ACH`.
When creating an ACH payment method on Adyen, this field is required by Zuora but it is not required by Adyen. To create the ACH payment method successfully, specify a real value for this field if you can. If it is not possible to get the real value for it, specify any of the allowed values as a dummy value, `Checking` preferably.
enum:
- BusinessChecking
- Checking
- Saving
achAddress1:
type: string
description: |
First address line for the ACH payment method.
maxLength: 255
achAddress2:
type: string
description: |
Second address line for the ACH payment method.
maxLength: 255
achBankName:
type: string
description: |
The name of the bank where the ACH payment account is held.
When creating an ACH payment method on Adyen, this field is required by Zuora but it is not required by Adyen. To create the ACH payment method successfully, specify a real value for this field if you can. If it is not possible to get the real value for it, specify a dummy value.
maxLength: 70
achCity:
type: string
description: |
City for the ACH payment method.
It is recommended to provide the city and country information when creating a payment method. The information will be used to process payments. If the information is not provided during payment method creation, the city and country data will be missing during payment processing.
maxLength: 40
achCountry:
description: |
Country for the ACH payment method. Must be a valid country name or abbreviation.
See View countries or regions for the list of supported country names and abbreviations.
It is recommended to provide the city and country information when creating a payment method. The information will be used to process payments. If the information is not provided during payment method creation, the city and country data will be missing during payment processing.
type: string
achPostalCode:
type: string
description: |
Zip code or postal code for the ACH payment method.
maxLength: 20
achState:
type: string
description: |
State for the ACH payment method. Must be a valid subregion (state or province) name or code. For more information, see View subregions of a specific country or region.
active:
type: boolean
description: |
Indicates whether the payment method type is active. This field is for Zuora internal use and does not impact customer integration or use cases.
isSystem:
type: boolean
description: |
Indicates whether the payment method is a system-generated payment method. This field is for Zuora internal use and does not impact customer integration or use cases.
bankBranchCode:
type: string
description: |
The branch code of the bank used for Direct Debit.
bankCheckDigit:
description: The check digit in the international bank account number, which confirms the validity of the account. Applicable to direct debit payment methods.
type: string
bankCity:
type: string
description: The city of the direct debit bank.
bankCode:
type: string
description: |
The sort code or number that identifies the bank. This is also known as the sort code.
bankIdentificationNumber:
type: string
description: The first six or eight digits of the payment method's number, such as the credit card number or account number. Banks use this number to identify a payment method.
bankName:
type: string
description: The name of the direct debit bank.
bankPostalCode:
type: string
description: The zip code or postal code of the direct debit bank.
bankStreetName:
type: string
description: The name of the street of the direct debit bank.
bankStreetNumber:
type: string
description: The number of the direct debit bank.
bankTransferAccountName:
type: string
description: The name on the direct debit bank account.
bankTransferAccountNumberMask:
type: string
description: |
This is a masked displayable version of the bank account number, used for
security purposes. For example: `XXXXXXXXX54321`.
bankTransferAccountType:
type: string
description: |
The type of the customer's bank account. Applicable to direct debit
payment methods.
bankTransferType:
description: |
Specifies the type of direct debit transfer. The value of this field is dependent on the country of the user.
Possible Values:
* `AutomatischIncasso` (NL)
* `LastschriftDE` (Germany)
* `LastschriftAT` (Austria)
* `DemandeDePrelevement` (FR)
* `DirectDebitUK` (UK)
* `Domicil` (Belgium)
* `LastschriftCH` (CH)
* `RID` (Italy)
* `OrdenDeDomiciliacion` (Spain)
* `Autogiro` (Sweden)
* `Betalingsservice` (Denmark)
enum:
- AutomatischIncasso
- LastschriftDE
- LastschriftAT
- DemandeDePrelevement
- DirectDebitUK
- Domicil
- LastschriftCH
- RID
- OrdenDeDomiciliacion
- Autogiro
- Betalingsservice
type: string
businessIdentificationCode:
type: string
description: |
The business identification code for Swiss direct payment methods that use
the Global Collect payment gateway. Only applicable to direct debit
payment methods in Switzerland with Global Collect.
city:
description: |
The city of the customer's address. Applicable to debit payment methods.
type: string
country:
type: string
description: The two-letter country code of the customer's address. Applicable to direct debit payment methods.
creditCardAddress1:
type: string
description: |
The first line of the card holder's address, which is often a street
address or business name. Applicable to credit card and direct debit
payment methods.
creditCardAddress2:
type: string
description: |
The second line of the card holder's address. Applicable to credit card
and direct debit payment methods.
creditCardCity:
type: string
description: |
The city of the card holder's address. Applicable to credit card and
direct debit payment methods.
creditCardCountry:
description: |
The country where the credit card holder stays.
When creating a payment method through a translated UI or Payment Page, a country name in a translated language might be selected.
Regardless of the country texts selected when creating the payment method, only the supported country name returns in this field.
For a complete list of supported country names, see View countries or regions.
Internationalization is not supported for the API field value.
type: string
creditCardExpirationMonth:
type: integer
format: int32
description: |
One or two digits expiration month.
minimum: 1
maximum: 12
creditCardExpirationYear:
type: integer
format: int32
description: |
Four-digit expiration year.
creditCardHolderName:
type: string
description: |
The full name of the credit card holder.
creditCardMaskNumber:
description: |
The masked credit card number, such as `*********1112`.
type: string
creditCardPostalCode:
type: string
description: |
The postal code for the address of the credit card holder.
creditCardState:
type: string
description: |
The state where the credit card holder stays.
creditCardType:
description: |
The type of the credit card or debit card.
Possible values include `Visa`, `MasterCard`, `AmericanExpress`, `Discover`, `JCB`, and `Diners`. For more information about credit card types supported by different payment gateways, see [Supported Payment Gateways](https://knowledgecenter.zuora.com/CB_Billing/M_Payment_Gateways/Supported_Payment_Gateways).
**Note:** This field is only returned for the Credit Card and Debit Card payment types.
type: string
deviceSessionId:
description: |
The session ID of the user when the `PaymentMethod` was created or updated.
type: string
existingMandate:
description: |
Indicates whether the mandate is an existing mandate.
enum:
- 'Yes'
- 'No'
type: string
email:
description: |
The email address of the payment method holder.
type: string
firstName:
type: string
description: |
The customer's first name. Only applicable to direct debit payment methods.
iBAN:
type: string
description: |
The International Bank Account Number used to create the SEPA payment method. The value is masked.
iPAddress:
type: string
description: |
The IP address of the user when the payment method was created or updated.
identityNumber:
type: string
description: |
The identity number of the account holder or the cardholder.
companyName:
type: string
description: |
The name of the company.
isCompany:
type: boolean
description: |
Whether the customer account is a company.
lastFailedSaleTransactionDate:
type: string
format: date
description: |
The date of the last failed attempt to collect payment with this payment
method.
lastName:
type: string
description: |
The customer's last name. Only applicable to direct debit payment methods.
lastTransactionDateTime:
type: string
description: |
The date and time of the most recent transaction.
format: date-time
lastTransactionStatus:
type: string
description: The status of the most recent transaction.
mandateCreationDate:
description: |
The date on which the mandate was created.
format: date
type: string
mandateId:
description: |
The mandate ID.
type: string
mandateReason:
description: |
The reason of the mandate from the gateway side.
type: string
mandateReceived:
type: string
description: |
Indicates whether the mandate is received from the gateway.
enum:
- 'Yes'
- 'No'
mandateStatus:
type: string
description: |
The status of the mandate from the gateway side.
mandateUpdateDate:
type: string
format: date
description: |
The date on which the mandate was updated.
maxConsecutivePaymentFailures:
type: integer
format: int32
description: |
The number of allowable consecutive failures Zuora attempts with the payment method before stopping.
paymentMethodId:
type: string
description: |
ID of the associated payment method.
name:
type: string
description: |
The name of the payment method.
numConsecutiveFailures:
type: integer
format: int32
description: |
The number of consecutive failed payments for this payment method. It is reset to `0` upon successful payment.
paymentMethodStatus:
type: string
description: |
The status of the payment method.
enum:
- Active
- Closed
- Scrubbed
paymentRetryWindow:
type: integer
format: int32
description: |
The retry interval setting, which prevents making a payment attempt if the last failed attempt was within the last specified number of hours.
paypalBaid:
type: string
description: |
ID of a PayPal billing agreement.
example: I-1TJ3GAGG82Y9
paypalEmail:
type: string
description: |
Email address associated with the PayPal payment method.
paypalPreapprovalKey:
type: string
description: |
The PayPal preapproval key.
paypalType:
type: string
description: |
The type of the PayPal payment method.
phone:
type: string
description: |
The phone number that the account holder registered with the bank. This
field is used for credit card validation when passing to a gateway.
postalCode:
type: string
description: |
The zip code of the customer's address. Only applicable to direct debit
payment methods.
secondTokenId:
description: |
A gateway unique identifier that replaces sensitive payment method data.
**Note:** This field is only returned for the Credit Card Reference Transaction payment type.
type: string
state:
type: string
description: |
The state of the customer's address. Only applicable to direct debit
payment methods.
streetName:
type: string
description: |
The street name of the customer's address. Only applicable to direct debit
payment methods.
streetNumber:
type: string
description: |
The street number of the customer's address. Only applicable to direct
debit payment methods.
tokenId:
type: string
description: |
A gateway unique identifier that replaces sensitive payment method data or
represents a gateway's unique customer profile. Applicable to CC Reference
Transaction payment methods.
totalNumberOfErrorPayments:
type: integer
format: int32
description: The number of error payments that used this payment method.
totalNumberOfProcessedPayments:
type: integer
format: int32
description: The number of successful payments that used this payment method.
type:
type: string
description: |
The type of the payment method. For example, `CreditCard`.
useDefaultRetryRule:
type: boolean
description: |
Indicates whether this payment method uses the default retry rules configured in the Zuora Payments settings.
methodReferenceId:
type: string
description: |
The identification reference of the custom payment method.
This field should be mapped to a field name defined in the `fields` array for the purpose of being used as a filter in reporting tools such as Payment Method Data Source Exports and Data Query.
userReferenceId:
type: string
description: |
The identification reference of the user or customer account.
This field should be mapped to a field name defined in the `fields` array for the purpose of being used as a filter in reporting tools such as Data Source Exports and Data Query.
subType:
type: string
description: |
The identification reference indicating the subtype of the custom payment method.
This field should be mapped to a field name defined in the `fields` array for the purpose of being used as a filter in reporting tools such as Data Source Exports and Data Query.
methodSpecificData:
type: string
description: |
Other method-specific data of the payment method.
additionalProperties:
type: object
description: |
Custom fields of the Payment Method Snapshot object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryPaymentMethodSnapshotResponse
ExpandedPaymentRun:
properties:
id:
type: string
description: |
The unique identifier of the payment run.
createdById:
type: string
description: |
The unique identifier of the user who created the payment run.
createdDate:
type: string
format: date-time
description: |
The time that the payment run gets created in the system, in the
`YYYY-MM-DD HH:MM:SS` format.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the payment run.
updatedDate:
type: string
format: date-time
description: |
The time that the payment run gets updated in the system, in the
`YYYY-MM-DD HH:MM:SS` format.
endDate:
type: string
description: |
The end date of the payment run.
executedDate:
type: string
format: date-time
description: |
The date and time when the payment run is executed, in `yyyy-mm-dd
hh:mm:ss` format. For example, 2024-03-01 11:30:37.
numberOfCreditBalanceAdjustments:
type: integer
format: int32
description: |
**Note:** This field is only available if you have the Credit Balance
feature enabled.
The number of credit balance adjustments that are successfully processed
in the payment run.
numberOfErrors:
format: int32
description: |
The number of payments with the status of `Error` and `Processing`.
type: integer
numberOfInvoices:
type: integer
format: int32
description: |
**Note:** This field is only available if you have the Invoice Settlement feature enabled.
The total number of invoices that are picked up for processing in the payment run.
numberOfPayments:
type: integer
format: int32
description: |
The number of payments that are successfully processed in the payment run.
numberOfUnprocessed:
type: integer
format: int32
description: |
The number of billing documents with remaining positive balances after the
payment run is completed.
paymentRunNumber:
type: string
description: |
Number of the payment run.
status:
description: |
The status of the created payment run.
enum:
- Pending
- Processing
- Completed
- Error
- Canceled
type: string
targetDate:
type: string
format: date
description: |
The target date used to determine which receivables to be collected in the
payment run.
applyCreditBalance:
description: |
Whether to apply credit balances in the payment run. This field is only
available when you have Invoice Settlement feature disabled.
type: boolean
consolidatedPayment:
type: boolean
description: |
**Note:** The **Process Electronic Payment** permission also needs to be allowed for a Manage Payment Runs role to work. See [Payments Roles](https://knowledgecenter.zuora.com/CF_Users_and_Administrators/A_Administrator_Settings/User_Roles/e_Payments_Roles) for more information.
Whether to process a single payment for all receivables that are due on an account.
processPaymentWithClosedPM:
description: |
Whether to process payments even if the default payment method is closed.
**Note:** The **Process Electronic Payment** permission also needs to be
allowed for a Manage Payment Runs role to work. See [Payments
Roles](https://knowledgecenter.zuora.com/CF_Users_and_Administrators/A_Administrator_Settings/User_Roles/e_Payments_Roles)
for more information.
type: boolean
collectPayment:
description: |
Whether to process electronic payments during the execution of payment
runs.
type: boolean
autoApplyCreditMemo:
description: |
Whether to automatically apply a posted credit memo to one or more
receivables in the payment run.
**Note:** This field is only available if you have [Invoice
Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement)
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: boolean
autoApplyUnappliedPayment:
description: |
Whether to automatically apply unapplied payments to one or more
receivables in the payment run.
**Note:** This field is only available if you have [Invoice
Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement)
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: boolean
numberOfCreditMemos:
type: integer
format: int32
description: |
The total number of credit memos that are successfully processed in the
payment run.
**Note:** This field is only available if you have the Invoice Settlement
feature enabled.
numberOfDebitMemos:
type: integer
format: int32
description: |
The total number of debit memos that are picked up for processing in the payment run.
**Note:** This field is only available if you have the Invoice Settlement feature enabled.
numberOfDebitMemosUnprocessed:
type: integer
format: int32
description: |
The total number of debit memos that are not processed in the payment run.
**Note:** This field is only available if you have the Invoice Settlement
feature enabled.
numberofUnappliedPayments:
type: integer
format: int32
description: |
The number of unapplied payments that are successfully processed in the
payment run.
**Note:** This field is only available if you have the Invoice Settlement
feature enabled.
totalExecutionTime:
type: integer
format: int64
description: |
The total time taken to execute the payment run in milliseconds.
errorMessage:
type: string
description: |
The detailed information of the error response.
runDate:
type: string
format: date
description: |
The date and time when the scheduled payment run is to be executed for
collecting payments.
nextRunOn:
type: string
format: date
description: |
The date when the next payment run is scheduled to run.
repeatType:
type: string
description: |
The repeat type of the payment run.
enum:
- None
- Daily
- Weekly
- Monthly
repeatFrom:
type: string
description: |
The start date of the scheduled payment run.
repeatTo:
type: string
description: |
The end date of of the scheduled payment run.
runTime:
type: integer
format: int32
description: |
The scheduled run time (hour) of day.
minimum: 0
maximum: 23
timeZone:
type: string
description: |
Timezone of the scheduled payment run.
monthlyOnDay:
type: string
description: |
The repeat day in a month.
weeklyOnDay:
type: string
description: |
The repeat day in a week.
This field is required if you set `repeatType` field to `Weekly`.
enum:
- Mon
- Tue
- Wed
- Thu
- Fri
- Sat
- Sun
accountId:
description: |
The ID of the customer account associated with the payment run.
type: string
batch:
type: string
description: |
The alias name given to a batch.
example: Batch1
billingCycleDay:
description: |
The billing cycle day (BCD), the day of the month when a bill run
generates invoices for the account.
example: 1
type: string
currency:
description: |
A currency defined in the web-based UI administrative settings.
example: USD
type: string
paymentGatewayId:
type: string
description: |
The ID of the gateway instance that processes the payment.
format: uuid
nullable: true
billingRunId:
type: string
description: |
The unique identifier of the billing run that the payment run is
associated with.
additionalProperties:
type: object
description: |
Custom fields of the Payment Run object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryPaymentRunResponse
ExpandedPaymentSchedule:
properties:
id:
type: string
description: |
The unique identifier of the payment schedule.
createdById:
type: string
description: |
The unique identifier of the user who created the payment schedule.
createdDate:
type: string
format: date-time
description: |
The time that the payment schedule gets created in the system, in the
`YYYY-MM-DD HH:MM:SS` format.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the payment schedule.
updatedDate:
type: string
format: date-time
description: |
The time that the payment schedule gets updated in the system, in the
`YYYY-MM-DD HH:MM:SS` format.
number:
type: string
description: |
Number of the payment schedule.
accountId:
type: string
description: |
ID of the account that owns the payment schedule.
invoiceId:
type: string
description: |
The unique identifier of the invoice to which the payment is applied.
debitmemoId:
type: string
description: |
The unique identifier of the debit memo to which the payment is applied.
paymentOptionId:
type: string
description: |
The unique identifier of the payment option that is used to process
the payment schedule.
startDate:
type: string
format: date
description: |
The date when the first payment of this payment schedule is
proccessed.
runHour:
type: integer
format: int32
description: |
At which hour in the day in the tenant’s timezone the recurring
payment schedule items will be collected.
Return `0` for custom payment schedules.
minimum: 0
maximum: 23
period:
type: string
description: |
For recurring payment schedule only. The period of payment generation.
Returns `null` for custom payment schedules.
nullable: true
enum:
- Monthly
- Weekly
- BiWeekly
- null
prepayment:
type: boolean
description: |
Indicates whether the payments created by the payment schedule are
used as a reserved payment. This field is available only if the
prepaid cash drawdown permission is enabled. See [Prepaid Cash with
Drawdown](https://knowledgecenter.zuora.com/Zuora_Billing/Billing_and_Invoicing/JA_Advanced_Consumption_Billing/Prepaid_Cash_with_Drawdown)
for more information.
occurrences:
type: integer
format: int32
description: |
The number of payment schedule items that are created by this payment schedule.
status:
type: string
description: |
The status of the payment schedule.
- Active: There is still payment schedule item to process.
- Canceled: After a payment schedule is canceled by the user, the
schedule is marked as `canceled`.
- Completed: After all payment schedule items are processed, the
schedule is marked as `Completed`.
enum:
- Active
- Canceled
- Completed
description:
type: string
description: |
The description of the payment schedule.
nextPaymentDate:
type: string
format: date
description: |
The date the next payment will be processed.
recentPaymentDate:
type: string
format: date
description: |
The date the last payment was processed.
totalPaymentsProcessed:
type: integer
format: int32
description: |
The number of processed payments.
totalPaymentsErrored:
type: integer
format: int32
description: |
The number of errored payments.
totalAmount:
description: |
The total amount that will be collected by the payment
schedule.
type: number
additionalProperties:
type: object
description: |
Custom fields of the Payment Schedule object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryPaymentScheduleResponse
ExpandedPaymentScheduleItem:
properties:
id:
type: string
description: |
The unique identifier of the payment schedule item.
createdById:
type: string
description: |
The unique identifier of the user who created the payment schedule item.
createdDate:
type: string
format: date-time
description: |
The time that the payment schedule item gets created in the system, in the
`YYYY-MM-DD HH:MM:SS` format.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the payment schedule item.
updatedDate:
type: string
format: date-time
description: |
The time that the payment schedule item gets updated in the system, in the
`YYYY-MM-DD HH:MM:SS` format.
number:
type: string
description: |
Number of the payment schedule item.
accountId:
type: string
description: |
ID of the account that owns the payment schedule.
invoiceId:
type: string
description: |
The unique identifier of the invoice to which the payment is applied.
debitmemoId:
type: string
description: |
The unique identifier of the debit memo to which the payment is applied.
paymentOptionId:
type: string
description: |
The unique identifier of the payment option that is used to process
the payment schedule item.
prepayment:
type: boolean
description: |
Indicates whether the payments created by the payment schedule are
used as a reserved payment. This field is available only if the
prepaid cash drawdown permission is enabled. See [Prepaid Cash with
Drawdown](https://knowledgecenter.zuora.com/Zuora_Billing/Billing_and_Invoicing/JA_Advanced_Consumption_Billing/Prepaid_Cash_with_Drawdown)
for more information.
scheduledDate:
type: string
format: date
description: |
The scheduled date when the payment is processed.
runHour:
type: integer
format: int32
description: |
At which hour in the day in the tenant’s timezone the recurring
payment schedule items will be collected.
Return `0` for custom payment schedules.
minimum: 0
maximum: 23
paymentMethodId:
type: string
description: |
ID of the payment method that will pay the billing documents.
paymentGatewayId:
type: string
nullable: true
description: |
ID of the payment gateway that processes the payment.
amount:
type: number
description: |
The total amount of the payment schedule item.
balance:
type: number
description: |
The remaining balance of payment schedule item.
currency:
type: string
description: |
The currency in which the payment is made.
Note: If this field was not specified, the default value is the currency set for the account.
status:
description: |
ID of the payment method of the payment schedule item.
- `Pending`: Waiting for processing.
- `Processed`: The payment has been collected.
- `Error`: Failed to collect the payment.
- `Canceled`: After a pending payment schedule item is canceled by the user, the item is marked as `Canceled`.
enum:
- Pending
- Processed
- Error
- Canceled
type: string
errorMessage:
type: string
description: |
The error message indicating if the error is related to the
configuration or the payment collection.
paymentId:
type: string
description: |
ID of the payment that is created by the payment schedule item, or linked to the payment schedule item.
This field is only available if the request doesn’t specify `Zuora-Version`, or `Zuora-Version` is set to a value equal to or smaller than\_`336.0`.
description:
type: string
description: |
The description of the payment schedule item.
cancellationReason:
type: string
description: |
The reason for the cancellation of payment schedule item.
paymentScheduleId:
type: string
description: |
ID of the payment schedule to which the payment schedule item belongs.
additionalProperties:
type: object
description: |
Custom fields of the Payment Schedule Item object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryPaymentScheduleItemResponse
ExpandedPrepaidBalance:
properties:
id:
type: string
description: |
The unique identifier of the prepaid balance.
createdById:
type: string
description: |
The unique identifier of the user who created the payment application.
createdDate:
type: string
format: date-time
description: |
The date and time when the payment application was created.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the payment application.
updatedDate:
type: string
format: date-time
description: |
The date and time when the payment application was last updated.
name:
type: string
description: |
The name of the prepaid balance.
totalFund:
type: number
description: |
The total amount of all prepaid balance funds.
balance:
type: number
description: |
The current prepaid balance.
endDate:
description: End date of the validity period.
format: date
type: string
startDate:
description: Start date of the validity period.
format: date
type: string
accountId:
type: string
description: |
The ID of the customer account to which the prepaid balance belongs.
origSubscriptionId:
type: string
description: |
If it belongs to a subscription, the original subscription ID.
uOM:
description: |
The units of measure for prepayment charge. Units of measure
are configured in the web-based UI. Your values depend on your
configuration in **Billing Settings**.
**Values**: a valid unit of measure
type: string
prepaidBalanceState:
type: string
description: |
The state of the prepaid balance.
enum:
- ACTIVE
- EXPIRED
prepaidType:
type: integer
format: int32
description: |
The type of the prepaid balance.
nullable: true
account:
$ref: '#/components/schemas/NestedAccountOnExpand'
origSubscription:
$ref: '#/components/schemas/NestedSubscriptionOnExpand'
additionalProperties:
type: object
description: |
Custom fields of the Prepaid Balance object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryPrepaidBalanceResponse
ExpandedPrepaidBalanceFund:
properties:
id:
type: string
description: |
The unique identifier of the prepaid balance fund.
createdById:
type: string
description: |
The unique identifier of the user who created the prepaid balance fund.
createdDate:
type: string
format: date-time
description: |
The date and time when the prepaid balance fund was created.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the prepaid balance fund.
updatedDate:
type: string
format: date-time
description: |
The date and time when the prepaid balance fund was last updated.
accountId:
type: string
description: |
The ID of the customer account to which the prepaid balance fund belongs.
balance:
type: number
description: |
The remaining balance (remaining units) on the fund.
chargeSegmentNumber:
type: integer
format: int32
description: |
The number of the charge segment. One prepaid balance fund can only belong to one charge segment.
endDate:
type: string
format: date
description: |
End date of the fund effective period.
fundedBalance:
type: number
description: |
The total units of the fund.
fundSourceType:
type: string
description: |
The type of the Prepaid Balance Fund.
enum:
- CHARGE
- ORDER_LINE_ITEM
- CREDIT_MEMO_ITEM
- DEBIT_MEMO_ITEM
fundingPrice:
type: number
description: |
The price amount of a fund. A rounded value that follows the associated invoice owner's currency rounding rule.
**Calculation**: (Number of billing periods in one fund validity period) * (price in one billing period)
totalBilled:
type: number
description: |
The total billed amount of a fund.
totalBalance:
type: number
description: |
The total balance of a fund.
originalTotalBalance:
type: number
description: |
The original total balance of a fund.
originalFundingPrice:
type: number
description: |
The original price amount of a fund.
originalFundEndDate:
type: string
format: date
description: |
The original end date of the fund effective period.
rolloverValidityPeriodStartDate:
type: string
format: date
description: |
Start date of the rollover validity period.
rolloverValidityPeriodEndDate:
type: string
format: date
description: |
End date of the rollover validity period.
prepaidBalanceId:
type: string
description: |
The ID of the prepaid balance associated to which this prepaid balance fund belongs.
priority:
type: integer
format: int32
description: |
The priority of the Fund. Possible values include: 10(high), 50(medium),100(low)
enum:
- 10
- 50
- 100
sourceId:
type: string
description: |
The source Id of the fund. It is the original charge ID.
startDate:
type: string
format: date
description: |
Start date of the fund effective period.
vpSummaryId:
type: string
rolloverCount:
type: integer
format: int32
originFundId:
type: string
rolloverApplyOption:
type: string
done:
type: integer
format: int32
account:
$ref: '#/components/schemas/NestedAccountOnExpand'
prepaidBalance:
$ref: '#/components/schemas/NestedPrepaidBalanceOnExpand'
source:
$ref: '#/components/schemas/NestedRatePlanChargeOnExpand'
vpSummary:
$ref: '#/components/schemas/NestedValidityPeriodSummaryOnExpand'
additionalProperties:
type: object
description: |
Custom fields of the Prepaid Balance Fund object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryPrepaidBalanceFundResponse
NestedPrepaidBalanceOnExpand:
properties:
id:
type: string
description: |
The unique identifier of the prepaid balance.
createdById:
type: string
description: |
The unique identifier of the user who created the payment application.
createdDate:
type: string
format: date-time
description: |
The date and time when the payment application was created.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the payment application.
updatedDate:
type: string
format: date-time
description: |
The date and time when the payment application was last updated.
name:
type: string
description: |
The name of the prepaid balance.
totalFund:
type: number
description: |
The total amount of all prepaid balance funds.
balance:
type: number
description: |
The current prepaid balance.
endDate:
description: End date of the validity period.
format: date
type: string
startDate:
description: Start date of the validity period.
format: date
type: string
accountId:
type: string
description: |
The ID of the customer account to which the prepaid balance belongs.
origSubscriptionId:
type: string
description: |
If it belongs to a subscription, the original subscription ID.
uOM:
description: |
The units of measure for prepayment charge. Units of measure
are configured in the web-based UI. Your values depend on your
configuration in **Billing Settings**.
**Values**: a valid unit of measure
type: string
prepaidBalanceState:
type: string
description: |
The state of the prepaid balance.
enum:
- ACTIVE
- EXPIRED
prepaidType:
type: integer
format: int32
description: |
The type of the prepaid balance.
nullable: true
account:
type: object
description: |
The account associated with the prepaid balance.
origSubscription:
type: object
description: |
The subscription associated with the prepaid balance.
additionalProperties:
type: object
description: |
Custom fields of the Prepaid Balance object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryPrepaidBalanceResponse
NestedValidityPeriodSummaryOnExpand:
properties:
id:
type: string
description: |
The unique identifier of the validity period summary.
createdById:
type: string
description: |
The unique identifier of the user who created the validity period summary.
createdDate:
type: string
format: date-time
description: |
The date and time when the validity period summary was created.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the validity period summary.
updatedDate:
type: string
format: date-time
description: |
The date and time when the validity period summary was last updated.
prepaidBalanceId:
type: string
description: |
The unique identifier of the prepaid balance.
startDate:
type: string
format: date
description: |
The start date of the validity period.
endDate:
type: string
format: date
description: |
The end date of the validity period.
totalBalance:
type: number
description: |
The total prepaid balance for the current validity period.
remainingBalance:
type: number
description: |
The remaining prepaid balance for the current validity period.
totalBilledAmount:
type: number
description: |
The total amount that has been billed.
billedBalanceAmount:
type: number
description: |
The total amount of the billing documents balances.
subscriptionNumber:
type: string
description: |
The number of the subscription the validity period belongs to.
uom:
type: string
description: |
The UOM of the validity period.
accountNumber:
type: string
description: |
The number of the account to which the prepaid balance belongs.
accountId:
type: string
description: |
The ID of the account to which the prepaid balance belongs.
overageRatedQuantity:
type: number
format: double
description: |
The overage rated quantity for the validity period.
**Note**: The `overageRatedQuantity` and `overageRatedAmount` fields of the Validity Period Summary object are approaching end of support on February 01, 2025. For more information, see Product and feature end of support plan.
overageRatedAmount:
type: number
format: double
description: |
The overage rated amount for the validity period.
**Note**: The `overageRatedQuantity` and `overageRatedAmount` fields of the Validity Period Summary object are approaching end of support on February 01, 2025. For more information, see Product and feature end of support plan.
account:
type: object
description: |
The account associated with the validty period summary.
prepaidBalance:
type: object
description: |
The prepaid balance associated with the validity period summary.
billingTiming:
type: string
description: |
The billing timing of the validity period.
enum:
- In Advance
- In Arrears
additionalProperties:
type: object
description: |
Custom fields of the Validity Period Summary object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryValidityPeriodSummaryResponse
ExpandedPrepaidBalanceTransaction:
properties:
id:
type: string
description: |
The unique identifier of the prepaid balance transaction.
createdById:
type: string
description: |
The unique identifier of the user who created the prepaid balance transaction.
createdDate:
type: string
format: date-time
description: |
The date and time when the prepaid balance transaction was created.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the prepaid balance transaction.
updatedDate:
type: string
format: date-time
description: |
The date and time when the prepaid balance transaction was last updated.
accountId:
type: string
description: |
The ID of the customer account on which the prepaid balance transaction occurs.
prepaidBalanceId:
type: string
description: |
The ID of the prepaid balance.
fundId:
type: string
description: |
The ID of the prepaid balance fund.
amount:
type: number
description: |
The amount of units to be adjusted to the prepaid balance (could be positive or negative).
balance:
type: number
description: |
The prepaid balance after a transaction.
sourceId:
type: string
description: |
The transaction source id (original Charge Id, Guided Usage Id, Order Line Item Id).
transactionDate:
type: string
format: date
description: |
The date when the prepaid balance transaction occurs.
transactionSourceType:
type: string
description: |
The type of the transaction source.
enum:
- CHARGE
- ORDER_LINE_ITEM
- USAGE
prepaidBalanceTransactionType:
type: string
description: |
The type of the Prepaid Balance Transaction.
enum:
- PREPAYMENT
- DRAWDOWN
- PREPAYMENT_ADJUSTMENT
- DRAWDOWN_ADJUSTMENT
- DRAWDOWN_REVERSAL
- PREPAYMENT_CREDIT_BACK
- PREPAYMENT_CREDIT_BACK_REVERSAL
usageUom:
type: string
drawdownRate:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
The [conversion rate](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_drawdown_charge#UOM_Conversion) between Usage UOM and Drawdown UOM for a [drawdown charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_drawdown_charge). Must be a positive number (>0).
type: number
nullable: true
account:
$ref: '#/components/schemas/NestedAccountOnExpand'
prepaidBalance:
$ref: '#/components/schemas/NestedPrepaidBalanceOnExpand'
fund:
$ref: '#/components/schemas/NestedPrepaidBalanceFundOnExpand'
additionalProperties:
type: object
description: |
Custom fields of the Prepaid Balance Transaction object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryPrepaidBalanceTransactionResponse
NestedPrepaidBalanceFundOnExpand:
properties:
id:
type: string
description: |
The unique identifier of the prepaid balance fund.
createdById:
type: string
description: |
The unique identifier of the user who created the prepaid balance fund.
createdDate:
type: string
format: date-time
description: |
The date and time when the prepaid balance fund was created.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the prepaid balance fund.
updatedDate:
type: string
format: date-time
description: |
The date and time when the prepaid balance fund was last updated.
accountId:
type: string
description: |
The ID of the customer account to which the prepaid balance fund belongs.
balance:
type: number
description: |
The remaining balance (remaining units) on the fund.
chargeSegmentNumber:
type: integer
format: int32
description: |
The number of the charge segment. One prepaid balance fund can only belong to one charge segment.
endDate:
type: string
format: date
description: |
End date of the fund effective period.
fundedBalance:
type: number
description: |
The total units of the fund.
fundSourceType:
type: string
description: |
The type of the Prepaid Balance Fund.
enum:
- CHARGE
- ORDER_LINE_ITEM
- CREDIT_MEMO_ITEM
- DEBIT_MEMO_ITEM
fundingPrice:
type: number
description: |
The price amount of a fund. A rounded value that follows the associated invoice owner's currency rounding rule.
**Calculation**: (Number of billing periods in one fund validity period) * (price in one billing period)
totalBilled:
type: number
totalBalance:
type: number
originalTotalBalance:
type: number
originalFundingPrice:
type: number
originalFundEndDate:
type: string
format: date
rolloverValidityPeriodStartDate:
type: string
format: date
rolloverValidityPeriodEndDate:
type: string
format: date
prepaidBalanceId:
type: string
description: |
The ID of the prepaid balance associated to which this prepaid balance fund belongs.
priority:
type: integer
format: int32
description: |
The priority of the Fund. Possible values include: 10(high), 50(medium),100(low)
enum:
- 10
- 50
- 100
sourceId:
type: string
description: |
The source Id of the fund. It is the original charge ID.
startDate:
type: string
format: date
description: |
Start date of the fund effective period.
vpSummaryId:
type: string
rolloverCount:
type: integer
format: int32
originFundId:
type: string
rolloverApplyOption:
type: string
done:
type: integer
format: int32
account:
type: object
description: |
The account associated with the prepaid balance fund.
prepaidBalance:
type: object
description: |
The prepaid balance that contains the prepaid balance fund.
source:
type: object
description: |
The rate plan charge associated with the prepaid balance fund.
vpSummary:
type: object
description: |
The validity period summary associated with the prepaid balance fund.
additionalProperties:
type: object
description: |
Custom fields of the Prepaid Balance Fund object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryPrepaidBalanceFundResponse
ExpandedProcessedUsage:
properties:
id:
type: string
description: |
The unique identifier of the processed usage.
createdById:
type: string
description: |
The unique identifier of the user who created the processed usage.
createdDate:
type: string
format: date-time
description: |
The date and time when the processed usage was created.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the processed usage.
updatedDate:
type: string
format: date-time
description: |
The date and time when the processed usage was last updated.
usageId:
type: string
description: |
The unique identifier of the usage.
amount:
type: number
description: |
The amount of the processed usage.
billingPeriodEndDate:
type: string
description: |
The end date of the billing period for the processed usage.
billingPeriodStartDate:
type: string
description: |
The start date of the billing period for the processed usage.
invoiceItemId:
type: string
description: |
The unique identifier of the invoice item associated with the processed usage.
creditMemoItemId:
type: string
description: |
The unique identifier of the credit memo item associated with the processed usage.
ratePlanChargeId:
type: string
description: |
ID of the rate plan charge associated with the processed usage.
usage:
$ref: '#/components/schemas/NestedUsageOnExpand'
invoiceItem:
$ref: '#/components/schemas/NestedInvoiceItemOnExpand'
creditMemoItem:
$ref: '#/components/schemas/NestedCreditMemoItemOnExpand'
type: object
title: QueryProcessedUsageResponse
additionalProperties: false
ExpandedProduct:
properties:
id:
type: string
description: |
The unique identifier of the product.
createdById:
type: string
description: |
The unique identifier of the user who created the product.
createdDate:
type: string
format: date-time
description: |
The date and time when the product was created.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the product.
updatedDate:
type: string
format: date-time
description: |
The date and time when the product was last updated.
allowFeatureChanges:
type: boolean
description: |
Controls whether to allow your users to add or remove features while creating or amending a subscription.
default: false
description:
type: string
description: |
A description of the product.
name:
type: string
description: |
The name of the product. This information is displayed in the product
catalog pages in the web-based UI.
effectiveEndDate:
type: string
format: date
description: |
The date when the product expires and can't be subscribed to anymore,
in the `yyyy-mm-dd` format.
effectiveStartDate:
type: string
format: date
description: |
The date when the product becomes available and can be subscribed to, in the `yyyy-mm-dd` format.
sKU:
type: string
description: |
The unique SKU for the product.
productNumber:
type: string
description: |
The product number of the product.
category:
type: string
description: |
Category of the product. Used by Zuora Quotes Guided Product Selector.
enum:
- Base Products
- Add On Services
- Miscellaneous Products
productRatePlans:
type: array
items:
$ref: '#/components/schemas/NestedProductRatePlanOnExpand'
additionalProperties:
type: object
description: |
Custom fields of the Product object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryProductResponse
NestedProductRatePlanOnExpand:
properties:
id:
type: string
description: |
The unique identifier of the product rate plan.
createdById:
type: string
description: |
The unique identifier of the user who created the product rate plan.
createdDate:
type: string
format: date-time
description: |
The date and time when the product rate plan was created.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the product rate plan.
updatedDate:
type: string
format: date-time
description: |
The date and time when the product rate plan was last updated.
productId:
type: string
description: |
The unique identifier of the product to which this product rate
plan belongs.
name:
type: string
description: |
The name of the product rate plan.
description:
type: string
description: |
A description of the product rate plan.
effectiveStartDate:
type: string
format: date
description: |
First date the rate plan is active (i.e., available to be subscribed
to), as `yyyy-mm-dd`. Before this date, the status is `NotStarted`.
effectiveEndDate:
type: string
format: date
description: |
Final date the rate plan is active, as `yyyy-mm-dd`. After this date,
the rate plan status is `Expired`.
grade:
type: integer
format: int32
description: |
The grade of the product rate plan.
**Note**: This field is in the **Early Adopter** phase. We are
actively soliciting feedback from a small set of early adopters before
releasing it as generally available. If you want to join this early
adopter program, submit a request at [Zuora Global
Support](http://support.zuora.com/).
productRatePlanNumber:
type: string
description: |
The natural key of the product rate plan.
product:
type: object
description: |
The product associated with the product rate plan.
productRatePlanCharges:
type: array
items:
type: object
description: |
The product rate plan charges on the product rate plan.
additionalProperties:
type: object
description: |
Custom fields of the Product Rate Plan object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryProductRatePlanResponse
ExpandedProductRatePlan:
properties:
id:
type: string
description: |
The unique identifier of the product rate plan.
createdById:
type: string
description: |
The unique identifier of the user who created the product rate plan.
createdDate:
type: string
format: date-time
description: |
The date and time when the product rate plan was created.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the product rate plan.
updatedDate:
type: string
format: date-time
description: |
The date and time when the product rate plan was last updated.
productId:
type: string
description: |
The unique identifier of the product to which this product rate
plan belongs.
name:
type: string
description: |
The name of the product rate plan.
description:
type: string
description: |
A description of the product rate plan.
effectiveStartDate:
type: string
format: date
description: |
First date the rate plan is active (i.e., available to be subscribed
to), as `yyyy-mm-dd`. Before this date, the status is `NotStarted`.
effectiveEndDate:
type: string
format: date
description: |
Final date the rate plan is active, as `yyyy-mm-dd`. After this date,
the rate plan status is `Expired`.
grade:
type: integer
format: int32
description: |
The grade of the product rate plan.
**Note**: This field is in the **Early Adopter** phase. We are
actively soliciting feedback from a small set of early adopters before
releasing it as generally available. If you want to join this early
adopter program, submit a request at [Zuora Global
Support](http://support.zuora.com/).
productRatePlanNumber:
type: string
description: |
The natural key of the product rate plan.
product:
$ref: '#/components/schemas/NestedProductOnExpand'
productRatePlanCharges:
type: array
items:
$ref: '#/components/schemas/NestedPrpcOnExpand'
additionalProperties:
type: object
description: |
Custom fields of the Product Rate Plan object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryProductRatePlanResponse
NestedProductOnExpand:
properties:
id:
type: string
description: |
The unique identifier of the product.
createdById:
type: string
description: |
The unique identifier of the user who created the product.
createdDate:
type: string
format: date-time
description: |
The date and time when the product was created.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the product.
updatedDate:
type: string
format: date-time
description: |
The date and time when the product was last updated.
allowFeatureChanges:
type: boolean
description: |
Controls whether to allow your users to add or remove features while creating or amending a subscription.
default: false
description:
type: string
description: |
A description of the product.
name:
type: string
description: |
The name of the product. This information is displayed in the product
catalog pages in the web-based UI.
effectiveEndDate:
type: string
format: date
description: |
The date when the product expires and can't be subscribed to anymore,
in the `yyyy-mm-dd` format.
effectiveStartDate:
type: string
format: date
description: |
The date when the product becomes available and can be subscribed to, in the `yyyy-mm-dd` format.
sKU:
type: string
description: |
The unique SKU for the product.
productNumber:
type: string
description: |
The product number of the product.
category:
type: string
description: |
Category of the product. Used by Zuora Quotes Guided Product Selector.
enum:
- Base Products
- Add On Services
- Miscellaneous Products
productRatePlans:
type: array
items:
type: object
description: The product rate plans contained in this product.
additionalProperties:
type: object
description: |
Custom fields of the Product object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryProductResponse
NestedPrpcOnExpand:
properties:
id:
type: string
description: |
The unique identifier of the product rate plan charge.
createdById:
type: string
description: |
The unique identifier of the user who created the product rate plan charge.
createdDate:
type: string
format: date-time
description: |
The date and time when the product rate plan charge was created.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the product rate plan charge.
updatedDate:
type: string
format: date-time
description: |
The date and time when the product rate plan charge was last updated.
accountingCode:
type: string
description: |
The accounting code for the charge. Accounting codes group
transactions that contain similar accounting attributes.
maxLength: 100
applyDiscountTo:
type: string
description: |
Indicates which type of charge the discount charge applies to.
enum:
- ONETIME
- RECURRING
- USAGE
- ONETIMERECURRING
- ONETIMEUSAGE
- RECURRINGUSAGE
- ONETIMERECURRINGUSAGE
- null
nullable: true
chargeFunction:
description: |
**Note**: This field is only available if you have the Prepaid with Drawdown or Minimum Commitment feature enabled.
This field defines what type of charge it is:
* Standard: Normal charge with no Prepayment or Commitment or Drawdown.
* Prepayment: For recurring charges. Unit or currency based prepaid charge.
* CommitmentTrueUp: For recurring charges. Currency based minimum commitment charge.
* Drawdown: For usage charges. Drawdown from prepaid funds.
* DrawdownAndCreditCommitment: For usage charges. Drawdown from prepaid funds and then credit to minimum commitment funds.
* CreditCommitment: For usage charges. Credit to minimum commitment funds.
enum:
- Standard
- Prepayment
- CommitmentTrueUp
- Drawdown
- CreditCommitment
- DrawdownAndCreditCommitment
type: string
isAllocationEligible:
type: boolean
description: |
Indicates whether the charge segment is allocation eligible in revenue recognition.
default: false
isUnbilled:
type: boolean
description: |
Specifies how to perform the accounting during revenue recognition.
default: false
applyToBillingPeriodPartially:
description: |
Allow the discount duration to be aligned with the billing period partially.
type: boolean
default: false
billCycleDay:
type: integer
format: int64
description: |
Sets the bill cycle day (BCD) for the charge. The BCD determines which
day of the month customer is billed. The BCD value in the account can
override the BCD in this object.
minimum: 1
maximum: 31
billCycleType:
description: |
Specifies how to determine the billing day for the
charge.
enum:
- DefaultFromCustomer
- SpecificDayofMonth
- SubscriptionStartDay
- ChargeTriggerDay
- SpecificDayofWeek
- TermStartDay
- TermEndDay
type: string
billingPeriod:
description: |
The billing period for the charge. The start day of the billing period
is also called the bill cycle day (BCD).
enum:
- Month
- Quarter
- Annual
- Semi-Annual
- Specific Months
- Subscription Term
- Week
- Specific Weeks
- Specific Days
type: string
billingPeriodAlignment:
type: string
description: |
The billing period alignment setting for this charge.
enum:
- AlignToCharge
- AlignToSubscriptionStart
- AlignToTermStart
- AlignToTermEnd
billingTiming:
type: string
description: |
The billing timing for this charge.
enum:
- IN_ADVANCE
- IN_ARREARS
chargeModel:
description: |
Determines how to calculate charges. Charge models must be individually activated in Zuora Billing administration.
enum:
- Discount-Fixed Amount
- Discount-Percentage
- Flat Fee Pricing
- Per Unit Pricing
- Overage Pricing
- Tiered Pricing
- Tiered with Overage Pricing
- Volume Pricing
- Delivery Pricing
- MultiAttributePricing
- PreratedPerUnit
- PreratedPricing`
- HighWatermarkVolumePricing
- HighWatermarkTieredPricing
type: string
chargeType:
description: |
Specifies the type of charge.
enum:
- OneTime
- Recurring
- Usage
type: string
creditOption:
type: string
description: |
**Note**: This field is only available if you have the [Prepaid with
Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown)
feature enabled.
The way to calculate credit. See [Credit
Option](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge#Credit_Option)
for more information.
enum:
- TimeBased
- ConsumptionBased
- FullCreditBack
defaultQuantity:
type: number
nullable: true
description: |
The default quantity.
This field is applicable only for one-time and recurring charges.
deferredRevenueAccount:
type: string
description: |
The name of the deferred revenue account for this charge.
This feature is in **Limited Availability**. If you wish to have
access to the feature, submit a request at [Zuora Global
Support](http://support.zuora.com/).
maxLength: 100
description:
type: string
description: |
Description of the product rate plan charge.
discountClassId:
type: string
description: |
ID of the class the discount belongs to. The discount class defines the order in which discount product rate plan charges are applied.
For more information, see [Manage Discount Classes](https://knowledgecenter.zuora.com/BC_Subscription_Management/Product_Catalog/B_Charge_Models/Manage_Discount_Classes).
nullable: true
discountLevel:
description: |
The application scope of the discount charge. For example, if the value of this field is `subscription` and the value of the `applyDiscountTo` field is `RECURRING`, the discount charge applies to all recurring charges in the same subscription as the discount charge.
enum:
- rateplan
- subscription
- account
- null
type: string
nullable: true
drawdownRate:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
The [conversion rate](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_drawdown_charge#UOM_Conversion) between Usage UOM and Drawdown UOM for a [drawdown charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_drawdown_charge). Must be a positive number (>0).
type: number
nullable: true
endDateCondition:
description: |
The end date condition for this charge.
enum:
- SubscriptionEnd
- OneTime
- FixedPeriod
- SpecificEndDate
type: string
excludeItemBillingFromRevenueAccounting:
type: boolean
description: |
Indicates whether to exclude the related invoice items, invoice item adjustments, credit memo items, and debit memo items from revenue accounting.
**Note**: This field is only available if you have the Order to Revenue or Billing - Revenue Integration feature enabled.
excludeItemBookingFromRevenueAccounting:
type: boolean
description: |
Indicates whether to exclude the related rate plan charges and order line items from revenue accounting.
**Note**: This field is only available if you have the Order to Revenue or Billing - Revenue Integration feature enabled.
includedUnits:
type: number
description: |
Specifies the number of units in the base set of units.
isPrepaid:
type: boolean
default: false
description: |
**Note**: This field is only available if you have the [Prepaid with
Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown)
feature enabled.
Indicates whether this charge is a prepayment (topup) charge or a
drawdown charge.
isRollover:
type: boolean
description: |
**Note**: This field is only available if you have the [Prepaid with
Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown)
feature enabled.
It determines whether the rollover fields are needed.
isStackedDiscount:
type: boolean
description: |
**Note**: This field is only applicable to the Discount - Percentage charge model.
This field indicates whether the discount is to be calculated as stacked discount. Possible values are as follows:
- `True`: This is a stacked discount, which should be calculated by stacking with other discounts.
- `False`: This is not a stacked discount, which should be calculated in sequence with other discounts.
For more information, see [Stacked discounts](https://knowledgecenter.zuora.com/Zuora_Billing/Products/Product_Catalog/B_Charge_Models/B_Discount_Charge_Models).
legacyRevenueReporting:
type: boolean
description: |
Indicates whether to use the legacy revenue reporting for this charge.
listPriceBase:
description: |
The list price base for the product rate plan charge.
This field is only applicable for recurring charges.
enum:
- Per Billing Period
- Per Month
- Per Week
- Per Year
- Per Specific Months
type: string
specificListPriceBase:
type: integer
format: int32
description: |
The number of months for the list price base of the charge. The value of this field is `null` if you do not set the value of the `listPriceBase` field to `Per_Specific_Months`.
nullable: true
maxQuantity:
type: number
description: |
The maximum number of units for this charge. This field and the `minQuantity` field can be used to create a range of units allowed in a product rate plan charge.
minQuantity:
type: number
description: |
The minimum number of units for this charge. This field and the `maxQuantity` field can be used to create a range of units allowed in a product rate plan charge.
name:
description: |
Name of the product rate-plan charge. Not required to be unique.
type: string
numberOfPeriod:
type: integer
format: int64
description: |
Specifies the number of periods to use when calculating charges in an overage smoothing charge model.
This field is ued when overage smoothing model is `RollingWindow` or `Rollover`.
nullable: true
overageCalculationOption:
description: |
Value specifies when to calculate overage charges.
type: string
enum:
- EndOfSmoothingPeriod
- PerBillingPeriod
- null
nullable: true
overageUnusedUnitsCreditOption:
type: string
description: |
Determines whether to credit the customer with unused units of usage.
enum:
- NoCredit
- CreditBySpecificRate
nullable: true
prepaidOperationType:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
The type of this charge. It is either a prepayment (topup) charge or a drawdown charge.
enum:
- topup
- drawdown
- null
type: string
nullable: true
prepaidQuantity:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
The number of units included in a [prepayment charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge). Must be a positive number (>0).
type: number
nullable: true
prepaidTotalQuantity:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
The total amount of units that end customers can use during a validity period when they subscribe to a [prepayment charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge).
type: number
nullable: true
priceChangeOption:
description: |
Applies an automatic price change when a termed subscription is
renewed and the following applies:
1. AutomatedPriceChange setting is on
2. Charge type is not one-time
3. Charge model is not discount fixed amount
enum:
- NoChange
- SpecificPercentageValue
- UseLatestProductCatalogPricing
type: string
default: NoChange
nullable: true
priceIncreasePercentage:
type: number
description: |
Specifies the percentage to increase or decrease the price of a termed subscription's renewal. Use this field if you set the `PriceChangeOption` value to `SpecificPercentageValue`.
1. AutomatedPriceChange setting is on
2. Charge type is not one-time
3. Charge model is not discount fixed amount
Values: a decimal between -100 and 100
minimum: -100
maximum: 100
nullable: true
productRatePlanChargeNumber:
type: string
description: |
The natural key of the product rate plan charge.
prorationOption:
type: string
description: |
**Note**: This field is only available if you have the Charge Level Proration feature enabled.
The charge-level proration option for the product rate plan charge.
ratingGroup:
description: |
Specifies a rating group based on which usage records are rated.
Possible values:
- `ByBillingPeriod` (default): The rating is based on all the usages in a billing period.
- `ByUsageStartDate`: The rating is based on all the usages on the same usage start date.
- `ByUsageRecord`: The rating is based on each usage record.
- `ByUsageUpload`: The rating is based on all the usages in a uploaded usage file (`.xls` or `.csv`).
- `ByGroupId`: The rating is based on all the usages in a custom group.
**Note:**
- The `ByBillingPeriod` value can be applied for all charge models.
- The `ByUsageStartDate`, `ByUsageRecord`, and `ByUsageUpload` values can only be applied for per unit, volume pricing, and tiered pricing charge models.
- The `ByGroupId` value is only available if you have the Active Rating feature enabled.
- Use this field only for Usage charges. One-Time Charges and Recurring Charges return `NULL`.
type: string
nullable: true
revRecTriggerCondition:
description: |
Specifies when revenue recognition begins.
enum:
- ContractEffectiveDate
- ServiceActivationDate
- CustomerAcceptanceDate
- null
maxLength: 22
type: string
nullable: true
revenueRecognitionRuleName:
description: |
The name of the revenue recognition rule governing the revenue schedule.
type: string
rolloverApply:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
This field defines the priority of rollover, which is either first or last.
enum:
- ApplyFirst
- ApplyLast
type: string
rolloverPeriodLength:
default: null
description: |
**Note**: This field is only available if you have the [Prepaid with
Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown)
feature enabled.
The period length of the rollover fund.
type: integer
format: int32
rolloverPeriods:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
This field defines the number of rollover periods, it is restricted to 3.
type: integer
format: int64
recognizedRevenueAccount:
description: |
The name of the recognized revenue account for this charge.
- Required when the Allow Blank Accounting Code setting is No.
- Optional when the Allow Blank Accounting Code setting is Yes.
This feature is in **Limited Availability**. If you wish to have access to the feature, submit a request at [Zuora Global Support](http://support.zuora.com/).
maxLength: 100
type: string
smoothingModel:
description: |
Specifies the smoothing model for an overage smoothing charge model or
an tiered with overage model, which is an advanced type of a usage
model that avoids spikes in usage charges. If a customer's usage
spikes in a single period, then an overage smoothing model eases
overage charges by considering usage and multiple periods.
One of the following values shows which smoothing model will be
applied to the charge when `Overage` or `Tiered with Overage` is used:
- `RollingWindow` considers a number of periods to smooth usage. The
rolling window starts and increments forward based on billing
frequency. When allowed usage is met, then period resets and a new
window begins.
- `Rollover` considers a fixed number of periods before calculating
usage. The net balance at the end of a period is unused usage, which
is carried over to the next period's balance.
type: string
nullable: true
specificBillingPeriod:
type: integer
format: int64
description: |
When the billing period is set to `Specific` Months then this positive
integer reflects the number of months for billing period charges.
nullable: true
taxable:
type: boolean
description: |
Specifies whether the charge is taxable; used by Zuora Tax.
taxCode:
type: string
description: |
Specifies the tax code for taxation rules; used by Zuora Tax.
taxMode:
description: |
Specifies how to define taxation for the charge; used by Zuora Tax.
enum:
- TaxExclusive
- TaxInclusive
- null
type: string
nullable: true
triggerEvent:
type: string
description: |
Specifies when to start billing the customer for the charge.
Values: one of the following:
- `ContractEffective` is the date when the subscription's contract goes into effect and the charge is ready to be billed.
- `ServiceActivation` is the date when the services or products for a subscription have been activated and the customers have access.
- `CustomerAcceptance` is when the customer accepts the services or products for a subscription.
- `SpecificDate` is the date specified.
enum:
- ContractEffective
- ServiceActivation
- CustomerAcceptance
- SpecificDate
upToPeriods:
type: integer
format: int64
nullable: true
description: |
Specifies the length of the period during which the charge is active.
If this period ends before the subscription ends, the charge ends when
this period ends.
If the subscription end date is subsequently changed through a
Renewal, or Terms and Conditions amendment, the charge end date will
change accordingly up to the original period end.
upToPeriodsType:
description: |
The period type used to define when the charge ends.
enum:
- Billing Periods
- Days
- Weeks
- Months
- Years
- null
type: string
nullable: true
usageRecordRatingOption:
description: |
Determines how Zuora processes usage records for per-unit usage
charges.
type: string
nullable: true
useDiscountSpecificAccountingCode:
type: boolean
nullable: true
description: |
Determines whether to define a new accounting code for the new
discount charge.
useTenantDefaultForPriceChange:
type: boolean
description: |
Shows the tenant-level percentage uplift value for an automatic price
change to a termed subscription's renewal. You set the tenant uplift
value in the web-based UI: **Settings > Billing > Define Default
Subscription Settings**.
validityPeriodType:
type: string
description: |
**Note**: This field is only available if you have the [Prepaid with
Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown)
feature enabled.
The period in which the prepayment units are valid to use as defined
in a [prepayment
charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge).
enum:
- SubscriptionTerm
- Annual
- SemiAnnual
- Quarter
- Month
weeklyBillCycleDay:
description: |
Specifies which day of the week as the bill cycle day (BCD) for the
charge.
This feature is in **Limited Availability**. If you wish to have
access to the feature, submit a request at [Zuora Global
Support](http://support.zuora.com/).
enum:
- Sunday
- Monday
- Tuesday
- Wednesday
- Thursday
- Friday
- Saturday
type: string
priceUpsellQuantityStacked:
type: boolean
description: |
Indicates whether the price upsell quantity is stacked.
deliveryScheduleId:
type: string
description: |
The unique identifier of the delivery schedule associated with the
product rate plan charge. This field is applicable only when this charge is
using Delivery Pricing charge model.
commitmentType:
type: string
description: |
**Note**: This field is only available if you have the Unbilled Usage feature enabled.
To use this field, you must set the `X-Zuora-WSDL-Version` request header to `133` or higher. Otherwise, an error occurs.
This field defines the type of commitment. A prepaid charge can be `UNIT` or `CURRENCY`. A minimum commitment(in-arrears) charge can only be `CURRENCY` type. For topup(recurring or one-time) charges, this field indicates what type of funds are created.
* If UNIT, it will create a fund with given prepaidUom.
* If CURRENCY, it will create a fund with the currency amount calculated in list price.
For drawdown(usage) charges, this field indicates what type of funds are drawdown from that created from topup charges.
enum:
- UNIT
- CURRENCY
isCommitted:
type: boolean
description: |
Indicates whether the charge is commited.
productRatePlanId:
type: string
description: |
The unique identifier of the product rate plan to which this product rate plan charge belongs.
accountReceivableAccountingCodeId:
type: string
description: |
The type of the accounting code for accounts receivable.
recognizedRevenueAccountingCodeId:
description: |
The accounting code for recognized revenue, such as Monthly Recurring
Charges or Overage Charges.
type: string
deferredRevenueAccountingCodeId:
description: |
The type associated with the deferred revenue accounting code, such as
Deferred Revenue.
type: string
nullable: true
adjustmentLiabilityAccountingCodeId:
type: string
description: |
The type associated with the adjustment liability accounting code.
**Note**: This field is only available if you have the Zuora Billing -
Revenue Integration feature enabled.
adjustmentRevenueAccountingCodeId:
type: string
description: |
The type associated with the adjustment revenue accounting code.
**Note**: This field is only available if you have the Zuora Billing -
Revenue Integration feature enabled.
contractAssetAccountingCodeId:
type: string
description: |
The type associated with the contract asset accounting code.
**Note**: This field is only available if you have the Zuora Billing -
Revenue Integration feature enabled.
contractLiabilityAccountingCodeId:
type: string
description: |
The accounting code for contract liability.
**Note**: This field is only available if you have the Zuora Billing -
Revenue Integration feature enabled.
contractRecognizedRevenueAccountingCodeId:
type: string
description: |
The accounting code for contract recognized revenue.
**Note**: This field is only available if you have the Zuora Billing -
Revenue Integration feature enabled.
unbilledReceivablesAccountingCodeId:
description: |
The accounting code for unbilled receivables.
**Note**: This field is only available if you have the Zuora Billing -
Revenue Integration feature enabled.
type: string
nullable: true
revRecCode:
description: |
Associates this product rate plan charge with a specific revenue
recognition code.
maxLength: 70
type: string
nullable: true
uOM:
type: string
description: |
Describes the Units of Measure (uom) configured in **Settings >
Billing** for the productRatePlanCharges.
nullable: true
drawdownUom:
type: string
description: |
**Note**: This field is only available if you have the [Prepaid with
Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown)
feature enabled.
Unit of measurement for a [drawdown
charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_drawdown_charge).
prepaidUom:
description: |
**Note**: This field is only available if you have the [Prepaid with
Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown)
feature enabled.
Unit of measurement for a [prepayment
charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge).
type: string
nullable: true
productRatePlan:
type: object
description: |
The product rate plan that contains this product rate plan charge.
productRatePlanChargeTiers:
type: array
items:
type: object
description: |
The product rate plan charge tiers contained in this product rate plan charge.
additionalProperties:
type: object
description: |
Custom fields of the Product Rate Plan Charge object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryProductRatePlanChargeResponse
ExpandedProductRatePlanCharge:
properties:
id:
type: string
description: |
The unique identifier of the product rate plan charge.
createdById:
type: string
description: |
The unique identifier of the user who created the product rate plan charge.
createdDate:
type: string
format: date-time
description: |
The date and time when the product rate plan charge was created.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the product rate plan charge.
updatedDate:
type: string
format: date-time
description: |
The date and time when the product rate plan charge was last updated.
accountingCode:
type: string
description: |
The accounting code for the charge. Accounting codes group
transactions that contain similar accounting attributes.
maxLength: 100
applyDiscountTo:
type: string
description: |
Indicates which type of charge the discount charge applies to.
enum:
- ONETIME
- RECURRING
- USAGE
- ONETIMERECURRING
- ONETIMEUSAGE
- RECURRINGUSAGE
- ONETIMERECURRINGUSAGE
- null
nullable: true
chargeFunction:
description: |
**Note**: This field is only available if you have the Prepaid with Drawdown or Minimum Commitment feature enabled.
This field defines what type of charge it is:
* Standard: Normal charge with no Prepayment or Commitment or Drawdown.
* Prepayment: For recurring charges. Unit or currency based prepaid charge.
* CommitmentTrueUp: For recurring charges. Currency based minimum commitment charge.
* Drawdown: For usage charges. Drawdown from prepaid funds.
* DrawdownAndCreditCommitment: For usage charges. Drawdown from prepaid funds and then credit to minimum commitment funds.
* CreditCommitment: For usage charges. Credit to minimum commitment funds.
enum:
- Standard
- Prepayment
- CommitmentTrueUp
- Drawdown
- CreditCommitment
- DrawdownAndCreditCommitment
type: string
isAllocationEligible:
type: boolean
description: |
Indicates whether the charge segment is allocation eligible in revenue recognition.
default: false
isUnbilled:
type: boolean
description: |
Specifies how to perform the accounting during revenue recognition.
default: false
applyToBillingPeriodPartially:
description: |
Allow the discount duration to be aligned with the billing period partially.
type: boolean
default: false
billCycleDay:
type: integer
format: int64
description: |
Sets the bill cycle day (BCD) for the charge. The BCD determines which
day of the month customer is billed. The BCD value in the account can
override the BCD in this object.
minimum: 1
maximum: 31
billCycleType:
description: |
Specifies how to determine the billing day for the
charge.
enum:
- DefaultFromCustomer
- SpecificDayofMonth
- SubscriptionStartDay
- ChargeTriggerDay
- SpecificDayofWeek
- TermStartDay
- TermEndDay
type: string
billingPeriod:
description: |
The billing period for the charge. The start day of the billing period
is also called the bill cycle day (BCD).
enum:
- Month
- Quarter
- Annual
- Semi-Annual
- Specific Months
- Subscription Term
- Week
- Specific Weeks
- Specific Days
type: string
billingPeriodAlignment:
type: string
description: |
The billing period alignment setting for this charge.
enum:
- AlignToCharge
- AlignToSubscriptionStart
- AlignToTermStart
- AlignToTermEnd
billingTiming:
type: string
description: |
The billing timing for this charge.
enum:
- IN_ADVANCE
- IN_ARREARS
chargeModel:
description: |
Determines how to calculate charges. Charge models must be individually activated in Zuora Billing administration.
enum:
- Discount-Fixed Amount
- Discount-Percentage
- Flat Fee Pricing
- Per Unit Pricing
- Overage Pricing
- Tiered Pricing
- Tiered with Overage Pricing
- Volume Pricing
- Delivery Pricing
- MultiAttributePricing
- PreratedPerUnit
- PreratedPricing`
- HighWatermarkVolumePricing
- HighWatermarkTieredPricing
type: string
chargeType:
description: |
Specifies the type of charge.
enum:
- OneTime
- Recurring
- Usage
type: string
creditOption:
type: string
description: |
**Note**: This field is only available if you have the [Prepaid with
Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown)
feature enabled.
The way to calculate credit. See [Credit
Option](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge#Credit_Option)
for more information.
enum:
- TimeBased
- ConsumptionBased
- FullCreditBack
defaultQuantity:
type: number
nullable: true
description: |
The default quantity.
This field is applicable only for one-time and recurring charges.
deferredRevenueAccount:
type: string
description: |
The name of the deferred revenue account for this charge.
This feature is in **Limited Availability**. If you wish to have
access to the feature, submit a request at [Zuora Global
Support](http://support.zuora.com/).
maxLength: 100
description:
type: string
description: |
Description of the product rate plan charge.
discountClassId:
type: string
description: |
ID of the class the discount belongs to. The discount class defines the order in which discount product rate plan charges are applied.
For more information, see [Manage Discount Classes](https://knowledgecenter.zuora.com/BC_Subscription_Management/Product_Catalog/B_Charge_Models/Manage_Discount_Classes).
nullable: true
discountLevel:
description: |
The application scope of the discount charge. For example, if the value of this field is `subscription` and the value of the `applyDiscountTo` field is `RECURRING`, the discount charge applies to all recurring charges in the same subscription as the discount charge.
enum:
- rateplan
- subscription
- account
- null
type: string
nullable: true
drawdownRate:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
The [conversion rate](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_drawdown_charge#UOM_Conversion) between Usage UOM and Drawdown UOM for a [drawdown charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_drawdown_charge). Must be a positive number (>0).
type: number
nullable: true
endDateCondition:
description: |
The end date condition for this charge.
enum:
- SubscriptionEnd
- OneTime
- FixedPeriod
- SpecificEndDate
type: string
excludeItemBillingFromRevenueAccounting:
type: boolean
description: |
Indicates whether to exclude the related invoice items, invoice item adjustments, credit memo items, and debit memo items from revenue accounting.
**Note**: This field is only available if you have the Order to Revenue or Billing - Revenue Integration feature enabled.
excludeItemBookingFromRevenueAccounting:
type: boolean
description: |
Indicates whether to exclude the related rate plan charges and order line items from revenue accounting.
**Note**: This field is only available if you have the Order to Revenue or Billing - Revenue Integration feature enabled.
includedUnits:
type: number
description: |
Specifies the number of units in the base set of units.
isPrepaid:
type: boolean
default: false
description: |
**Note**: This field is only available if you have the [Prepaid with
Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown)
feature enabled.
Indicates whether this charge is a prepayment (topup) charge or a
drawdown charge.
isRollover:
type: boolean
description: |
**Note**: This field is only available if you have the [Prepaid with
Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown)
feature enabled.
It determines whether the rollover fields are needed.
isStackedDiscount:
type: boolean
description: |
**Note**: This field is only applicable to the Discount - Percentage charge model.
This field indicates whether the discount is to be calculated as stacked discount. Possible values are as follows:
- `True`: This is a stacked discount, which should be calculated by stacking with other discounts.
- `False`: This is not a stacked discount, which should be calculated in sequence with other discounts.
For more information, see [Stacked discounts](https://knowledgecenter.zuora.com/Zuora_Billing/Products/Product_Catalog/B_Charge_Models/B_Discount_Charge_Models).
legacyRevenueReporting:
type: boolean
description: |
Indicates whether to use the legacy revenue reporting for this charge.
listPriceBase:
description: |
The list price base for the product rate plan charge.
This field is only applicable for recurring charges.
enum:
- Per Billing Period
- Per Month
- Per Week
- Per Year
- Per Specific Months
type: string
specificListPriceBase:
type: integer
format: int32
description: |
The number of months for the list price base of the charge. The value of this field is `null` if you do not set the value of the `listPriceBase` field to `Per_Specific_Months`.
nullable: true
maxQuantity:
type: number
description: |
The maximum number of units for this charge. This field and the `minQuantity` field can be used to create a range of units allowed in a product rate plan charge.
minQuantity:
type: number
description: |
The minimum number of units for this charge. This field and the `maxQuantity` field can be used to create a range of units allowed in a product rate plan charge.
name:
description: |
Name of the product rate-plan charge. Not required to be unique.
type: string
numberOfPeriod:
type: integer
format: int64
description: |
Specifies the number of periods to use when calculating charges in an overage smoothing charge model.
This field is ued when overage smoothing model is `RollingWindow` or `Rollover`.
nullable: true
overageCalculationOption:
description: |
Value specifies when to calculate overage charges.
type: string
enum:
- EndOfSmoothingPeriod
- PerBillingPeriod
- null
nullable: true
overageUnusedUnitsCreditOption:
type: string
description: |
Determines whether to credit the customer with unused units of usage.
enum:
- NoCredit
- CreditBySpecificRate
nullable: true
prepaidOperationType:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
The type of this charge. It is either a prepayment (topup) charge or a drawdown charge.
enum:
- topup
- drawdown
- null
type: string
nullable: true
prepaidQuantity:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
The number of units included in a [prepayment charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge). Must be a positive number (>0).
type: number
nullable: true
prepaidTotalQuantity:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
The total amount of units that end customers can use during a validity period when they subscribe to a [prepayment charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge).
type: number
nullable: true
priceChangeOption:
description: |
Applies an automatic price change when a termed subscription is
renewed and the following applies:
1. AutomatedPriceChange setting is on
2. Charge type is not one-time
3. Charge model is not discount fixed amount
enum:
- NoChange
- SpecificPercentageValue
- UseLatestProductCatalogPricing
type: string
default: NoChange
nullable: true
priceIncreasePercentage:
type: number
description: |
Specifies the percentage to increase or decrease the price of a termed subscription's renewal. Use this field if you set the `PriceChangeOption` value to `SpecificPercentageValue`.
1. AutomatedPriceChange setting is on
2. Charge type is not one-time
3. Charge model is not discount fixed amount
Values: a decimal between -100 and 100
minimum: -100
maximum: 100
nullable: true
productRatePlanChargeNumber:
type: string
description: |
The natural key of the product rate plan charge.
prorationOption:
type: string
description: |
**Note**: This field is only available if you have the Charge Level Proration feature enabled.
The charge-level proration option for the product rate plan charge.
ratingGroup:
description: |
Specifies a rating group based on which usage records are rated.
Possible values:
- `ByBillingPeriod` (default): The rating is based on all the usages in a billing period.
- `ByUsageStartDate`: The rating is based on all the usages on the same usage start date.
- `ByUsageRecord`: The rating is based on each usage record.
- `ByUsageUpload`: The rating is based on all the usages in a uploaded usage file (`.xls` or `.csv`).
- `ByGroupId`: The rating is based on all the usages in a custom group.
**Note:**
- The `ByBillingPeriod` value can be applied for all charge models.
- The `ByUsageStartDate`, `ByUsageRecord`, and `ByUsageUpload` values can only be applied for per unit, volume pricing, and tiered pricing charge models.
- The `ByGroupId` value is only available if you have the Active Rating feature enabled.
- Use this field only for Usage charges. One-Time Charges and Recurring Charges return `NULL`.
type: string
nullable: true
revRecTriggerCondition:
description: |
Specifies when revenue recognition begins.
enum:
- ContractEffectiveDate
- ServiceActivationDate
- CustomerAcceptanceDate
- null
maxLength: 22
type: string
nullable: true
revenueRecognitionRuleName:
description: |
The name of the revenue recognition rule governing the revenue schedule.
type: string
rolloverApply:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
This field defines the priority of rollover, which is either first or last.
enum:
- ApplyFirst
- ApplyLast
type: string
rolloverPeriodLength:
default: null
description: |
**Note**: This field is only available if you have the [Prepaid with
Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown)
feature enabled.
The period length of the rollover fund.
type: integer
format: int32
rolloverPeriods:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
This field defines the number of rollover periods, it is restricted to 3.
type: integer
format: int64
recognizedRevenueAccount:
description: |
The name of the recognized revenue account for this charge.
- Required when the Allow Blank Accounting Code setting is No.
- Optional when the Allow Blank Accounting Code setting is Yes.
This feature is in **Limited Availability**. If you wish to have access to the feature, submit a request at [Zuora Global Support](http://support.zuora.com/).
maxLength: 100
type: string
smoothingModel:
description: |
Specifies the smoothing model for an overage smoothing charge model or
an tiered with overage model, which is an advanced type of a usage
model that avoids spikes in usage charges. If a customer's usage
spikes in a single period, then an overage smoothing model eases
overage charges by considering usage and multiple periods.
One of the following values shows which smoothing model will be
applied to the charge when `Overage` or `Tiered with Overage` is used:
- `RollingWindow` considers a number of periods to smooth usage. The
rolling window starts and increments forward based on billing
frequency. When allowed usage is met, then period resets and a new
window begins.
- `Rollover` considers a fixed number of periods before calculating
usage. The net balance at the end of a period is unused usage, which
is carried over to the next period's balance.
type: string
nullable: true
specificBillingPeriod:
type: integer
format: int64
description: |
When the billing period is set to `Specific` Months then this positive
integer reflects the number of months for billing period charges.
nullable: true
taxable:
type: boolean
description: |
Specifies whether the charge is taxable; used by Zuora Tax.
taxCode:
type: string
description: |
Specifies the tax code for taxation rules; used by Zuora Tax.
taxMode:
description: |
Specifies how to define taxation for the charge; used by Zuora Tax.
enum:
- TaxExclusive
- TaxInclusive
- null
type: string
nullable: true
triggerEvent:
type: string
description: |
Specifies when to start billing the customer for the charge.
Values: one of the following:
- `ContractEffective` is the date when the subscription's contract goes into effect and the charge is ready to be billed.
- `ServiceActivation` is the date when the services or products for a subscription have been activated and the customers have access.
- `CustomerAcceptance` is when the customer accepts the services or products for a subscription.
- `SpecificDate` is the date specified.
enum:
- ContractEffective
- ServiceActivation
- CustomerAcceptance
- SpecificDate
upToPeriods:
type: integer
format: int64
nullable: true
description: |
Specifies the length of the period during which the charge is active.
If this period ends before the subscription ends, the charge ends when
this period ends.
If the subscription end date is subsequently changed through a
Renewal, or Terms and Conditions amendment, the charge end date will
change accordingly up to the original period end.
upToPeriodsType:
description: |
The period type used to define when the charge ends.
enum:
- Billing Periods
- Days
- Weeks
- Months
- Years
- null
type: string
nullable: true
usageRecordRatingOption:
description: |
Determines how Zuora processes usage records for per-unit usage
charges.
type: string
nullable: true
useDiscountSpecificAccountingCode:
type: boolean
nullable: true
description: |
Determines whether to define a new accounting code for the new
discount charge.
useTenantDefaultForPriceChange:
type: boolean
description: |
Shows the tenant-level percentage uplift value for an automatic price
change to a termed subscription's renewal. You set the tenant uplift
value in the web-based UI: **Settings > Billing > Define Default
Subscription Settings**.
validityPeriodType:
type: string
description: |
**Note**: This field is only available if you have the [Prepaid with
Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown)
feature enabled.
The period in which the prepayment units are valid to use as defined
in a [prepayment
charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge).
enum:
- SubscriptionTerm
- Annual
- SemiAnnual
- Quarter
- Month
weeklyBillCycleDay:
description: |
Specifies which day of the week as the bill cycle day (BCD) for the
charge.
This feature is in **Limited Availability**. If you wish to have
access to the feature, submit a request at [Zuora Global
Support](http://support.zuora.com/).
enum:
- Sunday
- Monday
- Tuesday
- Wednesday
- Thursday
- Friday
- Saturday
type: string
priceUpsellQuantityStacked:
type: boolean
description: |
Indicates whether the price upsell quantity is stacked.
deliveryScheduleId:
type: string
description: |
The unique identifier of the delivery schedule associated with the
product rate plan charge. This field is applicable only when this charge is
using Delivery Pricing charge model.
commitmentType:
type: string
description: |
**Note**: This field is only available if you have the Unbilled Usage feature enabled.
To use this field, you must set the `X-Zuora-WSDL-Version` request header to `133` or higher. Otherwise, an error occurs.
This field defines the type of commitment. A prepaid charge can be `UNIT` or `CURRENCY`. A minimum commitment(in-arrears) charge can only be `CURRENCY` type. For topup(recurring or one-time) charges, this field indicates what type of funds are created.
* If UNIT, it will create a fund with given prepaidUom.
* If CURRENCY, it will create a fund with the currency amount calculated in list price.
For drawdown(usage) charges, this field indicates what type of funds are drawdown from that created from topup charges.
enum:
- UNIT
- CURRENCY
isCommitted:
type: boolean
description: |
Indicates whether the charge is commited.
productRatePlanId:
type: string
description: |
The unique identifier of the product rate plan to which this product rate plan charge belongs.
accountReceivableAccountingCodeId:
type: string
description: |
The type of the accounting code for accounts receivable.
recognizedRevenueAccountingCodeId:
description: |
The accounting code for recognized revenue, such as Monthly Recurring
Charges or Overage Charges.
type: string
deferredRevenueAccountingCodeId:
description: |
The type associated with the deferred revenue accounting code, such as
Deferred Revenue.
type: string
nullable: true
adjustmentLiabilityAccountingCodeId:
type: string
description: |
The type associated with the adjustment liability accounting code.
**Note**: This field is only available if you have the Zuora Billing -
Revenue Integration feature enabled.
adjustmentRevenueAccountingCodeId:
type: string
description: |
The type associated with the adjustment revenue accounting code.
**Note**: This field is only available if you have the Zuora Billing -
Revenue Integration feature enabled.
contractAssetAccountingCodeId:
type: string
description: |
The type associated with the contract asset accounting code.
**Note**: This field is only available if you have the Zuora Billing -
Revenue Integration feature enabled.
contractLiabilityAccountingCodeId:
type: string
description: |
The accounting code for contract liability.
**Note**: This field is only available if you have the Zuora Billing -
Revenue Integration feature enabled.
contractRecognizedRevenueAccountingCodeId:
type: string
description: |
The accounting code for contract recognized revenue.
**Note**: This field is only available if you have the Zuora Billing -
Revenue Integration feature enabled.
unbilledReceivablesAccountingCodeId:
description: |
The accounting code for unbilled receivables.
**Note**: This field is only available if you have the Zuora Billing -
Revenue Integration feature enabled.
type: string
nullable: true
revRecCode:
description: |
Associates this product rate plan charge with a specific revenue
recognition code.
maxLength: 70
type: string
nullable: true
uOM:
type: string
description: |
Describes the Units of Measure (uom) configured in **Settings >
Billing** for the productRatePlanCharges.
nullable: true
drawdownUom:
type: string
description: |
**Note**: This field is only available if you have the [Prepaid with
Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown)
feature enabled.
Unit of measurement for a [drawdown
charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_drawdown_charge).
prepaidUom:
description: |
**Note**: This field is only available if you have the [Prepaid with
Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown)
feature enabled.
Unit of measurement for a [prepayment
charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge).
type: string
nullable: true
productRatePlan:
$ref: '#/components/schemas/NestedProductRatePlanOnExpand'
productRatePlanChargeTiers:
type: array
items:
$ref: '#/components/schemas/NestedPrpcTierOnExpand'
additionalProperties:
type: object
description: |
Custom fields of the Product Rate Plan Charge object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryProductRatePlanChargeResponse
NestedPrpcTierOnExpand:
properties:
id:
type: string
description: |
The unique identifier of the product rate plan charge tier.
createdById:
type: string
description: |
The unique identifier of the user who created the product rate plan charge tier.
createdDate:
type: string
format: date-time
description: |
The time that the product rate plan charge tier gets created in the system, in the
`YYYY-MM-DD HH:MM:SS` format.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the product rate plan charge tier.
updatedDate:
type: string
format: date-time
description: |
The date and time when the product rate plan charge tier was last updated.
active:
type: boolean
description: |
Indicates whether the product rate plan charge tier is active.
currency:
type: string
description: |
The valid code corresponding to the currency for the tier's price.
discountAmount:
type: number
description: |
The specific amount for a fixed discount. This field is applicable for charges based on the Discount-Fixed Amount charge model.
format: double
discountPercentage:
type: number
description: |
The percentage of discount for a percentage discount. This field is applicable for charges based on the Discount-Percentage charge model.
format: double
endingUnit:
type: number
description: |
The end number of a range of units for the tier. This field is
applicable for charges based on the Tiered Pricing or Tiered with
Overage Pricing charge model.
includedUnits:
type: number
description: |
Specifies the number of units in the base set of units.
overagePrice:
description: |
Indicates whether the price is an overage price, which is the price when usage surpasses the last defined tier.
format: double
type: number
price:
type: number
description: |
The price of the tier if the charge is a flat fee, or the price of each unit in the tier if the charge model is tiered pricing.
format: double
priceFormat:
type: string
description: |
Indicates if pricing is a flat fee or is per unit. This field is for tiered and volume pricing models only.
enum:
- Flat Fee
- Per Unit
startingUnit:
type: number
description: |
The starting number of a range of units for the tier. This field is
applicable for charges based on the Tiered Pricing or Tiered with
Overage Pricing charge model.
tier:
type: integer
format: int32
description: |
A unique number that identifies the tier that the price applies to.
isDefault:
type: boolean
description: |
Indicates whether the tier is the default tier. The default tier is the
tier that is used when the usage does not fall into any of the defined
tiers.
productRatePlanChargeId:
type: string
description: |
The unique identifier of the product rate plan charge that the tier
belongs to.
productChargeDefinitionId:
type: string
description: |
The unique identifier of the product rate plan charge definition that
the tier belongs to.
productRatePlanCharge:
type: object
description: |
The product rate plan charge that contains this product rate plan charge tier.
additionalProperties:
type: object
description: |
Custom fields of the Product Rate Plan Charge Tier object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryProductRatePlanChargeTierResponse
ExpandedProductRatePlanChargeTier:
properties:
id:
type: string
description: |
The unique identifier of the product rate plan charge tier.
createdById:
type: string
description: |
The unique identifier of the user who created the product rate plan charge tier.
createdDate:
type: string
format: date-time
description: |
The time that the product rate plan charge tier gets created in the system, in the
`YYYY-MM-DD HH:MM:SS` format.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the product rate plan charge tier.
updatedDate:
type: string
format: date-time
description: |
The date and time when the product rate plan charge tier was last updated.
active:
type: boolean
description: |
Indicates whether the product rate plan charge tier is active.
currency:
type: string
description: |
The valid code corresponding to the currency for the tier's price.
discountAmount:
type: number
description: |
The specific amount for a fixed discount. This field is applicable for charges based on the Discount-Fixed Amount charge model.
format: double
discountPercentage:
type: number
description: |
The percentage of discount for a percentage discount. This field is applicable for charges based on the Discount-Percentage charge model.
format: double
endingUnit:
type: number
description: |
The end number of a range of units for the tier. This field is
applicable for charges based on the Tiered Pricing or Tiered with
Overage Pricing charge model.
includedUnits:
type: number
description: |
Specifies the number of units in the base set of units.
overagePrice:
description: |
Indicates whether the price is an overage price, which is the price when usage surpasses the last defined tier.
format: double
type: number
price:
type: number
description: |
The price of the tier if the charge is a flat fee, or the price of each unit in the tier if the charge model is tiered pricing.
format: double
priceFormat:
type: string
description: |
Indicates if pricing is a flat fee or is per unit. This field is for tiered and volume pricing models only.
enum:
- Flat Fee
- Per Unit
startingUnit:
type: number
description: |
The starting number of a range of units for the tier. This field is
applicable for charges based on the Tiered Pricing or Tiered with
Overage Pricing charge model.
tier:
type: integer
format: int32
description: |
A unique number that identifies the tier that the price applies to.
isDefault:
type: boolean
description: |
Indicates whether the tier is the default tier. The default tier is the
tier that is used when the usage does not fall into any of the defined
tiers.
productRatePlanChargeId:
type: string
description: |
The unique identifier of the product rate plan charge that the tier
belongs to.
productChargeDefinitionId:
type: string
description: |
The unique identifier of the product rate plan charge definition that
the tier belongs to.
productRatePlanCharge:
$ref: '#/components/schemas/NestedPrpcOnExpand'
additionalProperties:
type: object
description: |
Custom fields of the Product Rate Plan Charge Tier object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryProductRatePlanChargeTierResponse
ExpandedRamp:
properties:
id:
type: string
description: |
The unique identifier of the ramp.
createdById:
type: string
description: |
The unique identifier of the user who created the ramp.
createdDate:
type: string
format: date-time
description: |
The time that the ramp gets created in the system, in the
`YYYY-MM-DD HH:MM:SS` format.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the ramp.
updatedDate:
type: string
format: date-time
description: |
The date and time when the ramp was last updated.
name:
type: string
description: |
The name of the ramp.
number:
type: string
description: |
The number of the ramp. It is automaticcally generated by the billing system.
description:
type: string
description: |
The short description of the ramp.
subscriptionNumbers:
type: string
description: |
The number of the subscription that is considered as part of the ramp deal.
chargeNumbers:
type: string
description: |
The number of the rate plan charge. It can contain multiple charge numbers, separated by commas(`,`).
orderId:
type: string
description: |
The unique identifier of the order.
grossTcb:
description: The gross TCB value before discount charges are applied.
type: number
grossTcv:
description: The gross TCV value before discount charges are applied.
type: number
netTcb:
description: The net TCB value after discount charges are applied.
type: number
netTcv:
description: The net TCV value after discount charges are applied.
type: number
discountTcb:
description: The discount amount for the TCB.
type: number
discountTcv:
description: The discount amount for the TCV.
type: number
metricsProcessingStatus:
type: string
description: |
Status of the metrics processing.
enum:
- Completed
- NotStarted
additionalProperties:
type: object
description: |
Custom fields of the Ramp object. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryRampResponse
ExpandedRatePlan:
properties:
id:
type: string
description: |
The unique identifier of the rate plan.
createdById:
type: string
description: |
The unique identifier of the user who created the rate plan.
createdDate:
type: string
format: date-time
description: |
The date and time when the rate plan was created.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the rate plan.
updatedDate:
type: string
format: date-time
description: |
The date and time when the rate plan was last updated.
productId:
type: string
description: |
The unique identifier of the product associated with the rate plan.
amendmentId:
type: string
description: |
The unique identifier of the amendment made to the subscription.
**Note**: This field is not available for single version subscriptions.
amendmentType:
type: string
description: |
The type of amendment associated with the rate plan. This field only applies to amendment rate plans.
**Note**: This field is not available for single version subscriptions.
name:
type: string
description: |
The name of the rate plan.
productRatePlanId:
type: string
description: |
The unique identifier of the product rate plan that the rate plan is based on.
subscriptionId:
type: string
description: |
The unique identifier of the subscription associated with the rate plan.
subscriptionOwnerId:
type: string
description: |
The unique identifier of the account that owns the subscription.
invoiceOwnerId:
type: string
description: |
The unique identifier of the account that will pay the invoice.
reverted:
type: boolean
description: |
Indicates whether the rate plan has been reverted.
externallyManagedPlanId:
type: string
description: |
Indicates the unique identifier for the rate plan purchased on a
third-party store. This field is used to represent a subscription rate
plan created through third-party stores.
originalRatePlanId:
type: string
description: |
The original ID of the subscription rate plan, which is the ID of the subscription rate plan in the version-1 subscription.
subscriptionOfferId:
type: string
description: |
The unique identifier of the subscription offer associated with the rate plan.
**Note**: This field is not available for single version subscriptions.
subscriptionRatePlanNumber:
type: string
description: |
The number of the rate plan in the subscription.
subscription:
$ref: '#/components/schemas/NestedSubscriptionOnExpand'
productRatePlan:
$ref: '#/components/schemas/NestedProductRatePlanOnExpand'
ratePlanCharges:
type: array
items:
$ref: '#/components/schemas/NestedRatePlanChargeOnExpand'
additionalProperties:
type: object
description: |
Custom fields of the Rate Plan object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryRatePlanResponse
ExpandedRatePlanCharge:
properties:
id:
type: string
description: |
The unique identifier of the rate plan charge.
createdById:
type: string
description: |
The unique identifier of the user who created the rate plan charge.
createdDate:
type: string
format: date-time
description: |
The date and time when the rate plan charge was created.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the rate plan charge.
updatedDate:
type: string
format: date-time
description: |
The date and time when the rate plan charge was last updated.
ratePlanId:
type: string
description: |
The unique identifier of the rate plan to which this rate plan charge belongs.
productRatePlanChargeId:
type: string
description: |
The unique identifier of the product rate plan charge associated with this product rate plan charge.
accountingCode:
description: |
The accounting code for the charge. Accounting codes group transactions that contain similar accounting attributes.
**Values**: inherited from `ProductRatePlanCharge.AccountingCode`
**Note**: This value changes if `ProductRatePlanCharge.AccountingCode` is updated.
The values of `UpdatedById` and `UpdatedDate` for the `RatePlanCharge` do not change when `ProductRatePlanCharge.AccountingCode` is updated.
type: string
applyDiscountTo:
description: |
Specifies the type of charges a specific discount applies to.
**Values**: inherited from `ProductRatePlanCharge.ApplyDiscountTo`
type: string
billCycleDay:
type: integer
format: int64
description: |
Indicates the charge's billing cycle day (BCD), which is
when bill runs generate invoices for charges associated with the product
rate plan charge or the account.
**Values**: inherited from `ProductRatePlanCharge.BillCycleDay`
billCycleType:
type: string
description: |
Specifies how to determine the billing day for the charge.
**Values**: inherited from `ProductRatePlanCharge.BillCycleType`
**Note:** You can override the value inherited from the Product Rate
Plan Charge, but only when creating a new subscription or a New Product
amendment.
billingPeriod:
type: string
description: |
Allows billing period to be overridden on rate plan Charge.
**Values**: **inherited from `ProductRatePlanCharge.BillingPeriod`
**Note:**
You can override the value inherited from the Product Rate Plan Charge,
but only when creating a new subscription or a New Product amendment.
billingPeriodAlignment:
type: string
description: |
Aligns charges within the same subscription if multiple charges
begin on different dates.
**Values**: inherited from `ProductRatePlanCharge.BillingPeriodAlignment`
billingTiming:
type: string
description: |
The billing timing for the charge. You can choose to bill in advance or in arrears for recurring charge types. This field is not used in one-time or usage based charge types.
**Note:** You can override the value inherited from the Product Rate Plan Charge when a subscription has a recurring charge type.
enum:
- In Advance
- In Arrears
chargedThroughDate:
type: string
format: date
description: |
The date through which a customer has been billed for the charge.
maxLength: 29
chargeModel:
type: string
description: |
Determines how to evaluate charges. Charge models must be
individually activated in the web-based UI.
**Values**: inherited from `ProductRatePlanCharge.ChargeModel`
chargeNumber:
description: |
A unique number that identifies the charge. This number is returned as a string.
**Values**: one of the following:
- automatically generated if left `null`
- a unique number of 50 characters or fewer
type: string
chargeType:
type: string
description: |
Specifies the type of charge.
**Values**: inherited from `ProductRatePlanCharge.ChargeType`
description:
type: string
description: |
A description of the rate plan charge.
discountLevel:
type: string
description: |
Application scope of the discount charge. For example, if the value of this field is `subscription` and the value of the `applyDiscountTo` field is `RECURRING`, the discount charge applies to all recurring charges in the same subscription as the discount charge.
enum:
- rateplan
- subscription
- account
dMRC:
type: number
description: |
A delta monthly recurring charge is the change in monthly
recurring revenue caused by an amendment or a new subscription.
**Character limit**: 16
**Values**: automatically generated
drawdownRate:
description: |
**Note**: This field is only available if you have the [Prepaid with
Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown)
feature enabled.
The [conversion
rate](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_drawdown_charge#UOM_Conversion)
between Usage UOM and Drawdown UOM for a [drawdown
charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_drawdown_charge).
Must be a positive number (>0).
type: number
dTCV:
type: number
description: |
After an Amendment, the change in the total contract value
(TCV) amount for this charge, compared with its previous value.
**Character limit**: 16
**Values**: automatically generated
effectiveEndDate:
type: string
format: date
description: |
Start date when the rate plan charge becomes active, as `yyyy-mm-dd`.
effectiveStartDate:
type: string
format: date
description: |
Final date the rate plan is active, as `yyyy-mm-dd`.
endDateCondition:
description: |
Condition for the charge to become inactive.
- If the value of this field is `FixedPeriod`, the charge is active for a
predefined duration based on the value of the `upToPeriodsType` and
`upToPeriods` fields.
- If the value of this field is `SpecificEndDate`, use the
`specificEndDate` field to specify the date when the charge becomes
inactive.
enum:
- SubscriptionEnd
- FixedPeriod
- SpecificEndDate
- OneTime
type: string
estimatedStartDate:
type: string
format: date
description: |
The estimated start date of the pending charge in an active subscription.
The value must be a date within the subscription term. The system will then automatically calculate the estimated end date for the pending charge. The estimated start and end dates are used to manage the estimated charge duration and forecast the revenue for the pending charge.
**Note:** This field is available only when the Pending Subscription Processing feature is turned on.
estimatedEndDate:
type: string
format: date
description: |
The estimated end date of the pending charge in an active subscription.
The system automatically calculates the estimated end date for the pending charge. The estimated start and end dates are used to manage the estimated charge duration and forecast the revenue for the pending charge.
**Note:** This field is available only when the Pending Subscription Processing feature is turned on.
excludeItemBillingFromRevenueAccounting:
default: false
description: |
The flag to exclude rate plan charge related invoice items, invoice item adjustments, credit memo items, and debit memo items from revenue accounting.
If both the following features are enabled in your tenant, you must ensure the `excludeItemBillingFromRevenueAccounting` field is set consistently for a prepayment charge and the corresponding drawdown charge. In addition, if the `excludeItemBookingFromRevenueAccounting` field in an Create Subscription or Add Product order action is set to `false`, you must also set the `excludeItemBillingFromRevenueAccounting` field in this order action to `false`.
* Prepaid with Drawdown
* Unbilled Usage
**Note**: This field is only available if you have the Order to Revenue or [Zuora Billing - Revenue Integration](https://knowledgecenter.zuora.com/Zuora_Revenue/Zuora_Billing_-_Revenue_Integration) feature enabled.
type: boolean
excludeItemBookingFromRevenueAccounting:
default: false
description: |
The flag to exclude rate plan charges from revenue accounting.
If both the following features are enabled in your tenant, you must ensure the `excludeItemBookingFromRevenueAccounting` field is set consistently for a prepayment charge and the corresponding drawdown charge.
* Prepaid with Drawdown
* Unbilled Usage
**Note**: This field is only available if you have the Order to Revenue or [Zuora Billing - Revenue Integration](https://knowledgecenter.zuora.com/Zuora_Revenue/Zuora_Billing_-_Revenue_Integration) feature enabled.
type: boolean
invoiceScheduleId:
type: string
description: |
The unique identifier of the invoice schedule associated with the subscription.
isLastSegment:
type: boolean
description: |
Indicates if the segment of the rate plan charge is the most
recent segment.
**Character limit**: 5
**Values**: automatically generated.
isPrepaid:
type: boolean
description: |
**Note**: This field is only available if you have the [Prepaid with
Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown)
feature enabled.
Indicates whether this charge is a prepayment (topup) charge or a
drawdown charge.
isRollover:
type: boolean
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
It determines whether the rollover fields are needed.
rolloverPeriods:
type: integer
format: int64
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
This field defines the number of rollover periods, it is restricted to 3.
rolloverPeriodLength:
type: integer
format: int32
nullable: true
description: |
**Note**: This field is only available if you have the [Prepaid with
Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown)
feature enabled.
Use this field when you want to set the rollover fund's period length shorter than the prepayment charge's validity period. In this case, you must set the `rolloverPeriods` field to 1. For example, you can define the rollover fund's period length as 5 months, shorter than the prepayment charge's validity period: a year.
rolloverApply:
type: string
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
This field defines the priority of rollover, which is either first or last.
enum:
- ApplyFirst
- ApplyLast
isProcessed:
type: boolean
description: |
Indicates whether the rate plan charge has been processed.
listPriceBase:
type: string
description: |
The list price base for the product rate plan charge.
enum:
- Per Billing Period
- Per Month
- Per Week
- Per Year
- Per Specific Months
specificListPriceBase:
type: integer
format: int32
description: |
The number of months for the list price base of the charge. This field is required if you set the value of the `ListPriceBase` field to `Per Specific Months`.
**Notes**:
- This field is available only if you have the Annual List Price feature enabled.
- The value of this field is `null` if you do not set the value of the `ListPriceBase` field to `Per Specific Months`.
maximum: 200
minimum: 1
nullable: true
priceUpsellQuantityStacked:
type: boolean
commitmentType:
description: |
**Note**: This field is only available if you have the Unbilled Usage feature enabled.
To use this field, you must set the `X-Zuora-WSDL-Version` request header to `133` or higher. Otherwise, an error occurs.
This field defines the type of commitment. A prepaid charge can be `UNIT` or `CURRENCY`. A minimum commitment(in-arrears) charge can only be `CURRENCY` type. For topup(recurring or one-time) charges, this field indicates what type of funds are created.
* If UNIT, it will create a fund with given prepaidUom.
* If CURRENCY, it will create a fund with the currency amount calculated in list price.
For drawdown(usage) charges, this field indicates what type of funds are drawdown from that created from topup charges.
enum:
- UNIT
- CURRENCY
type: string
isCommitted:
type: boolean
description: |
Indicates whether the rate plan charge is commited.
mRR:
type: number
description: |
Monthly recurring revenue (MRR) is the amount of recurring
charges in a given month. The MRR calculation doesn't include one-time
charges nor usage charges.
**Character limit**: 16
**Values**: automatically generated
name:
type: string
description: |
The name of the rate plan charge.
**Character limit**: 100
**Values**: automatically generated
numberOfPeriods:
type: integer
format: int64
description: |
Specifies the number of periods to use when calculating charges
in an overage smoothing charge model.
**Character limit**: 5
**Values**: inherited from `ProductRatePlanCharge.NumberOfPeriod`
originalId:
type: string
description: |
The original ID of the rate plan charge.
**Character limit**: 32
**Values**: automatically generated
overageCalculationOption:
type: string
description: |
Determines when to calculate overage charges. If the value
of the SmoothingMode field is null (not specified and not inherited from
ProductRatePlanCharge.SmoothingMode), the value of this field is ignored.
**Character limit**: 20
**Values**: inherited from `ProductRatePlanCharge.OverageCalculationOption`
overageUnusedUnitsCreditOption:
type: string
description: |
Determines whether to credit the customer with unused units
of usage.
**Character limit**: 20
**Values**: inherited from `ProductRatePlanCharge.OverageUnusedUnitsCreditOption`
prepaidOperationType:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
The type of this charge. It is either a prepayment (topup) charge or a drawdown charge.
enum:
- topup
- drawdown
- null
type: string
nullable: true
prepaidQuantity:
type: number
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
The number of units included in a [prepayment charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge). Must be a positive number (>0).
nullable: true
prepaidTotalQuantity:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
The total amount of units that end customers can use during a validity period when they subscribe to a [prepayment charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge).
type: number
nullable: true
priceChangeOption:
type: string
description: |
Applies an automatic price change when a termed subscription is renewed.
**Values**: one of the following:
- `NoChange` (default)
- `SpecificPercentageValue`
- `UseLatestProductCatalogPricing`
priceIncreasePercentage:
type: number
format: double
description: |
Specifies the percentage to increase or decrease the price
of renewed subscriptions.
**Character limit**: 16
**Values**: a decimal value between -100 and 100
processedThroughDate:
type: string
format: date
description: |
The date until when charges have been processed. When billing
in arrears, such as usage, this field value is the the same as the `ChargedThroughDate`
value. This date is the earliest date when a charge can be amended.
**Character limit**: 29
**Values**: automatically generated
prorationOption:
type: string
description: |
Determines how to prorate charges when a subscription is created or amended.
quantity:
type: number
description: |
The default quantity of units, such as the number of authors
in a hosted wiki service. Valid for all charge models except for Flat
Fee pricing.
**Character limit**: 16
**Values**: a valid quantity value
numberOfDeliveries:
type: number
description: |
Number of deliveries in the billing period for the charge segment.
The `numberOfDeliveries` is used for the Delivery Pricing charge model only.
**Note**: The Delivery Pricing charge model is in the **Early Adopter** phase. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available. To manage and access this feature through the self-service interface, see [Enable billing features by yourself](https://knowledgecenter.zuora.com/Zuora_Billing/Bill_your_customers/Billing_Settings/Manage_Features) in the Knowledge Center. You can check **Delivery Pricing** in **Billing Settings** > **Enable Charge Types / Models**.
ratingGroup:
type: string
description: |
A rating group based on which usage records are rated. Only
applicable to Usage charges.
Possible values:
- `ByBillingPeriod`: The rating is based on all the usages in a billing period.
- `ByUsageStartDate`: The rating is based on all the usages on the same usage start date.
- `ByUsageRecord`: The rating is based on each usage record.
- `ByUsageUpload`: The rating is based on all the usages in a uploaded usage file (`.xls` or `.csv`).
- `ByGroupId`: The rating is based on all the usages in a custom group.
For more information, see [Usage rating by group](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Usage/Usage_Rating_by_Group).
enum:
- ByBillingPeriod
- ByUsageStartDate
- ByUsageRecord
- ByUsageUpload
- ByGroupId
revenueRecognitionRuleName:
type: string
description: |
Specifies the Revenue Recognition Rule that you want the
Rate Plan Charge to use. This field can be updated when **Status** is
`Draft`. By default, the Revenue Recognition Rule is inherited from
the Product Rate Plan Charge. For Amend calls, you can use this field
only for NewProduct amendments. For Update calls, you can use this field
only to update subscriptions in draft status. Note that if you use this
field to specify a Revenue Recognition Rule for the Rate Plan Charge,
the rule will remain as specified even if you later change the rule
used by the corresponding Product Rate Plan Charge.
**Character limit**: n/a
**Values**: inherited from `ProductRatePlanCharge.RevenueRecognitionRuleName` or the name of an active Revenue Recognition Rule
**Note**: Unless overridden, this value changes if `ProductRatePlanCharge.RevenueRecognitionRuleName` is updated.
The values of `UpdatedById` and `UpdatedDate` for the `RatePlanCharge` do not change when `ProductRatePlanCharge.RevenueRecognitionRuleName` is updated.
revenueRecognitionTiming:
description: |
Specifies the type of revenue recognition timing.
Predefined options are listed as enum values in this API Reference. Other options might also be avaliable depending on the revenue recognition policy configuration in the Zuora Billing UI.
**Note**: This field is only available if you have the Order to Revenue feature enabled.
maxLength: 200
type: string
enum:
- Upon Billing Document Posting Date
- Upon Order Activation Date
revenueAmortizationMethod:
description: |
Specifies the type of revenue amortization method.
Predefined options are listed as enum values in this API Reference. Other options might also be avaliable depending on the revenue recognition policy configuration in the Zuora Billing UI.
**Note**: This field is only available if you have the Order to Revenue feature enabled.
maxLength: 200
type: string
enum:
- Immediate
- Ratable Using Start And End Dates
revRecCode:
type: string
description: |
Associates this product rate plan charge with a specific revenue recognition code.
**Character limit**: 70
**Values**: inherited from `ProductRatePlanCharge.RevRecCode` or a valid revenue recognition code
**Note**: Unless overridden, this value changes if `ProductRatePlanCharge.RevRecCode` is updated.
The values of `UpdatedById` and `UpdatedDate` for the `RatePlanCharge` do not change when `ProductRatePlanCharge.RevRecCode` is updated.
revRecTriggerCondition:
type: string
description: |
Specifies when revenue recognition begins.
**Character limit**: 22
**Values**: inherited from `ProductRatePlanCharge.RevRecTriggerCondition` or one of the following:
- `ContractEffectiveDate`
- `ServiceActivationDate`
- `CustomerAcceptanceDate`
Note: Unless overridden, this value changes if `ProductRatePlanCharge.RevRecTriggerCondition` is updated.
The values of `UpdatedById` and `UpdatedDate` for the `RatePlanCharge` do not change when `ProductRatePlanCharge.RevRecTriggerCondition` is updated. "
segment:
type: integer
format: int32
description: |
The identifying number of the subscription rate plan segment.
Segments are numbered sequentially, starting with 1.
**Character limit**: 2
**Values**: automatically generated
specificBillingPeriod:
type: integer
format: int64
description: |
Customizes the number of months or weeks for the charges
billing period. This field is required if you set the value of the BillingPeriod
field to `Specific Months` or `Specific Weeks`.
**Character limit**: 5
**Values**: inherited from `ProductRatePlanCharge.BillingPeriod`
**Note:** You can override the value inherited from the Product Rate Plan Charge, but only when creating a new subscription or a New Product amendment.
specificEndDate:
type: string
format: date
description: |
The specific date on which the charge ends, in `yyyy-mm-dd` format.
**Character limit**: 29
**Note**:
- This field is only applicable when the `EndDateCondition` field is set to `SpecificEndDate`.
- If the subscription ends before the specific end date, the charge ends when the subscription ends. But if the subscription end date is subsequently changed through a Renewal, or Terms and Conditions amendment, the charge will end on the specific end date.
tCV:
description: |
The total contract value (TCV) is the value of a single rate
plan charge in a subscription over the lifetime of the subscription.
This value does not represent all charges on the subscription. The TCV
includes recurring charges and one-time charges, but it doesn't include
usage charge.
**Character limit**: 16
**Values**: automatically generated
format: double
type: number
triggerDate:
description: |
The date when the charge becomes effective and billing begins,
in `yyyy-mm-dd` format. This field is required if the `TriggerEvent`
field value is `SpecificDate`.
**Character limit**: 29
format: date
type: string
triggerEvent:
description: |
Specifies when to start billing the customer for the charge.
**Note: **This field can be passed through the Subscribe and Amend calls and will override the default value set on the Product Rate Plan Charge.
**Character limit**: 18
**Values**: inherited from `ProductRatePlanCharge.TriggerEvent` and can be one of the following values:
- `ContractEffective` is the date when the subscription's contract goes into effect and the charge is ready to be billed.
- `ServiceActivation` is when the services or products for a subscription have been activated and the customers have access.
- `CustomerAcceptance` is when the customer accepts the services or products for a subscription.
- `SpecificDate` is valid only on the RatePlanCharge.
type: string
uOM:
description: |
Specifies the units to measure usage.
**Character limit**: 25
**Values**: inherited from `ProductRatePlanCharge.UOM`
type: string
upToPeriods:
type: integer
format: int64
description: |
Specifies the length of the period during which the charge is active. If this period ends before the subscription ends, the charge ends when this period ends.
**Character limit**: 5
**Values**: inherited from `ProductRatePlanCharge.UpToPeriods` **Note**:
- You must use this field together with the `UpToPeriodsType` field to specify the time period. This field is only applicable only when the `EndDateCondition` field is set to `FixedPeriod`.
- You can override the value inherited from the Product Rate Plan Charge, but only when creating a new subscription or a New Product amendment.
- Use this field to override the value in `ProductRatePlanCharge.UpToPeriod`.
- If you override the value in this field, enter a whole number between 0 and 65535, exclusive.
- If the subscription end date is subsequently changed through a Renewal, or Terms and Conditions amendment, the charge end date will change accordingly up to the original period end.
upToPeriodsType:
type: string
description: |
The period type used to define when the charge ends. This field can be updated when **Status** is `Draft`.
**Note**:
- You must use this field together with the `UpToPeriods` field to specify the time period.
- This field is only applicable only when the `EndDateCondition` field is set to `FixedPeriod`.
enum:
- Billing Periods
- Days
- Weeks
- Months
- Years
default: Billing Periods
version:
type: integer
format: int64
description: |
The version of the rate plan charge. Each time a charge is
amended, Zuora creates a new version of the rate plan charge.
**Character limit**: 5
**Values**: automatically generated.
weeklyBillCycleDay:
description: |
Specifies which day of the week as the bill cycle day (BCD) for the charge.
type: string
enum:
- Sunday
- Monday
- Tuesday
- Wednesday
- Thursday
- Friday
- Saturday
subscriptionId:
type: string
description: |
The unique identifier of the subscription to which the rate plan charge belongs.
subscriptionOwnerId:
type: string
description: |
ID of the account that owns the subscription.
invoiceOwnerId:
type: string
description: |
ID of the account that will pay the billing documents for the subscription.
originalOrderDate:
type: string
format: date
description: |
The date when the rate plan charge is created through an order or amendment. This field is to standardize the booking date information to increase audit ability and traceability of data between Zuora Billing and Zuora Revenue. It is mapped as the booking date for a sales order line in Zuora Revenue.
amendedByOrderOn:
type: string
format: date
description: |
The date when the rate plan charge is amended through an order
or amendment. This field is to standardize the booking date
information to increase audit ability and traceability of data
between Zuora Billing and Zuora Revenue. It is mapped as the
booking date for a sale order line in Zuora Revenue.
validityPeriodType:
type: string
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
The period in which the prepayment units are valid to use as defined in a [prepayment charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge).
enum:
- SUBSCRIPTION_TERM
- ANNUAL
- SEMI_ANNUAL
- QUARTER
- MONTH
creditOption:
type: string
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
The way to calculate credit. See [Credit Option](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge#Credit_Option) for more information.
enum:
- TimeBased
- ConsumptionBased
- FullCreditBack
applyToBillingPeriodPartially:
type: boolean
description: |
Allow the discount duration to be aligned with the billing period partially.
**Note**: You must enable the [Enhanced Discounts](https://knowledgecenter.zuora.com/Zuora_Billing/Build_products_and_prices/Basic_concepts_and_terms/B_Charge_Models/D_Manage_Enhanced_Discount) feature to access this field.
productChargeDefinitionId:
type: string
description: |
The unique ID of the product charge definition.
accountReceivableAccountingCodeId:
description: |
ID of the accountReceivableAccountingCode of a standalone charge.
**Note:** This field is available when the Standalone Orders, Zuora Finance, and Invoice Settlement features are enabled.
type: string
deferredRevenueAccountingCodeId:
description: |
ID of the deferredRevenueAccountingCode of a standalone charge.
**Note:** This field is available when the Standalone Orders and Zuora Finance features are enabled.
type: string
recognizedRevenueAccountingCodeId:
description: |
ID of the recognizedRevenueAccountingCode of a standalone charge.
**Note:** This field is available when the Standalone Orders and Zuora Finance features are enabled.
type: string
prepaidUOM:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
Unit of measurement for a [prepayment charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_prepayment_charge).
type: string
drawdownUom:
description: |
**Note**: This field is only available if you have the [Prepaid with Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown) feature enabled.
Unit of measurement for a [drawdown charge](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Create_drawdown_charge).
type: string
salesPrice:
type: number
description: |
The sales price associated with the rate plan charge expressed as a decimal.
**Notes**:
- This field is only available to subscriptions that are created through orders and exist after 2023-01-10.
- This field applies to the following charge models, and the values vary with the charge models:
- Flat fee: the value equals the value of the `price` field.
- Per unit: the value equals `price` multiplied by `quantity`.
- Fixed amount discount: the value equals the value of the `discountAmount` field.
- Volume: The calculation of the tier price is dependent on whether the price format is the flat fee or per unit.
- Tiered: The calculation of the tier price is dependent on whether the price format is the flat fee or per unit.
taxable:
type: boolean
description: |
Indicates whether the rate plan charge is taxable.
reverted:
type: boolean
description: |
Indicates whether the rate plan charge has been reverted.
reflectDiscountInNetAmount:
type: boolean
description: |
Indicates whether the discount is reflected in the net amount.
ratePlan:
$ref: '#/components/schemas/NestedRatePlanOnExpand'
productRatePlanCharge:
$ref: '#/components/schemas/NestedPrpcOnExpand'
additionalProperties:
type: object
description: |
Custom fields of the Rate Plan Charge object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryRatePlanChargeResponse
NestedRatePlanOnExpand:
properties:
id:
type: string
description: |
The unique identifier of the rate plan.
createdById:
type: string
description: |
The unique identifier of the user who created the rate plan.
createdDate:
type: string
format: date-time
description: |
The date and time when the rate plan was created.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the rate plan.
updatedDate:
type: string
format: date-time
description: |
The date and time when the rate plan was last updated.
productId:
type: string
description: |
The unique identifier of the product associated with the rate plan.
amendmentId:
type: string
description: |
The unique identifier of the amendment made to the subscription.
**Note**: This field is not available for single version subscriptions.
amendmentType:
type: string
description: |
The type of amendment associated with the rate plan. This field only applies to amendment rate plans.
**Note**: This field is not available for single version subscriptions.
name:
type: string
description: |
The name of the rate plan.
productRatePlanId:
type: string
description: |
The unique identifier of the product rate plan that the rate plan is based on.
subscriptionId:
type: string
description: |
The unique identifier of the subscription associated with the rate plan.
subscriptionOwnerId:
type: string
description: |
The unique identifier of the account that owns the subscription.
invoiceOwnerId:
type: string
description: |
The unique identifier of the account that will pay the invoice.
externallyManagedPlanId:
type: string
description: |
Indicates the unique identifier for the rate plan purchased on a
third-party store. This field is used to represent a subscription rate
plan created through third-party stores.
originalRatePlanId:
type: string
description: |
The original ID of the subscription rate plan, which is the ID of the subscription rate plan in the version-1 subscription.
subscriptionOfferId:
type: string
description: |
The unique identifier of the subscription offer associated with the rate plan.
**Note**: This field is not available for single version subscriptions.
subscriptionRatePlanNumber:
type: string
description: |
The number of the rate plan in the subscription.
subscription:
type: object
description: |
The subscription associated with the rate plan.
productRatePlan:
type: object
description: |
The product rate plan associated with the rate plan.
reverted:
type: boolean
description: |
Indicates whether the rate plan has been reverted.
ratePlanCharges:
type: array
items:
type: object
description: |
The rate plan charges on the rate plan.
additionalProperties:
type: object
description: |
Custom fields of the Rate Plan object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryRatePlanResponse
ExpandedRatePlanChargeTier:
properties:
currency:
type: string
description: |
The currency of the rate plan charge tier.
discountAmount:
type: number
description: |
The discount amount if it is a amount-based discount.
discountPercentage:
type: number
description: |
The discount percentage if it is a percentage-based discount.
endingUnit:
type: number
description: |
The ending number of a range of units for the tier.
includedUnits:
type: number
description: |
The number of units included in the tier.
overagePrice:
type: number
description: |
The overage price. An overage occurs when usage surpasses the last defined tier.
This field is applicable only to tier pricing and volume pricing models.
price:
type: number
description: |
The price of the tier if the charge is a flat fee, or the price of each unit in the tier if the change model is tiered pricing.
priceFormat:
type: string
description: |
Indicates if the price is a flat fee or is per unit.
enum:
- Per Unit
- Flat Fee
startingUnit:
type: number
description: |
The start number of a range of units for the tier.
tier:
type: integer
format: int64
description: |
A unique number that identifies the tier that the price applies to.
id:
type: string
description: |
The unique identifier of the rate plan charge tier.
createdById:
type: string
description: |
The unique identifier of the user who created the rate plan charge tier.
createdDate:
type: string
format: date-time
description: |
The date and time when the rate plan charge tier was created.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the rate plan charge tier.
updatedDate:
type: string
format: date-time
description: |
The date and time when the rate plan charge tier was last updated.
ratePlanChargeId:
type: string
description: |
The unique identifier of the rate plan charge to which the rate plan charge tier belongs.
ratePlanCharge:
$ref: '#/components/schemas/NestedRatePlanChargeOnExpand'
type: object
title: QueryRatePlanChargeTierResponse
additionalProperties: true
ExpandedRatingResult:
properties:
id:
type: string
description: |
The unique identifier of the rating result.
createdByID:
type: string
description: |
The unique identifier of the user who created the rating result.
createdDate:
type: string
format: date-time
description: |
The date and time when the rating result was created in the Zuora
system, in the `yyyy-mm-dd hh:mm:ss` format.
updatedByID:
type: string
description: |
The unique identifier of the user who last updated the rating result.
updatedDate:
type: string
format: date-time
description: |
The date and time when the rating result was last updated, in the `yyyy-mm-dd hh:mm:ss` format.
accountId:
type: string
description: |
The unique identifier of the customer account associated with the rating result.
subscriptionId:
type: string
description: |
The unique identifier of the subscription associated with the rating result.
ratePlanChargeId:
type: string
description: |
The unique identifier of the rate plan charge associated with the rating result.
quantity:
type: number
description: |
The quantity of the charge.
amount:
type: number
description: |
The amount of the charge.
serviceStartDate:
type: string
format: date
description: |
The start date of the service period for the rating result.
serviceEndDate:
type: string
format: date
description: |
The end date of the service period for the rating result.
status:
type: string
description: |
The status of the rating result.
isPartial:
type: boolean
description: |
Indicates whether the rating result is partial.
chargeSegmentNumber:
type: integer
format: int32
description: |
Rate plan charge number.
invoiceItemId:
type: string
description: |
The unique identifier of the invoice item associated with the rating result.
actualPeriodStartDate:
type: string
format: date
description: |
The start date of the actual period for the rating result.
actualPeriodEndDate:
type: string
format: date
description: |
The end date of the actual period for the rating result.
billingCycleDay:
type: integer
format: int32
description: |
The day of the month on which the billing cycle starts.
account:
$ref: '#/components/schemas/NestedAccountOnExpand'
ratePlanCharge:
$ref: '#/components/schemas/NestedRatePlanChargeOnExpand'
subscription:
$ref: '#/components/schemas/NestedSubscriptionOnExpand'
invoiceItem:
$ref: '#/components/schemas/NestedInvoiceItemOnExpand'
type: object
title: QueryRatingResultResponse
additionalProperties: false
ExpandedRefund:
properties:
id:
type: string
description: |
The unique identifier of the refund.
createdById:
type: string
description: |
The unique identifier of the user who created the refund.
createdDate:
type: string
format: date-time
description: |
The date and time when the refund was created.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the refund.
updatedDate:
type: string
format: date-time
description: |
The date and time when the refund was last updated.
accountId:
description: |
The ID of the account associated with this refund. Zuora associates the refund automatically with the account from the associated payment or credit memo.
type: string
amount:
description: |
The total amount of the refund.
format: double
type: number
cancelledOn:
description: |
The date and time when the refund was cancelled, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
comment:
description: |
Comments about the refund.
type: string
nullable: true
paymentMethodSnapshotId:
type: string
description: |
The unique ID of the payment method snapshot which is a copy of the particular payment method used in a transaction.
accountingCode:
type: string
description: |
The accounting code that maps to this refund transaction in your accounting
system.
currency:
type: string
description: |
The currency of the refund.
gatewayReconciliationReason:
description: |
The reason of gateway reconciliation.
type: string
gatewayReconciliationStatus:
description: |
The status of gateway reconciliation.
type: string
gatewayResponse:
description: |
The message returned from the payment gateway for the refund. This
message is gateway-dependent.
type: string
gatewayResponseCode:
description: |
The code returned from the payment gateway for the refund. This code
is gateway-dependent.
type: string
gatewayState:
description: |
The status of the refund in the gateway.
enum:
- MarkedForSubmission
- Submitted
- Settled
- NotSubmitted
- FailedToSettle
type: string
markedForSubmissionOn:
description: |
The date and time when a refund was marked and waiting for batch submission to the payment process, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
methodType:
description: |
How an external refund was issued to a customer.
enum:
- ACH
- Cash
- Check
- CreditCard
- PayPal
- WireTransfer
- DebitCard
- CreditCardReferenceTransaction
- BankTransfer
- Other
type: string
paymentMethodId:
type: string
description: |
The unique ID of the payment method that the customer used to make the refund.
payoutId:
type: string
description: |
The payout ID of the refund from the gateway side.
reasonCode:
type: string
description: |
A code identifying the reason for the transaction.
refundNumber:
type: string
description: |
The number of the refund.
referenceID:
description: |
The transaction ID returned by the payment gateway for an electronic refund. Use this field to reconcile refunds between your gateway and Zuora Payments.
type: string
refundDate:
description: |
The date when the refund takes effect, in `yyyy-mm-dd` format. For example, 2017-03-01.
format: date
type: string
refundTransactionTime:
description: |
The date and time when the refund was issued, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
type: string
sourceType:
type: string
description: |
Specifies whether the refund is a refund payment or a credit balance.
enum:
- Payment
- CreditBalance
- CreditMemo
secondRefundReferenceId:
description: |
The transaction ID returned by the payment gateway if there is an additional transaction for the refund. Use this field to reconcile payments between your gateway and Zuora Payments.
type: string
settledOn:
description: |
The date and time when the refund was settled in the payment processor, in `yyyy-mm-dd hh:mm:ss` format. This field is used by the Spectrum gateway only and not applicable to other gateways.
format: date-time
type: string
softDescriptor:
description: |
A payment gateway-specific field that maps Zuora to other gateways.
type: string
softDescriptorPhone:
description: |
A payment gateway-specific field that maps Zuora to other gateways.
type: string
status:
description: |
The status of the refund.
enum:
- Processed
- Canceled
- Error
- Processing
type: string
submittedOn:
type: string
description: |
The date and time when the refund was submitted, in `yyyy-mm-dd hh:mm:ss` format.
format: date-time
transferredToAccounting:
description: |
Whether the refund was transferred to an external accounting system. Use this field for integration with accounting systems, such as NetSuite.
enum:
- Processing
- 'Yes'
- 'No'
- Error
- Ignore
type: string
type:
type: string
description: |
The type of the refund.
enum:
- External
- Electronic
associatedTransactionNumber:
type: string
description: |
The number of the associated transactions, such as payments.
gateway:
type: string
description: |
The gateway that processed the original payment. A gateway is an online service provider that connects an online shopping cart to a payment processor.
Zuora uses this same gateway for the corresponding refund.
If this payment gateway is no longer active, then the electronic refund fails.
account:
$ref: '#/components/schemas/NestedAccountOnExpand'
paymentMethod:
$ref: '#/components/schemas/NestedPaymentMethodOnExpand'
refundApplications:
type: array
items:
$ref: '#/components/schemas/NestedRefundApplicationOnExpand'
additionalProperties:
type: object
description: |
Custom fields of the Refund object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryRefundResponse
NestedRefundApplicationOnExpand:
properties:
id:
type: string
description: |
The unique identifier of the refund application.
createdById:
type: string
description: |
The unique identifier of the user who created the refund application.
createdDate:
type: string
format: date-time
description: |
The date and time when the refund application was created.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the refund application.
updatedDate:
type: string
format: date-time
description: |
The date and time when the refund application was last updated.
accountId:
type: string
description: |
The ID of the account associated with this refund application.
applicationGroupId:
type: string
description: |
The ID of the application group to which this payment application belongs.
applyAmount:
type: number
description: |
The total amount of the refund to be applied.
format: double
creditMemoId:
type: string
description: |
The unique identifier of the credit memo to which the associated payment was applied.
effectiveDate:
type: string
format: date
description: |
The date when the refund application becomes effective.
invoiceId:
type: string
description: |
The unique identifier of the invoice to which the associated payment was applied.
paymentId:
type: string
description: |
The unique identifier of the payment associated with the refund application.
refundId:
type: string
description: |
The unique identifier of the refund associated with the refund application.
accountReceivableAccountingCodeId:
type: string
description: |
The Account Receivable accounting code of a standalone charge.
onAccountAccountingCodeId:
description: |
The accounting code that maps to an on account in your accounting
system.
type: string
unappliedPaymentAccountingCodeId:
type: string
description: |
The accounting code for the unapplied payment.
cashAccountingCodeId:
type: string
description: |
The accounting code for cash payments.
journalEntryId:
type: string
description: |
The ID of the journal entry that corresponds to this transaction.
refund:
type: object
description: |
The refund associated with the refund application.
payment:
type: object
description: |
The payment associated with the refund application.
refundApplicationItems:
type: array
items:
type: object
description: |
The refund application items contained in the refund application.
type: object
title: QueryRefundApplicationResponse
additionalProperties: false
ExpandedRefundApplication:
properties:
id:
type: string
description: |
The unique identifier of the refund application.
createdById:
type: string
description: |
The unique identifier of the user who created the refund application.
createdDate:
type: string
format: date-time
description: |
The date and time when the refund application was created.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the refund application.
updatedDate:
type: string
format: date-time
description: |
The date and time when the refund application was last updated.
accountId:
type: string
description: |
The ID of the account associated with this refund application.
applicationGroupId:
type: string
description: |
The ID of the application group to which this payment application belongs.
applyAmount:
type: number
description: |
The total amount of the refund to be applied.
format: double
creditMemoId:
type: string
description: |
The unique identifier of the credit memo to which the associated payment was applied.
effectiveDate:
type: string
format: date
description: |
The date when the refund application becomes effective.
invoiceId:
type: string
description: |
The unique identifier of the invoice to which the associated payment was applied.
paymentId:
type: string
description: |
The unique identifier of the payment associated with the refund application.
refundId:
type: string
description: |
The unique identifier of the refund associated with the refund application.
accountReceivableAccountingCodeId:
type: string
description: |
The accountReceivableAccountingCode of a standalone charge.
onAccountAccountingCodeId:
description: |
The accounting code that maps to an on account in your accounting
system.
type: string
unappliedPaymentAccountingCodeId:
type: string
description: |
The accounting code for the unapplied payment.
cashAccountingCodeId:
type: string
description: |
The accounting code for cash payments.
journalEntryId:
type: string
description: |
The ID of the journal entry that corresponds to this transaction.
refund:
$ref: '#/components/schemas/NestedRefundOnExpand'
payment:
$ref: '#/components/schemas/NestedPaymentOnExpand'
refundApplicationItems:
type: array
items:
$ref: '#/components/schemas/NestedRefundApplicationItemOnExpand'
type: object
title: QueryRefundApplicationResponse
additionalProperties: false
NestedRefundApplicationItemOnExpand:
properties:
id:
type: string
description: |
The unique identifier of the refund application item.
createdById:
type: string
description: |
The unique identifier of the user who created the refund application item.
createdDate:
type: string
format: date-time
description: |
The date and time when the refund application item was created.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the refund application item.
updatedDate:
type: string
format: date-time
description: |
The date and time when the refund application item was last updated.
amount:
type: number
description: |
The amount of the refund application item.
effectiveDate:
type: string
format: date
description: |
The date when the refund application item becomes effective.
applicationGroupId:
type: string
description: |
The ID of the application group to which this refund application belongs.
refundApplicationId:
type: string
description: |
The ID of the refund application to which this refund application item belongs.
accountReceivableAccountingCodeId:
type: string
description: |
The Account Receivable accounting code of a standalone charge.
onAccountAccountingCodeId:
description: |
The accounting code that maps to an on account in your accounting system.
type: string
unappliedPaymentAccountingCodeId:
type: string
description: |
The accounting code for the unapplied payment.
cashAccountingCodeId:
type: string
description: |
The accounting code for cash payments.
journalEntryId:
type: string
description: |
The ID of the journal entry that corresponds to this transaction.
creditTaxationItemId:
type: string
description: |
The unique identifier of the credit taxation item to which the refund application item is applied.
creditMemoItemId:
type: string
description: |
The unique identifier of the credit memo item to which the refund application item is applied.
refundApplication:
type: object
description: |
The refund application object that contains the refund application item.
type: object
title: QueryRefundApplicationItemResponse
additionalProperties: false
ExpandedRefundApplicationItem:
properties:
id:
type: string
description: |
The unique identifier of the refund application item.
createdById:
type: string
description: |
The unique identifier of the user who created the refund application item.
createdDate:
type: string
format: date-time
description: |
The date and time when the refund application item was created.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the refund application item.
updatedDate:
type: string
format: date-time
description: |
The date and time when the refund application item was last updated.
amount:
type: number
description: |
The amount of the refund application item.
effectiveDate:
type: string
format: date
description: |
The date when the refund application item becomes effective.
applicationGroupId:
type: string
description: |
The ID of the application group to which this refund application belongs.
refundApplicationId:
type: string
description: |
The ID of the refund application to which this refund application item belongs.
accountReceivableAccountingCodeId:
type: string
description: |
The Account Receivable accounting code of a standalone charge.
onAccountAccountingCodeId:
description: |
The accounting code that maps to an on account in your accounting system.
type: string
unappliedPaymentAccountingCodeId:
type: string
description: |
The accounting code for the unapplied payment.
cashAccountingCodeId:
type: string
description: |
The accounting code for cash payments.
journalEntryId:
type: string
description: |
The ID of the journal entry that corresponds to this transaction.
creditTaxationItemId:
type: string
description: |
The unique identifier of the credit taxation item to which the refund application item is applied.
creditMemoItemId:
type: string
description: |
The unique identifier of the credit memo item to which the refund application item is applied.
refundApplication:
$ref: '#/components/schemas/NestedRefundApplicationOnExpand'
type: object
title: QueryRefundApplicationItemResponse
additionalProperties: false
ExpandedSummaryStatementRun:
properties:
accountId:
description: |
The unique identifier for the statement account.
type: string
autoEmailEnabled:
description: |
Indicates whether automatic emails are enabled.
type: string
batchName:
description: |
The name of the batch used to filter accounts, for example, Batch1.
type: string
billCycleDay:
description: |
The bill cycle day for filtering accounts, represented as a number, for example '01' to '31'.
nullable: true
type: string
createdDate:
description: |
The date and time when the summary statement run was created.
format: dateTime
type: string
updatedDate:
description: |
The date and time when the summary statement run was last updated.
format: dateTime
type: string
createdById:
description: |
The user ID of the person who created the summary statement run.
type: string
updatedById:
description: |
The user ID of the person who last updated the summary statement run.
type: string
dateRangeType:
description: |
The type of date range used for the statement.
enum:
- Custom
- PreviousOneCalendarMonth
- PreviousThreeCalendarMonth
type: string
deleted:
description: |
Indicates whether the statement has been deleted.
type: string
description:
description: |
A description of the summary statement run.
type: string
endDate:
description: |
The end date of the statement in the format YYYY-MM-DD.
format: date
type: string
id:
description: |
The unique identifier of the statement.
type: string
numberOfAccounts:
description: |
The number of accounts being processed in the summary statement run.
type: string
runType:
description: |
The type of summary statement run.
enum:
- AdHoc
- Scheduled
type: string
startDate:
description: |
The start date of the statement in the format YYYY-MM-DD.
format: date
type: string
statementRunNumber:
description: |
The unique number assigned to this statement run.
type: string
status:
description: |
The current status of the statement, with possible values:
- Pending
- Processing
- GenerationCompleted
- Completed (indicates PDF generation is completed and emails are triggered if AutoEmailEnabled)
- Error
- Terminated
For AutoEmailEnabled, the possible values are Pending, Processing, GenerationCompleted, Completed, Error
For AutoEmailDisabled, the possible values are Pending, Processing, Completed
enum:
- Pending
- Processing
- GenerationCompleted
- Completed
- Error
- Terminated
type: string
targetAccountCategory:
description: |
The method used to filter accounts.
enum:
- SingleAccount
- AllAccounts
- AccountsWithOpenInvoices
- AccountsWithOpenBalances
- AccountsWithoutInvoices
- AccountsWithoutInvoicesAndOpenBalances
type: string
errorCategory:
description: |
The category of error when the operation fails.
type: string
errorMessage:
description: |
The specific error message when the operation fails.
type: string
success:
description: Indicates whether the call succeeded.
type: boolean
statementDate:
description: |
The date of the statement in the format YYYY-MM-DD.
format: date
type: string
statementNumber:
description: |
The unique number assigned to the statement.
type: string
statementRunId:
description: |
ID of the statement run.
type: string
emailStatus:
type: string
description: |
The email status of the statement.
type: object
ExpandedSummaryStatement:
properties:
accountId:
description: |
The unique identifier for the statement account.
type: string
autoEmailEnabled:
description: |
Indicates whether to send an email after a statement is generated. Acceptable values are `true` or `false`. If unspecified, the default value is `false`.
type: boolean
description:
description: |
A text description of the statement run.
type: string
batchName:
description: Name of the batch.
type: string
nullable: true
billCycleDay:
description: |
The bill cycle day for filtering accounts, with values ranging from '01' to '31'.
nullable: true
type: string
dateRangeType:
description: |
The date range for the statement.
If `PreviousThreeCalendarMonth` or `PreviousOneCalendarMonth` is selected, the start and end dates are automatically calculated.
For example, if `PreviousThreeCalendarMonth` is chosen today (2024-08-20), the dates would be 2024-05-01 to 2024-07-31.
enum:
- Custom
- PreviousThreeCalendarMonth
- PreviousOneCalendarMonth
type: string
runType:
description: |
The scheduled type of the run which can either be AdHoc or Scheduled. Currently, only `AdHoc` is supported.
enum:
- AdHoc
type: string
createdById:
description: |
The ID of the user who created the statement.
type: string
createdDate:
description: |
The date and time when the statement was created.
format: dateTime
type: string
deleted:
description: |
Indicates whether the statement has been deleted.
type: string
endDate:
description: |
The end date of the statement in the format YYYY-MM-DD.
format: date
type: string
fileId:
description: |
The ID associated with the file generated for the statement.
type: string
id:
description: |
The unique identifier of the statement.
type: string
startDate:
description: |
The start date of the statement in the format YYYY-MM-DD.
format: date
type: string
emailStatus:
type: string
description: |
The email status of the statement.
statementDate:
description: |
The date of the statement in the format YYYY-MM-DD.
format: date
type: string
statementNumber:
description: |
The unique number assigned to the statement.
type: string
statementRunNumber:
description: |
The number of the related statement run.
type: string
statementRunId:
description: |
The ID of the related statement run.
type: string
status:
description: |
The current status of the statement.
enum:
- Pending
- Processing
- Completed
- Error
- Terminated
type: string
targetAccountCategory:
type: string
description: |
The method used to filter accounts.
enum:
- SingleAccount
- AllAccounts
- AccountsWithOpenInvoices
- AccountsWithOpenBalances
- AccountsWithoutInvoices
- AccountsWithoutInvoicesAndOpenBalances
updatedById:
description: |
The ID of the user who last updated the statement.
type: string
updatedDate:
description: |
The date and time when the statement was last updated.
format: dateTime
type: string
errorCategory:
description: |
The category of error when the operation fails.
type: string
errorMessage:
description: |
The specific error message when the operation fails.
type: string
success:
description: Indicates whether the call succeeded.
type: boolean
type: object
ExpandedSubscription:
properties:
id:
type: string
description: |
The unique identifier of the subscription.
createdById:
type: string
description: |
The unique identifier of the user who created the subscription.
createdDate:
type: string
format: date-time
description: |
The date and time when the subscription was created in the Zuora
system, in the `yyyy-mm-dd hh:mm:ss` format.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the subscription.
updatedDate:
type: string
format: date-time
description: |
The date and time when the subscription was last updated, in the `yyyy-mm-dd hh:mm:ss` format.
accountId:
type: string
description: The ID of the account associated with this subscription.
autoRenew:
type: boolean
description: |
If `true`, the subscription automatically renews at the end of the
term.
default: false
cancelledDate:
type: string
format: date
description: |
The date on which the subscription was canceled.
contractAcceptanceDate:
type: string
format: date
description: |
The date when the customer accepts the contract, in the `yyyy-mm-dd` format.
If this field is not set:
- If the `serviceActivationDate` field is not set, the value of this
field is set to be the contract effective date.
- If the `serviceActivationDate` field is set, the value of this field
is set to be the service activation date.
The billing trigger dates must follow this rule:
contractEffectiveDate <= serviceActivationDate <=
contractAcceptanceDate
contractEffectiveDate:
type: string
format: date
description: |
The date when the subscription is activated, in the `yyyy-mm-dd` format.
You must specify a Service Activation date if the Customer Acceptance
date is set. If the Customer Acceptance date is not set, the value of
the `serviceActivationDate` field defaults to be the Contract
Effective Date.
The billing trigger dates must follow this rule:
contractEffectiveDate <= serviceActivationDate <=
contractAcceptanceDate
creatorAccountId:
type: string
description: |
The ID of the account that created the subscription. This field is
automatically populated with the ID of the account that creates the
subscription.
**Note**: This field is not available for single version subscriptions.
creatorInvoiceOwnerId:
type: string
description: |
The account ID that owns the invoices associated with the subscription or the amended subscription.
**Note**: This field is not available for single version subscriptions.
currentTerm:
type: integer
format: int64
description: |
The length of the period for the current subscription term.
currentTermPeriodType:
type: string
description: |
The period type for the current subscription term.
enum:
- Month
- Year
- Day
- Week
default: Month
initialTerm:
type: integer
format: int64
description: |
The length of the period for the initial subscription term.
initialTermPeriodType:
type: string
description: |
The period type for the first subscription term.
enum:
- Month
- Year
- Day
- Week
default: Month
invoiceOwnerId:
type: string
description: |
The account ID that owns the invoices associated with the subscription.
isInvoiceSeparate:
type: boolean
default: false
description: |
Determines if the subscription is invoiced separately.
If `true`, then all charges for this subscription are collected into the subscription's own invoice.
isSingleVersioned:
type: boolean
description: |
If `true`, the subscription is a single version subscription.
name:
type: string
description: |
The name of the subscription.
notes:
type: string
description: |
Additional information about the subscription.
maxLength: 65535
originalCreatedDate:
type: string
description: |
The date when the subscription was originally created.
This value is the same as the `createdDate` value until the subscription is amended.
originalId:
type: string
description: |
The original rate plan charge ID. Only available for update
subscription.
**Note**: This field is not available for single version subscriptions.
previousSubscriptionId:
type: string
description: |
The ID of the previous subscription. This field is only available if
the subscription is a renewal subscription.
**Note**: This field is not available for single version subscriptions.
renewalSetting:
type: string
description: |
Specifies whether a termed subscription will remain `TERMED` or change to `EVERGREEN` when it is renewed.
enum:
- RENEW_WITH_SPECIFIC_TERM
- RENEW_TO_EVERGREEN
default: RENEW_WITH_SPECIFIC_TERM
renewalTerm:
type: integer
format: int64
description: |
The length of the period for the subscription renewal term.
renewalTermPeriodType:
type: string
description: |
The period type for the subscription renewal term.
enum:
- Month
- Year
- Day
- Week
default: Month
revision:
type: string
description: |
An auto-generated decimal value uniquely tagged with a subscription.
The value always contains one decimal place, for example, the revision
of a new subscription is 1.0. If a further version of the subscription
is created, the revision value will be increased by 1. Also, the
revision value is always incremental regardless of deletion of
subscription versions.
serviceActivationDate:
type: string
format: date
description: |
The date on which the services or products within a subscription have been activated and access has been provided to the customer, in the `yyyy-mm-dd` format.
status:
type: string
description: |
Subscription status.
enum:
- Draft
- Pending Activation
- Pending Acceptance
- Active
- Cancelled
- Suspended
isLatestVersion:
description: |
If `true`, the current subscription object is the latest version.
**Note**: This field is not available for single version subscriptions.
type: boolean
subscriptionEndDate:
type: string
format: date
description: |
The date when the subscription term ends, where the subscription ends
at midnight the day before.
For example, if the `subscriptionEndDate` is 12/31/2016, the
subscriptions ends at midnight (00:00:00 hours) on 12/30/2016.
This date is the same as the term end date or the cancelation date, as
appropriate.
subscriptionStartDate:
type: string
format: date
description: |
Date the subscription becomes effective.
subscriptionVersionAmendmentId:
type: string
description: |
The ID of the amendment made to this subscription version.
**Note**: This field is not available for single version subscriptions.
termEndDate:
type: string
format: date
description: |
Date the subscription term ends. If the subscription is evergreen,
this is null or is the cancellation date (if one has been set).
termStartDate:
type: string
format: date
description: |
Date the subscription term begins. If this is a renewal subscription,
this date is different from the subscription start date.
termType:
type: string
description: |
The type of the subscription term.
enum:
- TERMED
- EVERGREEN
version:
type: integer
format: int64
description: This is the subscription version automatically generated by Zuora Billing. Each order or amendment creates a new version of the subscription, which incorporates the changes made in the order or amendment.
cMRR:
type: number
description: |
Monthly recurring revenue of the subscription.
billToContactSnapshotId:
type: string
description: |
The ID of the bill-to contact snapshot.
billToContactId:
type: string
description: |
The ID of the bill-to contact for the subscription.
invoiceTemplateId:
type: string
description: |
The ID of the invoice template associated with the subscription.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request or you select **Default Template from Account** for this field during subscription creation, the value of this field is automatically set to `null` in the response body.
sequenceSetId:
description: |
The ID of the sequence set associated with the subscription.
**Note**:
- If you have the Flexible Billing Attributes feature disabled, this field is unavailable in the request body and the value of this field is `null` in the response body.
- If you have the Flexible Billing Attributes feature enabled, and you do not specify this field in the request or you select **Default Set from Account** for this field during subscription creation, the value of this field is automatically set to `null` in the response body.
type: string
nullable: true
shipToContactId:
type: string
description: |
The ID of the ship-to contact for the subscription.
shipToContactSnapshotId:
type: string
description: |
The ID of the ship-to contact snapshot.
soldToContactId:
type: string
description: |
The ID of the sold-to contact for the subscription.
soldToContactSnapshotId:
type: string
description: |
The ID of the sold-to contact snapshot.
externallyManagedBy:
type: string
description: |
An enum field on the Subscription object to indicate the name of a
third-party store. This field is used to represent subscriptions created
through third-party stores.
enum:
- Amazon
- Apple
- Google
- Roku
lastBookingDate:
description: |
The last booking date of the subscription object. This field is
writable only when the subscription is newly created as a first
version subscription. You can override the date value when creating a
subscription through the Subscribe and Amend API or the subscription
creation UI (non-Orders). Otherwise, the default value `today` is set
per the user's timezone. The value of this field is as follows:
* For a new subscription created by the [Subscribe and Amend
APIs](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Orders_Harmonization/Orders_Migration_Guidance#Subscribe_and_Amend_APIs_to_Migrate),
this field has the value of the subscription creation date.
* For a subscription changed by an amendment, this field has the value
of the amendment booking date.
* For a subscription created or changed by an order, this field has
the value of the order date.
format: date
type: string
invoiceScheduleId:
type: string
description: |
The ID of the invoice schedule associated with the subscription.
If multiple invoice schedules are created for different terms of a
subscription, this field stores the latest invoice schedule.
**Note**: This field is available only if you have the Billing Schedule feature enabled.
cancelReason:
type: string
description: |
The reason for a subscription cancellation copied from the
`changeReason` field of a Cancel Subscription order action.
This field contains valid value only if a subscription is cancelled
through the Orders UI or API. Otherwise, the value for this field will
always be `null`.
prepayment:
type: boolean
description: |
Whether the subscription is prepaid.
currency:
description: |
The currency of the subscription.
**Note**: This field is available only if you have the Multiple Currencies feature enabled.
type: string
orderId:
description: |
The ID of the order associated with the subscription.
**Note**: This field is available only for orders that exist after the end of June 2023.
type: string
rampId:
type: string
description: |
The ID of the ramp object associated with the subscription.
**Note**: This field is available only if you have the Ramp feature enabled.
paymentTerm:
type: string
description: |
Name of the payment term associated with the account. For example,
"Net 30". The payment term determines the due dates of invoices.
quoteNumber__QT:
type: string
description: |
The unique identifier of the Quote. This field is used in Zuora data
sources to report on Subscription metrics. If the subscription originated
from Zuora Quotes, the value is populated with the value from Zuora
Quotes.
maxLength: 32
quoteType__QT:
description: |
The Quote type that represents the subscription lifecycle stage such as
New, Amendment, Renew or Cancel. This field is used in Zuora data sources
to report on Subscription metrics. If the subscription originated from
Zuora Quotes, the value is populated with the value from Zuora Quotes.
maxLength: 32
type: string
quoteBusinessType__QT:
type: string
description: |
The specific identifier for the type of business transaction the Quote
represents such as New, Upsell, Downsell, Renewal or Churn. This field is
used in Zuora data sources to report on Subscription metrics. If the
subscription originated from Zuora Quotes, the value is populated with the
value from Zuora Quotes.
maxLength: 32
opportunityName__QT:
type: string
description: |
The unique identifier of the Opportunity. This field is used in Zuora data
sources to report on Subscription metrics. If the subscription originated
from Zuora Quotes, the value is populated with the value from Zuora
Quotes.
maxLength: 100
opportunityCloseDate__QT:
type: string
format: date
cpqBundleJsonId__QT:
description: |
The Bundle product structures from Zuora Quotes if you utilize Bundling in Salesforce. Do not change the value in this field.
maxLength: 32
type: string
account:
$ref: '#/components/schemas/NestedAccountOnExpand'
invoiceOwner:
$ref: '#/components/schemas/NestedAccountOnExpand'
billToContact:
$ref: '#/components/schemas/ExpandedContact'
soldToContact:
$ref: '#/components/schemas/ExpandedContact'
invoiceItems:
type: array
items:
$ref: '#/components/schemas/NestedInvoiceItemOnExpand'
ratePlans:
type: array
items:
$ref: '#/components/schemas/NestedRatePlanOnExpand'
additionalProperties:
type: object
description: |
Custom fields of the Subscription object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QuerySubscriptionResponse
ExpandedUsage:
properties:
id:
type: string
description: |
The unique identifier of the usage.
createdById:
type: string
description: |
The unique identifier of the user who created the usage.
createdDate:
type: string
format: date-time
description: |
The date and time when the usage was created.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the usage.
updatedDate:
type: string
format: date-time
description: |
The date and time when the usage was last updated.
accountId:
type: string
description: |
The ID of the customer account associated with the usage.
accountNumber:
type: string
description: |
The number of the customer account associated with the usage.
ratePlanChargeId:
type: string
description: |
ID of the rate plan charge that pays for this usage.
endDateTime:
type: string
description: |
End date of the time period in which usage is tracked. Zuora uses
this field value to determine the usage date.
format: date-time
productRatePlanChargeId:
type: string
description: |
The product rate plan charge number that you use for a dynamic usage charge.
quantity:
type: number
description: |
Number of units used.
rbeStatus:
type: string
description: |
Indicates if the rating and billing engine (RBE) processed usage data for an invoice.
enum:
- Importing
- Pending
- Processed
sourceType:
type: string
description: |
Indicates if the usage records were imported from the web-based UI or the API.
enum:
- API
- Import
startDateTime:
description: |
Start date of the time period in which usage is tracked. Zuora uses
this field value to determine the usage date.
format: date-time
type: string
subscriptionId:
type: string
description: |
The original ID of the subscription that contains the fees related to the usage data.
submissionDateTime:
type: string
format: date-time
description: |
The date and time when the usage was submitted.
uOM:
type: string
description: |
The units to measure usage. Units of measure are configured in the web-based UI. Your values depend on your configuration in **Billing Settings**.
description:
type: string
description: |
A description of the usage record.
importId:
type: string
description: |
The unique identifier of the import.
uniqueKey:
description: |
a customer-defined specific identifier of a usage record.
**Note**: This field is only available if you have the [Prepaid with
Drawdown](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown)
feature or the Unbilled Usage feature enabled. See [Upload usage record with unique
key](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/Prepaid_with_Drawdown/Prepaid_balance_transactions#Upload_usage_record_with_unique_key)
for more information.
type: string
fileId:
description: |
File ID of the uploaded usage records file. You can use this file ID with [Get files](https://developer.zuora.com/api-references/api/operation/GET_Files) to download the file.
type: string
fileName:
type: string
description: |
The name of the import file when the usage record is imported from the file.
account:
$ref: '#/components/schemas/NestedAccountOnExpand'
additionalProperties:
type: object
description: |
Custom fields of the Usage object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryUsageResponse
ExpandedValidityPeriodSummary:
properties:
id:
type: string
description: |
The unique identifier of the validity period summary.
createdById:
type: string
description: |
The unique identifier of the user who created the validity period summary.
createdDate:
type: string
format: date-time
description: |
The date and time when the validity period summary was created.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the validity period summary.
updatedDate:
type: string
format: date-time
description: |
The date and time when the validity period summary was last updated.
prepaidBalanceId:
type: string
description: |
The unique identifier of the prepaid balance.
startDate:
type: string
format: date
description: |
The start date of the validity period.
endDate:
type: string
format: date
description: |
The end date of the validity period.
totalBalance:
type: number
description: |
The total prepaid balance for the current validity period.
remainingBalance:
type: number
description: |
The remaining prepaid balance for the current validity period.
totalBilledAmount:
type: number
description: |
The total amount that has been billed.
billedBalanceAmount:
type: number
description: |
The total amount of the billing documents balances.
subscriptionNumber:
type: string
description: |
The number of the subscription the validity period belongs to.
uom:
type: string
description: |
The UOM of the validity period.
accountNumber:
type: string
description: |
The number of the account to which the prepaid balance belongs.
accountId:
type: string
description: |
The ID of the account to which the prepaid balance belongs.
billingTiming:
type: string
description: |
The billing timing of the validity period.
enum:
- In Advance
- In Arrears
overageRatedQuantity:
type: number
format: double
description: |
The overage rated quantity for the validity period.
**Note**: The `overageRatedQuantity` and `overageRatedAmount` fields of the Validity Period Summary object are approaching end of support on February 01, 2025. For more information, see Product and feature end of support plan.
overageRatedAmount:
type: number
format: double
description: |
The overage rated amount for the validity period.
**Note**: The `overageRatedQuantity` and `overageRatedAmount` fields of the Validity Period Summary object are approaching end of support on February 01, 2025. For more information, see Product and feature end of support plan.
account:
$ref: '#/components/schemas/NestedAccountOnExpand'
prepaidBalance:
$ref: '#/components/schemas/NestedPrepaidBalanceOnExpand'
additionalProperties:
type: object
description: |
Custom fields of the Validity Period Summary object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryValidityPeriodSummaryResponse
ExpandedContactSnapshot:
properties:
id:
type: string
description: |
The unique identifier of the contact snapshot.
createdById:
type: string
description: |
The unique identifier of the user who created the snapshot.
createdDate:
type: string
format: date-time
description: |
The date and time when the contact snapshot was created.
updatedById:
type: string
description: |
The unique identifier of the user who last updated the snapshot.
updatedDate:
type: string
format: date-time
description: |
The date and time when the contact snapshot was last updated.
accountId:
type: string
description: |
The unique identifier of the associated billing account.
contactId:
type: string
description: |
The unique identifier of the original contact.
firstName:
type: string
description: |
The first name of the contact.
lastName:
type: string
description: |
The last name of the contact.
nickName:
type: string
description: |
The nickname of the contact.
address1:
type: string
description: |
The first line of the address.
address2:
type: string
description: |
The second line of the address.
city:
type: string
description: |
The city of the contact's address.
state:
type: string
description: |
The state or province of the contact's address.
postalCode:
type: string
description: |
The postal or ZIP code.
county:
type: string
description: |
The county or region of the contact.
country:
type: string
description: |
The county or region of the contact.
taxRegion:
type: string
description: |
The tax region applicable to the contact.
description:
type: string
description: |
The free-form description of the contact snapshot.
homePhone:
type: string
description: |
The home phone number.
otherPhone:
type: string
description: |
Any other phone number.
otherPhoneType:
type: string
description: |
The type of the other phone number.
fax:
type: string
description: |
The fax number.
personalEmail:
type: string
description: |
The personal email address.
workEmail:
type: string
description: |
The personal email address.
deleted:
type: boolean
description: |
Indicates whether the contact snapshot is marked as deleted.
additionalProperties:
type: object
description: |
Custom fields of the ContactSnapshot object. Only the indexed custom fields with a specified value (not null) are returned. The name of each custom field has the form *customField*__c. Custom field names are case sensitive. See Custom Fields for more information.
type: object
title: QueryContactSnapshotResponse
QueryRatingDetailsResponse:
type: object
title: QueryRatingDetailsResponse
properties:
nextPage:
type: string
nullable: true
description: |
A string to use as the `cursor` value in the next request to paginate results.
data:
type: array
description: Array of rating detail results.
items:
$ref: '#/components/schemas/RatingDetails'
additionalProperties: false
RatingDetails:
type: object
title: RatingDetailResponse
properties:
id:
type: string
description: The unique identifier of the Rating Detail.
invoiceItemId:
type: string
description: The unique identifier of the Invoice Item this Rating Detail is associated to.
creditMemoItemId:
type: string
nullable: true
description: The unique identifier of the Credit Memo Item this Rating Detail is associated to.
chargeType:
type: string
description: The type of charge of the associated Invoice Item.
chargeModel:
type: string
description: The charge model of the associated Invoice Item.
formula:
type: string
description: Text with mathematical formula used to rate the amount.
calculation:
type: string
description: Details of the rating done by replacing values in the formula.
calculatedAmount:
type: number
format: double
description: The output result of the rating calculation.
currency:
type: string
description: The currency code of the calculated amount.
unitOfMeasure:
type: string
description: Unit of measure if it's a usage charge.
quantity:
type: number
format: double
nullable: true
description: If usage charge, quantity of usages.
billedQuantity:
type: number
format: double
nullable: true
description: For on-demand usage charges, previously billed quantity in the same billing period.
billedAmount:
type: number
format: double
nullable: true
description: For on-demand usage charges, previously billed amount in the same billing period.
isProration:
type: boolean
description: True if the billing period is a prorated period.
isCredit:
type: boolean
description: True if this is a credit.
listPriceBase:
type: string
description: List price base from the rate plan charge.
billingCycleDay:
type: integer
description: Billing cycle day from the rate plan charge.
billingCycleType:
type: string
description: Billing cycle type from the rate plan charge.
billingPeriod:
type: string
description: Billing period from the rate plan charge.
specificBillingPeriod:
type: string
description: Specific billing period from the rate plan charge.
validityPeriodType:
type: string
description: Validity period type for prepaid or commitment charges.
billingPeriodAlignment:
type: string
description: Billing period alignment from the rate plan charge.
alignmentStartDate:
type: string
format: date
description: Start date used for billing alignment.
amountWithoutTax:
type: number
format: double
description: The amount from the Invoice Item or Credit Memo Item.
isInclusiveTaxNoRounding:
type: boolean
description: True if tax mode option is set to tax inclusive.
isProrationPartialPeriod:
type: boolean
description: True if billing rule "Prorate recurring charges for partial period?" is Yes.
isProrateMonthlyCharges:
type: boolean
description: True if billing rule "Bill usage/recurring charges for partial month?" is Yes.
isProrateWeeklyCharges:
type: boolean
description: True if billing rule "Bill usage/recurring charges for partial week?" is Yes.
prorationUnitRule:
type: string
description: Value of billing rule for prorating units.
daysInMonthRule:
type: string
description: Value of billing rule for days in a month.
recurringCreditProrationOptionRule:
type: string
description: Billing rule for recurring credit proration option.
isCreditWithOriginalCE:
type: boolean
description: True if permission for credit with original invoice item amount is enabled.
isProrateDiscountCredit:
type: boolean
description: True if prorated discount credit rule is enabled.
stackedDiscountClassApplyRule:
type: string
description: Billing rule for applying stacked discount class.
recurringPeriodStart:
type: string
format: date
description: Start date of the current service period.
recurringPeriodEnd:
type: string
format: date
description: End date of the current service period.
chargeStartDate:
type: string
format: date
description: Charge start date.
chargeEndDate:
type: string
format: date
description: Charge end date.
subStartDate:
type: string
format: date
description: Subscription start date.
subEndDate:
type: string
format: date
description: Subscription end date.
termStartDate:
type: string
format: date
description: Term start date.
termEndDate:
type: string
format: date
description: Term end date.
creditOption:
type: string
description: Credit option from the rate plan charge.
fundingPrice:
type: number
format: double
description: Total price of current validity period fund.
totalBalance:
type: number
format: double
description: Total fund or discount schedule balance.
remainingBalance:
type: number
format: double
description: Remaining fund or discount schedule balance.
originalBillingPeriodStart:
type: string
format: date
description: Start date of original billing period if credit.
originalBillingPeriodEnd:
type: string
format: date
description: End date of original billing period if credit.
originalAmount:
type: number
format: double
description: Original billed amount if credit.
basePrice:
type: number
format: double
description: Base price or fixed amount.
discountClass:
type: string
description: Discount class as in rate plan charge.
discountClassOrder:
type: integer
description: Order number of discount class.
discountLevel:
type: string
description: Discount level from rate plan charge.
discountApplySequence:
type: integer
description: Sequence in which the discount is applied.
discountSchedulePeriodStart:
type: string
format: date
description: Discount schedule start date.
discountSchedulePeriodEnd:
type: string
format: date
description: Discount schedule end date.
regularChargeAmount:
type: number
format: double
description: Amount of the charge that the discount is applied to.
regularChargeAmountLeft:
type: number
format: double
description: Remaining amount of charge before this discount is applied.
originalRegularChargeAmount:
type: number
format: double
description: Original amount of charge before credit.
discountBalanceFormula:
type: string
description: Formula used to calculate discount total balance.
additionalProperties: false
headers:
GLOBAL_HEADER_RESPONSE_Zuora_TrackId:
schema:
type: string
maxLength: 64
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.
GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Type:
schema:
type: string
description: |
The type of the concurrency limit, which can be `Default`, `High-volume transactions`, or `Object Query`.
For more information, see [Concurrent request limits](https://developer.zuora.com/docs/guides/rate-limits/#concurrent-request-limits).
GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Limit:
schema:
type: integer
description: |
The total number of the permitted concurrent requests.
For more information, see [Concurrent request limits](https://developer.zuora.com/docs/guides/rate-limits/#concurrent-request-limits).
GLOBAL_HEADER_RESPONSE_Concurrency_Limit_Remaining:
schema:
type: integer
description: |
The remaining number of the permitted concurrent requests.
For more information, see [Concurrent request limits](https://developer.zuora.com/docs/guides/rate-limits/#concurrent-request-limits).
GLOBAL_HEADER_RESPONSE_Zuora_RequestId:
schema:
type: string
minLength: 36
maxLength: 36
description: |
The Zuora internal identifier of the API call.
You cannot control the value of this header.
GLOBAL_HEADER_RESPONSE_Content_Encoding:
schema:
type: string
description: |
This header is returned if you specify the `Accept-Encoding: gzip` request header and the response contains over 1000 bytes of data.
Note that only the following MIME types support gzipped responses:
- `application/json`
- `application/xml`
- `text/html`
- `text/csv`
- `text/plain`
GLOBAL_HEADER_RESPONSE_RateLimit_Limit:
schema:
type: string
description: |
The request limit quota for the time window closest to exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/rate-limits/) for more information.
GLOBAL_HEADER_RESPONSE_RateLimit_Remaining:
schema:
type: number
description: |
The number of requests remaining in the time window closest to quota exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/rate-limits/) for more information.
GLOBAL_HEADER_RESPONSE_RateLimit_Reset:
schema:
type: number
description: 'The number of seconds until the quota resets for the time window closest to quota exhaustion. See [rate limits](https://developer.zuora.com/docs/guides/rate-limits/) for more information. '
x-tagGroups:
- name: Authentication
tags:
- OAuth
- name: Commerce
tags:
- Commerce
- name: Customer Accounts
tags:
- Accounts
- Contacts
- Contact Snapshots
- name: Orders and Subscriptions
tags:
- Sign Up
- Orders
- Order Actions
- Order Line Items
- Fulfillments
- Ramps
- Subscriptions
- Omnichannel Subscriptions
- Subscription Change History
- Rate Plans
- Commitments
- name: Advanced Consumption Billing
tags:
- Prepaid with Drawdown
- name: Usage
tags:
- Usage
- name: Mediation
tags:
- Meters
- name: Billing Documents
tags:
- Delivery Adjustments
- Billing Documents
- Invoices
- Credit Memos
- Debit Memos
- E-Invoicing
- Invoice Schedules
- Taxation Items
- Sequence Sets
- Operations
- Summary Statements
- 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
- Payment Profiles
- Configurable Payment Retry
- name: Object Query
tags:
- Object Queries
- 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
- Tax Health
- name: Workflow
tags:
- Workflows
- name: Data Query
tags:
- Data Queries
- name: AQuA
tags:
- Aggregate Queries
- name: Deployment Manager
tags:
- Configuration Templates
- Metadata
- name: Data Loader
tags:
- Bulk Data
- name: OneID
tags:
- SCIM
- name: Multiple Organizations
tags:
- Data Labeling
- name: Order to Revenue
tags:
- Data Backfill
- Regenerate
- name: Test Environments
tags:
- Test Environments
- Test Environment Jobs
- Test Environment Notifications
- name: General-Purpose Operations
tags:
- Actions
- Settings
- Files
- Imports
- Custom Exchange Rates
- Attachments
- Describe
- name: Legacy v1 Products
tags:
- Products
- Catalog
- Catalog Groups
- Product Rate Plans
- Product Rate Plan Definitions
- Product Rate Plan Charges
- Product Charge Definitions
- Product Rate Plan Charge Tiers
- Zuora Revenue Integration