# 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.<br>
- *Supported payment methods*: Subscriptions currently support recurring card payments and recurring bank account payments (<a href="/guides/online-payments/bank-payments/ach-direct-debits">ACH</a> in the USA).<br>
- *Approved merchants*: At this time, only approved merchants with one of the following processors can create subscriptions: `DUMMY_V1` and `FINIX_V1`.<br><br>

**Related Guides:**
- [Creating Subscriptions](/guides/subscriptions)
- [Creating Subscription Plans](/guides/subscriptions/subscription-plans)
- [Recurring Payments Guidelines](/guides/subscriptions/recurring-payment-guidelines)


## Create a Subscription

 - [POST /subscriptions](https://docs.finix.com/api/subscriptions/createsubscription.md): 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](https://docs.finix.com/api/subscriptions/listsubscriptions.md): Retrieve a list of Subscription resources.

For details on how to query endpoints using the available parameters, see Query Parameters.

## Fetch a Subscription

 - [GET /subscriptions/{subscription_id}](https://docs.finix.com/api/subscriptions/getsubscription.md): Retrieve the details of a previously created Subscription.

## Update Subscription

 - [PUT /subscriptions/{subscription_id}](https://docs.finix.com/api/subscriptions/updatesubscription.md): Update an existing Subscription resource, typically used for subscriptions created without a Subscription Plan. Note that you can only update specific resource fields.

Common use cases for updating a Subscription include:

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

### Updating the billing cycle day

Set billing_cycle_day to change the day of the month the Subscription bills. Invoices that have already been issued do not change, and the current billing period completes at the full amount. On the next billing date, the buyer is charged a prorated amount that bridges the gap to the new billing cycle day, then full billing resumes. To learn more, see Billing cycle day.

## Cancel a Subscription

 - [DELETE /subscriptions/{subscription_id}](https://docs.finix.com/api/subscriptions/removesubscription.md): Cancel a Subscription.

## Create a Subscription Balance Entry

 - [POST /subscriptions/{subscription_id}/subscription_balance_entries](https://docs.finix.com/api/subscriptions/createsubscriptionbalanceentry.md): 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](https://docs.finix.com/api/subscriptions/listsubscriptionbalanceentries.md): 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.

For details on how to query endpoints using the available parameters, see Query Parameters.

## Update Subscription Balance Entry

 - [PUT /subscriptions/{subscription_id}/subscription_balance_entries/{subscription_balance_entry_id}](https://docs.finix.com/api/subscriptions/updatesubscriptionbalanceentry.md): Update the tags for an existing Subscription Balance Entry.