Subscriptions

A Subscription resource represents a recurring charge to a Payment Instrument at regular intervals. Subscribers can be buyers, customers, or merchants.

Subscriptions are supported for USA and Canadian merchants.

When creating a Subscription, you have the option to use a Subscription Plan.

Limitations:

• Supported countries: Subscriptions are available in the United States and Canada.
  
• Supported payment methods: Subscriptions currently support recurring card payments and recurring bank account payments (ACH in the USA).
  
• Approved merchants: At this time, only approved merchants with one of the following processors can create subscriptions: DUMMY_V1 and FINIX_V1.
  
  

Create a Subscription

• POST /subscriptions: 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.

{% admonition type="info" %} When the Payment Instrument › type is PAYMENT_CARD, APPLE_PAY, or GOOGLE_PAY, Finix runs a $0.01 Authorization to validate the card (AVS and CVV). If validation fails, the API returns 422 and the Subscription is not created. {% /admonition %}

List Subscriptions

• GET /subscriptions: Retrieve a list of Subscription resources.

Fetch a Subscription

• GET /subscriptions/{subscription_id}: Retrieve the details of a previously created Subscription.

Update Subscription

• PUT /subscriptions/{subscription_id}: Update an existing Subscription resource, typically used for subscriptions created without a Subscription Plan. Note that you can only update specific resource fields.

Two common use cases for updating a Subscription are:

Updating the payment amount

This operation allows for adjusting the payment amount, such as when a subscriber decides to donate more or less money to a charity or upgrade/downgrade a product or service.

Updating billing details

If the subscriber wishes to change their payment details, you can update the buyer_details.instrument_id property with a new [Payment Instrument].

Cancel a Subscription

• DELETE /subscriptions/{subscription_id}: Cancel a Subscription.

Create a Subscription Balance Entry

• POST /subscriptions/{subscription_id}/subscription_balance_entries: Create a Subscription Balance Entry. A Subscription Balance Entry represents a credit applied to a Subscription.

List Subscription Balance Entries

• GET /subscriptions/{subscription_id}/subscription_balance_entries: Retrieve a list of Subscription Balance Entry resources to view a timeline of all changes to a Subscription balance by a user. Currently, only credits can modify a Subscription balance.

Update Subscription Balance Entry

• PUT /subscriptions/{subscription_id}/subscription_balance_entries/{subscription_balance_entry_id}: Update the tags for an existing Subscription Balance Entry.