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.
Quickstart API Reference
//
Activate a subscription
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
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
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 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
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
Query
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`, `order_number` Example: fields[]=id,created_time
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` Example: subscription_plans.fields[]=id,created_time
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
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`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled` Example: account.fields[]=id,created_time
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`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled` Example: invoice_owner_account.fields[]=id,created_time
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`, `name`, `active`, `description`, `plan_number`, `product_id`, `active_currencies` Example: plan.fields[]=id,created_time
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`, `active`, `name`, `type`, `sku`, `description` Example: product.fields[]=id,created_time
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`, `tiers`, `charge_model`, `charge_type`, `name`, `description`, `revenue_recognition_rule`, `stacked_discount`, `recognized_revenue_accounting_code`, `deferred_revenue_accounting_code`, `accounting_code`, `recurring`, `start_event`, `tax_code`, `tax_inclusive`, `taxable`, `unit_of_measure`, `quantity`, `min_quantity`, `max_quantity`, `price_base_interval`, `discount_level`, `overage`, `plan_id`, `tiers_mode`, `apply_discount_to`, `prepayment`, `drawdown`, `discount_amounts`, `unit_amounts`, `discount_percent`, `amounts`, `price_change_percentage`, `price_change_option`, `price_increase_option` Example: price.fields[]=id,created_time
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`, `address`, `home_phone`, `first_name`, `last_name`, `email`, `work_email`, `nickname`, `other_phone`, `work_phone`, `mobile_phone`, `tax_region`, `other_phone_type`, `fax` Example: bill_to.fields[]=id,created_time
Allows you to specify which fields are returned in the response.
Accepted values
`prepaid_UOM`, `start_date`, `end_date`, `total_balance`, `remaining_balance` Example: prepaid_balance.fields[]=id,created_time
Allows you to specify which fields are returned in the response.
Accepted values
`validity_periods` Example: prepaid_balances.fields[]=id,created_time
Allows you to specify which fields are returned in the response.
Accepted values
`prepaid_UOM`, `start_date`, `end_date`, `total_balance`, `remaining_balance`, `overage_rated_amount`, `overage_rated_quantity` Example: validity_period.fields[]=id,created_time
Allows you to specify which fields are returned in the response.
Accepted values
`transaction_date`, `type`, `quantity` Example: transactions.fields[]=id,created_time
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.
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
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.
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`, `order_number` Example: subscription.fields[]=id,created_time
Headers
Bodyapplication/jsonrequiredA 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 (').
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
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.
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.
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.
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.
The date on which the subscription is canceled. Can be either the end of the subscription term or the end of the billing period.
Enum"invoice_period_end""subscription_term_end"
Indicates whether to write off the outstanding balance on the invoice after canceling the subscription.
Default false
The financial information of the credit memo items generated to write off the invoice balance.
Set of user-defined fields associated with this object. Useful for storing additional information about the object in a structured format.
- Mock serverhttps://developer.zuora.com/_mock/other-api/quickstart-api/subscriptions/{subscription_id}/cancel
- US Developer & Central Sandbox (incl. Test Drive)https://rest.test.zuora.com/v2/subscriptions/{subscription_id}/cancel
- US API Sandbox Cloud 1https://rest.sandbox.na.zuora.com/v2/subscriptions/{subscription_id}/cancel
- US API Sandbox Cloud 2https://rest.apisandbox.zuora.com/v2/subscriptions/{subscription_id}/cancel
- US Production Cloud 1https://rest.na.zuora.com/v2/subscriptions/{subscription_id}/cancel
- US Production Cloud 2https://rest.zuora.com/v2/subscriptions/{subscription_id}/cancel
- EU Developer & Central Sandboxhttps://rest.test.eu.zuora.com/v2/subscriptions/{subscription_id}/cancel
- EU API Sandboxhttps://rest.sandbox.eu.zuora.com/v2/subscriptions/{subscription_id}/cancel
- EU Productionhttps://rest.eu.zuora.com/v2/subscriptions/{subscription_id}/cancel
- APAC Developer & Central Sandboxhttps://rest.test.ap.zuora.com/v2/subscriptions/{subscription_id}/cancel
- APAC Productionhttps://rest.ap.zuora.com/v2/subscriptions/{subscription_id}/cancel
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
'https://developer.zuora.com/_mock/other-api/quickstart-api/subscriptions/{subscription_id}/cancel?fields%5B%5D=id%2Ccreated_time&subscription_plans.fields%5B%5D=id%2Ccreated_time&subscription_items.fields%5B%5D=id%2Ccreated_time&account.fields%5B%5D=id%2Ccreated_time&invoice_owner_account.fields%5B%5D=id%2Ccreated_time&plan.fields%5B%5D=id%2Ccreated_time&product.fields%5B%5D=id%2Ccreated_time&price.fields%5B%5D=id%2Ccreated_time&bill_to.fields%5B%5D=id%2Ccreated_time&prepaid_balance.fields%5B%5D=id%2Ccreated_time&prepaid_balances.fields%5B%5D=id%2Ccreated_time&validity_period.fields%5B%5D=id%2Ccreated_time&transactions.fields%5B%5D=id%2Ccreated_time&expand%5B%5D=string&filter%5B%5D=string&page_size=1&subscription.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 '{
"cancel_date": "2022-10-01",
"write_off": true,
"write_off_behavior": {
"recognized_revenue_accounting_code": "Subscription Revenue",
"deferred_revenue_accounting_code": "Subscription Revenue"
}
}'Default Response
The request limit quota for the time window closest to exhaustion. See rate limits for more information.
The number of requests remaining in the time window closest to quota exhaustion. See rate limits for more information.
The number of seconds until the quota resets for the time window closest to quota exhaustion. See rate limits for more information.
The date and time when the object was last updated in ISO 8601 UTC format.
The date and time when the object was created in ISO 8601 UTC format.
Set of user-defined fields associated with this object. Useful for storing additional information about the object in a structured format.
Status of the subscription.
Enum"draft""pending_activation""pending_acceptance""active""expired""canceled""paused"
The version of the subscription. This version can be used in the filter[] query parameter to filter subscriptions.
Identifier of the account that owns the invoice associated with this subscription.
If this field is set to true, the subscription automatically renews at the end of the current term.
Date when the subscribed-to service is activated.
Example: "2023-01-01"
Date when all the services or products in the subscription are accepted by the subscriber.
Example: "2023-01-01"
If true, the subscription is billed separately from other subscriptions. If false, the subscription is included with other subscriptions in the account invoice. The default is false.
Total prepaid units available during a subscription. It is an aggregate of all funds under a subscription.
3-letter ISO 4217 currency code. This field is available only if you have the Multiple Currencies feature enabled.
The last booking date of the subscription object. You can override the date value when creating a subscription through the "Subscribe and Amend" API. The default value today is set per the user's timezone. The value of this field is as follows:
- For a new subscription created by the Subscribe and Amend APIs, this field has the value of the subscription creation date.
- For a subscription changed by an amendment, this field has the value of the amendment booking date.
- For a subscription created or changed by an order, this field has the value of the order date.
Example: "2023-01-01"
The billing document settings for the customer.
Response
application/json
{ "id": "8ad08dc9878f3dd6018790c8998f05bf", "updated_by_id": "2c92c0946a6dffc0016a7faab604299b", "updated_time": "2023-04-17T12:54:38-07:00", "created_by_id": "2c92c0946a6dffc0016a7faab604299b", "created_time": "2023-04-17T12:54:38-07:00", "custom_fields": { "cancel_Reason_Code__c": "Customer Initiated" }, "subscription_number": "A-S00014014", "state": "canceled", "account_id": "8ad0823f8455bb400184633077e63aaf", "invoice_owner_account_id": "8ad0823f8455bb400184633077e63aaf", "auto_renew": true, "latest_version": true, "initial_term": { "type": "termed", "interval_count": 1, "interval": "month" }, "current_term": { "type": "termed", "start_date": "2022-11-04", "end_date": "2022-10-01", "interval_count": 1, "interval": "month" }, "renewal_term": { "type": "termed", "interval_count": 1, "interval": "month" }, "start_date": "2022-11-04", "end_date": "2022-10-01", "description": "test subscription", "contract_effective": "2022-11-04", "service_activation": "2022-11-04", "customer_acceptance": "2022-11-04", "invoice_separately": false, "version": 2, "order_number": "O-00023516", "bill_to_id": null, "payment_terms": null, "billing_document_settings": { "sequence_set_id": null, "template_id": null } }
Request
A subscription must be active before you can bill your subscribers. Activating a subscription requires entering at least one of the following dates: contract_effective, service_activation, and customer_acceptance. See Billing Trigger Dates for more information.
Security
bearerAuth
Query
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`, `order_number` Example: fields[]=id,created_time
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` Example: subscription_plans.fields[]=id,created_time
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
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`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled` Example: account.fields[]=id,created_time
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`, `auto_pay`, `account_number`, `bill_to_id`, `sold_to_id`, `billing_document_settings`, `communication_profile_id`, `crm_id`, `sales_rep`, `parent_account_id`, `payment_gateway`, `payment_terms`, `remaining_credit_memo_balance`, `remaining_debit_memo_balance`, `remaining_invoice_balance`, `remaining_payment_balance`, `sequence_set_id`, `tax_certificate`, `batch`, `tax_identifier`, `bill_cycle_day`, `description`, `name`, `currency`, `default_payment_method_id`, `enabled` Example: invoice_owner_account.fields[]=id,created_time
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`, `name`, `active`, `description`, `plan_number`, `product_id`, `active_currencies` Example: plan.fields[]=id,created_time
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`, `active`, `name`, `type`, `sku`, `description` Example: product.fields[]=id,created_time
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`, `tiers`, `charge_model`, `charge_type`, `name`, `description`, `revenue_recognition_rule`, `stacked_discount`, `recognized_revenue_accounting_code`, `deferred_revenue_accounting_code`, `accounting_code`, `recurring`, `start_event`, `tax_code`, `tax_inclusive`, `taxable`, `unit_of_measure`, `quantity`, `min_quantity`, `max_quantity`, `price_base_interval`, `discount_level`, `overage`, `plan_id`, `tiers_mode`, `apply_discount_to`, `prepayment`, `drawdown`, `discount_amounts`, `unit_amounts`, `discount_percent`, `amounts`, `price_change_percentage`, `price_change_option`, `price_increase_option` Example: price.fields[]=id,created_time
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`, `address`, `home_phone`, `first_name`, `last_name`, `email`, `work_email`, `nickname`, `other_phone`, `work_phone`, `mobile_phone`, `tax_region`, `other_phone_type`, `fax` Example: bill_to.fields[]=id,created_time
Allows you to specify which fields are returned in the response.
Accepted values
`prepaid_UOM`, `start_date`, `end_date`, `total_balance`, `remaining_balance` Example: prepaid_balance.fields[]=id,created_time
Allows you to specify which fields are returned in the response.
Accepted values
`validity_periods` Example: prepaid_balances.fields[]=id,created_time
Allows you to specify which fields are returned in the response.
Accepted values
`prepaid_UOM`, `start_date`, `end_date`, `total_balance`, `remaining_balance`, `overage_rated_amount`, `overage_rated_quantity` Example: validity_period.fields[]=id,created_time
Allows you to specify which fields are returned in the response.
Accepted values
`transaction_date`, `type`, `quantity` Example: transactions.fields[]=id,created_time
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.
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
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.
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`, `order_number` Example: subscription.fields[]=id,created_time
Headers
Bodyapplication/jsonrequiredA 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 (').
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
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.
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.
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.
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.
Effective contract date for this subscription, in the yyyy-mm-dd format.
Example: "2023-06-01"
The date on which the services or products within a subscription have been activated and access has been provided to the customer, as the yyyy-mm-dd format.
- If Zuora is configured to require service activation and the
service_activationfield is not set for asubscription_plansorder action or the "Create a subscription" operation, apendingorder and/or apending_activationsubscription are created. - If Zuora is configured to require service activation and the
service_activationfield is not set for any of the following order actions or the "Update a subscription" operation, apendingorder is created. The subscription status is not impacted. Note: This feature is in Limited Availability. If you want to have access to the feature, submit a request at Zuora Global Support.add_subscription_plansupdate_subscription_plansremove_subscription_plansrenewterms
Example: "2023-06-01"
The date on which the services or products within a subscription have been accepted by the customer, in the yyyy-mm-dd format.
- If Zuora is configured to require customer acceptance and the
customer_acceptancefield is not set for asubscription_plansorder action or the "Create a subscription" operation, apendingorder and/or apending_acceptancesubscription are created. At the same time, if the service activation date field is also required and not set, apendingorder and/or apending_activationsubscription are created instead. - If Zuora is configured to require customer acceptance and the
customer_acceptancefield is not set for any of the following order actions or the "Update a subscription" operation, apendingorder is created. The subscription status is not impacted. Note: This feature is in Limited Availability. If you want to have access to the feature, submit a request at Zuora Global Support.add_subscription_plansupdate_subscription_plansremove_subscription_plansrenewterms
Example: "2023-06-01"
- Mock serverhttps://developer.zuora.com/_mock/other-api/quickstart-api/subscriptions/{subscription_id}/activate
- US Developer & Central Sandbox (incl. Test Drive)https://rest.test.zuora.com/v2/subscriptions/{subscription_id}/activate
- US API Sandbox Cloud 1https://rest.sandbox.na.zuora.com/v2/subscriptions/{subscription_id}/activate
- US API Sandbox Cloud 2https://rest.apisandbox.zuora.com/v2/subscriptions/{subscription_id}/activate
- US Production Cloud 1https://rest.na.zuora.com/v2/subscriptions/{subscription_id}/activate
- US Production Cloud 2https://rest.zuora.com/v2/subscriptions/{subscription_id}/activate
- EU Developer & Central Sandboxhttps://rest.test.eu.zuora.com/v2/subscriptions/{subscription_id}/activate
- EU API Sandboxhttps://rest.sandbox.eu.zuora.com/v2/subscriptions/{subscription_id}/activate
- EU Productionhttps://rest.eu.zuora.com/v2/subscriptions/{subscription_id}/activate
- APAC Developer & Central Sandboxhttps://rest.test.ap.zuora.com/v2/subscriptions/{subscription_id}/activate
- APAC Productionhttps://rest.ap.zuora.com/v2/subscriptions/{subscription_id}/activate
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
'https://developer.zuora.com/_mock/other-api/quickstart-api/subscriptions/{subscription_id}/activate?fields%5B%5D=id%2Ccreated_time&subscription_plans.fields%5B%5D=id%2Ccreated_time&subscription_items.fields%5B%5D=id%2Ccreated_time&account.fields%5B%5D=id%2Ccreated_time&invoice_owner_account.fields%5B%5D=id%2Ccreated_time&plan.fields%5B%5D=id%2Ccreated_time&product.fields%5B%5D=id%2Ccreated_time&price.fields%5B%5D=id%2Ccreated_time&bill_to.fields%5B%5D=id%2Ccreated_time&prepaid_balance.fields%5B%5D=id%2Ccreated_time&prepaid_balances.fields%5B%5D=id%2Ccreated_time&validity_period.fields%5B%5D=id%2Ccreated_time&transactions.fields%5B%5D=id%2Ccreated_time&expand%5B%5D=string&filter%5B%5D=string&page_size=1&subscription.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 '{
"service_activation": "2022-08-01",
"customer_acceptance": "2022-08-01"
}'Default Response
The request limit quota for the time window closest to exhaustion. See rate limits for more information.
The number of requests remaining in the time window closest to quota exhaustion. See rate limits for more information.
The number of seconds until the quota resets for the time window closest to quota exhaustion. See rate limits for more information.
The date and time when the object was last updated in ISO 8601 UTC format.
The date and time when the object was created in ISO 8601 UTC format.
Set of user-defined fields associated with this object. Useful for storing additional information about the object in a structured format.
Status of the subscription.
Enum"draft""pending_activation""pending_acceptance""active""expired""canceled""paused"
The version of the subscription. This version can be used in the filter[] query parameter to filter subscriptions.
Identifier of the account that owns the invoice associated with this subscription.
If this field is set to true, the subscription automatically renews at the end of the current term.
Date when the subscribed-to service is activated.
Example: "2023-01-01"
Date when all the services or products in the subscription are accepted by the subscriber.
Example: "2023-01-01"
If true, the subscription is billed separately from other subscriptions. If false, the subscription is included with other subscriptions in the account invoice. The default is false.
Total prepaid units available during a subscription. It is an aggregate of all funds under a subscription.
3-letter ISO 4217 currency code. This field is available only if you have the Multiple Currencies feature enabled.
The last booking date of the subscription object. You can override the date value when creating a subscription through the "Subscribe and Amend" API. The default value today is set per the user's timezone. The value of this field is as follows:
- For a new subscription created by the Subscribe and Amend APIs, this field has the value of the subscription creation date.
- For a subscription changed by an amendment, this field has the value of the amendment booking date.
- For a subscription created or changed by an order, this field has the value of the order date.
Example: "2023-01-01"
The billing document settings for the customer.
Response
application/json
{ "id": "8ad09b7d8258af4401825f733e6c43ae", "custom_fields": { "field__c": "custom field value" }, "subscription_number": "A-S00013332", "state": "active", "account_id": "2c92c0f86a8dd422016a9e7a70116b0d", "invoice_owner_account_id": "2c92c0f86a8dd422016a9e7a70116b0d", "auto_renew": true, "latest_version": true, "initial_term": { "interval_count": 1, "interval": "year", "type": "termed" }, "current_term": { "interval_count": 1, "interval": "year", "start_date": "2022-07-01", "type": "termed", "end_date": "2023-07-01" }, "start_date": "2022-07-01", "end_date": "2023-07-01", "description": "Create Subscription", "contract_effective": "2022-07-01", "service_activation": "2022-08-01", "customer_acceptance": "2022-08-01", "invoice_separately": false, "order_number": "O-00020843" }
Request
You can preview the billing document metrics or the order delta metrics across a specified time frame.
Security
bearerAuth
Headers
Bodyapplication/jsonrequiredA 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 (').
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
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.
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.
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.
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.
Identifier of the account that owns the invoice associated with this subscription. If you specify this field, do not specify invoice_owner_account_data.
Identifier of the account that owns the invoice associated with this subscription. If you specify this field, do not specify invoice_owner_account_data.
The information of the new account that owns the invoice associated with this subscription. If you specify this field, do not specify invoice_owner_account_id.
Identifier of the account that owns the subscription. Subscription owner account can be different from the invoice owner account. If you specify this field, do not specify account_data.
Identifier of the account that owns the subscription. Subscription owner account can be different from the invoice owner account. If you specify this field, do not specify account_data.
Account data that is used for the subscription preview. If you specify this field, do not specify account_id. Note that this operation is only for preview and no subscription is created.
Container for the contract effective, service activation, and customer acceptance dates of the order action or subscription.
- If Zuora is configured to require service activation and the
service_activationfield is not set for asubscription_plansorder action or the "Create a subscription" operation, apendingorder and/or apending_activationsubscription are created. - If Zuora is configured to require customer acceptance and the
customer_acceptancefield is not set for asubscription_plansorder action or the "Create a subscription" operation, apendingorder and/or apending_acceptancesubscription are created. At the same time, if the service activation date field is also required and not set, apendingorder and/or apending_activationsubscription are created instead. - If Zuora is configured to require service activation and the
service_activationfield is not set for any of the following order actions or the "Update a subscription" operation, apendingorder is created. The subscription status is not impacted. Note: This feature is in Limited Availability. If you want to have access to the feature, submit a request at Zuora Global Support.add_subscription_plansupdate_subscription_plansremove_subscription_plansrenewterms
customer_acceptance field is not set for any of the following order actions or the "Update a subscription" operation, a pending order is created. The subscription status is not impacted. Note: This feature is in Limited Availability. If you want to have access to the feature, submit a request at Zuora Global Support. add_subscription_plansupdate_subscription_plansremove_subscription_plansrenewterms
Separates a single subscription from other subscriptions and creates an invoice for this subscription. If the value is true, the subscription is billed separately from other subscriptions. If the value is false, the subscription is included with other subscriptions in the account invoice.
Set of user-defined fields associated with this object. Useful for storing additional information about the object in a structured format.
The plans associated with the new subscription.
The billing document settings for the customer.
3-letter ISO 4217 currency code. This field is available only if you have the Multiple Currencies feature enabled.
Specifies the metrics you want to preview. You can preivew metrics of billing documents, the order delta metrics, or both.
Items Enum"billing_documents""delta_metrics"
- Mock serverhttps://developer.zuora.com/_mock/other-api/quickstart-api/subscriptions/preview
- US Developer & Central Sandbox (incl. Test Drive)https://rest.test.zuora.com/v2/subscriptions/preview
- US API Sandbox Cloud 1https://rest.sandbox.na.zuora.com/v2/subscriptions/preview
- US API Sandbox Cloud 2https://rest.apisandbox.zuora.com/v2/subscriptions/preview
- US Production Cloud 1https://rest.na.zuora.com/v2/subscriptions/preview
- US Production Cloud 2https://rest.zuora.com/v2/subscriptions/preview
- EU Developer & Central Sandboxhttps://rest.test.eu.zuora.com/v2/subscriptions/preview
- EU API Sandboxhttps://rest.sandbox.eu.zuora.com/v2/subscriptions/preview
- EU Productionhttps://rest.eu.zuora.com/v2/subscriptions/preview
- APAC Developer & Central Sandboxhttps://rest.test.ap.zuora.com/v2/subscriptions/preview
- APAC Productionhttps://rest.ap.zuora.com/v2/subscriptions/preview
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
https://developer.zuora.com/_mock/other-api/quickstart-api/subscriptions/preview \
-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 '{
"account_id": "8ad09b7d8292b85d0182a4d6f875225a",
"subscription_plans": [
{
"plan_id": "8ad09bce82aa84840182afab5e7b04fb"
}
],
"metrics": [
"billing_documents"
],
"end_date": "2022-11-05"
}'Default Response
The request limit quota for the time window closest to exhaustion. See rate limits for more information.
The number of requests remaining in the time window closest to quota exhaustion. See rate limits for more information.
The number of seconds until the quota resets for the time window closest to quota exhaustion. See rate limits for more information.
Response
application/json
{ "billing_documents": [ { … } ] }
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
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
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 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 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
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
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
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
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
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
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