Create a Subscription

Create a Subscription to charge a Payment Instrument on a recurring schedule. Without a trial period, the first Transfer is created within 60 minutes of the Subscription being created.

Optional features:

• Trial period - include trial_details to delay the first charge; first_charge_at in the response shows when billing begins. If the Subscription is based on a Subscription Plan, trial_details do not override those from the plan.
• Discount phase - include discount_phase_details with a reduced amount and a billing_interval_count to apply a discounted price for a set number of cycles before full billing resumes. If the Subscription is based on a Subscription Plan, discount_phase_details do not override the plan's values.
• Subscription Plan - provide a subscription_plan_id to base the Subscription on a Subscription Plan template (inherits amount, billing_interval, and more). You cannot set the amount field when you use a Subscription Plan.
• Future start - set start_subscription_at to a future timestamp; the Subscription starts in state NOT_STARTED with subscription_phase: NONE.
• Billing cycle day - set billing_cycle_day to control which day of the month billing occurs for monthly-cycle subscriptions (e.g., MONTHLY, BIMONTHLY, QUARTERLY, SEMIYEARLY, YEARLY, BIYEARLY, TRIYEARLY). If the start date doesn't match the billing cycle day, the first invoice is prorated.
• Fixed length - set total_billing_intervals to expire the Subscription after a fixed number of billing cycles.

Endpoint: POST /subscriptions

Security: BasicAuth

Header parameters:

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

• Content-Type (string)
  The data type being sent in the request body must be application/json.
  Example: "application/json"

Response 201 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 (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.
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

• 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: "ABW", "AFG", "AGO", "AIA", "ALA", "ALB", "AND", "ARE", "ARG", "ARM", "ASM", "ATA", "ATF", "ATG", "AUS", "AUT", "AZE", "BDI", "BEL", "BEN", "BES", "BFA", "BGD", "BGR", "BHR", "BHS", "BIH", "BLM", "BLR", "BLZ", "BMU", "BOL", "BRA", "BRB", "BRN", "BTN", "BVT", "BWA", "CAF", "CAN", "CCK", "CHE", "CHL", "CHN", "CIV", "CMR", "COD", "COG", "COK", "COL", "COM", "CPV", "CRI", "CUB", "CUW", "CXR", "CYM", "CYP", "CZE", "DEU", "DJI", "DMA", "DNK", "DOM", "DZA", "ECU", "EGY", "ERI", "ESH", "ESP", "EST", "ETH", "FIN", "FJI", "FLK", "FRA", "FRO", "FSM", "GAB", "GBR", "GEO", "GGY", "GHA", "GIB", "GIN", "GLP", "GMB", "GNB", "GNQ", "GRC", "GRD", "GRL", "GTM", "GUF", "GUM", "GUY", "HKG", "HMD", "HND", "HRV", "HTI", "HUN", "IDN", "IMN", "IND", "IOT", "IRL", "IRN", "IRQ", "ISL", "ISR", "ITA", "JAM", "JEY", "JOR", "JPN", "KAZ", "KEN", "KGZ", "KHM", "KIR", "KNA", "KOR", "KWT", "LAO", "LBN", "LBR", "LBY", "LCA", "LIE", "LKA", "LSO", "LTU", "LUX", "LVA", "MAC", "MAF", "MAR", "MCO", "MDA", "MDG", "MDV", "MEX", "MHL", "MKD", "MLI", "MLT", "MMR", "MNE", "MNG", "MNP", "MRT", "MSR", "MTQ", "MUS", "MWI", "MYS", "MYT", "NAM", "NCL", "NER", "NFK", "NGA", "NIC", "NIU", "NLD", "NOR", "NPL", "NRU", "NZL", "OMN", "PAK", "PAN", "PCN", "PER", "PHL", "PLW", "PNG", "POL", "PRI", "PRK", "PRT", "PRY", "PSE", "PYF", "QAT", "REU", "ROU", "RUS", "RWA", "SAU", "SDN", "SEN", "SGP", "SGS", "SHN", "SJM", "SLB", "SLE", "SLV", "SMR", "SOM", "SPM", "SRB", "SSD", "STP", "SUR", "SVK", "SVN", "SWE", "SWZ", "SXM", "SYC", "SYR", "TCA", "TCD", "TGO", "THA", "TJK", "TKL", "TKM", "TLS", "TON", "TTO", "TUN", "TUR", "TUV", "TWN", "TZA", "UGA", "UKR", "UMI", "URY", "USA", "UZB", "VAT", "VCT", "VEN", "VGB", "VIR", "VNM", "VUT", "WLF", "WSM", "XKX", "YEM", "ZAF", "ZMB", "ZWE"

• canceled_via (string,null)
  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.
  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 (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 (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)

  • next_billing_date.month (integer)
  • next_billing_date.day (integer)

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

• start_subscription_at (string)
  Indicates that the subscription is scheduled to begin in the future. The timestamp specifies the exact start date for subscription billing.

• state (string)
  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. 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. Currently, automatic billing of the Payment Instrument is the only available method. 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. After this period, the buyer is charged the full amount from the Subscription.

• 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.

• 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. Enum: "EVERGREEN", "DISCOUNT", "FIXED", "NONE", "TRIAL"

• subscription_plan_id (string)
  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. Example: "subscription_plan_ctBbJ1ihsC8Hpju4RQfZE"

• tags (object,null)
  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_intervals (integer)
  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.

• _links (object)
  An object containing link(s) relevant to the request. You can store these links for follow-up requests.

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

• _links.self.href (string)