# CRUD: Retrieve a subscription

Endpoint: GET /v1/object/subscription/{id}
Version: 2025-12-17

## Header parameters:

  - `Accept-Encoding` (string)
    Include the Accept-Encoding: gzip header to compress responses as a gzipped file. It can significantly reduce the bandwidth required for a response. 

If specified, Zuora automatically compresses responses that contain over 1000 bytes of data, and the response contains a Content-Encoding header with the compression algorithm so that your client can decompress it.

  - `Content-Encoding` (string)
    Include the Content-Encoding: gzip header to compress a request. With this header specified, you should upload a gzipped file for the request payload instead of sending the JSON payload.

  - `Authorization` (string)
    The value is in the Bearer {token} format where {token} is a valid OAuth token generated by calling Create an OAuth token.

  - `Zuora-Entity-Ids` (string)
    An entity ID. If you have Zuora Multi-entity enabled and the OAuth token is valid for more than one entity, you must use this header to specify which entity to perform the operation in. If the OAuth token is only valid for a single entity, or you do not have Zuora Multi-entity enabled, you do not need to set this header.

  - `Zuora-Track-Id` (string)
    A custom identifier for tracing the API call. If you set a value for this header, Zuora returns the same value in the response headers. This header enables you to associate your system process identifiers with Zuora 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 ("), and quote (').

  - `X-Zuora-WSDL-Version` (string)
    Zuora WSDL version number.

## Query parameters:

  - `fields` (string)
    Object fields to return

## Path parameters:

  - `id` (string, required)
    Object id

## Response 200 fields (application/json):

  - `AccountId` (string)
    This field can be updated when Status is Draft. The ID of a valid account ID.

  - `AutoRenew` (boolean)
    This field can be updated when Status is Draft. Indicates if the subscription automatically renews at the end of the term.
Values: true, false

  - `CancelledDate` (string)
    The date on which the subscription was canceled.

  - `ContractAcceptanceDate` (string)
    The date when the customer accepts the contract. This field can be updated when Status is Draft.

  - `ContractEffectiveDate` (string)
    The date when the contract takes effect. This field can be updated when Status is Draft.
Note: This field is required in the subscribe call. If you set the value of this field to null and both the ServiceActivationDate and ContractAcceptanceDate fields are not required, the subscribe call still returns success, but the new subscription is in DRAFT status. To activate the subscription, you must set a valid date to this field.

  - `CreatedById` (string)
    The user ID of the person who created the subscription. Character limit: 32 Values: automatically generated

  - `CreatedDate` (string)
    The date the subscription was created. This value is the same as the OriginalCreatedDate value until the subscription is amended.
Values: automatically generated

  - `CreatorAccountId` (string)
    The account ID that created the subscription or the amended subscription.
Character limit: 32 Values: automatically generated

  - `CreatorInvoiceOwnerId` (string)
    The account ID that owns the invoices associated with the subscription or the amended subscription.
Character limit: 32 Values: automatically generated

  - `CurrentTerm` (integer)
    The length of the period for the current subscription term. If TermType is set to TERMED, this field is required and must be greater than 0. If TermType is set to EVERGREEN, this value is ignored. Default is 0.
Character limit: 20 Values: automatically generated

  - `CurrentTermPeriodType` (string)
    The period type for the current subscription term. This field is used with the CurrentTerm field to specify the current subscription term.
Values:

- Month (default)
- Year
- Day
- Week

  - `ExternallyManagedBy` (string)
    An enum field on the Subscription object to indicate the name of a third-party store. This field is used to represent subscriptions created through third-party stores.
    Enum: "Amazon", "Apple", "Google", "Roku"

  - `Id` (string)
    Object identifier.

  - `InitialTerm` (integer)
    The length of the period for the first subscription term. This field can be updated when Status is Draft.
Required: If TermType is Termed Character limit: 20 Values: any valid number. The default value is 0.

  - `InitialTermPeriodType` (string)
    The period type for the first subscription term.
Values:

- Month (default)
- Year
- Day
- Week
Note:

- This field can be updated when Status is Draft.
- This field is used with the InitialTerm field to specify the initial subscription term.

  - `InvoiceOwnerId` (string)
    This field can be updated when Status is Draft. A valid account ID.

  - `IsInvoiceSeparate` (boolean)
    Determines if the subscription is invoiced separately. If TRUE, then all charges for this subscription are collected into the subscription's own invoice.
Values: TRUE, FALSE (default)

  - `IsLatestVersion` (boolean)
    Determines if the subscription is the latest version. If the value of this field is TRUE, the subscription is the latest version.
Values: TRUE, FALSE (default)

  - `Name` (string)
    The unique identifier of the subscription. If you don't specify a value, then Zuora generates a name automatically. Whether auto-generated or manually specified, the subscription name must be unique. Otherwise an error will occur.
Character limit: 100 Values: one of the following:

- leave null to automatically generate
- a string of 100 characters or fewer

  - `Notes` (string)
    Use this field to record comments about the subscription.
Character limit: 500 Values: a string of 500 characters or fewer

  - `OriginalCreatedDate` (string)
    The date when the subscription was originally created. This value is the same as the CreatedDate value until the subscription is amended.
Values: automatically generated

  - `OriginalId` (string)
    The original ID of this subscription.
Values: automatically generated

  - `PaymentTerm` (string)
    The name of the payment term associated with the subscription. For example, Net 30. The payment term determines the due dates of invoices.

Note: This field is only available if you set the X-Zuora-WSDL-Version header parameter to 115 or later. The value of this field is null if you have the [Flexible Billing Attributes](https://knowledgecenter.zuora.com/Billing/Subscriptions/Flexible_Billing_Attributes) feature disabled.

  - `PreviousSubscriptionId` (string)
    The subscription ID immediately prior to the current subscription.
Character limit: 32 Values: automatically generated

  - `RenewalSetting` (string)
    This field can be updated when Status is Draft. Specifies whether a termed subscription will remain termed or change to evergreen when it is renewed.
Required: If TermType is Termed Values: RENEW_WITH_SPECIFIC_TERM (default), RENEW_TO_EVERGREEN

  - `RenewalTerm` (integer)
    The length of the period for the subscription renewal term. This field can be updated when Status is Draft.
Required: If TermType is Termed.
Character limit: 20 Values: one of the following:

- leave null to default to 0
- any number

  - `RenewalTermPeriodType` (string)
    The period type for the subscription renewal term.
Values:

- Month (default)
- Year
- Day
- Week
Note:

- This field is used with the RenewalTerm field to specify the subscription renewal term.
- This field can be updated when Status is Draft.

  - `Revision` (string)
    An auto-generated decimal value uniquely tagged with a subscription. The value always contains one decimal place, for example, the revision of a new subscription is 1.0. If a further version of the subscription is created, the Revision value will be increased by 1. Also, the Revision value is always incremental regardless of deletion of subscription versions.
Note: To get this field, you must set the Zuora WSDL version to 107.0 or over in the X-Zuora-WSDL-Version header parameter.

  - `ServiceActivationDate` (string)
    The date when the subscription is activated. This field can be updated when Status is Draft.

  - `Status` (string)
    The status of the subscription.
Character limit: 18 Values: automatically generated Possible values: one of the following:

- Draft
- PendingActivation
- PendingAcceptance
- Active
- Cancelled
- Expired
- Suspended (This value is in Limited Availability.)

  - `SubscriptionBillToId` (string)
    The bill-to contact ID of the subscription.

Note: This field is only available if you set the X-Zuora-WSDL-Version header parameter to 121 or later. The value of this field is null if you have the [Flexible Billing Attributes](https://knowledgecenter.zuora.com/Billing/Subscriptions/Flexible_Billing_Attributes) feature disabled.

  - `SubscriptionBillToSnapshotId` (string)
    The snapshot ID of the subscription's bill-to contact. The snapshot ID will not change after the subscription version is created.

Note: This field is only available if you set the X-Zuora-WSDL-Version header parameter to 121 or later. The value of this field is null if you have the [Flexible Billing Attributes](https://knowledgecenter.zuora.com/Billing/Subscriptions/Flexible_Billing_Attributes) feature disabled.

  - `SubscriptionEndDate` (string)
    The date when the subscription term ends, where the subscription ends at midnight the day before. For example, if the SubscriptionEndDate is 12/31/2016, the subscriptions ends at midnight (00:00:00 hours) on 12/30/2016. This date is the same as the term end date or the cancelation date, as appropriate.
Character limit: 29 Values: automatically generated

  - `SubscriptionStartDate` (string)
    The date when the subscription term starts. This date is the same as the start date of the original term, which isn't necessarily the start date of the current or new term.
Character limit: 29 Values: automatically generated

  - `TermEndDate` (string)
    This field can be updated when Status is Draft. The date when the subscription term ends. If the subscription is evergreen, the TermEndDate value is null or is the cancelation date, as appropriate. Character limit: 29 Values: automatically generated

  - `TermStartDate` (string)
    This field can be updated when Status is Draft. The date when the subscription term begins. If this is a renewal subscription, then this date is different from the subscription start date.
Character limit: 29 Version notes: --

  - `TermType` (string)
    This field can be updated when Status is Draft. Indicates if a subscription is termed or evergreen.
Character limit: 9 Values: TERMED, EVERGREEN

  - `UpdatedById` (string)
    The ID of the user who last updated the subscription.
Character limit: 32 Values: automatically generated

  - `UpdatedDate` (string)
    The date when the subscription was last updated.
Character limit: 29 Values: automatically generated

  - `Version` (integer)
    The version number of the subscription.
Values: automatically generated

  - `lastBookingDate` (string)
    The last booking date of the subscription object. This field is writable only when the subscription is newly created as a first version subscription. You can override the date value when creating a subscription through the Subscribe and Amend API or the subscription creation UI (non-Orders). Otherwise, 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](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Orders_Harmonization/Orders_Migration_Guidance#Subscribe_and_Amend_APIs_to_Migrate), 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.

  - `Currency` (string)
    The code of currency that is used for this subscription. If the currency is not selected, the default currency from the account will be used.

All subscriptions in the same order must use the same currency. The currency for a subscription cannot be changed.

Note: This field is available only if you have the Multiple Currencies feature enabled and set the X-Zuora-WSDL-Version header parameter to 137 or later.

  - `CpqBundleJsonId__QT` (string)
    The Bundle product structures from Zuora Quotes if you utilize Bundling in Salesforce. Do not change the value in this field.

  - `OpportunityCloseDate__QT` (string)
    The closing date of the Opportunity. This field is used in Zuora data sources to report on Subscription metrics. If the subscription originated from Zuora Quotes, the value is populated with the value from Zuora Quotes.

  - `OpportunityName__QT` (string)
    The unique identifier of the Opportunity. This field is used in Zuora data sources to report on Subscription metrics. If the subscription originated from Zuora Quotes, the value is populated with the value from Zuora Quotes.

  - `QuoteBusinessType__QT` (string)
    The specific identifier for the type of business transaction the Quote represents such as New, Upsell, Downsell, Renewal or Churn. This field is used in Zuora data sources to report on Subscription metrics. If the subscription originated from Zuora Quotes, the value is populated with the value from Zuora Quotes.

  - `QuoteNumber__QT` (string)
    The unique identifier of the Quote. This field is used in Zuora data sources to report on Subscription metrics. If the subscription originated from Zuora Quotes, the value is populated with the value from Zuora Quotes.

  - `QuoteType__QT` (string)
    The Quote type that represents the subscription lifecycle stage such as New, Amendment, Renew or Cancel. This field is used in Zuora data sources to report on Subscription metrics. If the subscription originated from Zuora Quotes, the value is populated with the value from Zuora Quotes.

  - `IntegrationId__NS` (string)
    ID of the corresponding object in NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).

  - `IntegrationStatus__NS` (string)
    Status of the subscription's synchronization with NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).

  - `Project__NS` (string)
    The NetSuite project that the subscription was created from. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).

  - `SalesOrder__NS` (string)
    The NetSuite sales order than the subscription was created from. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).

  - `SyncDate__NS` (string)
    Date when the subscription was synchronized with NetSuite. Only available if you have installed the [Zuora Connector for NetSuite](https://www.zuora.com/connect/app/?appId=265).

## Response 401 fields (application/json):

  - `message` (string)
    Error message.

If the error message is "Authentication error", ensure that the Authorization request header contains valid authentication credentials, then retry the request. See [Authentication](https://developer.zuora.com/rest-api/general-concepts/authentication/) for more information.

If the error message is "Failed to get user info", retry the request.

## Response 404 fields (application/json):

  - `done` (boolean)

  - `records` (array)

  - `size` (integer)