Fetch a Subscription

Retrieve the details of a previously created Subscription.

Endpoint: GET /subscriptions/{subscription_id}
Security: BasicAuth

Path parameters:

• subscription_id (string, required)
  The Subscription ID.
  Example: "subscription_cAqNtRY2oKTJWbjMSDgrk"

Header parameters:

• Finix-Version (string)
  Specify the API version of your request. For more details, see Versioning.
  Example: "2022-02-01"

Response 200 fields (application/json):

• id (string)
  The ID of the resource.

• created_at (string)
  Timestamp of when the object was created.

• updated_at (string)
  Timestamp of when the object was last updated.

• amount (integer)
  The total amount that will be debited in cents (e.g. 100 cents to debit $1.00).
  Example: 5000

• application_id (string)
  The ID of the Application associated with the Subscription.

• billing_cycle_day (integer,null)
  The day of the month on which the Subscription is billed. Only applies to subscriptions with a monthly billing cycle. Accepted values are 1 to 31.
  Example: 1

• billing_interval (string)
  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
    Enum: "BIMONTHLY", "BIWEEKLY", "BIYEARLY", "DAILY", "MONTHLY", "QUARTERLY", "SEMIYEARLY", "TRIYEARLY", "WEEKLY", "YEARLY"

• buyer_details (object)
  An object containing details about the buyer.

• buyer_details.identity_id (string)
  The identity ID of the buyer.

• buyer_details.instrument_id (any)
  The ID of the Payment Instrument from which the subscription payments get debited.

• buyer_details.requested_delivery_methods (array)
  A list of requested delivery methods. Each method specifies
  the type of delivery and the destination(s) where the receipt should be sent.

• buyer_details.requested_delivery_methods.type (string, required)
  The method of receipt delivery.
  Enum: "EMAIL", "SMS", "PRINT"

• buyer_details.requested_delivery_methods.destinations (array, required)
  A list of destination addresses or identifiers where the receipt should be sent.

• buyer_details.shipping_address (object,null)

• buyer_details.shipping_address.line1 (string,null, required)
  First line of the address (max 35 characters).

• buyer_details.shipping_address.line2 (string,null)
  Second line of the address (max 35 characters).

• buyer_details.shipping_address.city (string,null, required)
  City (max 20 characters).

• buyer_details.shipping_address.region (string,null, required)
  2-letter State code.

• buyer_details.shipping_address.postal_code (string,null, required)
  Zip or Postal code (max 7 characters).

• buyer_details.shipping_address.country (string,null, required)
  Enum for country codes.

• canceled_via (string,null)
  If the subscription was canceled, this field shows how the cancellation was initiated.
  Possible values:

  • MERCHANT
  • AUTOMATED_OVERDUE
  • SUPPORT
    Enum: "MERCHANT", "AUTOMATED_OVERDUE", "SUPPORT"

• currency (string)
  ISO 4217 3-letter currency code.
  Enum: "USD", "CAD"

• expires_at (string)
  The date-time that the Subscription expires if total_billing_intervals is set for the Subscription.

• first_charge_at (string)
  Timestamp when the first Transfer will occur.

• linked_to (string)
  The ID of the Merchant resource that you wish to link to the Subscription.

• linked_type (string)
  The type of the resource that is specified in the linked_to field.
  Enum: "MERCHANT"

• next_billing_date (object)
  Details when the next Transfer will occur.

• next_billing_date.year (integer)
  The year the next Transfer will occur.

• next_billing_date.month (integer)
  The month the next Transfer will occur.

• next_billing_date.day (integer)
  The day the next Transfer will occur.

• nickname (string)
  A human-readable name for the resource.

• start_subscription_at (string)
  Indicates that the subscription is scheduled to begin in the future.

• state (string)
  The state of the Subscription.
  Enum: "ACTIVE", "CANCELED", "EXPIRED", "NOT_STARTED", "PAST_DUE"

• subscription_details (object)
  An object containing subscription details.

• subscription_details.collection_method (string, required)
  The method by which subscription payments are collected.
  Enum: "BILL_AUTOMATICALLY"

• subscription_details.send_invoice (boolean)
  Whether to send the user an invoice.

• subscription_details.send_receipt (boolean)
  Whether to send the user a receipt.

• subscription_details.trial_details (object)
  Object containing trial details.

• subscription_details.trial_details.interval_type (string)
  The unit of time for the trial period.
  Enum: "DAY", "WEEK", "MONTH", "YEAR"

• subscription_details.trial_details.interval_count (integer)
  The number of intervals of interval_type used to describe the duration of the trial.

• subscription_details.trial_details.trial_started_at (string,null)
  A timestamp indicating when the trial period began.

• subscription_details.trial_details.trial_expected_start_at (string)
  A timestamp indicating when the trial period is expected to start.

• subscription_details.trial_details.trial_expected_end_at (string)
  A timestamp indicating when the trial period ends.

• subscription_details.discount_phase_details (object)
  Object containing discount phase details.

• subscription_details.discount_phase_details.amount (integer)
  The discounted amount (in cents) that the buyer is charged during the discount phase.

• subscription_details.discount_phase_details.billing_interval_count (integer)
  The number of billing intervals the discount applies.

• subscription_details.discount_phase_details.discount_phase_started_at (string,null)
  A timestamp indicating when the discount phase began.

• subscription_details.discount_phase_details.discount_phase_expected_start_at (string)
  A timestamp indicating when the discount phase is expected to start.

• subscription_details.discount_phase_details.discount_phase_expected_end_at (string)
  A timestamp indicating when the discount phase is expected to end.

• subscription_details.notification_preferences (object)
  Object containing notification preferences.

• subscription_details.notification_preferences.send_confirmation (boolean)
  Whether to send a confirmation email to the user.

• subscription_link_id (string,null)
  The ID of the Subscription Link that created the Subscription.

• subscription_phase (string)
  Indicates the period within a subscription where specific rules apply.
  Enum: "EVERGREEN", "DISCOUNT", "FIXED", "NONE", "TRIAL"

• subscription_plan_id (string)
  The ID of a Subscription Plan from which this Subscription was created.
  Example: "subscription_plan_ctBbJ1ihsC8Hpju4RQfZE"

• tags (object,null)
  Include up to 50 key: value pairs to annotate requests with custom metadata.

• total_billing_intervals (integer)
  The total number of billing intervals for the Subscription.

• _links (object)
  An object containing link(s) relevant to the request.

• _links.self (object)
  Link to the resource that was used in the request.

• _links.self.href (string)

Response 401 fields (application/json):

• total (integer, required)
  Total number of errors returned.

• _embedded (object, required)
  Container for embedded error objects.

• _embedded.errors (array)
  List of individual error objects.

• _embedded.errors.code (string)
  The error code.

• _embedded.errors.logref (string)
  A log reference identifier for the error.

• _embedded.errors.message (string)
  A human-friendly error message.

• _embedded.errors._links (object)
  Links related to this error.

• _embedded.errors._links.self (object)
  Link to the resource related to the error.

• _embedded.errors._links.self.href (string)
  URL of the related resource.

Response 403 fields (application/json):

• total (integer, required)
  Total number of errors returned.

• _embedded (object, required)
  Container for embedded error objects.

• _embedded.errors (array)
  List of individual error objects.

• _embedded.errors.code (string)
  The error code.

• _embedded.errors.logref (string)
  A log reference identifier for the error.

• _embedded.errors.message (string)
  A human-friendly error message.

• _embedded.errors._links (object)
  Links related to this error.

• _embedded.errors._links.self (object)
  Link to the resource related to the error.

• _embedded.errors._links.self.href (string)
  URL of the related resource.

Response 404 fields (application/json):

• total (integer, required)
  Total number of errors returned.

• _embedded (object, required)
  Container for embedded error objects.

• _embedded.errors (array)
  List of individual error objects.

• _embedded.errors.code (string)
  The error code.

• _embedded.errors.logref (string)
  A log reference identifier for the error.

• _embedded.errors.message (string)
  A human-friendly error message.

• _embedded.errors._links (object)
  Links related to this error.

• _embedded.errors._links.self (object)
  Link to the resource related to the error.

• _embedded.errors._links.self.href (string)
  URL of the related resource.

Response 406 fields (application/json):

• total (integer, required)
  Total number of errors returned.

• _embedded (object, required)
  Container for embedded error objects.

• _embedded.errors (array)
  List of individual error objects.

• _embedded.errors.code (string)
  The error code.

• _embedded.errors.logref (string)
  A log reference identifier for the error.

• _embedded.errors.message (string)
  A human-friendly error message.

• _embedded.errors._links (object)
  Links related to this error.

• _embedded.errors._links.self (object)
  Link to the resource related to the error.

• _embedded.errors._links.self.href (string)
  URL of the related resource.