# Subscriptions

A `Subscription` resource represents a recurring charge to a `Payment Instrument` at regular intervals. Subscribers can be buyers, customers, or merchants. <br><br>
When creating a `Subscription`, you have the option to use a `Subscription Plan`.

**Limitations**:
- *Supported countries*: At this time, subscriptions are available in the United States.<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 resource to charge a Payment Instrument regularly. 

If there is no trial period, the subscription will create a Transfer shortly after creation (within 60 minutes).

The following options are available when creating a subscription.

### Adding a trial period

You can create a subscription with a trial period by providing trial_details in the request body. After creating a subscription, a Transfer will occur after the trial period has elapsed. The first_charge_at property in the response determines when the transfer will take place.

### Adding a discount phase

To apply a discount, include discount_phase_details in the request body. Set discount_phase_details.amount as the discounted price and discount_phase_details.billing_interval_count to specify how many billing intervals the discount applies. After this period, the customer is charged the full amount from the Subscription.

### Using a Subscription Plan

Think of a Subscription Plan as a template for the Subscription resource. When creating a subscription, you can use a Subscription Plan by providing a subscription_plan_id. Doing so lets you base a subscription on existing values for amount, billing_interval, and more.

### Future Subscription

Schedule a subscription by setting start_subscription_at to a future timestamp. The response will show subscription_phase as NONE and state as NOT_STARTED, indicating it has not started. This applies to both subscriptions with or without a subscription plan.

### Fixed-Length Subscription

You can set a subscription to expire by specifying the total_billing_intervals, which indicates the number of recurring billing cycles in months or weeks. You can set subscriptions created from subscription plans to expire.

### Card Validation with $0 Authorization

When creating a subscription using a card-type Payment Instrument, Finix performs a $0 Authorization to validate the card. This check confirms that the card is active and verifies the billing address and security code (AVS and CVV).

If the card fails validation, the API returns a 422 Unprocessable Entity error and the subscription is not created. This protects against invalid or risky cards, helping reduce failed payments and fraud.

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