Orders basics for developers

Why Orders matters? In Zuora, nearly every monetizable event such as sign‑ups, upsells, and renewals, ultimately routes through a single call: Create an order(POST /v1/orders). Master this call and you will control account creation, subscription lifecycles, and revenue recognition with one payload instead of stitching together multiple endpoints. Order’s atomic payload feature captures not just the order, but also allows you to:

• Create the billing account for a net new sign-up or use an existing account.
• Capture physical goods' orders, on their own or in combination with recurring subscription of services that utilize those items.
• Optionally modify pricing or discounting unique for this order.
• Optionally invoice and collect payment immediately.
• Preview an order so you can present the exact pricing, including taxation, to a prospect or customer prior to purchase.

We have a more extensive treatment of our object model, but essentials include:

• An order must either create a new billing account OR specify an existing billing account.
• An order captures products and services along with pricing and quantities, requested by a customer. It can happen not only at the start of their contract, but orders capture all changes to a customer's portfolio of products and services.
• Orders consist of either:
  • Order line items for physical goods, or
  • Order actions for recurring subscription products or services, or
  • A combination of both.
• Order actions that either allow you to add, remove, change quantity or pricing for the products or services on a subscription, OR allow you to suspend, resume, renew, change the owner of, change the terms and conditions, or cancel that subscription.

The first Orders API tutorial, Create subscriptions, focuses on examples of creating subscriptions using orders. The second tutorial gives examples of post-creation options in the subscription lifecycle. The Create an order(POST /v1/orders) call has links to examples of every order action.

If you're doing data migrations, don't miss the Create an order asynchronously options.

The following diagram shows how product catalog items are invoked in the orders call. Copies are made specifically for the affected subscription so you can overwrite and capture order-specific quantities and pricing:

The diagram for physical goods orders is similar but slightly simpler as there's no requirement to have a subscription to capture the time-based contractural information:

The POST v1/orders request payload can be tricky to read, understand, and construct. The following diagram decomposes the payload and might help you understand how this call works: