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

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}](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): 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's balance by a user. Currently, only credits can modify a subscription's balance.

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

## Update a Subscription Balance Entry

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