Create orders

Orders are contractual agreements between merchants and customers. You can create multiple subscriptions and make updates to subscriptions 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.

Core concepts

Order

An order represents a record of transactions where your customers purchase the services or physical goods you offer.

Order delta metrics

Order Delta Metrics represent the changes in key metrics as the result of an order. Delta metrics of order actions, including:

  • Order Delta Mrr
  • Order Delta Tcb

Order actions

Order actions represent the actions that can be performed on subscriptions, such as creating subscriptions, making changes to subscriptions, and cancelling subscriptions.

Order line items

Order Line Items are objects contained in an Order object to represent non-subscription based charges. With order line items, you can use the Orders API and UI to send non-subscription based transactional charges, such as one-time fees, physical goods, or professional service charges without the need for a subscription.

The following diagram describes the relationships among these core concepts:

Orders Objects Relationship

For more information about the Orders feature, see Orders.

When should I use the the Orders operations?

Compared to the Subscription operations, the "Create an order" operation is much more efficient in the following scenarios:

  • Create a new account with one or multiple subscriptions in one call
  • Make multiple changes to subscriptions on an existing account in one call
  • Create multiple order line items, update order line items, and manage the state of each order line item in one call
  • Create recurring subscriptions together with order line items

You can also use the "Preview an order" to view order delta metrics and billing document item metrics for every change made to subscriptions and order line items.

Quickstart API
v1 API

Preview an order

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.test.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"
							}
						}
					]
				}
			]
		}
	]
}

Create an order

Example: Create a new account with multiple subscriptions

Overview

To create a new account with one or multiple subscriptions, you must specify the following fields in the request payload:

  • account_data
    • bill_to > first_name
    • bill_to > last_name
    • name
    • currency
  • subscription
    • initial_term
    • renewal_term
    • start_on > contract_effective
    • subscription_plans > plan_id

Sample use case

Suppose that you offer the following plans for your flagship product, Super Network Service:

  • Network service plan (plan_id=8ad09fc2843cc2fb01843f4504b761af) that contains the following license-based prices. Each can be sold independently of the other.
    • Basic: 20 USD per month for each license (price_id = 8ad0887e850fc589018512981a1b4acb)
    • Enhanced: 40 USD per month for each license (price_id = 8ad0877b84ade9350184af7ccff43ad2)
  • Support service plan (plan_id=8ad0877b84f775280184f8047ab011e9) that contains the following flat-fee prices:
    • Basic support (price_id=8ad09bce84f7896b0184f80caa622518): 300 USD per year
    • Premium support (price_id=8ad59ece84f8462b0184f80caa981334): 500 USD per year

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

  • Account name (name): ABC Network Account
  • Account currency (currency): USD
  • Bill-to contact (bill_to): Amy Lawrence
  • Payment method (payment_method): a credit card of Visa

They purchase 20 licenses for the Basic version price and 5 licenses for the Enhanced version for 4 months. The initial term is 1 year starting from 2023-01-01, and it will become evergreen upon renewal. They also subscribe to the Basic Support service for 1 year.

Code examples

cURLJavaNode
Copy
Copied
curl --request POST \
  --url https://rest.test.zuora.com/v2/orders \
  --header 'Authorization: Bearer addae50e361d464584d57818d8d9d1d9' \
  --header 'Content-Type: application/json' \
  --data '{
	"description": "Create a new account with subscriptions",
	"account_data": {
		"name": "ABCD Account",
		"currency": "USD",
		"bill_to": {
			"first_name": "Amy",
			"last_name": "Lawrence",
			"address": {
				"line1": "101 Redwood Shores Parkway",
				"line2": "",
				"city": "Redwood City",
				"state": "California",
				"country": "USA",
				"postal_code": "94064"
			},
			"work_phone": "(888) 976-9056",
			"work_email": "amy.lawrence@zuora.com"
		},
		"payment_method": {
			"type": "card",
			"billing_details": {
				"name": "John Doe"
			},
			"card": {
				"card_number": "41111111111",
				"brand": "visa",
				"expiry_month": 11,
				"expiry_year": 2023,
				"security_code": "123"
			}
		}
	},
	"order_date": "2023-01-01",
	"subscriptions": [
		{
			"initial_term": {
				"interval_count": 1,
				"interval": "year",
				"type": "termed"
			},
			"renewal_term": {
				"type": "evergreen"
			},
			"start_on": {
				"contract_effective": "2023-01-01"
			},
			"subscription_plans": [
			{
				"plan_id": "8ad09fc2843cc2fb01843f4504b761af",
                "prices": [
                {
                    "price_id": "8ad0887e850fc589018512981a1b4acb",
                    "quantity": 20,
                    "start_date": "2023-01-01",
                    "end_date": "2023-12-31"        
                    },
                {
                    "price_id": "8ad0877b84ade9350184af7ccff43ad2",
                    "quantity": 5,
                    "start_date": "2023-02-15",
                    "end_date": "2023-06-15"
                }
                ]
		    }				
	        ]
		},
		{
			"initial_term": {
				"interval_count": 3,
				"interval": "year",
				"type": "termed"
			},
			"renewal_term": {
				"type": "evergreen"
			},
			"start_on": {
				"contract_effective": "2023-01-01"
			},
			"subscription_plans": [
				{
				   "plan_id": "8ad0877b84f775280184f8047ab011e9",
                    "prices": [
                    {
                        "price_id": "8ad09bce84f7896b0184f80caa622518",
                        "start_date": "2023-01-01"       
                    }
				    ]
				}				
			]
		}
	]
}'
Copy
Copied
//Declare dates to be used in requests
LocalDate orderDate = LocalDate.of(2023,1,1);
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);

// First subscription request
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 subscriptionPlanRequest1 = new SubscriptionPlanCreateRequest()
    .planId("8ad09fc2843cc2fb01843f4504b761af")
    .prices(prices);


PostSubscriptionOrderRequest subscriptionRequest1 = new PostSubscriptionOrderRequest()
    .initialTerm(new Term().interval(Term.IntervalEnum.YEAR).intervalCount(1).type(Term.TypeEnum.TERMED))
    .renewalTerm(new Term().type(Term.TypeEnum.EVERGREEN))
    .putCustomFieldsItem("TestSubscriptionRequired__c", "testValue")
    .startOn(new StartOn().contractEffective(startDate1))
    .subscriptionPlans(Collections.singletonList(subscriptionPlanRequest1));

// Second subscription request
SubscriptionItemCreateRequest subscriptionItemCreateRequest3 = new SubscriptionItemCreateRequest()
    .priceId("8ad09bce84f7896b0184f80caa622518")
    .startDate(startDate1);

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

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

ArrayList multiSubscriptions = new ArrayList();
multiSubscriptions.add(subscriptionRequest1);
multiSubscriptions.add(subscriptionRequest2);

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

AccountPaymentMethodRequest paymentMethodRequest = new AccountPaymentMethodRequest()
    .type(AccountPaymentMethodRequest.TypeEnum.CARD)
    .billingDetails(new BillingDetails().name("John Doe"))
    .card(new Card()
            .cardNumber("41111111111")
            .brand(Card.BrandEnum.VISA)
            .expiryMonth(new BigDecimal(11))
            .expiryYear(new BigDecimal(2025))
            .securityCode("123"));


AccountCreateRequest accountCreateRequest = new AccountCreateRequest()
    .name("ABCD Account")
    .billTo(contactCreateRequest)
    .currency("USD")                    
    .paymentMethod(paymentMethodRequest);

// Create an order request

OrderCreateRequest orderCreateRequest = new OrderCreateRequest()
    .accountData(accountCreateRequest)
    .description("Create a new account with subscriptions")
    .orderDate(orderDate)
    .subscriptions(multiSubscriptions);

// Create an order
Order order = zuoraClient.orders().createOrder(orderCreateRequest);
Copy
Copied
// New account information
const billToContact = {
   first_name: 'Amy',
   last_name: 'Lawrence',
   email: 'amy.lawrence@zuora.com',
   address:{
       line1: '123 ABC Street',
       city: 'San Francisco',
       state: 'California',
       country: 'United States',
   }
};

const account = {
    bill_to: billToContact,
    name: 'Amy Lawrence account',
    currency: 'USD',
};
 
// First subscription request
const subscriptionPlan1 = [{
    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: '2023-01-15',
        end_date: '2023-06-15',
    },
    ]
}];

const subscriptionRequest1 = {
    initial_term: {
        interval_count:1,
        interval: 'year',
        type: 'termed',
    },
    renewal_term:{
        type: 'evergreen',
    },
    subscription_plans: subscriptionPlan1,
    start_on:{
        contract_effective: "2023-01-01",
    },
};

//Second subscription request
const subscriptionPlan2 = [{
    plan_id: '8ad09fc2843cc2fb01843f4504b761af',
    prices: [
    {
        price_id: '8ad0887e850fc589018512981a1b4acb',
        start_date: '2023-01-01',       
    },
    ]
}];

const subscriptionRequest2 = {
    initial_term: {
        interval_count:1,
        interval: 'year',
        type: 'termed',
    },
    renewal_term:{
        type: 'evergreen',
    },
    subscription_plans: subscriptionPlans2,
    start_on:{
        contract_effective: "2023-01-01",
    },
};

// Order request
const orderRequest = {
    description: 'Description of a new order',
    account_data: account,
    order_date: '2023-01-01',
    subscriptions: [subscriptionRequest1, subscriptionRequest2],
};
// Create an order
const createdOrder = await zuoraClient.orders.createOrder(orderRequest);

Example: Make multiple changes to a subscription on an existing account

You can use one or multiple of the following fields to update subscriptions:

  • To add subscription plans to a subscription, specify add_subscription_plans.
  • To remove subscription plans from a subscription, specify remove_subscription_plans.
  • To update subscription plans from a subscription such as changing quantity, price, or other information, specify update_subscription_plans.
  • To renew a subscription, specify renew.
  • To cancel a subscription, specify cancel.
  • To pause a subscription, specify pause.
  • To resume a paused subscription, specify resume.

Sample use case

Suppose that your company offers movie streaming service. One of your plan is the Unlimited plan: it used to be 18 USD per month per license. On 2023-01-01, this price is increased to 20 USD.

In addition, from 2023-01-01, you start to offer an add-on product - subscribers can pay 10 USD to get an exclusive movie poster delivered to subscribers’ homes each month.

One of your customers (account_number=RC-00020939) has created a subscription (subscription_number= A-S00013623) to your Unlimited plan since last September. On 2023-01-01, the original subscription needs to be updated because the unit price (unit_price) is changed. Also, they want to subscribe to the add-on product (plan_id=8ad095dd84eac7940184f3a4aca90b80 and price_id =8ad09bce84eac7860184f3a55a6f347e).

Code examples

cURLJavaNode
Copy
Copied
curl --request POST \
  --url https://rest.test.zuora.com/v2/orders \
  --header 'Authorization: Bearer 7ec1695d1f3c45e89ea5752b2020f54e' \
  --header 'Content-Type: application/json' \
  --data '{
	"description": "Create an order to make multiple changes to the subscription",
	"account_number": "RC-00020939",
	"order_date": "2023-01-01",
	"subscriptions": [
	{
        "subscription_number": "A-S00013623",
        "update_subscription_plans": [{
            "subscription_plan": {
                "subscription_plan_id": "8ad08d29857fc0ec018582b039f248ea",
                "subscription_items": [{
                    "subscription_item_number": "C-00048867",
                    "unit_amount": 20
                }]
			}
		}
		],
        "add_subscription_plans": [{
            "subscription_plan": {
                "plan_id": "8ad095dd84eac7940184f3a4aca90b80",
                "prices": [{
                    "price_id": "8ad09bce84eac7860184f3a55a6f347e"
                }]
            }
        }]
	}
	]
}'
Copy
Copied
LocalDate orderDate = LocalDate.of(2023,1,1);

// Add subscription plan request payload

SubscriptionItemCreateRequest addedPrice = new SubscriptionItemCreateRequest()
    .priceId("8ad09bce84eac7860184f3a55a6f347e");

SubscriptionPlanCreateRequest newSubscriptionPlan = new SubscriptionPlanCreateRequest()
    .planId("8ad095dd84eac7940184f3a4aca90b80")
    .prices(Collections.singletonList(addedPrice));

SubscriptionAddPlanPatchRequest addedSubscriptionPlanRequest = new SubscriptionAddPlanPatchRequest()
    .subscriptionPlan(newSubscriptionPlan);

// Update subscription plan request payload

SubscriptionItemPatchRequest updatedPrice = new SubscriptionItemPatchRequest()
    .subscriptionItemNumber("C-00048867")
    .unitAmount(new BigDecimal(20));

SubscriptionPlanPatchRequest updatedSubscriptionPlan = new SubscriptionPlanPatchRequest()
    .subscriptionPlanId("8ad095dd84eac7940184f3a4aca90b80")
    .subscriptionItems(Collections.singletonList(updatedPrice));

SubscriptionUpdatePlanPatchRequest updatedSubscriptionPlanRequest = new SubscriptionUpdatePlanPatchRequest()
    .subscriptionPlan(updatedSubscriptionPlan);

PostSubscriptionOrderRequest multiActionSubscriptionRequest = new PostSubscriptionOrderRequest()
    .subscriptionNumber("A-S00013623")
    .updateSubscriptionPlans(Collections.singletonList(updatedSubscriptionPlanRequest))
    .addSubscriptionPlans(Collections.singletonList(addedSubscriptionPlanRequest));

// Create an order request payload
OrderCreateRequest orderCreateRequest = new OrderCreateRequest()
    .accountNumber("RC-00020939")
    .description("Create an order to make multiple changes to the subscription")
    .orderDate(orderDate)
    .subscriptions(Collections.singletonList(multiActionSubscriptionRequest));

// Create an order
Order order = zuoraClient.orders().createOrder(orderCreateRequest);
Copy
Copied
const addSubscriptionPlanRequest = {
    subscription_plan: {
        plan_id: '8ad095dd84eac7940184f3a4aca90b80',
        prices: [
        {
            price_id: '8ad09bce84eac7860184f3a55a6f347e', 
        }
        ]
    }
};
const updateSubscriptionPlanRequest = {
    subscription_plan: {
        subscription_plan_id: '8ad08d29857fc0ec018582b039f248ea',
        subscription_items: [
        {  
            subscription_item_number: 'C-00048867',
            unit_amount: 90, 
        }
        ]
    }
};
 
const subscriptionRequest = {
    subscription_number: 'A-S00013623',
    update_subscription_plans: [updateSubscriptionPlanRequest],
    add_subscription_plans: [addSubscriptionPlanRequest],
};
 
const orderRequest = {
    description: 'Create an order to make multiple changes to the subscription',
    account_number: 'RC-00020939',
    order_date: '2023-01-01',
    subscriptions: [subscriptionRequest],
};
 
const createdOrder = await zuoraClient.orders.createOrder(orderRequest);

Example: Create a new subscription with an order line item for an existing account

To create a new subscription with an order line item for an existing account, you must specify the following fields in the request payload:

  • account_number
  • line_items
    • type
    • name
  • subscription
    • initial_term
    • renewal_term
    • start_on > contract_effective
    • subscription_plans

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)

If end subscribers want to subscribe to the Premium, they also need to pay a one-off setup fee which charges 10 USD for each license.

One of your subscribers purchases 20 licenses for the Basic version price and 5 licenses for the Enhanced version for 4 months. The initial term is 1 year starting from 2023-01-01, and it will become evergreen upon renewal.

Code examples

cURLJavaNode
Copy
Copied
curl --request POST \
  --url https://rest.test.zuora.com/v2/orders \
  --header 'Authorization: Bearer 9439d1f00b804505abb69bab70c4dcc7' \
  --header 'Content-Type: application/json' \
  --data '{
	"description": "Create a new subscription with an order line item",
	"account_number":"RC-00020939",
	"order_date": "2023-01-01",
    "line_items": [
        {
        "name": "Setup fee",
        "type": "fee",
        "unit_amount": 10,
        "quantity": 5,
        "start_date": "2023-01-01"
        }
    ],
	"subscriptions": [
		{
			"initial_term": {
				"interval_count": 1,
				"interval": "year",
				"type": "termed"
			},
			"renewal_term": {
				"type": "evergreen"
			},
			"start_on": {
				"contract_effective": "2022-01-01"
			},
			"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": "2023-02-15",
                        "end_date": "2023-06-15"
                    }
                    ]
                }				
            ]
		}
	]
}'
Copy
Copied
LocalDate orderDate = LocalDate.of(2023,1,1);
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);

// First 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.YEAR)
            .intervalCount(1)
            .type(Term.TypeEnum.TERMED))
    .renewalTerm(new Term().type(Term.TypeEnum.EVERGREEN))
    .startOn(new StartOn().contractEffective(startDate1))
    .subscriptionPlans(Collections.singletonList(subscriptionPlanRequest));

// OLI request payload

LineItemCreateRequest newOliRequest = new LineItemCreateRequest()
    .name("Setup Fee")
    .type(LineItemCreateRequest.TypeEnum.FEE)
    .unitAmount(new BigDecimal(10))
    .quantity(new BigDecimal(5))
    .startDate(orderDate);

//Create an order request payload
OrderCreateRequest orderCreateRequest = new OrderCreateRequest()
    .description("Create a new subscription with an order line item")
    .orderDate(orderDate)
    .accountNumber("RC-00020939")
    .lineItems(Collections.singletonList(newOliRequest))
    .subscriptions(Collections.singletonList(newSubscriptionRequest));

// Create an order
Order order = zuoraClient.orders().createOrder(orderCreateRequest);
Copy
Copied
const subscriptionPlans = [{
    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 oli = {
    name: 'Setup fee',
    type: 'fee',
    unit_amount: 10,
    quantity: 5,
    start_date: '2023-01-01',
};
 
const subscriptionRequest = {
    initial_term: {
        interval_count:1,
        interval: 'year',
        type: 'termed',
    },
    renewal_term:{
        type: 'evergreen',
    },
    subscription_plans: subscriptionPlans,
    start_on:{
        contract_effective: "2023-01-01",
    }
};
 
const orderRequest = {
    description: 'Create an order with a recurring item and an order line item',
    account_number: 'RC-00020939',
    order_date: '2023-01-01',
    line_items: [oli],
    subscriptions: [subscriptionRequest],
};
 
const createdOrder = await zuoraClient.orders.createOrder(orderRequest);

Retrieve an order

The Retrieve an order operation retrieves the detailed information about a specific order.

Sample use case

Your customers want to view the detailed information of their changes in an order (order_number=O-00021614), you can use the "Retrieve an order" operation to return the details.

Code examples

cURLJavaNode
Copy
Copied
curl --request GET \
     --url https://rest.test.zuora.com/v2/orders/O-00021614 \
     --header 'Authorization: Bearer 210901c2dd6c4c748a09e3a0fcaee12f' \
     --header 'Content-Type: application/json'
Copy
Copied
Order orderResponse = zuoraClient.orders().getOrder("O-00021614");
System.out.println(orderResponse.toString());
Copy
Copied
const getOrderResponse = await zuoraClient.orders.getOrder('O-00021614');
console.log(getOrderResponse);

Then you can get the following sample response:

Copy
Copied
{
	"id": "8ad09e20858682bc01859fd1633a1de3",
	"updated_by_id": "8ad09bce80507dab0180688bdabc20cb",
	"updated_time": "2023-01-10T23:52:58-08:00",
	"created_by_id": "8ad09bce80507dab0180688bdabc20cb",
	"created_time": "2023-01-10T23:52:57-08:00",
	"category": null,
	"description": "description of a new account",
	"order_date": "2023-01-01",
	"order_number": "O-00021630",
	"line_items": [],
	"subscriptions": [
		{
			"id": "8ad09e20858682bc01859fd164471dea",
			"updated_by_id": "8ad09bce80507dab0180688bdabc20cb",
			"updated_time": "2023-01-10T23:52:58-08:00",
			"created_by_id": "8ad09bce80507dab0180688bdabc20cb",
			"created_time": "2023-01-10T23:52:58-08:00",
			"subscription_number": "A-S00013655",
			"state": "active",
			"account_id": "8ad09b21858682bc01859f0a6de91594",
			"invoice_owner_account_id": "8ad09b21858682bc01859f0a6de91594",
			"auto_renew": false,
			"latest_version": true,
			"initial_term": {
				"type": "termed",
				"interval_count": 1,
				"interval": "year"
			},
			"current_term": {
				"type": "termed",
				"start_date": "2022-01-01",
				"end_date": "2023-01-01",
				"interval_count": 1,
				"interval": "year"
			},
			"renewal_term": {
				"type": "evergreen"
			},
			"start_date": "2022-01-01",
			"end_date": "2023-01-01",
			"description": "",
			"contract_effective": "2022-01-01",
			"service_activation": "2022-01-01",
			"customer_acceptance": "2022-01-01",
			"invoice_separately": false,
			"version": 1,
			"order_number": "O-00021630",
			"actions": [
				{
					"action_id": "8ad09e20858682bc01859fd1634e1de6",
					"type": "create",
					"sequence": 0,
					"start_on": {
						"contract_effective": "2022-01-01",
						"service_activation": "2022-01-01",
						"customer_acceptance": "2022-01-01"
					},
					"subscription_plans": [
						{
							"id": "8ad09e20858682bc01859fd164c01dff",
							"plan_id": "8ad09fc2843cc2fb01843f4504b761af",
							"unique_token": null,
							"subscription_items": [
								{
									"id": "8ad09e20858682bc01859fd164c01e08",
									"subscription_item_number": "C-00048963",
									"name": "Recurring Yearly Plan 2",
									"description": "Subscription under yearly plan",
									"charged_through_date": "2023-01-01",
									"recurring": {
										"on": "subscription_start_day",
										"alignment_behavior": "none",
										"interval": "year",
										"interval_count": 1,
										"timing": "in_advance",
										"usage": false,
										"duration_interval": "year",
										"duration_interval_count": 1,
										"recurring_on": "subscription_start_day"
									},
									"price_id": "8ad09bce8455cd0c01845e8d3c152199",
									"start_event": "contract_effective",
									"tax_inclusive": false,
									"unit_of_measure": "License",
									"quantity": 1,
									"price_base_interval": "billing_period",
									"created_time": "2023-01-10T23:52:58-08:00",
									"charge_model": "per_unit",
									"charge_type": "recurring",
									"created_by_id": "8ad09bce80507dab0180688bdabc20cb",
									"updated_by_id": "8ad09bce80507dab0180688bdabc20cb",
									"updated_time": "2023-01-10T23:52:58-08:00",
									"subscription_plan_id": "8ad09e20858682bc01859fd164c01dff",
									"start_date": "2022-01-01",
									"end_date": "2023-01-01",
									"processed_through_date": "2022-01-01",
									"active": false,
									"state": "active",
									"unit_amount": 0
								},
								{
									"id": "8ad09e20858682bc01859fd164c01e07",
									"subscription_item_number": "C-00048961",
									"name": "Recurring Yearly Plan 2",
									"description": "Subscription under yearly plan",
									"charged_through_date": "2023-01-01",
									"recurring": {
										"on": "subscription_start_day",
										"alignment_behavior": "none",
										"interval": "year",
										"interval_count": 1,
										"timing": "in_advance",
										"usage": false,
										"duration_interval": "year",
										"duration_interval_count": 1,
										"recurring_on": "subscription_start_day"
									},
									"price_id": "8ad08e0184ade9350184af5bf1f46007",
									"start_event": "contract_effective",
									"tax_inclusive": false,
									"unit_of_measure": "License",
									"quantity": 1,
									"price_base_interval": "billing_period",
									"created_time": "2023-01-10T23:52:58-08:00",
									"charge_model": "per_unit",
									"charge_type": "recurring",
									"created_by_id": "8ad09bce80507dab0180688bdabc20cb",
									"updated_by_id": "8ad09bce80507dab0180688bdabc20cb",
									"updated_time": "2023-01-10T23:52:58-08:00",
									"subscription_plan_id": "8ad09e20858682bc01859fd164c01dff",
									"custom_fields": {
										"Price__c": "0"
									},
									"start_date": "2022-01-01",
									"end_date": "2023-01-01",
									"processed_through_date": "2022-01-01",
									"active": false,
									"state": "active",
									"unit_amount": 150
								}
                            ]
						}
					]
				}
			]
		}
	]
}