Preview an order asynchronously

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.

Request

header Parameters

Idempotency-Key	string <= 255 characters Specify a unique idempotency key if you want to perform an idempotent POST or PATCH request. Do not use this header in other request types. With this header specified, the Zuora server can identify subsequent retries of the same request using this value, which prevents the same operation from being performed multiple times by accident.
Accept-Encoding	string Include the `Accept-Encoding: gzip` header to compress responses as a gzipped file. It can significantly reduce the bandwidth required for a response. If specified, Zuora automatically compresses responses that contain over 1000 bytes of data, and the response contains a `Content-Encoding` header with the compression algorithm so that your client can decompress it.
Content-Encoding	string 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.
Authorization	string The value is in the `Bearer {token}` format where {token} is a valid OAuth token generated by calling Create an OAuth token.
Zuora-Track-Id	string <= 64 characters A custom identifier for tracing the API call. If you set a value for this header, Zuora returns the same value in the response headers. This header enables you to associate your system process identifiers with Zuora API calls, to assist with troubleshooting in the event of an issue. The value of this field must use the US-ASCII character set and must not include any of the following characters: colon (`:`), semicolon (`;`), double quote (`"`), and quote (`'`).
Zuora-Entity-Ids	string An entity ID. If you have Zuora Multi-entity enabled and the OAuth token is valid for more than one entity, you must use this header to specify which entity to perform the operation in. If the OAuth token is only valid for a single entity, or you do not have Zuora Multi-entity enabled, you should not set this header.
Zuora-Org-Ids	string 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. If the header is not set, the operation is performed in scope of the user's accessible orgs.

Request Body schema: application/json
required

category	string Default: "NewSales" Category of the order to indicate a product sale or return. Default value is `NewSales`. Enum: "NewSales" "Return"
	object (orderFieldsCustom) Container for custom fields of an Order object.
description	string <= 500 characters A description of the order.
existingAccountNumber	string <= 70 characters The account number that this order will be created under. Note that invoice owner account of the subscriptions included in this order should be the same with the account of the order.
orderDate required	string <date> 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.
	Array of objects (CreateOrderOrderLineItem) 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 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.
orderNumber	string <= 100 characters The order number of this order. Note: Make sure the order number does not contain a slash.
	object (previewAccountInfo) Information about the account that will own the order.
required	object (PreviewOptions)
reasonCode	string <= 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.
	Array of objects Each item includes a set of order actions, which will be applied to the same base subscription.

Responses

202

Accepted

post/v1/async/orders/preview

Request samples

Payload
cURL

application/json

{"customFields": { },
"description": "This is a description for the Order.",
"existingAccountNumber": "A00000101",
"orderDate": "2018-10-01",
"orderLineItems": [{"amountPerUnit": 50,
"billingTrigger": "BillImmediately",
"customFields": {"someField__c": "some string"
},
"deferredRevenueAccountingCode": "Unearned Revenues",
"description": "With Dual Stereo Microphones, HD 1080p, Black",
"itemName": "webcam",
"itemType": "Product",
"listPricePerUnit": 59,
"productCode": "C9201",
"purchaseOrderNumber": "960-000764",
"quantity": 2,
"recognizedRevenueAccountingCode": "Earned Revenues",
"revenueRecognitionRule": "recognized upon invoice",
"taxCode": "8018",
"taxMode": "TaxInclusive",
"transactionEndDate": "2021-02-01",
"transactionStartDate": "2021-02-01"
}
],
"previewOptions": {"previewThruType": "SpecificDate",
"previewTypes": ["OrderMetrics",
"BillingDocs",
"ChargeMetrics"
],
"specificPreviewThruDate": "2019-01-01"
},
"subscriptions": [{"orderActions": [{"triggerDates": [{"name": "ContractEffective",
"triggerDate": "2018-12-01"
},
{"name": "ServiceActivation",
"triggerDate": "2018-12-01"
},
{"name": "CustomerAcceptance",
"triggerDate": "2018-12-01"
}
],
"type": "UpdateProduct",
"updateProduct": {"chargeUpdates": [{"chargeNumber": "C-00000210",
"pricing": {"recurringPerUnit": {"listPrice": 20
}
}
}
],
"ratePlanId": "2c98919c67a5ae9d0167a68f8eb20262"
}
}
],
"subscriptionNumber": "A-S00000100"
},
{"orderActions": [{"suspend": {"suspendPolicy": "Today"
},
"triggerDates": [{"name": "ContractEffective",
"triggerDate": "2018-12-01"
},
{"name": "ServiceActivation",
"triggerDate": "2018-12-01"
},
{"name": "CustomerAcceptance",
"triggerDate": "2018-12-01"
}
],
"type": "Suspend"
}
],
"subscriptionNumber": "A-S00000101"
},
{"orderActions": [{"resume": {"extendsTerm": true,
"resumePeriods": 10,
"resumePeriodsType": "Day",
"resumePolicy": "FixedPeriodsFromSuspendDate"
},
"triggerDates": [{"name": "ContractEffective",
"triggerDate": "2018-12-12"
},
{"name": "ServiceActivation",
"triggerDate": "2018-12-12"
},
{"name": "CustomerAcceptance",
"triggerDate": "2018-12-12"
}
],
"type": "Resume"
}
],
"subscriptionNumber": "A-S00000102"
}
]
}

Response samples

application/json

{"jobId": "2c90a02d676688200167770ce20601b6"
}