Skip to content
/Orders

Quickstart API Reference (2025-11-12)

Zuora's Quickstart API represents a simplified programmatic experience with coverage for common eCommerce use cases only. Quickstart is NOT a replacement of the v1 API.

If you are starting new development, we recommend you use the v1 API for all your use cases. New features are only available in the v1 API. We no longer recommend Quickstart for new eCommerce development. We are not deprecating the Quickstart API and will continue to fix bugs, but we will not accept enhancement requests for the Quickstart API.

To use the Quickstart API, you must have the following features enabled on your tenant:

To find the latest changes made to the Zuora Quickstart API, check the Quickstart API Changelog.

Download OpenAPI description
index.json
index.yaml
Languages
Servers
Mock server
https://developer.zuora.com/_mock/other-api/quickstart-api
US Developer & Central Sandbox (incl. Test Drive)
https://rest.test.zuora.com/v2
US API Sandbox Cloud 1
https://rest.sandbox.na.zuora.com/v2
US API Sandbox Cloud 2
https://rest.apisandbox.zuora.com/v2
US Production Cloud 1
https://rest.na.zuora.com/v2
US Production Cloud 2
https://rest.zuora.com/v2
EU Developer & Central Sandbox
https://rest.test.eu.zuora.com/v2
EU API Sandbox
https://rest.sandbox.eu.zuora.com/v2
EU Production
https://rest.eu.zuora.com/v2
APAC Developer & Central Sandbox
https://rest.test.ap.zuora.com/v2
APAC Production
https://rest.ap.zuora.com/v2

Products

Products describe the specific goods or services you offer to your customers and help you track inventory or provisioning. They should be used in conjunction with Plans and Prices to configure pricing.

Operations

Plans

Plans are collections of Prices which define the unit cost, currency, and (optional) billing cycle for both recurring and one-time purchases of Products. While Products help you track inventory or provisioning, plans and prices help you track payment terms. Different physical goods or levels of service should be represented by products, and pricing and billing cycle options should be represented by prices grouped together in a plan. This approach lets you change prices without having to change your provisioning scheme. For example, you might have a single ''Gold'' product that has prices for $100/month, $1000/year, and $50 once with the alternative billing cycle and pricing options each represented by a different plan and the recurring and one-time prices represented by different prices.

Operations

Prices

Prices define the unit cost, currency, and (optional) billing cycle for both recurring and one-time purchases of products. Products help you track inventory or provisioning, and plans and prices help you track payment terms. Different physical goods or levels of service should be represented by products, and pricing options should be represented by prices. This approach lets you change prices without having to change your provisioning scheme. For example, you might have a single ''Gold'' product that has prices for $100/month, $1000/year, and $50 once.

Operations

Accounts

This object represents your customer. It lets you create recurring charges and track payments that belong to the same customer.

Operations

Contacts

Contacts represent your customer's contact details.

Operations

Orders

The Orders operations enable you to create or make modifications to subscriptions in a batch.

Operations

List orders

Request

Lists all or a subset of orders in your tenant.

Security
bearerAuth
Query
cursorstring

A cursor for use in pagination. A cursor defines the starting place in a list. For instance, if you make a list request and receive 100 objects, ending with next_page=W3sib3JkZXJ=, your subsequent call can include cursor=W3sib3JkZXJ= in order to fetch the next page of the list.

expand[]Array of strings

Allows you to expand responses by including related object information in a single call. See the Expand responses section of the Quickstart API Tutorials for detailed instructions.

filter[]Array of strings

A case-sensitive filter on the list. See the Filter lists section of the Quickstart API Tutorials for detailed instructions.

sort[]Array of strings

A case-sensitive query parameter that specifies the sort order of the list, which can be either ascending (e.g. account_number.asc) or descending (e.g. account_number.desc). You cannot sort on properties that are arrays. If the array-type properties are specified for the sort[] parameter, they are ignored.

page_sizeinteger[ 1 .. 99 ]

The maximum number of results to return in a single page. If the specified page_size is less than 1 or greater than 99, Zuora will return a 400 error.

Default 30
fields[]Array of strings

Allows you to specify which fields are returned in the response.

Accepted values `custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `order_number`, `order_date`, `state`, `category`, `description`, `scheduled_date`, `scheduled_date_policy`, `line_items`, `subscriptions`
Example: fields[]=id,created_time
order_actions.fields[]Array of strings

Allows you to specify which fields are returned in the response.

Accepted values `type`, `action_id`, `sequence`, `start_on`, `subscription_plans`, `renew`, `terms`, `cancel`, `pause`, `resume`, `order`
Example: order_actions.fields[]=id,created_time
subscriptions.fields[]Array of strings

Allows you to specify which fields are returned in the response.

Accepted values `custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `subscription_number`, `state`, `account_id`, `invoice_owner_account_id`, `auto_renew`, `version`, `initial_term`, `current_term`, `renewal_term`, `start_date`, `end_date`, `description`, `contract_effective`, `service_activation`, `customer_acceptance`, `invoice_separately`, `latest_version`, `payment_terms`, `billing_document_settings`, `bill_to_id`, `sold_to_id`, `contracted_mrr`, `currency`, `cancel_reason`, `last_booking_date`, `actions`
Example: subscriptions.fields[]=id,created_time
line_items.fields[]Array of strings

Allows you to specify which fields are returned in the response.

Accepted values `custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `total`, `subtotal`, `quantity_fulfilled`, `quantity_pending_fulfillment`, `unit_of_measure`, `accounting_code`, `adjustment_liability_account`, `unit_amount`, `target_date`, `billing_rule`, `contract_asset_account`, `contract_liability_account`, `description`, `discount_total`, `revenue`, `discount_unit_amount`, `discount_percent`, `category`, `name`, `item_number`, `type`, `list_price`, `list_unit_price`, `original_order_date`, `original_order_id`, `original_order_line_item_id`, `original_order_line_item_number`, `original_order_number`, `product_code`, `price_id`, `purchase_order_number`, `quantity`, `quantity_available_for_return`, `related_subscription_number`, `requires_fulfillment`, `sold_to_id`, `original_sold_to_id`, `tax_code`, `tax_inclusive`, `end_date`, `start_date`, `unbilled_receivables_account`, `state`, `order_id`
Example: line_items.fields[]=id,created_time
subscription_plans.fields[]Array of strings

Allows you to specify which fields are returned in the response.

Accepted values `custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `name`, `plan_id`, `subscription_id`, `product_id`, `subscription_plan_number`, `subscription_items`
Example: subscription_plans.fields[]=id,created_time
subscription_items.fields[]Array of strings

Allows you to specify which fields are returned in the response.

Accepted values `custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `charge_model`, `charge_type`, `tiers`, `subscription_item_number`, `name`, `description`, `charged_through_date`, `recurring`, `price_id`, `start_event`, `tax_code`, `tax_inclusive`, `unit_of_measure`, `quantity`, `price_base_interval`, `overage`, `subscription_plan_id`, `tiers_mode`, `processed_through_date`, `active`, `state`, `unit_amount`, `amount`, `discount_amount`, `discount_percent`, `price_change_percentage`, `price_change_option`
Example: subscription_items.fields[]=id,created_time
invoice_items.fields[]Array of strings

Allows you to specify which fields are returned in the response.

Accepted values `custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `booking_reference`, `applied_to_item_id`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `invoice_id`, `sku`, `name`, `purchase_order_number`, `quantity`, `recognized_revenue_account`, `remaining_balance`, `revenue_recognition_rule_name`, `accounting_code`, `service_end`, `service_start`, `accounts_receivable_account`, `subscription_id`, `subscription_item_id`, `tax`, `tax_code`, `tax_inclusive`, `unit_amount`, `unit_of_measure`, `document_item_date`
Example: invoice_items.fields[]=id,created_time
order.fields[]Array of stringsDeprecated

Allows you to specify which fields are returned in the response.

Accepted values `custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `order_number`, `order_date`, `state`, `category`, `description`, `scheduled_date`, `scheduled_date_policy`, `line_items`, `subscriptions`
Example: order.fields[]=id,created_time
Headers
zuora-track-idstring

A custom identifier for tracking API requests. If you set a value for this header, Zuora returns the same value in the response header. This header enables you to track your 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 ("), or quote (').

asyncboolean

Making asynchronous requests allows you to scale your applications more efficiently by leveraging Zuora's infrastructure to enqueue and execute requests for you without blocking. These requests also use built-in retry semantics, which makes them much less likely to fail for non-deterministic reasons, even in extreme high-throughput scenarios. Meanwhile, when you send a request to one of these endpoints, you can expect to receive a response in less than 150 milliseconds and these calls are unlikely to trigger rate limit errors. If set to true, Zuora returns a 202 Accepted response, and the response body contains only a request ID.

Default false
zuora-entity-idsstring

An entity ID. If you have Multi-entity enabled and the authorization token is valid for more than one entity, you must use this header to specify which entity to perform the operation on. If the authorization token is only valid for a single entity or you do not have Multi-entity enabled, you do not need to set this header.

idempotency-keystring

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. This idempotency key should be a unique value, and the Zuora server identifies subsequent retries of the same request using this value. For more information, see Idempotent Requests.

accept-encodingstring

Include a accept-encoding: gzip header to compress responses, which can reduce the bandwidth required for a response. If specified, Zuora automatically compresses responses that contain over 1000 bytes. For more information about this header, see Request and Response Compression.

content-encodingstring

Include a content-encoding: gzip header to compress a request. Upload a gzipped file for the payload if you specify this header. For more information, see Request and Response Compression.

zuora-org-idsstring

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.

curl -i -X GET \
  'https://developer.zuora.com/_mock/other-api/quickstart-api/orders?cursor=string&expand%5B%5D=string&filter%5B%5D=string&sort%5B%5D=string&page_size=30&fields%5B%5D=id%2Ccreated_time&order_actions.fields%5B%5D=id%2Ccreated_time&subscriptions.fields%5B%5D=id%2Ccreated_time&line_items.fields%5B%5D=id%2Ccreated_time&subscription_plans.fields%5B%5D=id%2Ccreated_time&subscription_items.fields%5B%5D=id%2Ccreated_time&invoice_items.fields%5B%5D=id%2Ccreated_time&order.fields%5B%5D=id%2Ccreated_time' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'accept-encoding: string' \
  -H 'async: false' \
  -H 'content-encoding: string' \
  -H 'idempotency-key: string' \
  -H 'zuora-entity-ids: string' \
  -H 'zuora-org-ids: string' \
  -H 'zuora-track-id: string'

Responses

Default Response

Headers
ratelimit-limitstring

The request limit quota for the time window closest to exhaustion. See rate limits for more information.

ratelimit-remainingnumber

The number of requests remaining in the time window closest to quota exhaustion. See rate limits for more information.

ratelimit-resetnumber

The number of seconds until the quota resets for the time window closest to quota exhaustion. See rate limits for more information.

zuora-request-idstring

Zuora’s internal identifier for this request.

zuora-track-idstring

A user-supplied identifier for this request. If you supply a zuora-track-id as a request header, Zuora returns the zuora-track-id as a response header.

Bodyapplication/json
next_pagestring or null
dataArray of objects(Order)
Response
application/json
{
  "next_page": "W3sib3JkZXJCeSI6eyJmaWVsZCI6IlVwZGF0ZWREYXRlIiwib3JkZXIiOiJERVNDIn0sInZhbHVlIjoiMjAyMi0xMi0yMFQxMjoyODo1NC0wODowMCJ9LHsib3JkZXJCeSI6eyJmaWVsZCI6IklkIiwib3JkZXIiOiJERVNDIn0sInZhbHVlIjoiMmM5MmMwZjk2YWJjMTdkZTAxNmFiZDYyYmQwYzU4NTQifV0=",
  "data": [
    { … },
    { … }
  ]
}

Create an order

Request

You can use this operation to create subscriptions and make changes to existing subscriptions. You can also use this operation to create order line items.

Note that the following limitations apply to this operation:

  • Up to 50 subscriptions are allowed in a single call.
  • Up to 100 order line items are allowed in an order.
  • Up to 1000 orders are allowed on a subscription.

Security
bearerAuth
Query
fields[]Array of strings

Allows you to specify which fields are returned in the response.

Accepted values `custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `order_number`, `order_date`, `state`, `category`, `description`, `scheduled_date`, `scheduled_date_policy`, `line_items`, `subscriptions`
Example: fields[]=id,created_time
order_actions.fields[]Array of strings

Allows you to specify which fields are returned in the response.

Accepted values `type`, `action_id`, `sequence`, `start_on`, `subscription_plans`, `renew`, `terms`, `cancel`, `pause`, `resume`, `order`
Example: order_actions.fields[]=id,created_time
subscriptions.fields[]Array of strings

Allows you to specify which fields are returned in the response.

Accepted values `custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `subscription_number`, `state`, `account_id`, `invoice_owner_account_id`, `auto_renew`, `version`, `initial_term`, `current_term`, `renewal_term`, `start_date`, `end_date`, `description`, `contract_effective`, `service_activation`, `customer_acceptance`, `invoice_separately`, `latest_version`, `payment_terms`, `billing_document_settings`, `bill_to_id`, `sold_to_id`, `contracted_mrr`, `currency`, `cancel_reason`, `last_booking_date`, `actions`
Example: subscriptions.fields[]=id,created_time
line_items.fields[]Array of strings

Allows you to specify which fields are returned in the response.

Accepted values `custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `total`, `subtotal`, `quantity_fulfilled`, `quantity_pending_fulfillment`, `unit_of_measure`, `accounting_code`, `adjustment_liability_account`, `unit_amount`, `target_date`, `billing_rule`, `contract_asset_account`, `contract_liability_account`, `description`, `discount_total`, `revenue`, `discount_unit_amount`, `discount_percent`, `category`, `name`, `item_number`, `type`, `list_price`, `list_unit_price`, `original_order_date`, `original_order_id`, `original_order_line_item_id`, `original_order_line_item_number`, `original_order_number`, `product_code`, `price_id`, `purchase_order_number`, `quantity`, `quantity_available_for_return`, `related_subscription_number`, `requires_fulfillment`, `sold_to_id`, `original_sold_to_id`, `tax_code`, `tax_inclusive`, `end_date`, `start_date`, `unbilled_receivables_account`, `state`, `order_id`
Example: line_items.fields[]=id,created_time
subscription_plans.fields[]Array of strings

Allows you to specify which fields are returned in the response.

Accepted values `custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `name`, `plan_id`, `subscription_id`, `product_id`, `subscription_plan_number`, `subscription_items`
Example: subscription_plans.fields[]=id,created_time
subscription_items.fields[]Array of strings

Allows you to specify which fields are returned in the response.

Accepted values `custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `charge_model`, `charge_type`, `tiers`, `subscription_item_number`, `name`, `description`, `charged_through_date`, `recurring`, `price_id`, `start_event`, `tax_code`, `tax_inclusive`, `unit_of_measure`, `quantity`, `price_base_interval`, `overage`, `subscription_plan_id`, `tiers_mode`, `processed_through_date`, `active`, `state`, `unit_amount`, `amount`, `discount_amount`, `discount_percent`, `price_change_percentage`, `price_change_option`
Example: subscription_items.fields[]=id,created_time
invoice_items.fields[]Array of strings

Allows you to specify which fields are returned in the response.

Accepted values `custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `booking_reference`, `applied_to_item_id`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `invoice_id`, `sku`, `name`, `purchase_order_number`, `quantity`, `recognized_revenue_account`, `remaining_balance`, `revenue_recognition_rule_name`, `accounting_code`, `service_end`, `service_start`, `accounts_receivable_account`, `subscription_id`, `subscription_item_id`, `tax`, `tax_code`, `tax_inclusive`, `unit_amount`, `unit_of_measure`, `document_item_date`
Example: invoice_items.fields[]=id,created_time
expand[]Array of strings

Allows you to expand responses by including related object information in a single call. See the Expand responses section of the Quickstart API Tutorials for detailed instructions.

filter[]Array of strings

A case-sensitive filter on the list. See the Filter lists section of the Quickstart API Tutorial for detailed instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the filter[] parameter on the related objects such as filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63

page_sizeinteger[ 1 .. 99 ]

The maximum number of results to return in a single page. If the specified page_size is less than 1 or greater than 99, Zuora will return a 400 error.

order.fields[]Array of stringsDeprecated

Allows you to specify which fields are returned in the response.

Accepted values `custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `order_number`, `order_date`, `state`, `category`, `description`, `scheduled_date`, `scheduled_date_policy`, `line_items`, `subscriptions`
Example: order.fields[]=id,created_time
Headers
zuora-track-idstring

A custom identifier for tracking API requests. If you set a value for this header, Zuora returns the same value in the response header. This header enables you to track your 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 ("), or quote (').

asyncboolean

Making asynchronous requests allows you to scale your applications more efficiently by leveraging Zuora's infrastructure to enqueue and execute requests for you without blocking. These requests also use built-in retry semantics, which makes them much less likely to fail for non-deterministic reasons, even in extreme high-throughput scenarios. Meanwhile, when you send a request to one of these endpoints, you can expect to receive a response in less than 150 milliseconds and these calls are unlikely to trigger rate limit errors. If set to true, Zuora returns a 202 Accepted response, and the response body contains only a request ID.

Default false
zuora-entity-idsstring

An entity ID. If you have Multi-entity enabled and the authorization token is valid for more than one entity, you must use this header to specify which entity to perform the operation on. If the authorization token is only valid for a single entity or you do not have Multi-entity enabled, you do not need to set this header.

idempotency-keystring

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. This idempotency key should be a unique value, and the Zuora server identifies subsequent retries of the same request using this value. For more information, see Idempotent Requests.

accept-encodingstring

Include a accept-encoding: gzip header to compress responses, which can reduce the bandwidth required for a response. If specified, Zuora automatically compresses responses that contain over 1000 bytes. For more information about this header, see Request and Response Compression.

content-encodingstring

Include a content-encoding: gzip header to compress a request. Upload a gzipped file for the payload if you specify this header. For more information, see Request and Response Compression.

Bodyapplication/jsonrequired
categorystring

Category of the order to indicate a product sale or return. Default value is sale.

Enum"sale""return"
custom_fieldsobject(CustomFields)

Set of user-defined fields associated with this object. Useful for storing additional information about the object in a structured format.

descriptionstring

An arbitrary string attached to the object. Often useful for displaying to users.

Example: "description of test account"
account_numberstring

Human-readable identifier of the account. It can be user-supplied.

Example: "A-100001"
account_idstring

Identifier of the account.

Example: "2c92c0f86a8dd422016a9e7a70116b0d"
account_dataobject(AccountCreateRequest)

The information of the new account that owns the subscription. The subscription owner account can be different from the invoice owner account. If you specify this field, do not specify account_id.

order_datestring(date)

The date when the order is signed. All the order actions under this order will use this order date as the contract effective date if the contract effective date field is skipped or its value is left as null.

Example: "2022-01-01"
order_numberstring

The order number of the new order. If not provided, system will auto-generate a number for this order. Note: Ensure that the order number does not contain a slash.

line_itemsArray of objects(LineItemCreateRequest)

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. By specifying this field, you can launch non-subscription and unified monetization business models in Zuora, in addition to subscription business models.

processing_optionsobject(OrdersProcessingOption)

Processing options for the invoice or payment.

subscriptionsArray of objects(PostSubscriptionOrderRequest)

Based on the intended order action, each item should include specific fields. For example, to create a new subscription for a new account, you must specify the account_data and subscription_plans fields at a minimum.

scheduling_optionsobject(OrdersSchedulingOptions)
statestring

The status of the order.

Enum"pending""complete""draft""canceled""scheduled""executing""failed"
curl -i -X POST \
  'https://developer.zuora.com/_mock/other-api/quickstart-api/orders?fields%5B%5D=id%2Ccreated_time&order_actions.fields%5B%5D=id%2Ccreated_time&subscriptions.fields%5B%5D=id%2Ccreated_time&line_items.fields%5B%5D=id%2Ccreated_time&subscription_plans.fields%5B%5D=id%2Ccreated_time&subscription_items.fields%5B%5D=id%2Ccreated_time&invoice_items.fields%5B%5D=id%2Ccreated_time&expand%5B%5D=string&filter%5B%5D=string&page_size=1&order.fields%5B%5D=id%2Ccreated_time' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'accept-encoding: string' \
  -H 'async: false' \
  -H 'content-encoding: string' \
  -H 'idempotency-key: string' \
  -H 'zuora-entity-ids: string' \
  -H 'zuora-track-id: string' \
  -d '{
    "description": "Create an new order with a new account",
    "account_data": {
      "name": "Zuora'\''s Order Account",
      "currency": "USD",
      "bill_to": {
        "first_name": "Amy",
        "last_name": "Lawrence",
        "address": {
          "line1": "101 Redwood Shores Parkway",
          "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-01"
              },
              {
                "price_id": "8ad0877b84ade9350184af7ccff43ad2",
                "quantity": 5,
                "start_date": "2023-01-15",
                "end_date": "2023-06-15"
              }
            ]
          }
        ]
      }
    ]
  }'

Responses

Default Response

Headers
ratelimit-limitstring

The request limit quota for the time window closest to exhaustion. See rate limits for more information.

ratelimit-remainingnumber

The number of requests remaining in the time window closest to quota exhaustion. See rate limits for more information.

ratelimit-resetnumber

The number of seconds until the quota resets for the time window closest to quota exhaustion. See rate limits for more information.

zuora-request-idstring

Zuora’s internal identifier for this request.

zuora-track-idstring

A user-supplied identifier for this request. If you supply a zuora-track-id as a request header, Zuora returns the zuora-track-id as a response header.

Bodyapplication/json
idstringread-only

Unique identifier for the object.

updated_by_idstringread-only

Unique identifier of the Zuora user who last updated the object

updated_timestring(date-time)read-only

The date and time when the object was last updated in ISO 8601 UTC format.

created_by_idstringread-only

Unique identifier of the Zuora user who created the object

created_timestring(date-time)read-only

The date and time when the object was created in ISO 8601 UTC format.

custom_fieldsobject(CustomFields)

Set of user-defined fields associated with this object. Useful for storing additional information about the object in a structured format.

custom_objectsobjectread-only

The custom objects associated with a Zuora standard object.

order_numberstring

The order number of the new order. If not provided, system will auto-generate a number for this order. Note: Ensure that the order number does not contain a slash.

order_datestring(date)

The date when the order is signed. All the order actions under this order will use this order date as the contract effective date if the contract effective date field is skipped or its value is left as null.

Example: "2022-01-01"
descriptionstring

An arbitrary string attached to the object. Often useful for displaying to users.

Example: "description of test account"
categorystring

Category of the order to indicate a product sale or return. Default value is sale.

Enum"sale""return"
account_idstring

Identifier of the account associated with this subscription.

accountobject(Account)

Information of the new account associated with the subscription.

line_itemsobject(LineItemListResponse)
ar_transactionsobject(ArTransactionsOrders)
subscriptionsArray of objects(PostSubscriptionOrderResponse)

Each item includes specific fields based on the intended order action.

statestring

The status of the order.

Enum"pending""complete""draft""canceled""scheduled""executing""failed"
scheduled_datestring(date)

The date when the order is scheduled to be processed.

scheduled_date_policystring

Date policy of the scheduled order.

Response
application/json
{
  "id": "8ad0934e861a27bd018624b93d2f11d9",
  "order_number": "O-00021762",
  "order_date": "2023-01-01",
  "state": "pending",
  "created_time": "2023-02-05T19:16:04-08:00",
  "created_by_id": "8ad09bce80507dab0180688bdabc20cb",
  "updated_time": "2023-02-05T19:16:05-08:00",
  "updated_by_id": "8ad09bce80507dab0180688bdabc20cb",
  "description": "Create a new subscription with a new account",
  "account_id": "8ad0934e861a27bd018624b93ca211cb",
  "line_items": [],
  "subscriptions": [
    { … }
  ]
}

Retrieve an order

Request

Use this operation to retrieve the detailed information about a specific order.

Security
bearerAuth
Path
order_idstringrequired

Identifier for the order, either order_number or order_id

Query
fields[]Array of strings

Allows you to specify which fields are returned in the response.

Accepted values `custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `order_number`, `order_date`, `state`, `category`, `description`, `scheduled_date`, `scheduled_date_policy`, `line_items`, `subscriptions`
Example: fields[]=id,created_time
order_actions.fields[]Array of strings

Allows you to specify which fields are returned in the response.

Accepted values `type`, `action_id`, `sequence`, `start_on`, `subscription_plans`, `renew`, `terms`, `cancel`, `pause`, `resume`, `order`
Example: order_actions.fields[]=id,created_time
subscriptions.fields[]Array of strings

Allows you to specify which fields are returned in the response.

Accepted values `custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `subscription_number`, `state`, `account_id`, `invoice_owner_account_id`, `auto_renew`, `version`, `initial_term`, `current_term`, `renewal_term`, `start_date`, `end_date`, `description`, `contract_effective`, `service_activation`, `customer_acceptance`, `invoice_separately`, `latest_version`, `payment_terms`, `billing_document_settings`, `bill_to_id`, `sold_to_id`, `contracted_mrr`, `currency`, `cancel_reason`, `last_booking_date`, `actions`
Example: subscriptions.fields[]=id,created_time
line_items.fields[]Array of strings

Allows you to specify which fields are returned in the response.

Accepted values `custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `total`, `subtotal`, `quantity_fulfilled`, `quantity_pending_fulfillment`, `unit_of_measure`, `accounting_code`, `adjustment_liability_account`, `unit_amount`, `target_date`, `billing_rule`, `contract_asset_account`, `contract_liability_account`, `description`, `discount_total`, `revenue`, `discount_unit_amount`, `discount_percent`, `category`, `name`, `item_number`, `type`, `list_price`, `list_unit_price`, `original_order_date`, `original_order_id`, `original_order_line_item_id`, `original_order_line_item_number`, `original_order_number`, `product_code`, `price_id`, `purchase_order_number`, `quantity`, `quantity_available_for_return`, `related_subscription_number`, `requires_fulfillment`, `sold_to_id`, `original_sold_to_id`, `tax_code`, `tax_inclusive`, `end_date`, `start_date`, `unbilled_receivables_account`, `state`, `order_id`
Example: line_items.fields[]=id,created_time
subscription_plans.fields[]Array of strings

Allows you to specify which fields are returned in the response.

Accepted values `custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `name`, `plan_id`, `subscription_id`, `product_id`, `subscription_plan_number`, `subscription_items`
Example: subscription_plans.fields[]=id,created_time
subscription_items.fields[]Array of strings

Allows you to specify which fields are returned in the response.

Accepted values `custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `start_date`, `end_date`, `charge_model`, `charge_type`, `tiers`, `subscription_item_number`, `name`, `description`, `charged_through_date`, `recurring`, `price_id`, `start_event`, `tax_code`, `tax_inclusive`, `unit_of_measure`, `quantity`, `price_base_interval`, `overage`, `subscription_plan_id`, `tiers_mode`, `processed_through_date`, `active`, `state`, `unit_amount`, `amount`, `discount_amount`, `discount_percent`, `price_change_percentage`, `price_change_option`
Example: subscription_items.fields[]=id,created_time
invoice_items.fields[]Array of strings

Allows you to specify which fields are returned in the response.

Accepted values `custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `amount`, `booking_reference`, `applied_to_item_id`, `price_id`, `discount_item`, `deferred_revenue_account`, `description`, `invoice_id`, `sku`, `name`, `purchase_order_number`, `quantity`, `recognized_revenue_account`, `remaining_balance`, `revenue_recognition_rule_name`, `accounting_code`, `service_end`, `service_start`, `accounts_receivable_account`, `subscription_id`, `subscription_item_id`, `tax`, `tax_code`, `tax_inclusive`, `unit_amount`, `unit_of_measure`, `document_item_date`
Example: invoice_items.fields[]=id,created_time
expand[]Array of strings

Allows you to expand responses by including related object information in a single call. See the Expand responses section of the Quickstart API Tutorials for detailed instructions.

filter[]Array of strings

A case-sensitive filter on the list. See the Filter lists section of the Quickstart API Tutorial for detailed instructions.
Note that the filters on this operation are only applicable to the related objects. For example, when you are calling the "Retrieve a billing document" operation, you can use the filter[] parameter on the related objects such as filter[]=items[account_id].EQ:8ad09e208858b5cf0188595208151c63

page_sizeinteger[ 1 .. 99 ]

The maximum number of results to return in a single page. If the specified page_size is less than 1 or greater than 99, Zuora will return a 400 error.

order.fields[]Array of stringsDeprecated

Allows you to specify which fields are returned in the response.

Accepted values `custom_fields`, `created_by_id`, `updated_by_id`, `created_time`, `id`, `updated_time`, `account_id`, `order_number`, `order_date`, `state`, `category`, `description`, `scheduled_date`, `scheduled_date_policy`, `line_items`, `subscriptions`
Example: order.fields[]=id,created_time
Headers
zuora-track-idstring

A custom identifier for tracking API requests. If you set a value for this header, Zuora returns the same value in the response header. This header enables you to track your 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 ("), or quote (').

asyncboolean

Making asynchronous requests allows you to scale your applications more efficiently by leveraging Zuora's infrastructure to enqueue and execute requests for you without blocking. These requests also use built-in retry semantics, which makes them much less likely to fail for non-deterministic reasons, even in extreme high-throughput scenarios. Meanwhile, when you send a request to one of these endpoints, you can expect to receive a response in less than 150 milliseconds and these calls are unlikely to trigger rate limit errors. If set to true, Zuora returns a 202 Accepted response, and the response body contains only a request ID.

Default false
zuora-entity-idsstring

An entity ID. If you have Multi-entity enabled and the authorization token is valid for more than one entity, you must use this header to specify which entity to perform the operation on. If the authorization token is only valid for a single entity or you do not have Multi-entity enabled, you do not need to set this header.

idempotency-keystring

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. This idempotency key should be a unique value, and the Zuora server identifies subsequent retries of the same request using this value. For more information, see Idempotent Requests.

accept-encodingstring

Include a accept-encoding: gzip header to compress responses, which can reduce the bandwidth required for a response. If specified, Zuora automatically compresses responses that contain over 1000 bytes. For more information about this header, see Request and Response Compression.

content-encodingstring

Include a content-encoding: gzip header to compress a request. Upload a gzipped file for the payload if you specify this header. For more information, see Request and Response Compression.

zuora-org-idsstring

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.

curl -i -X GET \
  'https://developer.zuora.com/_mock/other-api/quickstart-api/orders/{order_id}?fields%5B%5D=id%2Ccreated_time&order_actions.fields%5B%5D=id%2Ccreated_time&subscriptions.fields%5B%5D=id%2Ccreated_time&line_items.fields%5B%5D=id%2Ccreated_time&subscription_plans.fields%5B%5D=id%2Ccreated_time&subscription_items.fields%5B%5D=id%2Ccreated_time&invoice_items.fields%5B%5D=id%2Ccreated_time&expand%5B%5D=string&filter%5B%5D=string&page_size=1&order.fields%5B%5D=id%2Ccreated_time' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'accept-encoding: string' \
  -H 'async: false' \
  -H 'content-encoding: string' \
  -H 'idempotency-key: string' \
  -H 'zuora-entity-ids: string' \
  -H 'zuora-org-ids: string' \
  -H 'zuora-track-id: string'

Responses

Default Response

Headers
ratelimit-limitstring

The request limit quota for the time window closest to exhaustion. See rate limits for more information.

ratelimit-remainingnumber

The number of requests remaining in the time window closest to quota exhaustion. See rate limits for more information.

ratelimit-resetnumber

The number of seconds until the quota resets for the time window closest to quota exhaustion. See rate limits for more information.

zuora-request-idstring

Zuora’s internal identifier for this request.

zuora-track-idstring

A user-supplied identifier for this request. If you supply a zuora-track-id as a request header, Zuora returns the zuora-track-id as a response header.

Bodyapplication/json
idstringread-only

Unique identifier for the object.

updated_by_idstringread-only

Unique identifier of the Zuora user who last updated the object

updated_timestring(date-time)read-only

The date and time when the object was last updated in ISO 8601 UTC format.

created_by_idstringread-only

Unique identifier of the Zuora user who created the object

created_timestring(date-time)read-only

The date and time when the object was created in ISO 8601 UTC format.

custom_fieldsobject(CustomFields)

Set of user-defined fields associated with this object. Useful for storing additional information about the object in a structured format.

custom_objectsobjectread-only

The custom objects associated with a Zuora standard object.

order_numberstring

The order number of the new order. If not provided, system will auto-generate a number for this order. Note: Ensure that the order number does not contain a slash.

order_datestring(date)

The date when the order is signed. All the order actions under this order will use this order date as the contract effective date if the contract effective date field is skipped or its value is left as null.

Example: "2022-01-01"
descriptionstring

An arbitrary string attached to the object. Often useful for displaying to users.

Example: "description of test account"
categorystring

Category of the order to indicate a product sale or return. Default value is sale.

Enum"sale""return"
account_idstring

Identifier of the account associated with this subscription.

accountobject(Account)

Information of the new account associated with the subscription.

line_itemsobject(LineItemListResponse)
ar_transactionsobject(ArTransactionsOrders)
subscriptionsArray of objects(PostSubscriptionOrderResponse)

Each item includes specific fields based on the intended order action.

statestring

The status of the order.

Enum"pending""complete""draft""canceled""scheduled""executing""failed"
scheduled_datestring(date)

The date when the order is scheduled to be processed.

scheduled_date_policystring

Date policy of the scheduled order.

Response
application/json
{
  "id": "8ad08ccf8437067601843a7af4e64rq3",
  "order_number": "O-0002341801234",
  "order_date": "2022-01-01",
  "state": "complete",
  "category": "sale",
  "created_time": "2023-04-14T06:37:13-07:00",
  "created_by_id": "2c92c0946a6dffc0016a7faab604299b",
  "updated_time": "2023-04-14T06:37:14-07:00",
  "updated_by_id": "2c92c0946a6dffc0016a7faab604299b",
  "custom_fields": {},
  "description": "description of test account",
  "account_id": "8ad0934e86da6aca0186db46d29a2cee",
  "subscriptions": [
    { … }
  ]
}

Order Line Items

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 have the ability to launch non-subscription and unified monetization business models in Zuora, in addition to subscription business models.

Operations

Subscriptions

Subscriptions allow you to charge a customer on a recurring basis, such as a monthly charge or a charge based on usage and must be associated with an Account object. Subscriptions can also include one-time charges, such as service activation fees.

Operations

Subscription Plans

A subscription plan is part of a subscription or an amendment to a subscription, and it comes from a price. Like a product and its plans, a subscription can have one or more subscription plans. Subscription plans represent a price or a collection of prices for a service you sell. An individual subscription plan contains all prices specific to a particular subscription.

Operations

Subscription Items

A subscription item is a part of a subscription plan, and it comes from a price.

Operations

Fulfillments

Fulfillments are subordinate objects attached to their related order line item. You can manage the entire order line item lifecycle through fulfillments in the following ways:

  • Create and attach fulfillments to an order line item to track the shipment or return status.
  • Trigger billing based on the fulfillment state and generate billing documents based on the fulfillments accordingly.
  • Create and attach fulfillment items to a fulfillment to keep track of all the assets in your system.

Operations

Fulfillment Items

Fulfillment items are subordinate objects attached to their related fulfillment.

Operations

Invoices

Invoices are statements of amounts owed by a customer and are usually generated by a bill run. For more information about invoices, see Invoices.

Operations

Credit Memos

Credit memos reduce invoice and account balances. By applying one or more credit memos to invoices with positive balances, you can reduce the invoice balances in the same way as applying a payment to an invoice. For more information about credit memos, see Credit and debit memos.

Operations

Debit Memos

Debit memos increase the amount a customer owes. Debit memos can be used to correct undercharging on an invoice or to levy ad hoc charges outside the context of a subscription. Just like an invoice, debit memo balances can be settled by applying either a payment or a credit memo. For more information about debit memos, see Credit and debit memos.

Operations

Bill Runs

Bill runs automatically create invoices for your customers on a set schedule, as well as create invoices for your customers, as needed. A bill run gathers information from one or more customer accounts and generates invoices for those accounts. The operations in this section allows you to create, update, get, or delete bill runs.

Operations

Bill Run Previews

The Bill Run Previews operations allow you to generates a preview of future billing document items for a batch of accounts through a bill run. A bill run preivew job also generates a downloadable CSV file containing a preview of invoice item data for the customer account batch.

Operations

Taxation Items

The TaxationItem object is used to add a tax amount to an invoice item. Z-Tax and third-party tax engines such as Avalara or Connect tax engine can create TaxationItem objects. Before you use the Taxation Item object, you have to configure Z-Tax, Avalara, or Connect tax engine, as the object's fields rely on the values you create during the configuration process.

Operations

Usage Records

The operations in this section allows you to create, update, get, or delete usage records. Zuora expects no more than 25 million usage records per month. If you want to go over this limit, contact your Zuora account manager for further consultation.

Operations

Payment Methods

Payment methods represent your customer's payment instruments. They can be used to collect payments or saved to Account objects to store instrument details for future payments.

Important: The type field in the request body schema of the Create a payment method operation enumerates the supported payment methods. Not all payment gateways support all these payment method types. Check Supported payment methods to check the supported payment methods for each gateway.

If you need to create payment methods outside the scope of this operaton, you have to use the Create a payment method operation of the v1 API instead of the Quickstart API. We do not plan to add additional payment methods to the Quickstart API. Any new payment methods will only be available through the v1 API and Zuora client libraries.

Operations

Payments

Payments represents a customer payment. The Payment object holds all of the information about a payment, including the payment amount and which billing documents the payment is applied to.

Operations

Payment Runs

Payment runs are used to collect payments using electronic payment methods. Even if a payment was made to an invoice but had an error, if an invoice has a positive balance and meets all the filter criteria for the payment run, Zuora will pick up the invoice for processing in the payment run.
Zuora supports two type of payment runs: ad hoc and recurring. These are similar to ad hoc and scheduled bill runs

Operations

Payment Schedules

The Payment Schedules feature enables you to collect a series of payments following customized timelines and rules. You have the flexibility to leverage a payment schedule to process either a single payment or multiple payments.
You can leverage this feature to split invoice or account balances into several installments, and then automatically process payments for the installments. Payment schedules can also be used to collect external payments made for the installments. Meanwhile, we’ve provided you the capability to easily manage and modify existing schedules, as well as to manually retry failed payments with updated configurations.

Operations

Payment Schedule Items

A payment schedule consists of one or more payment schedule items that can be picked up by payment runs, which are hourly scheduled by Zuora. Each payment schedule item will trigger a payment process.

Operations

Refunds

A refund returns money to a customer. For instance, refunds are used when a customer cancels service and is no longer your customer. The Quickstart API allows you to refund payments, update refunds, and get refunds.

Operations

Custom Objects

Zuora Custom Objects provides a uniform custom data service for you to manage custom objects in Zuora. Those custom data is stored on Zuora's platform and can be used to extend the data model to accommodate your specific use cases.

Operations

Query Runs

The Query Runs operations allow you to create, retrieve, or cancel a Data Query job run.

Operations

Workflows

Run a specified workflow. In the request body, you can include parameters that you want to pass to the workflow. For the parameters to be recognized and picked up by tasks in the workflow, you need to define the parameters first.

Operations

Billing Documents

Note: The API operations in this section have been deprecated.

Billing Documents represent your customer's invoices, credit memos and debit memos. Invoices are statements of amounts owed by a customer, and are either generated one-off, or generated periodically from a subscription. They contain invoice items, and proration adjustments that may be caused by changes to a subscription. If your invoice is configured to be charged automatically, Zuora automatically finalizes your invoice and attempts payment otherwise Zuora will email the invoice to your customer and await payment. Any customer credit memos may be applied before determining the amount due for the invoice (i.e., the amount that will be charged).

Operations

Billing Document Items

The API operations in this section have been deprecated.

Billing document items represent each item in your customer's invoices, credit memos, or debit memos.

Operations