Preview an order asynchronously

POST

/v1/async/orders/preview

POST

/v1/async/orders/preview

from zuora import ZuoraClient, PreviewOptions, PreviewOrderOrderAction, PreviewOrderCreateSubscription, PreviewOrderRatePlanOverride, PreviewOrderCreateSubscriptionTerms, PreviewOrderCreateSubscriptionTermsInitialTerm, RenewalTerm, TriggerDate
import datetime
from zuora.orders import PostOrderPreviewAsyncRequestTypeSubscriptionsItem
client = ZuoraClient(
    token="YOUR_TOKEN_HERE",
)
client.orders.post_preview_order_asynchronously(
    existing_account_number="A00000097",
    order_date=datetime.date.fromisoformat("2024-07-01"),
    preview_options=PreviewOptions(
        preview_thru_type="SpecificDate",
        preview_types=[
            "BillingDocs"
        ],
        specific_preview_thru_date=datetime.date.fromisoformat("2024-07-31"),
    ),
    subscriptions=[
        PostOrderPreviewAsyncRequestTypeSubscriptionsItem(
            order_actions=[
                PreviewOrderOrderAction(
                    create_subscription=PreviewOrderCreateSubscription(
                        subscribe_to_rate_plans=[
                            PreviewOrderRatePlanOverride(
                                product_rate_plan_id="8ad081dd9096ef9501909b40bb4e74a4",
                            )
                        ],
                        terms=PreviewOrderCreateSubscriptionTerms(
                            initial_term=PreviewOrderCreateSubscriptionTermsInitialTerm(
                                period=12,
                                period_type="Month",
                                term_type="TERMED",
                            ),
                            renewal_setting="RENEW_WITH_SPECIFIC_TERM",
                            renewal_terms=[
                                RenewalTerm(
                                    period=12,
                                    period_type="Month",
                                )
                            ],
                        ),
                    ),
                    trigger_dates=[
                        TriggerDate(
                            name="ContractEffective",
                            trigger_date=datetime.date.fromisoformat("2024-07-01"),
                        ),
                        TriggerDate(
                            name="ServiceActivation",
                            trigger_date=datetime.date.fromisoformat("2024-07-01"),
                        ),
                        TriggerDate(
                            name="CustomerAcceptance",
                            trigger_date=datetime.date.fromisoformat("2024-07-01"),
                        )
                    ],
                    type="CreateSubscription",
                )
            ],
        )
    ],
)

202response

{
  "jobId": "2c90a02d676688200167770ce20601b6"
}

Notes:

This operation is only available if you have the Orders feature enabled. Orders is now generally available as of Zuora Billing Release 284 (August 2020). If you are an existing Zuora Subscribe and Amend customer, we recommend you enable Orders Harmonization to access the Orders feature. With Orders, you can access both existing functions for subscription and billing management and the new features on Zuora Billing.
The Order Line Items feature is now generally available to all Zuora customers. You need to enable the Orders feature to access the Order Line Items feature. As of Zuora Billing Release 313 (November 2021), new customers who onboard on Orders will have the Order Line Items feature enabled by default.
You cannot preview enhanced discounts and usage charges.

In the case where a normal “Preview an order” operation call will time out, use this operation instead to preview an order asynchronously. A job will be previewing the order in the back end; the job ID will be returned for tracking the job status and result.

Billing preview behavior regarding draft invoices

By default, the billing preview behavior regarding draft invoices is as below:

When you preview billing for your order and the order contains subscriptions only, the draft invoices are excluded.
When you preview billing for your order and the order contains order line items only, the draft invoices are included.
When you preview billing for an order that contains both subscriptions order line items, the draft invoices are included for both subscriptions and order line items.

However, if you want to always exclude the draft invoices in billing preview, submit a request at Zuora Global Support.

Limits on Orders API

The limit of orders allowed on a subscription is 1000.

The limit of order line items allowed in an order is 100.

Zuora has the following limits on the Orders synchronous API to prevent performance degradation:

Up to 50 subscriptions are allowed in a single Create an order or Preview an order operation call.
Up to 50 order actions are allowed in a single Create an order or Preview an order operation call.
Up to 50 order actions are allowed on a single subscription in a Create an order or Preview an order operation call.

If you have an Order that exceeds any limits of the above, Zuora recommends you use the following asynchronous API operations:

Create an order asynchronously
Preview an order asynchronously
Retrieve the status and response of a job for checking the status of the asynchronous API operations

Zuora has the following limits on the Orders asynchronous API operations to prevent performance degradation:

Up to 300 subscriptions are allowed in a single Create an order asynchronously or Preview an order asynchronously operation call.
Up to 300 order actions are allowed in a single Create an order asynchronously or Preview an order asynchronously operation call.
Up to 300 order actions are allowed on a single subscription in a Create an order asynchronously or Preview an order asynchronously operation call.

Authentication

AuthorizationBearer

Use Bearer {{token}} in the Authorization header for authentication.

Headers

Content-EncodingstringOptional

Include the Content-Encoding: gzip header to compress a request. With this header specified, you should upload a gzipped file for the request payload instead of sending the JSON payload.

Zuora-Org-IdsstringOptional

Comma separated IDs. If you have Zuora Multi-Org enabled, you can use this header to specify which orgs to perform the operation in. If you do not have Zuora Multi-Org enabled, you should not set this header.

The IDs must be a sub-set of the user’s accessible orgs. If you specify an org that the user does not have access to, the operation fails. This header is important in Multi-Org (MO) setups because it defines the organization context under which the API should operate—mainly used for read access or data visibility filtering. If the header is not set, the operation is performed in scope of the user’s accessible orgs.

Query parameters

summarizeInvoiceItembooleanOptionalDefaults to false

Indicates whether to return aggregated invoice item summaries for each invoice.

With this parameter set to true, the invoices > invoiceItemSummary field is returned in the preview result. The aggregated invoiceItemSummary field provides a forecast of the number of future invoices (previewInvoiceSequence), and the following information for each invoice:

subTotal
total
taxAmount
discountAmount
servicePeriodStartDate
servicePeriodEndDate

Request

This endpoint expects an object.

orderDatedateRequired

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.

previewOptionsobjectRequired

categoryenumOptionalDefaults to NewSales

Category of the order to indicate a product sale or return. Default value is NewSales.

Allowed values:

customFieldsmap from strings to anyOptional

Container for custom fields of an Order object.

descriptionstringOptional<=500 characters

A description of the order.

existingAccountIdstringOptional

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.

existingAccountNumberstringOptional<=70 characters

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.

orderLineItemslist of objectsOptional

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 feature is now generally available to all Zuora customers. You need to enable the Orders feature to access the Order Line Items feature. As of Zuora Billing Release 313 (November 2021), new customers who onboard on Orders will have the Order Line Items feature enabled by default.

orderNumberstringOptional<=100 characters

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 '.

previewAccountInfoobjectOptional

Information about the account that will own the order.

reasonCodestringOptional<=255 characters

Values of reason code configured in Billing Settings > Configure Reason Codes through Zuora UI. Indicates the reason when a return order line item occurs.

subscriptionslist of objectsOptional

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.

Response headers

Content-EncodingstringOptional

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

LocationstringOptional

URL for accessing the job result, in the format of /async-jobs/{jobId}. For example, /async-jobs/2c90a02d676688200167770ce20601b6

RateLimit-LimitstringOptional

The request limit quota for the time window closest to exhaustion. See rate limits for more information.

RateLimit-Remainingdouble

The number of requests remaining in the time window closest to quota exhaustion. See rate limits for more information.

RateLimit-Resetdouble

The number of seconds until the quota resets for the time window closest to quota exhaustion. See rate limits for more information.

Zuora-Request-IdstringOptional

The Zuora internal identifier of the API call. You cannot control the value of this header.

Zuora-Track-IdstringOptional

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.

Concurrency-Limit-TypestringOptional

The type of the concurrency limit, which can be Default, High-volume transactions, or Object Query.

For more information, see Concurrent request limits.

Concurrency-Limit-Limitinteger

The total number of the permitted concurrent requests.

For more information, see Concurrent request limits.

Concurrency-Limit-Remaininginteger

The remaining number of the permitted concurrent requests.

For more information, see Concurrent request limits.

Response

Accepted

jobIdstringOptionalformat: "UUID"

The ID of an asynchronous job that will be returned for tracking the status and result of the job.