Subscriptions

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

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.
  • Supported payment methods: Subscriptions currently support recurring card payments and recurring bank account payments (ACH in 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

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.

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.

Request
header Parameters
Finix-Version
string
Default: 2018-01-01

Specify the API version of your request. For more details, see Versioning.

Example: 2022-02-01
Request Body schema: application/json
amount
integer <int64>

The total amount that will be debited in cents (e.g. 100 cents to debit $1.00).

currency
required
string

ISO 4217 3-letter currency code. Currently, the only currency supported is USD.

Value: "USD"
linked_to
required
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
required
string

The type of the resource that is specified in the linked_to field.

Value: "MERCHANT"
nickname
string

A human-readable name for the resource.

billing_interval
required
string

How often the subscriber is billed.

Enum: "DAILY" "WEEKLY" "MONTHLY" "QUARTERLY" "YEARLY"
subscription_plan_id
string

The ID of the Subscription Plan from which to create the Subscription.

required
object

An object containing subscription details.

required
object

An object containing details about the subscriber.

Responses
201

A single Subscription object

401

Authentication information is missing or invalid

403

Forbidden

404

Object does not exist

422

Invalid field

post/subscriptions
Request samples 
Response samples 
application/json
{
  • "id": "subscription_cd7VyFticmvMmxJwv2aMB",
  • "created_at": "2024-07-12T10:25:25.50Z",
  • "updated_at": "2024-07-12T10:25:25.50Z",
  • "first_charge_at": "2024-07-12T10:25:25.00Z",
  • "amount": 2,
  • "buyer_details": {
    • "identity_id": "IDe8MHoq9cevVGocJwpAN8tR",
    • "instrument_id": "PIh5syYGDw2SnvFjPVLcV3oD"
    },
  • "currency": "USD",
  • "linked_to": "MUaC9hbNvRwBoCJzqrjWk69N",
  • "linked_type": "MERCHANT",
  • "nickname": "Gym membership",
  • "billing_interval": "YEARLY",
  • "subscription_details": {
    • "collection_method": "BILL_AUTOMATICALLY",
    • "send_invoice": false,
    • "send_receipt": false,
    • "trial_details": {
      }
    },
  • "subscription_phase": "TRIAL",
  • "state": "ACTIVE",
  • "subscription_plan_id": null,
  • "_links": {}
}
List Subscriptions
Retrieve a list of Subscription resources. 


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


Request 
query Parameters
amount
integer
Filter by an amount equal to the given value.


 
 Example:  amount=100
amount.lt
integer
Filter by an amount less than.


 
 Example:  amount.lt=100
amount.gt
integer
Filter by an amount greater than.


 
 Example:  amount.gt=100
limit
integer
The numbers of items to return.


 
 Example:  limit=10
after_cursor
string
Return every resource created after the cursor value.


 
 Example:  after_cursor=TRnasXQ5AmjsLnPMwnme7TL4
before_cursor
string
Return every resource created before the cursor value.


 
 Example:  before_cursor=TRnasXQ5AmjsLnPMwnme7TL4
header Parameters
Finix-Version
string
 Default:  2018-01-01
Specify the API version of your request. For more details, see Versioning.


 
 Example:  2022-02-01
Responses 
200
List of Subscription objects


401
Authentication information is missing or invalid


403
Forbidden


404
Object does not exist


422
Invalid field


get/subscriptions
Request samples 
curl "https://finix.sandbox-payments-api.com/subscriptions" \
  -H "Finix-Version: 2022-02-01" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
Response samples 
application/json
{
  • "_embedded": {
    • "subscriptions": [
      ]
    },
  • "_links": {},
  • "page": {
    • "limit": 100,
    • "next_cursor": "ZTyLnqRtGpWxuTMeOVjPbR7y"
    }
}
Fetch a Subscription
Retrieve the details of a previously created Subscription.


Request 
path Parameters
subscription_id
required
string
The ID of the Subscription.


 
header Parameters
Finix-Version
string
 Default:  2018-01-01
Specify the API version of your request. For more details, see Versioning.


 
 Example:  2022-02-01
Responses 
200
A single Subscription object


401
Authentication information is missing or invalid


403
Forbidden


404
Object does not exist


422
Invalid field


get/subscriptions/{subscription_id}
Request samples 
curl "https://finix.sandbox-payments-api.com/subscriptions/subscription_cdhqdXjTQfg62wHzJ41g5" \
  -H "Finix-Version: 2022-02-01" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
Response samples 
application/json
{
  • "id": "subscription_cd7VyFticmvMmxJwv2aMB",
  • "created_at": "2024-07-12T10:25:25.50Z",
  • "updated_at": "2024-07-12T10:25:25.50Z",
  • "first_charge_at": "2024-07-12T10:25:25.00Z",
  • "amount": 2,
  • "buyer_details": {
    • "identity_id": "IDe8MHoq9cevVGocJwpAN8tR",
    • "instrument_id": "PIh5syYGDw2SnvFjPVLcV3oD"
    },
  • "currency": "USD",
  • "linked_to": "MUaC9hbNvRwBoCJzqrjWk69N",
  • "linked_type": "MERCHANT",
  • "nickname": "Gym membership",
  • "billing_interval": "YEARLY",
  • "subscription_details": {
    • "collection_method": "BILL_AUTOMATICALLY",
    • "send_invoice": false,
    • "send_receipt": false,
    • "trial_details": {
      }
    },
  • "subscription_phase": "TRIAL",
  • "state": "ACTIVE",
  • "subscription_plan_id": null,
  • "_links": {}
}
Update a Subscription
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.


Request 
path Parameters
subscription_id
required
string
The ID of the Subscription.


 
header Parameters
Finix-Version
string
 Default:  2018-01-01
Specify the API version of your request. For more details, see Versioning.


 
 Example:  2022-02-01
Request Body schema: application/json
amount
integer <int64> 
The total amount that will be debited in cents (e.g. 100 cents to debit $1.00).


 
nickname
string
A human-readable name for the resource.


 
object
An object containing details about the subscriber.


 
Responses 
200
A single Subscription object


401
Authentication information is missing or invalid


403
Forbidden


404
Object does not exist


422
Invalid field


put/subscriptions/{subscription_id}
Request samples 
curl "https://finix.sandbox-payments-api.com/subscriptions/subscription_cdhqdXjTQfg62wHzJ41g5" \
  -H "Content-Type: application/json" \
  -H "Finix-Version: 2022-02-01" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
  -X PUT \
  -d '
  {
    "amount": 6299,
    "nickname": "Video streaming service",
    "buyer_details": {
      "instrument_id": "PIh5syYGDw2SnvFjPVLcV3oD"
    }
  }'
Response samples 
application/json
{
  • "id": "subscription_cd7VyFticmvMmxJwv2aMB",
  • "created_at": "2024-07-12T10:25:25.50Z",
  • "updated_at": "2024-07-12T10:25:25.50Z",
  • "first_charge_at": "2024-07-12T10:25:25.00Z",
  • "amount": 2,
  • "buyer_details": {
    • "identity_id": "IDe8MHoq9cevVGocJwpAN8tR",
    • "instrument_id": "PIh5syYGDw2SnvFjPVLcV3oD"
    },
  • "currency": "USD",
  • "linked_to": "MUaC9hbNvRwBoCJzqrjWk69N",
  • "linked_type": "MERCHANT",
  • "nickname": "Gym membership",
  • "billing_interval": "YEARLY",
  • "subscription_details": {
    • "collection_method": "BILL_AUTOMATICALLY",
    • "send_invoice": false,
    • "send_receipt": false,
    • "trial_details": {
      }
    },
  • "subscription_phase": "TRIAL",
  • "state": "ACTIVE",
  • "subscription_plan_id": null,
  • "_links": {}
}
Cancel a Subscription
Cancel a Subscription.


Request 
path Parameters
subscription_id
required
string
The ID of the Subscription.


 
header Parameters
Finix-Version
string
 Default:  2018-01-01
Specify the API version of your request. For more details, see Versioning.


 
 Example:  2022-02-01
Responses 
204
No content


401
Authentication information is missing or invalid


403
Forbidden


404
Object does not exist


delete/subscriptions/{subscription_id}
Request samples 
curl "https://finix.sandbox-payments-api.com/subscriptions/subscription_cdhqdXjTQfg62wHzJ41g" \
  -H "Finix-Version: 2022-02-01" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
  -X DEL
Response samples 
application/json
{
  • "total": 0,
  • "_embedded": {
    • "errors": [
      ]
    }
}