Lookup a subscription's details.
Pending Subscription Changes
When looking up a subscription that has pending changes, the new subscription details will be in a pending_subscription node. Since immediate subscription changes take place immediately, pending subscription changes will only show for changes occurring when the subscription renews.
Paused Subscriptions and current_term_ends_at timestamp
current_term_ends_at timestampWhile a subscription is paused, the current_term_ends_at timestamp of the subscription will not be updated to account for the time while the subscription is paused (e.g the timestamp does not get pushed out by the number of paused periods). This is due to the fact that the subscription could be resumed earlier or the number of pause periods can frequently be updated. Any of the former events could potentially change the timestamp. Once a subscription is returned to active, the current_term_renewal_date will be updated.
To calculate the new renewal date while a subscription is paused, you will want to take original renewal date add the length of the pause period.
| Subscription Parameters | Description |
|---|---|
| plan | Nested plan_code and plan name |
| uuid | Unique subscription ID |
| state | active, canceled, future, expired, paused |
| unit_amount_in_cents | Unit amount of the subscription |
| quantity | Number of units |
| currency | 3-letter ISO currency for the subscription |
| activated_at | Date the subscription was activated |
| canceled_at | Date the subscription was marked canceled |
| expires_at | Date the subscription will end (if state is canceled) or ended (if state is expired) |
| auto_renew | True if subscription term set to auto renew at end of term |
| current_period_started_at | Date the current billing period started |
| current_period_ends_at | Date the current billing period will end |
| current_term_started_at | Date and time that the current term started at. |
| current_term_ends_at | Date and time that the current term will end (or the date and time the term will renew if auto_renew is true) |
| total_billing_cycles | Total number of billing periods in the current term. |
| remaining_billing_cycles | Remaining number of billing periods in the current subscription term. Always set to 0 for subscriptions with a single billing period term. |
| renewal_billing_cycles | Total number of billing periods in the subscription's next term, if auto_renew is true |
| trial_started_at | Date the trial was started, if applicable |
| trial_ends_at | Date the trial ended, if applicable |
| tax_in_cents | Amount of tax or VAT within the transaction, in cents. |
| tax_type | Tax type as "vat" for VAT or "usst" for US Sales Tax. |
| tax_region | Region where taxes are applied. |
| tax_rate | Tax rate that will be applied to this subscription. |
| po_number | PO number reference. |
| net_terms | Invoice net terms in days. |
| collection_method | Invoice collection as "automatic" or "manual". |
| subscription_add_ons | Nested list of add-ons on the subscription, if applicable |
| pending_subscription | Nested information about a pending subscription change at renewal |
| terms_and_conditions | Optional notes field. This will default to the Terms and Conditions text specified on the Invoice Settings page in your Recurly admin. Specify custom notes with this tag to add or override Terms and Conditions. Custom notes will stay with a subscription on all renewals. |
| customer_notes | Optional notes field. This will default to the Customer Notes text specified on the Invoice Settings page in your Recurly admin. Specify custom notes with this tag to add or override Customer Notes. Custom notes will stay with a subscription on all renewals. |
| bank_account_authorized_at | Recurring subscriptions paid with ACH will have this attribute with an iso8601 timestamp value. This timestamp is used for alerting customers to reauthorize in 3 years in accordance with NACHA rules. If a subscription becomes inactive or the billing info is no longer a bank account, this timestamp is cleared and the attribute will not exist. |
| plan | Nested information about the new plan |
| unit_amount_in_cents | New subscription's unit amount in cents |
| quantity | New subscription quantity |
| subscription_add_ons | Nested list of add-ons |
| started_with_gift | True if the subscription started from a gift card. |
| converted_at | The timestamp representing when the subscription was converted from a gift card. |
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||