Preview an order

Zuora client libraries version 3.x is in the Early Adopter phase. It integrates both the v1 API and Quickstart API into a unified set of libraries. We recommend that you try our client libraries 3.x to start testing or integrating with Zuora.

End-user flow

Below is a typical checkout page for a customer in the purchase process.

The previewed billing amounts are displayed on the left and a Credit Card or ACH Payment Form is embedded on the right.

The code below is a sample "Preview an order" call that obtains these billing amounts for you.

Preview the order

The order summary part displays the total amount of the order, along with the selected product and product rate plan details.

Sample code

Assuming the subscription is set as an evergreen subscription, the following sample code calls the Preview an order operation and submits the following information for preview:

  • existingAccountNumber: A00024362 (obtained from the previous call)
  • subscribeToRatePlans:
  • previewTypes: BillingDocs, representing only the total amounts that will appear on the invoice.
  • orderDate: 2024-07-01
  • terms > initialTerm > termType: EVERGREEN
cURLJavaNode.jsPython
Copy
Copied
curl -L -X POST 'https://rest.test.zuora.com/v1/orders/preview' \
-H 'zuora-version: 341' \
-H 'Authorization: Bearer 68ec505613a94daeaa28aa4b44435696' \
-H 'Content-Type: application/json' \
-d '{
"orderDate": "2024-07-01",
"previewOptions":{
    "previewThruType": "NumberOfPeriods",
    "previewNumberOfPeriods": 1,
    "previewTypes": ["BillingDocs"]
},
 "existingAccountNumber": "A00024362",
 "subscriptions": [
    {
        "orderActions":[{
            "type": "CreateSubscription",
            "createSubscription": {
                "terms": {
                    "initialTerm": {
                        "termType": "EVERGREEN"
                    }
                },
                "subscribeToRatePlans": [{
                    "productRatePlanNumber": "PRP-00000180"
                }]
            }
        }]
    }
 ]
}'
Copy
Copied
import com.zuora.model.*;

// Code for client initialization
...

var initialTerm = new InitialTerm().periodType(null).termType(TermType.EVERGREEN);
var terms = new PreviewOrderCreateSubscriptionTerms().initialTerm(initialTerm);
var ratePlanOverride = new PreviewOrderRatePlanOverride().productRatePlanNumber("PRP-00000180");

var previewOrderCreateSubs = new PreviewOrderCreateSubscription()
        .terms(terms)
        .addSubscribeToRatePlansItem(ratePlanOverride);

var subscription = new PreviewOrderSubscriptions()
            .addOrderActionsItem(new PreviewOrderOrderAction()
                    .type(OrderActionType.CREATESUBSCRIPTION)
                    .createSubscription(previewOrderCreateSubs));

var previewOptions = new PreviewOptions()
            .previewThruType(PreviewOptionsPreviewThruType.NUMBEROFPERIODS)
            .previewNumberOfPeriods(1)
            .previewTypes(List.of(PreviewTypesEnum.BILLINGDOCS));

var request = new PreviewOrderRequest()
            .orderDate(LocalDate.now())
            .previewOptions(previewOptions)
            .existingAccountNumber(account.getAccountNumber())
            .addSubscriptionsItem(subscription);

var previewOrderResp = zuoraClient.ordersApi().previewOrderApi(request).execute();
System.out.print(previewOrderResp);
Copy
Copied
const initialTerm = new InitialTerm();
initialTerm.termType = 'EVERGREEN';
initialTerm.periodType = null;

const terms = new PreviewOrderCreateSubscriptionTerms(initialTerm);

const ratePlanOverride = new PreviewOrderRatePlanOverride();
ratePlanOverride.productRatePlanNumber = 'PRP-00000770';
 
const previewOrderCreateSubs = new PreviewOrderCreateSubscription()
previewOrderCreateSubs.terms = terms;
previewOrderCreateSubs.subscribeToRatePlans = [ratePlanOverride];


const subscription = new PreviewOrderSubscriptionsAsync()
const orderActions = new PreviewOrderOrderAction(CreateSubscription);
orderActions.type = 'CreateSubscription';
orderActions.createSubscription = previewOrderCreateSubs;
subscription.orderActions = [orderActions];


const previewOptions = new PreviewOptions()
previewOptions.previewThruType = 'NumberOfPeriods';
previewOptions.previewNumberOfPeriods = 1;
previewOptions.previewTypes = ['BillingDocs'];

const date = new Date();
date.setFullYear(2024,7,1);
const request = new PreviewOrderRequest(date.toISOString().split('T')[0], previewOptions);

request.existingAccountNumber = 'A00147434'
request.subscriptions = [subscription];

const previewOrderResp = await zuoraClient.ordersApi.previewOrder(request);
console.log(JSON.stringify(previewOrderResp, (k, v) => v ?? undefined, 2));
Copy
Copied
from datetime import date
from zuora_sdk import CreateOrderRequest, PreviewOrderRequest, PreviewOrderResponse, CreateOrderResponse, CreateOrderSubscription, \
    ProcessingOptionsWithDelayedCapturePayment
...


def preview_order(client=None):
    if not client:
        client = get_client()
    try:
        request = PreviewOrderRequest(
            order_date=date.today().strftime('%Y-%m-%d'),
            existing_account_number='A00000001',
            subscriptions=[{
                'order_actions': [{
                    'type': 'CreateSubscription',
                    'create_subscription': {
                        'terms': {'initial_term': {'term_type': 'EVERGREEN'}},
                        'subscribe_to_rate_plans': [{'product_rate_plan_number': 'PRP-00000151'}]
                    }
                }]
            }],
            preview_options={'preview_thru_type': 'NumberOfPeriods', 'preview_number_of_periods': 1, 'preview_types': ['BillingDocs']}
        )
        api_response: PreviewOrderResponse = client.orders_api().preview_order(request)
        print(api_response.to_json())
    except ApiException as e:
        print("Exception when calling OrdersApi->preview_order: %s\n" % e)
    return None

if __name__ == '__main__':
    preview_order()

If the request succeeds, you will get a response similar to the following snippet:

Copy
Copied
{
    "success": true,
    "previewResult": {
        "invoices": [
            {
                "amount": 49.99,
                "amountWithoutTax": 49.99,
                "taxAmount": 0.00,
                "targetDate": "2024-07-01",
                "invoiceItems": [
                    {
                        "serviceStartDate": "2024-07-01",
                        "serviceEndDate": "2024-07-31",
                        "amountWithoutTax": 49.99,
                        "taxAmount": 0.000000000,
                        "chargeDescription": "No refund if you cancel after 7 days.",
                        "chargeName": "Recurring per unit fee",
                        "chargeNumber": null,
                        "processingType": "Charge",
                        "productName": "SmartLearn Tablet",
                        "productRatePlanChargeId": "8a8aa19590e7dea30190ecf807da39ab",
                        "unitPrice": 49.990000000,
                        "subscriptionNumber": null,
                        "orderLineItemNumber": null,
                        "taxationItems": [],
                        "additionalInfo": {
                            "quantity": 1,
                            "unitOfMeasure": "License",
                            "numberOfDeliveries": 0.000000000
                        }
                    }
                ]
            }
        ]
    }
}

Next step

Collect-payments