FIfinix
Subscriptions

Fetch a Subscription

Changed on

Retrieve the details of a previously created Subscription.

get/subscriptions/{subscription_id}

Request

Headers

Finix-Versionstring
Example:2022-02-01

Specify the API version of your request. For more details, see Versioning.

Response

A single Subscription

idstring

The ID of the resource.

created_atstring date-time

Timestamp of when the object was created.

updated_atstring date-time

Timestamp of when the object was last updated.

amountinteger

The total amount that will be debited in cents (e.g. 100 cents to debit $1.00).

application_idstring

The ID of the Application associated with the Subscription.

billing_cycle_dayinteger nullable

The day of the month on which the Subscription is billed. Only applies to subscriptions with a monthly billing cycle (e.g., MONTHLY, BIMONTHLY, QUARTERLY, SEMIYEARLY, YEARLY, BIYEARLY, TRIYEARLY).

If the specified day doesn't exist in a given month (e.g., April 31), the subscription is billed on the last valid day of that month.

Accepted values are 1 to 31.

billing_interval'BIMONTHLY' | 'BIWEEKLY' | 'BIYEARLY' | 'DAILY' | 'MONTHLY' | 'QUARTERLY' | 'SEMIYEARLY' | 'TRIYEARLY' | 'WEEKLY' | 'YEARLY'

How often the buyer is billed. The possible billing intervals are as follows:

  • BIMONTHLY: every 2 months
  • BIWEEKLY: every 2 weeks
  • BIYEARLY: every 2 years
  • DAILY: every day
  • MONTHLY: every month
  • QUARTERLY: each quarter
  • SEMIYEARLY: twice a year
  • TRIYEARLY: every 3 years
  • WEEKLY: every week
  • YEARLY: every year
canceled_via'MERCHANT' | 'AUTOMATED_OVERDUE' | 'SUPPORT' nullable

If the subscription was canceled, this field shows how the cancellation was initiated.

Possible values:

  • MERCHANT - The customer (merchant) canceled the subscription themselves. The linked_to field indicates the related Merchant.
  • AUTOMATED_OVERDUE - The subscription was canceled by the overdue system.
  • SUPPORT - The subscription was canceled by Finix Support.
currency'USD' | 'CAD'

ISO 4217 3-letter currency code.

end_subscription_atstring date-time nullable

Timestamp of when the subscription ends. If end_subscription_at was included in the request, this field echoes that value. If only total_billing_intervals was provided, this field is calculated to match the last day of the final billing cycle.

expires_atstring date-time nullable

The date-time that the Subscription expires. Set when total_billing_intervals or end_subscription_at is provided. When end_subscription_at is set, this field mirrors that value.

first_charge_atstring date-time

Timestamp when the first Transfer will occur.

linked_tostring

The ID of the Merchant resource that you wish to link to the Subscription (i.e., the merchant that the subscription belongs to).

At this time, only approved merchants with one of the following processors are valid:

  • DUMMY_V1
  • FINIX_V1
linked_type'MERCHANT'

The type of the resource that is specified in the linked_to field.

nicknamestring nullable

A human-readable name for the resource.

start_subscription_atstring date-time

Indicates that the subscription is scheduled to begin in the future. The timestamp specifies the exact start date for subscription billing.

state'ACTIVE' | 'CANCELED' | 'EXPIRED' | 'NOT_STARTED' | 'PAST_DUE'

The state of the Subscription.

  • The NOT_STARTED state occurs when the subscription has not yet started, typically indicated by a start_subscription_at timestamp set during creation.
  • A subscription in the PAST_DUE state is unpaid but has not yet been canceled.
subscription_link_idstring nullable

The ID of the Subscription Link that created the Subscription.

subscription_phase'EVERGREEN' | 'DISCOUNT' | 'FIXED' | 'NONE' | 'TRIAL'

Indicates the period within a subscription where specific rules apply.

  • EVERGREEN - The buyer is billed continuously for the subscription until the subscription is canceled.
  • DISCOUNT - The buyer receives a discounted price for a limited billing interval, after which the customer is charged the full subscription amount.
  • FIXED state - Applicable to fixed-length subscriptions.
  • NONE - Indicates that when the start_subscription_at timestamp is set during subscription creation, the subscription is not yet in any phase, and billing has not started.
  • TRIAL - The period during which the buyer is not billed; after this phase, the buyer will begin being billed.
subscription_plan_idstring nullable

The ID of a Subscription Plan from which this Subscription was created. When provided, the plan's amount, billing_interval, and other defaults are inherited.

has_usage_based_planboolean nullable

Indicates whether the Subscription is associated with a usage-based Subscription Plan.

tagsTags nullable

Include up to 50 key: value pairs to annotate requests with custom metadata.

  • Maximum character length for individual keys is 40.
  • Maximum character length for individual values is 500. (For example, order_number: 25, item_type: produce, department: sales)
total_billing_intervalsinteger nullable

The total number of billing intervals for the Subscription. This represents the total count of recurring billing cycles, such as months or weeks, depending on the billing frequency.

Example response

{
  "amount": 5000,
  "billing_cycle_day": 1,
  "billing_interval": "MONTHLY",
  "subscription_plan_id": "subscription_plan_ctBbJ1ihsC8Hpju4RQfZE"
}

Changes