Preview Orders

This article explains how to use the Quickstart API to preview the key metrics of an order.

Overview

The Preview an order operation allows you to preview of the charge metrics and invoice items of a specified order. Preview for subscriptions and order line items are both supported.

This operation is only an order preview and no order is created.

To preview an order, you must specify the following fields:

  • metrics
  • account_number or account_data
  • subscriptions , line_items , or both

Sample use case

Suppose that you offer the Startup plan (plan_id=8ad09fc2843cc2fb01843f4504b761af) for your flagship product, Super Network Service. It contains the following license-based prices, and each price can be sold independently of the other:

  • Basic: 20 USD per month for each license ( price_id = 8ad0887e850fc589018512981a1b4acb )
  • Premium: 40 USD per month for each license ( price_id = 8ad0877b84ade9350184af7ccff43ad2 )

One of your subscribers creates a new account with the following basic information:

  • Account name ( name ): ABC Network Account
  • Account currency ( currency ): USD
  • Bill cycle day( bill_cycle_day ): 1
  • Sold-to contact ( sold_to ): Bella Lawrence

They want to purchase 20 licenses for the Basic version price for 6 months (2023-01-01 to 2022-06-30), and 5 licenses for the Enhanced version for 4 months (2023-02-15 to 2023-06-15). Before they purchase, they want to preview the delta order metrics of each subscription.

Code examples

cURLJavaNode
Copy
Copied
curl --request POST \
    --url https://rest.apisandbox.zuora.com/v2/orders/preview \
    --header 'Authorization: Bearer 4aac5c58c0c94142ba039f9eb5205be6' \
    --header 'Content-Type: application/json' \
    --data '{
        "description": "Preview an order request",
            "account_data": {
                "currency": "USD",
                "bill_cycle_day": 1,
                "sold_to": {
                    "first_name": "Bella",
                    "last_name": "Lawrence",
                    "address": {
                        "line1": "101 Redwood Shores Parkway",
                        "line2": "",
                        "city": "Redwood City",
                        "state": "California",
                        "country": "USA",
                        "postal_code": "94065"
                    },
                    "work_phone": "(888) 976-9056",
                    "work_email": "amy.lawrence@gmail.com"
                }
            },
            "metrics": ["delta_metrics"],
            "subscriptions": [
                {
                    "initial_term": {
                        "interval_count": 6,
                        "interval": "month",
                        "type": "termed"
                    },
                    "renewal_term": {
                        "type": "termed",
                        "interval": "month",
                        "interval_count": 3
                    },
                    "start_on": {
                        "contract_effective": "2023-01-01"
                    },
                    "subscription_plans": [
                        {
                            "plan_id": "8ad09fc2843cc2fb01843f4504b761af",
                            "prices": [
                                {
                                    "price_id": "8ad0887e850fc589018512981a1b4acb",
                                    "quantity": 20,
                                    "unit_amount": 20,
                                    "start_date": "2023-01-01",
                                    "end_date": "2023-06-30"        
                                },
                                {
                                    "price_id": "8ad0877b84ade9350184af7ccff43ad2",
                                    "quantity": 5,
                                    "unit_amount": 40,
                                    "start_date": "2023-02-15",
                                    "end_date": "2023-06-15"
                                }
                            ]
                        }				
                    ]
                }
            ]
        }
        '
Copy
Copied
LocalDate startDate1 = LocalDate.of(2023,1,1);
LocalDate endDate1 = LocalDate.of(2023,12,31);
LocalDate startDate2 = LocalDate.of(2023,2,15);
LocalDate endDate2 = LocalDate.of(2023,6,15);

// New subscription request payload
SubscriptionItemCreateRequest subscriptionItemCreateRequest1 = new SubscriptionItemCreateRequest()
    .priceId("8ad0887e850fc589018512981a1b4acb")
    .quantity(new BigDecimal(20))
    .startDate(startDate1)
    .endDate(endDate1);

SubscriptionItemCreateRequest subscriptionItemCreateRequest2 = new SubscriptionItemCreateRequest()
    .priceId("8ad0877b84ade9350184af7ccff43ad2")
    .quantity(new BigDecimal(5))
    .startDate(startDate2)
    .endDate(endDate2);

ArrayList prices = new ArrayList();
prices.add(subscriptionItemCreateRequest1);
prices.add(subscriptionItemCreateRequest2);

SubscriptionPlanCreateRequest subscriptionPlanRequest = new SubscriptionPlanCreateRequest()
    .planId("8ad09fc2843cc2fb01843f4504b761af")
    .prices(prices);

PostSubscriptionOrderRequest newSubscriptionRequest = new PostSubscriptionOrderRequest()
    .initialTerm(new Term()
        .interval(Term.IntervalEnum.MONTH)
        .intervalCount(1)
        .type(Term.TypeEnum.TERMED))
    .renewalTerm(new Term()
        .type(Term.TypeEnum.TERMED)
        .intervalCount(2)
        .interval(Term.IntervalEnum.MONTH))
    .startOn(new StartOn().contractEffective(startDate1))
    .subscriptionPlans(Collections.singletonList(subscriptionPlanRequest));

// New account request payload
AccountContactCreateRequest contactCreateRequest = new AccountContactCreateRequest()
    .firstName("Bella")
    .lastName("Lawrence")
    .workEmail("bella.lawrence@gmail.com")
    .workPhone("(888) 976-9056")
    .address(new Address()
        .country("USA")
        .state("California")
        .postalCode("94065")
        .line1("101 Redwood Shores Parkway")
        .city("Redwood City"));

SubscriptionPreviewAccountRequest accountCreateRequest = new SubscriptionPreviewAccountRequest()
    .billCycleDay(1)
    .soldTo(contactCreateRequest)
    .currency("USD");

// Order preview request payload
OrderPreviewCreateRequest orderPreviewRequest = new OrderPreviewCreateRequest()
    .description("Preview an order request")
    .accountData(accountCreateRequest)
    .metrics(Collections.singletonList(OrderPreviewCreateRequest.MetricsEnum.DELTA_METRICS))
    .subscriptions(Collections.singletonList(newSubscriptionRequest));

// Create an order preview
Map<String, Object> orderPreview = zuoraClient.orders().createOrderPreview(orderPreviewRequest);
Copy
Copied
const soldToContact = {
    first_name: 'Bella',
    last_name: 'Lawrence',
    work_phone: '(888) 976-9056',
    work_email: 'bella.lawrence@gmail.com',
    address:{
        line1: '101 Redwood Shores Parkway',
        city: 'Redwood City',
        state: 'California',
        country: 'USA',
 },
};
const account = {
    sold_to: soldToContact,
    currency: 'USD',
    bill_cycle_day: 1,
};
 
const subscription_plans = [{
    plan_id: '8ad09fc2843cc2fb01843f4504b761af',
    prices: [
    {
        price_id: '8ad0887e850fc589018512981a1b4acb',
        quantity: 20,
        start_date: '2023-01-01',
        end_date: '2023-12-01',      
    },
    {
        price_id: '8ad0877b84ade9350184af7ccff43ad2',
        quantity: 5,
        start_date: '2022-12-15',
        end_date: '2023-06-15',
    },
    ]
}];
 
 
const subscriptionRequest = {
    initial_term: {
        interval_count:1,
        interval: 'month',
        type: 'termed',
    },
    renewal_term:{
        type: 'termed',
        interval: 'month',
        interval_count: 2,
    },
    subscription_plans: subscription_plans,
    start_on:{
        contract_effective: "2023-01-01",
    },
};
 
const orderPreviewRequest = {
    description: 'Description of order preview',
    account_data: account,
    order_date: '2023-01-01',
    metrics: ['delta_metrics'],
    subscriptions: [subscriptionRequest],
};
 
const previewedOrder = await zuoraClient.orders.createOrderPreview(orderPreviewRequest); 

Then you can get the following response:

Copy
Copied
{
	"subscriptions": [
		{
			"subscription_number": "null",
			"actions": [
				{
					"action_id": "8ad0934e85ab06a10185bab719a937ee",
					"subscription_number": null,
					"action": "create_subscription",
					"sequence": 0,
					"subscription_items": [
						{
							"subscription_item_id": "8ad0934e85ab06a10185bab71aea381c",
							"price_id": "8ad0877b84ade9350184af7ccff43ad2",
							"start_date": "2023-02-15",
							"end_date": "2023-06-15",
							"tcb": {
								"gross_amount": 65.594730145,
								"net_amount": 65.594730145,
								"currency": "USD"
							},
							"mrr": {
								"gross_amount": 16.666666667,
								"net_amount": 16.666666667,
								"currency": "USD"
							}
						},
						{
							"subscription_item_id": "8ad0934e85ab06a10185bab71aea381e",
							"price_id": "8ad0887e850fc589018512981a1b4acb",
							"start_date": "2023-01-01",
							"end_date": "2023-06-30",
							"tcb": {
								"gross_amount": 197.260273973,
								"net_amount": 197.260273973,
								"currency": "USD"
							},
							"mrr": {
								"gross_amount": 33.333333333,
								"net_amount": 33.333333333,
								"currency": "USD"
							}
						},
						{
							"subscription_item_id": "8ad0934e85ab06a10185bab71aea3821",
							"price_id": "8ad08e0184ade9350184af5bf1f46007",
							"start_date": "2023-01-01",
							"end_date": "2023-07-01",
							"tcb": {
								"gross_amount": 74.383561644,
								"net_amount": 74.383561644,
								"currency": "USD"
							},
							"mrr": {
								"gross_amount": 12.5,
								"net_amount": 12.5,
								"currency": "USD"
							}
						}
					]
				}
			]
		}
	]
}