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,
}

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
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": [
      ]
    },
  • "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,
}

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,
}

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": [
      ]
    }
}