Create a Subscription

Finix API Reference Copy - Copy for LLM Copy page as Markdown for LLMs - View as Markdown\ \ Open this page as Markdown - Open in ChatGPT\ \ Get insights from ChatGPT - Open in Claude\ \ Get insights from Claude - Connect to Cursor Install MCP server on Cursor - Connect to VS Code Install MCP server on VS Code

The Finix API is resource oriented, relying heavily on common REST principles. Our API uses JSON encoded requests and responses.

You will receive separate Sandbox and Live accounts, as well as corresponding API credentials to access the Finix API.

link to section/Authentication Authentication

To communicate with the Finix API, you must authenticate your requests via HTTP Basic Authentication with a username:password combination, which you can get from your Finix Dashboard. If you do not have a Dashboard yet, you can test our APIs with the Sandbox credentials below.

Parameter	Value
Sandbox Username	`USsRhsHYZGBPnQw8CByJyEQW`
Sandbox Password	`8a14c2f9-d94b-4c72-8f5c-a62908e5b30e`

Request Format

curl "https://finix.sandbox-payments-api.com/" \
    -H "Content-Type: application/json" \
    -H "Finix-Version: 2022-02-01" \
    -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e

link to section/Environments Environments

Finix provides two environments with distinct base URLs to make API requests.

A Sandbox environment for developing and testing your integration.
A Live environment for processing payments.

These environments are entirely separate and do not share API Credentials.

Environment	Endpoint URL
Sandbox	`https://finix.sandbox-payments-api.com`
Live	`https://finix.live-payments-api.com`

Live Access

To get access to the Live environment, please reach out to your Finix point-of-contact.

link to section/HTTP-Codes-and-Errors HTTP Codes and Errors

Finix uses HTTP codes to communicate whether requests succeeded or failed. Requests to Finix's API return responses within less than one second.

However, communications between card networks and processors can increase response latency. Additionally, response latency for card-present devices can be higher depending on how quickly buyers complete the transaction on payment terminals.

Due of this, requests to the Finix API have a maximum timeout of 5 minutes.

For more details, see Error Codes. Also, you can test for specific errors and responses.

Code	Definition	Explanation
`400`	Bad Request	We could not parse your request. Verify you are providing valid JSON.
`401`	Unauthorized	We could not authenticate your request. Verify your `username` and `password` are correct.
`402`	Upstream Processor Error	Errors caused by 3rd-party service(s).
`403`	Forbidden	Your credentials do not have the correct permissions to perform the request.
`404`	Not Found	We could not find the specified resource.
`405`	Method Not Allowed	The specified resource does not support the HTTP Method used to submit the request.
`406`	Not Acceptable	The server could accept the submitted request. Confirm how the request was formatted and submitted.
`409`	Conflict	The submitted request conflicts with the current state of the server.
`422`	Unprocessable Entity	The parameters were valid, but the request failed. Usually, the error involves misunderstanding of how to perform the request (e.g., creating a transfer with a seller that is not-yet-approved).
`500`	Internal Server Error	We had a problem with our server. Try again later.

link to section/Idempotent-Requests Idempotent Requests

The Authorization and Transfer resources both have an idempotency_id field. Use this field to ensure the API Request is performed only once.

Why is this important? We've all experienced a checkout page that hangs on a request or payment, and feared that if we refresh or submit the payment again, we'd be charged twice.

Finix removes this ambiguity with the idempotency_id. You or the user can generate a unique ID that can be included as an idempotency_id with the usual request payload. If anyone attempts a request with the same idempotency_id, the response will raise an exception.

By passing an idempotency_id in the body of your requests, you can be rest assured that when you create an Authorization or Transfer, the user will be protected from potential network issues.

idempotency_id is available on the following three endpoints:

/transfers
/authorizations
/transfers/{id}/reversals

`idempotency_id` scope

idempotency_id checks against previous requests made on the same endpoint.

link to section/Query-Parameters Query Parameters

Every Finix resource (e.g., Authorizations, Transfers) can be listed and reviewed using GET requests. Additionally, every endpoint has query parameters available to help you filter the resources that are returned.

See the following example of how to query the Transfers endpoint for Transfer resources with type: DEBIT.

Query Parameter Example

curl "https://finix.sandbox-payments-api.com/transfers?type=DEBIT" \
    -H "Finix-Version: 2022-02-01" \
    -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e

link to section/Tags Tags

Many Finix resources (e.g., Authorization, Transfer) let you include tags to add key-value metadata to your Finix API resources. For example, when creating a Transfer, you might include customerId: Customer123 to tag the Transfer with your internal customer ID. You can update tags as many times as needed, as well as filter resources by tags.

Tags Example

{
    ...,
    "tags": {
        "card-type": "business card",
        "order_number": "H-1257",
        "customer_order_reference": "order1234",
        "item_type": "hardware",
        "vendor": "finix"
    }
}

The tags object accepts up to 50 key: value pairs to annotate resources with custom metadata.

Maximum character length for individual keys is 40.
Maximum character length for individual values is 500.

Special Characters

Finix does not allow special characters on tags (e.g., \, ,, ", ')

link to section/Versioning Versioning

As Finix improves our products and features, we will make changes to our APIs. When breaking changes are made to Finix's API, we may release a new dated API version.

The API version your requests use controls how API responses and webhooks behave (for example, the values you see in responses and the parameters you can include in requests). For more information, see Versioning.

link to section/Postman-Collection Postman Collection

Finix has a Postman collection to help in your development. You can fork it using the button below.

Overview

URL https://finix.com

Finix support@finix.com

Languages

cURL

Servers

Sandbox server

https://finix.sandbox-payments-api.com

link to Authorizations Authorizations

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

An Authorization (also known as a card hold) reserves a specific amount on a card to be captured (i.e. debited) at a later date, usually within seven days. When an Authorization is captured it produces a Transfer resource.

Related Guides:

Operations

post

/authorizations

get

/authorizations

get

/authorizations/{authorization_id}

put

/authorizations/{authorization_id}

put

/authorizations/{authorization_id_void_to}

+ Show

link to Compliance Forms Compliance Forms

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

To process payments, your Merchants must validate their compliance with PCI DSS requirements annually. To do this, your Merchants must attest to PCI Self-Assessment Questionnaire (SAQ) compliance forms.

Related Guides:

Operations

get

/compliance_forms/{compliance_form_id}

put

/compliance_forms/{compliance_form_id}

get

/compliance_forms

+ Show

link to Devices Devices

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

A Device resource represents a Point-of-Sale terminal. Devices are used for In-Person transactions.

Related Guides:

In-Person Payments

Operations

get

/devices

get

/devices/{device_id}

put

/devices/{device_id}

get

/devices/{device_id_connection}

get

/devices/{device_id}/device_metrics

post

/merchants/{merchant_id}/devices

+ Show

link to Disputes Disputes

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

Disputes, also known as chargebacks, are customer-disputed charges. A core part of the dispute lifecycle is the ability for a Merchant to upload evidence supporting their side.

Related Guides:

Managing Disputes

Operations

get

/disputes

get

/disputes/{dispute_id}

put

/disputes/{dispute_id}

post

/disputes/{dispute_id}/evidence

get

/disputes/{dispute_id}/evidence

get

/disputes/{dispute_id}/evidence/{evidence_id}

put

/disputes/{dispute_id}/evidence/{evidence_id}

delete

/disputes/{dispute_id}/evidence/{evidence_id}

Show4more...

+ Show

link to Fees Fees

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

A Fee is a charge levied against a Merchant. It represents how a platform charges its sellers for all various types of Fees.

Operations

get

/fees

post

/fees

get

/fees/{fee_id}

put

/fees/{fee_id}

+ Show

link to Fee Profiles Fee Profiles

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

A fee_profiles represents a pricing scheme that automatically applies fees to each transaction. Changes to fee_profiles go into effect immediately.

Related Guides:

Merchant Fee Profiles

Operations

post

/fee_profiles

get

/fee_profiles

get

/fee_profiles/{fee_profile_id}

+ Show

link to Files Files

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

Use Finix's File API to upload and manage files for your merchants.

Related Guides:

Operations

post

/files

get

/files

get

/files/{file_id}

get

/files/{file_id}/external_links

post

/files/{file_id}/external_links

post

/files/{file_id}/upload

get

/files/{file_id}/download

get

/files/{file_id}/external_links/{external_link_id}

+ Show

link to Identities Identities

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

An Identity resource represents either a person or business in Finix. You'll create an Identity to onboard your sellers, and verify the different owners.

Related Guides:

Operations

post

/identities

get

/identities

get

/identities/{identity_id}

put

/identities/{identity_id}

post

/identities/{identity_id}/associated_identities

get

/identities/{identity_id}/associated_identities

get

/identities/{identity_id}/merchants

+ Show

link to Merchants Merchants

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

A Merchant resource represents the entity's merchant account on a processor. Your Merchant must be APPROVED to process payments.

Related Guides:

Operations

post

/identities/{identity_id}/merchants

get

/merchants

get

/merchants/{merchant_id}

put

/merchants/{merchant_id}

post

/merchants/{merchant_id}/verifications

+ Show

link to Onboarding Forms Onboarding Forms

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

Finix offers and hosts pre-built onboarding forms that you can use to collect onboarding and identity verification information from your users.

Related Guides:

Onboarding via the API

Operations

post

/onboarding_forms

get

/onboarding_forms/{onboarding_form_id}

post

/onboarding_forms/{onboarding_form_id}/links

+ Show

link to Payment Instruments Payment Instruments

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

A Payment Instrument resource represents the payment details of a credit card or bank account. Payment details get tokenized multiple times and each tokenization produces a unique Payment Instrument.

A Payment Instrument is associated with a single Identity. Once a Payment Instrument is created, the Identity it's associated with can't be changed.

Including an address when creating a Payment Instrument can lower interchange on credit card transactions.

Related Guides:

Operations

post

/payment_instruments

get

/payment_instruments

get

/payment_instruments/{payment_instrument_id}

put

/payment_instruments/{payment_instrument_id}

get

/payment_instruments/{payment_instrument_id}/instrument_history

put

/payment_instruments/{payment_instrument_id_verify}

post

/payment_instruments/{payment_instrument_id_verify}/verifications

post

/apple_pay_sessions

+ Show

link to Payment Instrument Associations Payment Instrument Associations

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

In Finix, Payment Instruments are tied to the owner of that account. For example, Payment Instruments tied to buyer will be the cards used for purchases while Payment Instruments tied to a Merchant are the bank accounts where they receive settlements.

Therefore when billing events occur that are tied to a buyer's Payment Instrument (e.g. enrolling in account updater, using Plaid for tokenization, etc) Finix cannot automatically map those fees to a specific Merchant. By default, these costs are instead charged to your Application (e.g. the Platform, Marketplace, Vertical Saas owner's account) and will be deducted from your residual. If you wish to monetize these offerings or pass the fees on to your Merchant you must explicitly link the buyers Payment Instrument to a Merchant resource using the Payment Instrument Association

Operations

post

/payment_instrument_associations

get

/payment_instrument_associations

get

/payment_instrument_associations/{payment_instrument_association_id}

put

/payment_instrument_associations/{payment_instrument_association_id}

+ Show

link to Settlements Settlements

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

A Settlement represents a collection (i.e. batch) of Settlement Entries that will get paid out to a specific Merchant. A Settlement Entry can represent a Transfer, custom Fee, or Split Transfer.

Related Guides:

Payouts

Operations

get

/settlements

get

/settlements/{settlement_id}

put

/settlements/{settlement_id}

get

/settlements/{settlement_id}/entries

delete

/settlements/{settlement_id}/entries

get

/settlements/{settlement_id}/fees

get

/settlements/{settlement_id}/funding_transfers

delete

/settlements/{settlement_id}/transfers

Show3more...

+ Show

link to Settlement Queue Entries Settlement Queue Entries

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

A Settlement Queue Entry resource represents an entry in the settlement queue used to track when and how a transfer is queued to be processed.

If a merchant's settlement_queue_mode is set to MANUAL, all transfers will have a Settlement Queue Entry created and will not be placed into settlement until the Settlement Queue Entry is explicitly released.

Related Guides:

Account Structures and Settlements

Operations

get

/settlement_queue_entries

put

/settlement_queue_entries

get

/settlement_queue_entries/{settlement_queue_entry_id}

+ Show

link to Split Transfers Split Transfers

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

Transactions can be split among different merchants. A Split Transfer shows how funds from a split Transfer were distributed into a merchant's Settlement.

Related Guides:

Split Transactions

Operations

get

/fees

get

/split_transfers

get

/split_transfers/{split_transfer_id}

+ Show

link to Transfers Transfers

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

A Transfer represents any flow of funds either to or from a Payment Instrument. All payments in Finix are represented by a Transfer.

Related Guides:

Operations

post

/transfers

get

/transfers

get

/transfers/{transfer_id}

put

/transfers/{transfer_id}

post

/transfers/{transfer_id}/reversals

get

/transfers/{transfer_id}/reversals

+ Show

link to Users Users

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

A User resource represents a pair of API keys which are used to perform authenticated requests against the Finix API. When making authenticated requests via HTTP basic access authentication the ID of a User resource maps to the username, while the password corresponds to the password (i.e. secret key).

The password field for a User resource is only returned during the initial creation. Any following GET requests to the resource returns the password field as null for security purposes.

Related Guides:

Account Structure

Operations

get

/users

get

/users/{user_id}

put

/users/{user_id}

+ Show

link to Verifications Verifications

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

Verifications are used to verify Merchants and Payment Instruments.

For Merchants, a verification represents an attempt to onboard and underwrite a Merchant.

For Payment Instruments, a verification represents getting additional information from the card brands to verify a card is eligible for push to card.

Related Guides:

Operations

get

/merchants/{merchant_id}/verifications

get

/verifications

get

/verifications/{verification_id}

+ Show

link to Webhooks Webhooks

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

Webhooks let you set up integrations that subscribe to automated notifications (events) on the Finix API. When an enabled event occurs, Finix sends an HTTP POST payload to the Webhook's configured URL.

Related Guides:

Operations

post

/webhooks

get

/webhooks

get

/webhooks/{webhook_id}

put

/webhooks/{webhook_id}

+ Show

link to Gateway Integrations Gateway Integrations

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

A Gateway Integration represents a connection to a third-party payment gateway. At this time, the only supported gateway is Cybersource.

Cybersource is a Visa-owned payment gateway that integrates with Finix to provide secure payment processing and fraud management. Finix handles merchant onboarding and payouts through a unified API, while Cybersource manages gateway routing and fraud prevention for global card acceptance.

Operations

post

/gateway_integrations

get

/gateway_integrations

get

/gateway_integrations/{gateway_integration_id}

+ Show

link to Receipts Receipts

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

The Receipt resource generates a receipt for Transfers or Authorizations. You can then send the Receipt via Email, SMS, or use the information from the Receipt to send it yourself.

Related Guides:

Receipts for Online Payments

Operations

post

/receipts

get

/receipts/{receipt_id}

post

/receipts/{receipt_id}/delivery_attempts

get

/receipts/{receipt_id}/delivery_attempts

+ Show

link to Subscriptions Subscriptions

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

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.
Supported payment methods: Subscriptions currently support recurring card payments and recurring bank account payments ( ACH in the USA).
Approved merchants: At this time, only approved merchants with one of the following processors can create subscriptions: DUMMY_V1 and FINIX_V1.

Related Guides:

Operations

post

/subscriptions

get

/subscriptions

get

/subscriptions/{subscription_id}

put

/subscriptions/{subscription_id}

delete

/subscriptions/{subscription_id}

post

/subscriptions/{subscription_id}/subscription_balance_entries

get

/subscriptions/{subscription_id}/subscription_balance_entries

put

/subscriptions/{subscription_id}/subscription_balance_entries/{subscription_balance_entry_id}

link to Create a Subscription Create a Subscription

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

link to /subscriptions/createsubscription#subscriptions/createsubscription/request RequestExpand all

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.

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.

SecurityView security details

BasicAuth

link to /subscriptions/createsubscription#subscriptions/createsubscription/request/header Headers

link to /subscriptions/createsubscription#subscriptions/createsubscription/t=request&in=header&path=finix-version Finix-Version string

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

Default2022-02-01

Example:2022-02-01

link to /subscriptions/createsubscription#subscriptions/createsubscription/t=request&in=header&path=content-type Content-Type string

The data type being sent in the request body must be application/json.

Example:application/json

link to /subscriptions/createsubscription#subscriptions/createsubscription/request/body Bodyapplication/jsonrequired

One of:

Subscription - Minimal Fields

Subscription - Minimal Fields Subscription - All Fields Subscription - Billing Cycle Day Subscription - Discount Phase Subscription - Fixed-Length Subscription - Future Start Date Subscription - Trial Period Subscription - Subscription Plan - Minimal Fields Subscription - Subscription Plan - All Fields Subscription - Subscription Plan - Fixed-Length Subscription - Subscription Plan - Future Start Date

link to /subscriptions/createsubscription#subscriptions/createsubscription/t=request&path=&oneof=0/amount amount integer (int64) required

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

Example:5000

link to /subscriptions/createsubscription#subscriptions/createsubscription/t=request&path=&oneof=0/billing_interval billing_interval string required

How often the buyer is billed. The possible billing intervals are as follows:

BIMONTHLY: every 2 months
BIWEEKLY: every 2 weeks
BIYEARLY: every 2 years
DAILY: every day
MONTHLY: every month
QUARTERLY: each quarter
SEMIYEARLY: twice a year
TRIYEARLY: every 3 years
WEEKLY: every week
YEARLY: every year

Enum"BIMONTHLY""BIWEEKLY""BIYEARLY""DAILY""MONTHLY""QUARTERLY""SEMIYEARLY""TRIYEARLY""WEEKLY""YEARLY"

Example:"MONTHLY"

link to /subscriptions/createsubscription#subscriptions/createsubscription/t=request&path=&oneof=0/buyer_details buyer_details object required

An object containing details about the buyer.

link to /subscriptions/createsubscription#subscriptions/createsubscription/t=request&path=&oneof=0/buyer_details/identity_id buyer_details.identity_id string required

The identity ID of the buyer.

Example:"IDtEnKsZyJNUGK83ZTx4C45S"

link to /subscriptions/createsubscription#subscriptions/createsubscription/t=request&path=&oneof=0/buyer_details/instrument_id buyer_details.instrument_id any required

The ID of the Payment Instrument from which the subscription payments get debited.

Example:"PImXAVgkKVshKWWHUk4xXbve"

link to /subscriptions/createsubscription#subscriptions/createsubscription/t=request&path=&oneof=0/currency currency string required

ISO 4217 3-letter currency code.

Enum"CAD""USD"

link to /subscriptions/createsubscription#subscriptions/createsubscription/t=request&path=&oneof=0/linked_to linked_to string required

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

Example:"MUcgYZswyRfqSSbvMsxuaHxZ"

link to /subscriptions/createsubscription#subscriptions/createsubscription/t=request&path=&oneof=0/linked_type linked_type string required

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

Value"MERCHANT"

Example:"MERCHANT"

link to /subscriptions/createsubscription#subscriptions/createsubscription/t=request&path=&oneof=0/subscription_details subscription_details object required

An object containing subscription details.

link to /subscriptions/createsubscription#subscriptions/createsubscription/t=request&path=&oneof=0/subscription_details/collection_method subscription_details.collection_method string required

The method by which subscription payments are collected. Currently, automatically billing the Payment Instrument is the only method available.

Value"BILL_AUTOMATICALLY"

Example:"BILL_AUTOMATICALLY"

post

/subscriptions

Sandbox server https://finix.sandbox-payments-api.com/subscriptions

cURL

Subscription - Minimal Fields

curl -i -X POST \
  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \
  https://finix.sandbox-payments-api.com/subscriptions \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -d '{
    "amount": 19900,
    "billing_interval": "MONTHLY",
    "buyer_details": {
      "identity_id": "IDtEnKsZyJNUGK83ZTx4C45S",
      "instrument_id": "PImXAVgkKVshKWWHUk4xXbve"
    },
    "currency": "USD",
    "linked_to": "MUcgYZswyRfqSSbvMsxuaHxZ",
    "linked_type": "MERCHANT",
    "subscription_details": {
      "collection_method": "BILL_AUTOMATICALLY"
    }
  }'

link to /subscriptions/createsubscription#subscriptions/createsubscription/response&c=201 Responses

Expand all

Subscription

link to /subscriptions/createsubscription#subscriptions/createsubscription/response&c=201/headers Headers

link to /subscriptions/createsubscription#subscriptions/createsubscription/t=response&c=201&path=date date string

A response header indicating the date and time of the API request.

Example:"Tue, 08 Jul 2025 17:38:01 GMT"

link to /subscriptions/createsubscription#subscriptions/createsubscription/t=response&c=201&path=finix-apiuser-role finix-apiuser-role string

This response header indicating the role of the user who sent the API request.

Enum"ROLE_PLATFORM""ROLE_PARTNER""ROLE_MERCHANT"

Example:"ROLE_PARTNER"

link to /subscriptions/createsubscription#subscriptions/createsubscription/t=response&c=201&path=x-request-id x-request-id string

This response header provides a unique identifier for the API request.

Example:"055972f6534f92a896fbb61b11313ebb"

link to /subscriptions/createsubscription#subscriptions/createsubscription/response&c=201/body Bodyapplication/json

link to /subscriptions/createsubscription#subscriptions/createsubscription/t=response&c=201&path=id id string non-empty

The ID of the resource.

link to /subscriptions/createsubscription#subscriptions/createsubscription/t=response&c=201&path=created_at created_at string (date-time)

Timestamp of when the object was created.

link to /subscriptions/createsubscription#subscriptions/createsubscription/t=response&c=201&path=updated_at updated_at string (date-time)

Timestamp of when the object was last updated.

link to /subscriptions/createsubscription#subscriptions/createsubscription/t=response&c=201&path=amount amount integer (int64)

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

Example:5000

link to /subscriptions/createsubscription#subscriptions/createsubscription/t=response&c=201&path=application_id application_id string

The ID of the Application associated with the Subscription.

link to /subscriptions/createsubscription#subscriptions/createsubscription/t=response&c=201&path=billing_cycle_day billing_cycle_day integer or null [ 1 .. 31 ]

The day of the month on which the Subscription is billed. Only applies to subscriptions with a monthly billing cycle (e.g., MONTHLY, BIMONTHLY, QUARTERLY, SEMIYEARLY, YEARLY, BIYEARLY, TRIYEARLY).

If the specified day doesn't exist in a given month (e.g., April 31), the subscription is billed on the last valid day of that month.

Accepted values are 1 to 31.

Example:1

link to /subscriptions/createsubscription#subscriptions/createsubscription/t=response&c=201&path=billing_interval billing_interval string

How often the buyer is billed. The possible billing intervals are as follows:

Enum"BIMONTHLY""BIWEEKLY""BIYEARLY""DAILY""MONTHLY""QUARTERLY""SEMIYEARLY""TRIYEARLY""WEEKLY""YEARLY"

Example:"MONTHLY"

link to /subscriptions/createsubscription#subscriptions/createsubscription/t=response&c=201&path=buyer_details buyer_details object

An object containing details about the buyer.

+Show 4 properties

link to /subscriptions/createsubscription#subscriptions/createsubscription/t=response&c=201&path=canceled_via canceled_via string or null

If the subscription was canceled, this field shows how the cancellation was initiated.

Possible values:

MERCHANT - The customer (merchant) canceled the subscription themselves. The linked_to field indicates the related Merchant.
AUTOMATED_OVERDUE - The subscription was canceled by the overdue system.
SUPPORT - The subscription was canceled by Finix Support.

Enum"MERCHANT""AUTOMATED_OVERDUE""SUPPORT"

link to /subscriptions/createsubscription#subscriptions/createsubscription/t=response&c=201&path=currency currency string

ISO 4217 3-letter currency code.

Enum"USD""CAD"

link to /subscriptions/createsubscription#subscriptions/createsubscription/t=response&c=201&path=expires_at expires_at string (date-time)

The date-time that the Subscription expires if total_billing_intervals is set for the Subscription.

link to /subscriptions/createsubscription#subscriptions/createsubscription/t=response&c=201&path=first_charge_at first_charge_at string (date-time)

Timestamp when the first Transfer will occur.

link to /subscriptions/createsubscription#subscriptions/createsubscription/t=response&c=201&path=linked_to linked_to string

At this time, only approved merchants with one of the following processors are valid:

DUMMY_V1
FINIX_V1

link to /subscriptions/createsubscription#subscriptions/createsubscription/t=response&c=201&path=linked_type linked_type string

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

Value"MERCHANT"

link to /subscriptions/createsubscription#subscriptions/createsubscription/t=response&c=201&path=next_billing_date next_billing_date object

Details when the next Transfer will occur.

+Show 3 properties

link to /subscriptions/createsubscription#subscriptions/createsubscription/t=response&c=201&path=nickname nickname string

A human-readable name for the resource.

link to /subscriptions/createsubscription#subscriptions/createsubscription/t=response&c=201&path=start_subscription_at start_subscription_at string (date-time)

Indicates that the subscription is scheduled to begin in the future. The timestamp specifies the exact start date for subscription billing.

link to /subscriptions/createsubscription#subscriptions/createsubscription/t=response&c=201&path=state state string

The state of the Subscription.

The NOT_STARTED state occurs when the subscription has not yet started, typically indicated by a start_subscription_at timestamp set during creation.
A subscription in the PAST_DUE state is unpaid but has not yet been canceled.

Enum"ACTIVE""CANCELED""EXPIRED""NOT_STARTED""PAST_DUE"

link to /subscriptions/createsubscription#subscriptions/createsubscription/t=response&c=201&path=subscription_details subscription_details object

An object containing subscription details.

+Show 6 properties

link to /subscriptions/createsubscription#subscriptions/createsubscription/t=response&c=201&path=subscription_link_id subscription_link_id string or null

The ID of the Subscription Link that created the Subscription.

link to /subscriptions/createsubscription#subscriptions/createsubscription/t=response&c=201&path=subscription_phase subscription_phase string

Indicates the period within a subscription where specific rules apply.

EVERGREEN - The buyer is billed continuously for the subscription until the subscription is canceled.
DISCOUNT - The buyer receives a discounted price for a limited billing interval, after which the customer is charged the full subscription amount.
FIXED state - Applicable to fixed-length subscriptions.
NONE - Indicates that when the start_subscription_at timestamp is set during subscription creation, the subscription is not yet in any phase, and billing has not started.
TRIAL - The period during which the buyer is not billed; after this phase, the buyer will begin being billed.

Enum"EVERGREEN""DISCOUNT""FIXED""NONE""TRIAL"

link to /subscriptions/createsubscription#subscriptions/createsubscription/t=response&c=201&path=subscription_plan_id subscription_plan_id string

The ID of a Subscription Plan from which this Subscription was created. When provided, the plan's amount, billing_interval, and other defaults are inherited.

Example:"subscription_plan_ctBbJ1ihsC8Hpju4RQfZE"

link to /subscriptions/createsubscription#subscriptions/createsubscription/t=response&c=201&path=tags tags object or null

Include up to 50 key: value pairs to annotate requests with custom metadata.

Maximum character length for individual keys is 40.
Maximum character length for individual values is 500.(For example, order_number: 25, item_type: produce, department: sales)

+Show property

link to /subscriptions/createsubscription#subscriptions/createsubscription/t=response&c=201&path=total_billing_intervals total_billing_intervals integer

The total number of billing intervals for the Subscription. This represents the total count of recurring billing cycles, such as months or weeks, depending on the billing frequency.

link to /subscriptions/createsubscription#subscriptions/createsubscription/t=response&c=201&path=_links_links object

An object containing link(s) relevant to the request. You can store these links for follow-up requests.

+Show property

Response

application/json

Subscription - Minimal Fields

{
  "id": "subscription_cxe8cii53VTHqk5Q1SqP6",
  "created_at": "2026-02-17T18:36:16.36Z",
  "updated_at": "2026-02-17T18:36:16.36Z",
  "application_id": "APc9vhYcPsRuTSpKD9KpMtPe",
  "first_charge_at": "2026-02-17T18:36:16.00Z",
  "next_billing_date": {
    "year": 2026,
    "month": 2,
    "day": 17
  },
  "amount": 19900,
  "buyer_details": {
    "identity_id": "IDtEnKsZyJNUGK83ZTx4C45S",
    "instrument_id": "PImXAVgkKVshKWWHUk4xXbve",
    "requested_delivery_methods": [],
    "shipping_address": null
  },
  "currency": "USD",
  "linked_to": "MUcgYZswyRfqSSbvMsxuaHxZ",
  "linked_type": "MERCHANT",
  "nickname": null,
  "billing_interval": "MONTHLY",
  "subscription_details": {
    "collection_method": "BILL_AUTOMATICALLY",
    "send_invoice": false,
    "send_receipt": false,
    "trial_details": null,
    "discount_phase_details": null,
    "notification_preferences": { … }
  },
  "subscription_phase": "EVERGREEN",
  "state": "ACTIVE",
  "subscription_plan_id": null,
  "start_subscription_at": "2026-02-17T18:35:16.102Z",
  "total_billing_intervals": null,
  "expires_at": null,
  "canceled_via": null,
  "tags": {
    "order_number": "21DFASJSAKAS"
  },
  "subscription_link_id": null,
  "_links": {
    "self": { … }
  }
}

Was this helpful?

link to List Subscriptions List Subscriptions

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

link to /subscriptions/listsubscriptions#subscriptions/listsubscriptions/request Request

Retrieve a list of Subscription resources.

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

SecurityView security details

BasicAuth

link to /subscriptions/listsubscriptions#subscriptions/listsubscriptions/request/query Query

link to /subscriptions/listsubscriptions#subscriptions/listsubscriptions/t=request&in=query&path=after_cursor after_cursor string

Return every resource created after the cursor value.

link to /subscriptions/listsubscriptions#subscriptions/listsubscriptions/t=request&in=query&path=amount.gt amount.gt integer

Filter by an amount greater than.

Example:amount.gt=100

link to /subscriptions/listsubscriptions#subscriptions/listsubscriptions/t=request&in=query&path=amount.gte amount.gte integer

Filter by an amount greater than or equal.

Example:amount.gte=100

link to /subscriptions/listsubscriptions#subscriptions/listsubscriptions/t=request&in=query&path=amount.lt amount.lt integer

Filter by an amount less than.

Example:amount.lt=100

link to /subscriptions/listsubscriptions#subscriptions/listsubscriptions/t=request&in=query&path=amount.lte amount.lte integer

Filter by an amount less than or equal.

Example:amount.lte=100

link to /subscriptions/listsubscriptions#subscriptions/listsubscriptions/t=request&in=query&path=amount amount integer

Filter by an amount equal to the given value.

Example:amount=100

link to /subscriptions/listsubscriptions#subscriptions/listsubscriptions/t=request&in=query&path=application_id application_id string

Filter by Application ID.

Example:application_id=APc9vhYcPsRuTSpKD9KpMtPe

link to /subscriptions/listsubscriptions#subscriptions/listsubscriptions/t=request&in=query&path=before_cursor before_cursor string

Return every resource created before the cursor value.

link to /subscriptions/listsubscriptions#subscriptions/listsubscriptions/t=request&in=query&path=billing_interval billing_interval string

Filter by billing frequency.

Enum"BIMONTHLY""BIWEEKLY""BIYEARLY""DAILY""MONTHLY""QUARTERLY""SEMIYEARLY""TRIYEARLY""WEEKLY""YEARLY"

Example:billing_interval=MONTHLY

link to /subscriptions/listsubscriptions#subscriptions/listsubscriptions/t=request&in=query&path=buyer_identity_id buyer_identity_id string

Filter by the Buyer Identity's ID.

Example:buyer_identity_id=ID6Qm3BQUxGFcCWZ185TS8sn

link to /subscriptions/listsubscriptions#subscriptions/listsubscriptions/t=request&in=query&path=created_at.gte created_at.gte string (date-time)

Filter where created_at is after the given date.

Example:created_at.gte=2022-09-27T11:21:23

link to /subscriptions/listsubscriptions#subscriptions/listsubscriptions/t=request&in=query&path=created_at.lte created_at.lte string (date-time)

Filter where created_at is before the given date.

Example:created_at.lte=2026-09-27T11:21:23

link to /subscriptions/listsubscriptions#subscriptions/listsubscriptions/t=request&in=query&path=id id string

Filter by id.

link to /subscriptions/listsubscriptions#subscriptions/listsubscriptions/t=request&in=query&path=limit limit integer <= 100

The numbers of items to return.

Example:limit=10

link to /subscriptions/listsubscriptions#subscriptions/listsubscriptions/t=request&in=query&path=linked_to linked_to string

Filter subscriptions linked to a specific Merchant.

Example:linked_to=MUcgYZswyRfqSSbvMsxuaHxZ

link to /subscriptions/listsubscriptions#subscriptions/listsubscriptions/t=request&in=query&path=nickname nickname string

Filter by the Subscription name (exact match).

link to /subscriptions/listsubscriptions#subscriptions/listsubscriptions/t=request&in=query&path=nickname.like nickname.like string

Filter by the Subscription name (partial match).

link to /subscriptions/listsubscriptions#subscriptions/listsubscriptions/t=request&in=query&path=state state string

Filter by state:

ACTIVE
CANCELED
EXPIRED
NOT_STARTED
PAST DUE

Example:state=NOT_STARTED

link to /subscriptions/listsubscriptions#subscriptions/listsubscriptions/t=request&in=query&path=subscription_link_id subscription_link_id string

Filter subscriptions created by a Subscription Link.

Example:subscription_link_id=subscription_link_cvTp2K5CNH9Lr4BqCphcM

link to /subscriptions/listsubscriptions#subscriptions/listsubscriptions/t=request&in=query&path=subscription_plan_id subscription_plan_id string

Filter subscriptions that were created using a specific Subscription Plan.

Example:subscription_plan_id=subscription_plan_ciLn19pSKDTFoehtH7ET

link to /subscriptions/listsubscriptions#subscriptions/listsubscriptions/t=request&in=query&path=tags.key tags.key string

Filter by the tag's key. For more information, see Tags.

Example:tags.key=card_type

link to /subscriptions/listsubscriptions#subscriptions/listsubscriptions/t=request&in=query&path=tags.value tags.value string

Filter by the tag's value. For more information, see Tags.

Example:tags.value=business_card

link to /subscriptions/listsubscriptions#subscriptions/listsubscriptions/t=request&in=query&path=updated_at.gte updated_at.gte string (date-time)

Filter where updated_at is after the given date.

Example:updated_at.gte=2022-09-27T11:21:23

link to /subscriptions/listsubscriptions#subscriptions/listsubscriptions/t=request&in=query&path=updated_at.lte updated_at.lte string (date-time)

Filter where updated_at is before the given date.

Example:updated_at.lte=2026-09-27T11:21:23

link to /subscriptions/listsubscriptions#subscriptions/listsubscriptions/request/header Headers

link to /subscriptions/listsubscriptions#subscriptions/listsubscriptions/t=request&in=header&path=finix-version Finix-Version string

Default2022-02-01

Example:2022-02-01

get

/subscriptions

Sandbox server https://finix.sandbox-payments-api.com/subscriptions

curl

curl "https://finix.sandbox-payments-api.com/subscriptions" \
-H "Content-Type: application/json" \
-H "Finix-Version: 2022-02-01" \
-u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda

link to /subscriptions/listsubscriptions#subscriptions/listsubscriptions/response&c=200 Responses

Expand all

List of Subscription resources

link to /subscriptions/listsubscriptions#subscriptions/listsubscriptions/response&c=200/headers Headers

link to /subscriptions/listsubscriptions#subscriptions/listsubscriptions/t=response&c=200&path=date date string

A response header indicating the date and time of the API request.

Example:"Tue, 08 Jul 2025 17:38:01 GMT"

link to /subscriptions/listsubscriptions#subscriptions/listsubscriptions/t=response&c=200&path=finix-apiuser-role finix-apiuser-role string

This response header indicating the role of the user who sent the API request.

Enum"ROLE_PLATFORM""ROLE_PARTNER""ROLE_MERCHANT"

Example:"ROLE_PARTNER"

link to /subscriptions/listsubscriptions#subscriptions/listsubscriptions/t=response&c=200&path=x-request-id x-request-id string

This response header provides a unique identifier for the API request.

Example:"055972f6534f92a896fbb61b11313ebb"

link to /subscriptions/listsubscriptions#subscriptions/listsubscriptions/response&c=200/body Bodyapplication/json

link to /subscriptions/listsubscriptions#subscriptions/listsubscriptions/t=response&c=200&path=page page object

Details the page that's returned.

+Show 2 properties

link to /subscriptions/listsubscriptions#subscriptions/listsubscriptions/t=response&c=200&path=_embedded_embedded object

+Show property

link to /subscriptions/listsubscriptions#subscriptions/listsubscriptions/t=response&c=200&path=_links_links object

+Show 2 properties

Response

application/json

{
  "_embedded": {
    "subscriptions": [ … ]
  },
  "_links": {
    "self": { … },
    "next": { … }
  },
  "page": {
    "limit": 100,
    "next_cursor": "subscription_ciLmyAfbiM45NGxzu3YJK"
  }
}

Was this helpful?

link to Fetch a Subscription Fetch a Subscription

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

link to /subscriptions/getsubscription#subscriptions/getsubscription/request Request

Retrieve the details of a previously created Subscription.

SecurityView security details

BasicAuth

link to /subscriptions/getsubscription#subscriptions/getsubscription/request/path Path

link to /subscriptions/getsubscription#subscriptions/getsubscription/t=request&in=path&path=subscription_id subscription_id string required

The Subscription ID.

Example:subscription_cvTpAt87A4hncnuC4rkh6

link to /subscriptions/getsubscription#subscriptions/getsubscription/request/header Headers

link to /subscriptions/getsubscription#subscriptions/getsubscription/t=request&in=header&path=finix-version Finix-Version string

Default2022-02-01

Example:2022-02-01

get

/subscriptions/{subscription_id}

Sandbox server https://finix.sandbox-payments-api.com/subscriptions/{subscription\_id}

cURL

curl -i -X GET \
  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \
  https://finix.sandbox-payments-api.com/subscriptions/subscription_cvTpAt87A4hncnuC4rkh6 \
  -H 'Finix-Version: 2022-02-01'

link to /subscriptions/getsubscription#subscriptions/getsubscription/response&c=200 Responses

Expand all

A single Subscription

link to /subscriptions/getsubscription#subscriptions/getsubscription/response&c=200/headers Headers

link to /subscriptions/getsubscription#subscriptions/getsubscription/t=response&c=200&path=date date string

A response header indicating the date and time of the API request.

Example:"Tue, 08 Jul 2025 17:38:01 GMT"

link to /subscriptions/getsubscription#subscriptions/getsubscription/t=response&c=200&path=finix-apiuser-role finix-apiuser-role string

This response header indicating the role of the user who sent the API request.

Enum"ROLE_PLATFORM""ROLE_PARTNER""ROLE_MERCHANT"

Example:"ROLE_PARTNER"

link to /subscriptions/getsubscription#subscriptions/getsubscription/t=response&c=200&path=x-request-id x-request-id string

This response header provides a unique identifier for the API request.

Example:"055972f6534f92a896fbb61b11313ebb"

link to /subscriptions/getsubscription#subscriptions/getsubscription/response&c=200/body Bodyapplication/json

link to /subscriptions/getsubscription#subscriptions/getsubscription/t=response&c=200&path=id id string non-empty

The ID of the resource.

link to /subscriptions/getsubscription#subscriptions/getsubscription/t=response&c=200&path=created_at created_at string (date-time)

Timestamp of when the object was created.

link to /subscriptions/getsubscription#subscriptions/getsubscription/t=response&c=200&path=updated_at updated_at string (date-time)

Timestamp of when the object was last updated.

link to /subscriptions/getsubscription#subscriptions/getsubscription/t=response&c=200&path=amount amount integer (int64)

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

Example:5000

link to /subscriptions/getsubscription#subscriptions/getsubscription/t=response&c=200&path=application_id application_id string

The ID of the Application associated with the Subscription.

link to /subscriptions/getsubscription#subscriptions/getsubscription/t=response&c=200&path=billing_cycle_day billing_cycle_day integer or null [ 1 .. 31 ]

If the specified day doesn't exist in a given month (e.g., April 31), the subscription is billed on the last valid day of that month.

Accepted values are 1 to 31.

Example:1

link to /subscriptions/getsubscription#subscriptions/getsubscription/t=response&c=200&path=billing_interval billing_interval string

How often the buyer is billed. The possible billing intervals are as follows:

Enum"BIMONTHLY""BIWEEKLY""BIYEARLY""DAILY""MONTHLY""QUARTERLY""SEMIYEARLY""TRIYEARLY""WEEKLY""YEARLY"

Example:"MONTHLY"

link to /subscriptions/getsubscription#subscriptions/getsubscription/t=response&c=200&path=buyer_details buyer_details object

An object containing details about the buyer.

+Show 4 properties

link to /subscriptions/getsubscription#subscriptions/getsubscription/t=response&c=200&path=canceled_via canceled_via string or null

If the subscription was canceled, this field shows how the cancellation was initiated.

Possible values:

Enum"MERCHANT""AUTOMATED_OVERDUE""SUPPORT"

link to /subscriptions/getsubscription#subscriptions/getsubscription/t=response&c=200&path=currency currency string

ISO 4217 3-letter currency code.

Enum"USD""CAD"

link to /subscriptions/getsubscription#subscriptions/getsubscription/t=response&c=200&path=expires_at expires_at string (date-time)

The date-time that the Subscription expires if total_billing_intervals is set for the Subscription.

link to /subscriptions/getsubscription#subscriptions/getsubscription/t=response&c=200&path=first_charge_at first_charge_at string (date-time)

Timestamp when the first Transfer will occur.

link to /subscriptions/getsubscription#subscriptions/getsubscription/t=response&c=200&path=linked_to linked_to string

At this time, only approved merchants with one of the following processors are valid:

DUMMY_V1
FINIX_V1

link to /subscriptions/getsubscription#subscriptions/getsubscription/t=response&c=200&path=linked_type linked_type string

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

Value"MERCHANT"

link to /subscriptions/getsubscription#subscriptions/getsubscription/t=response&c=200&path=next_billing_date next_billing_date object

Details when the next Transfer will occur.

+Show 3 properties

link to /subscriptions/getsubscription#subscriptions/getsubscription/t=response&c=200&path=nickname nickname string

A human-readable name for the resource.

link to /subscriptions/getsubscription#subscriptions/getsubscription/t=response&c=200&path=start_subscription_at start_subscription_at string (date-time)

Indicates that the subscription is scheduled to begin in the future. The timestamp specifies the exact start date for subscription billing.

link to /subscriptions/getsubscription#subscriptions/getsubscription/t=response&c=200&path=state state string

The state of the Subscription.

Enum"ACTIVE""CANCELED""EXPIRED""NOT_STARTED""PAST_DUE"

link to /subscriptions/getsubscription#subscriptions/getsubscription/t=response&c=200&path=subscription_details subscription_details object

An object containing subscription details.

+Show 6 properties

link to /subscriptions/getsubscription#subscriptions/getsubscription/t=response&c=200&path=subscription_link_id subscription_link_id string or null

The ID of the Subscription Link that created the Subscription.

link to /subscriptions/getsubscription#subscriptions/getsubscription/t=response&c=200&path=subscription_phase subscription_phase string

Indicates the period within a subscription where specific rules apply.

Enum"EVERGREEN""DISCOUNT""FIXED""NONE""TRIAL"

link to /subscriptions/getsubscription#subscriptions/getsubscription/t=response&c=200&path=subscription_plan_id subscription_plan_id string

Example:"subscription_plan_ctBbJ1ihsC8Hpju4RQfZE"

link to /subscriptions/getsubscription#subscriptions/getsubscription/t=response&c=200&path=tags tags object or null

Include up to 50 key: value pairs to annotate requests with custom metadata.

+Show property

link to /subscriptions/getsubscription#subscriptions/getsubscription/t=response&c=200&path=total_billing_intervals total_billing_intervals integer

link to /subscriptions/getsubscription#subscriptions/getsubscription/t=response&c=200&path=_links_links object

An object containing link(s) relevant to the request. You can store these links for follow-up requests.

+Show property

Response

application/json

{
  "id": "subscription_czjuNwSvWAQiCfgguhKKd",
  "created_at": "2026-04-22T21:11:31.12Z",
  "updated_at": "2026-04-22T21:11:31.12Z",
  "amount": 19900,
  "application_id": "APc9vhYcPsRuTSpKD9KpMtPe",
  "billing_interval": "MONTHLY",
  "buyer_details": {
    "identity_id": "IDtEnKsZyJNUGK83ZTx4C45S",
    "instrument_id": "PImXAVgkKVshKWWHUk4xXbve",
    "requested_delivery_methods": [ … ],
    "shipping_address": { … }
  },
  "canceled_via": null,
  "currency": "USD",
  "expires_at": "2027-10-15T19:40:17.490Z",
  "first_charge_at": "2026-10-15T22:42:05.49Z",
  "has_usage_based_plan": false,
  "linked_to": "MUcgYZswyRfqSSbvMsxuaHxZ",
  "linked_type": "MERCHANT",
  "next_billing_date": {
    "year": 2026,
    "month": 10,
    "day": 15
  },
  "nickname": "Finflix Gold Package",
  "start_subscription_at": "2026-08-15T22:42:05.490Z",
  "state": "NOT_STARTED",
  "subscription_details": {
    "collection_method": "BILL_AUTOMATICALLY",
    "send_invoice": false,
    "send_receipt": false,
    "trial_details": { … },
    "discount_phase_details": { … },
    "notification_preferences": { … }
  },
  "subscription_link_id": null,
  "subscription_phase": "NONE",
  "subscription_plan_id": null,
  "tags": {
    "order_number": "21DFASJSAKAS"
  },
  "total_billing_intervals": 12,
  "_links": {
    "self": { … }
  }
}

Was this helpful?

link to Update Subscription Update Subscription

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

link to /subscriptions/updatesubscription#subscriptions/updatesubscription/request RequestExpand all

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:

link to section/Updating-the-payment-amount 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.

link to section/Updating-billing-details 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.

SecurityView security details

BasicAuth

link to /subscriptions/updatesubscription#subscriptions/updatesubscription/request/path Path

link to /subscriptions/updatesubscription#subscriptions/updatesubscription/t=request&in=path&path=subscription_id subscription_id string required

The Subscription ID.

Example: subscription_cvTpAt87A4hncnuC4rkh6

link to /subscriptions/updatesubscription#subscriptions/updatesubscription/request/body Bodyapplication/jsonrequired

One of:

Update SubscriptionUpdate Subscription - New Subscription Plan

link to /subscriptions/updatesubscription#subscriptions/updatesubscription/t=request&path=&oneof=0/amount amount integer (int64)

The total amount that will be debited in cents (e.g. 100 cents to debit $1.00). This field can be updated only for subscriptions not created from subscription plans.

link to /subscriptions/updatesubscription#subscriptions/updatesubscription/t=request&path=&oneof=0/billing_cycle_day billing_cycle_day integer or null [ 1 .. 31 ]

If the specified day doesn't exist in a given month (e.g., April 31), the subscription is billed on the last valid day of that month.

Accepted values are 1 to 31.

Example: 1

link to /subscriptions/updatesubscription#subscriptions/updatesubscription/t=request&path=&oneof=0/buyer_details buyer_details object

An object containing details about the buyer.

+Show 4 properties

link to /subscriptions/updatesubscription#subscriptions/updatesubscription/t=request&path=&oneof=0/nickname nickname string

A human-readable name for the resource.

link to /subscriptions/updatesubscription#subscriptions/updatesubscription/t=request&path=&oneof=0/subscription_details subscription_details object

An object containing subscription details.

+Show 2 properties

link to /subscriptions/updatesubscription#subscriptions/updatesubscription/t=request&path=&oneof=0/tags tags object or null

Include up to 50 key: value pairs to annotate requests with custom metadata.

Maximum character length for individual keys is 40.
Maximum character length for individual values is 500. (For example, order_number: 25, item_type: produce, department: sales)

+Show property

put

/subscriptions/{subscription_id}

Sandbox server https://finix.sandbox-payments-api.com/subscriptions/{subscription\_id}

cURL

Update Subscription

Update Subscription
Update Subscription - New Subscription Plan

curl -i -X PUT \
  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \
  https://finix.sandbox-payments-api.com/subscriptions/subscription_cvTpAt87A4hncnuC4rkh6 \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 12000,
    "buyer_details": {
      "instrument_id": "PIc6kMBvJB5CfHvBXRuRwwtU",
      "requested_delivery_methods": [\
        {\
          "destinations": [\
            "test@gmail.com"\
          ],\
          "type": "EMAIL"\
        }\
      ],
      "shipping_address": {
        "city": "Middletown",
        "country": "USA",
        "line1": "324 Oak Avenue",
        "line2": "Apartment 7",
        "postal_code": "19734",
        "region": "DE"
      }
    },
    "nickname": "Finflix Gold Package",
    "subscription_details": {
      "send_invoice": true,
      "send_receipt": true
    },
    "tags": {
      "package": "gold"
    }
  }'

link to /subscriptions/updatesubscription#subscriptions/updatesubscription/response&c=200 Responses

Expand all

A single Subscription

link to /subscriptions/updatesubscription#subscriptions/updatesubscription/response&c=200/headers Headers

link to /subscriptions/updatesubscription#subscriptions/updatesubscription/t=response&c=200&path=date date string

A response header indicating the date and time of the API request.

Example: "Tue, 08 Jul 2025 17:38:01 GMT"

link to /subscriptions/updatesubscription#subscriptions/updatesubscription/t=response&c=200&path=finix-apiuser-role finix-apiuser-role string

This response header indicating the role of the user who sent the API request.

Enum"ROLE_PLATFORM""ROLE_PARTNER""ROLE_MERCHANT"

Example: "ROLE_PARTNER"

link to /subscriptions/updatesubscription#subscriptions/updatesubscription/t=response&c=200&path=x-request-id x-request-id string

This response header provides a unique identifier for the API request.

Example: "055972f6534f92a896fbb61b11313ebb"

link to /subscriptions/updatesubscription#subscriptions/updatesubscription/response&c=200/body Bodyapplication/json

link to /subscriptions/updatesubscription#subscriptions/updatesubscription/t=response&c=200&path=id id string non-empty

The ID of the resource.

link to /subscriptions/updatesubscription#subscriptions/updatesubscription/t=response&c=200&path=created_at created_at string (date-time)

Timestamp of when the object was created.

link to /subscriptions/updatesubscription#subscriptions/updatesubscription/t=response&c=200&path=updated_at updated_at string (date-time)

Timestamp of when the object was last updated.

link to /subscriptions/updatesubscription#subscriptions/updatesubscription/t=response&c=200&path=amount amount integer (int64)

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

Example: 5000

link to /subscriptions/updatesubscription#subscriptions/updatesubscription/t=response&c=200&path=application_id application_id string

The ID of the Application associated with the Subscription.

link to /subscriptions/updatesubscription#subscriptions/updatesubscription/t=response&c=200&path=billing_cycle_day billing_cycle_day integer or null [ 1 .. 31 ]

If the specified day doesn't exist in a given month (e.g., April 31), the subscription is billed on the last valid day of that month.

Accepted values are 1 to 31.

Example: 1

link to /subscriptions/updatesubscription#subscriptions/updatesubscription/t=response&c=200&path=billing_interval billing_interval string

How often the buyer is billed. The possible billing intervals are as follows:

Enum"BIMONTHLY""BIWEEKLY""BIYEARLY""DAILY""MONTHLY""QUARTERLY""SEMIYEARLY""TRIYEARLY""WEEKLY""YEARLY"

Example: "MONTHLY"

link to /subscriptions/updatesubscription#subscriptions/updatesubscription/t=response&c=200&path=buyer_details buyer_details object

An object containing details about the buyer.

+Show 4 properties

link to /subscriptions/updatesubscription#subscriptions/updatesubscription/t=response&c=200&path=canceled_via canceled_via string or null

If the subscription was canceled, this field shows how the cancellation was initiated.

Possible values:

Enum"MERCHANT""AUTOMATED_OVERDUE""SUPPORT"

link to /subscriptions/updatesubscription#subscriptions/updatesubscription/t=response&c=200&path=currency currency string

ISO 4217 3-letter currency code.

Enum"USD""CAD"

link to /subscriptions/updatesubscription#subscriptions/updatesubscription/t=response&c=200&path=expires_at expires_at string (date-time)

The date-time that the Subscription expires if total_billing_intervals is set for the Subscription.

link to /subscriptions/updatesubscription#subscriptions/updatesubscription/t=response&c=200&path=first_charge_at first_charge_at string (date-time)

Timestamp when the first Transfer will occur.

link to /subscriptions/updatesubscription#subscriptions/updatesubscription/t=response&c=200&path=linked_to linked_to string

At this time, only approved merchants with one of the following processors are valid:

DUMMY_V1
FINIX_V1

link to /subscriptions/updatesubscription#subscriptions/updatesubscription/t=response&c=200&path=linked_type linked_type string

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

Value"MERCHANT"

link to /subscriptions/updatesubscription#subscriptions/updatesubscription/t=response&c=200&path=next_billing_date next_billing_date object

Details when the next Transfer will occur.

+Show 3 properties

link to /subscriptions/updatesubscription#subscriptions/updatesubscription/t=response&c=200&path=nickname nickname string

A human-readable name for the resource.

link to /subscriptions/updatesubscription#subscriptions/updatesubscription/t=response&c=200&path=start_subscription_at start_subscription_at string (date-time)

Indicates that the subscription is scheduled to begin in the future. The timestamp specifies the exact start date for subscription billing.

link to /subscriptions/updatesubscription#subscriptions/updatesubscription/t=response&c=200&path=state state string

The state of the Subscription.

Enum"ACTIVE""CANCELED""EXPIRED""NOT_STARTED""PAST_DUE"

link to /subscriptions/updatesubscription#subscriptions/updatesubscription/t=response&c=200&path=subscription_details subscription_details object

An object containing subscription details.

+Show 6 properties

link to /subscriptions/updatesubscription#subscriptions/updatesubscription/t=response&c=200&path=subscription_link_id subscription_link_id string or null

The ID of the Subscription Link that created the Subscription.

link to /subscriptions/updatesubscription#subscriptions/updatesubscription/t=response&c=200&path=subscription_phase subscription_phase string

Indicates the period within a subscription where specific rules apply.

Enum"EVERGREEN""DISCOUNT""FIXED""NONE""TRIAL"

link to /subscriptions/updatesubscription#subscriptions/updatesubscription/t=response&c=200&path=subscription_plan_id subscription_plan_id string

Example: "subscription_plan_ctBbJ1ihsC8Hpju4RQfZE"

link to /subscriptions/updatesubscription#subscriptions/updatesubscription/t=response&c=200&path=tags tags object or null

Include up to 50 key: value pairs to annotate requests with custom metadata.

+Show property

link to /subscriptions/updatesubscription#subscriptions/updatesubscription/t=response&c=200&path=total_billing_intervals total_billing_intervals integer

link to /subscriptions/updatesubscription#subscriptions/updatesubscription/t=response&c=200&path=_links_links object

An object containing link(s) relevant to the request. You can store these links for follow-up requests.

+Show property

Response

application/json

Update Subscription

Update Subscription
Update Subscription - New Subscription Plan

{
  "id": "subscription_cvTpAt87A4hncnuC4rkh6",
  "created_at": "2026-01-07T17:24:59.20Z",
  "updated_at": "2026-06-11T22:26:30.72Z",
  "amount": 12000,
  "application_id": "APc9vhYcPsRuTSpKD9KpMtPe",
  "billing_interval": "MONTHLY",
  "buyer_details": {
    "identity_id": "IDsbrL4KWzTRiZB3nNgoHR8q",
    "instrument_id": "PIc6kMBvJB5CfHvBXRuRwwtU",
    "requested_delivery_methods": [ … ],
    "shipping_address": { … }
  },
  "canceled_via": null,
  "currency": "USD",
  "expires_at": null,
  "first_charge_at": "2026-01-07T17:24:58.00Z",
  "has_usage_based_plan": false,
  "linked_to": "MUcgYZswyRfqSSbvMsxuaHxZ",
  "linked_type": "MERCHANT",
  "next_billing_date": {
    "year": 2026,
    "month": 7,
    "day": 7
  },
  "nickname": "Finflix Gold Package",
  "start_subscription_at": "2026-01-07T17:23:58.856Z",
  "state": "ACTIVE",
  "subscription_details": {
    "collection_method": "BILL_AUTOMATICALLY",
    "send_invoice": true,
    "send_receipt": true,
    "trial_details": null,
    "discount_phase_details": null,
    "notification_preferences": { … }
  },
  "subscription_link_id": "subscription_link_cvTp2K5CNH9Lr4BqCphcM",
  "subscription_phase": "EVERGREEN",
  "subscription_plan_id": "subscription_plan_cmsyQKfkpSEtUVfvxr9Dc",
  "tags": {
    "package": "gold"
  },
  "total_billing_intervals": null,
  "_links": {
    "self": { … }
  }
}

Was this helpful?

link to Cancel a Subscription Cancel a Subscription

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

link to /subscriptions/removesubscription#subscriptions/removesubscription/request Request

Cancel a Subscription.

SecurityView security details

BasicAuth

link to /subscriptions/removesubscription#subscriptions/removesubscription/request/path Path

link to /subscriptions/removesubscription#subscriptions/removesubscription/t=request&in=path&path=subscription_id subscription_id string required

The Subscription ID.

Example: subscription_cvTpAt87A4hncnuC4rkh6

link to /subscriptions/removesubscription#subscriptions/removesubscription/request/header Headers

link to /subscriptions/removesubscription#subscriptions/removesubscription/t=request&in=header&path=finix-version Finix-Version string

Default 2022-02-01

Example: 2022-02-01

delete

/subscriptions/{subscription_id}

Sandbox server https://finix.sandbox-payments-api.com/subscriptions/{subscription\_id}

cURL

curl -i -X DELETE \
  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \
  https://finix.sandbox-payments-api.com/subscriptions/subscription_cvTpAt87A4hncnuC4rkh6 \
  -H 'Finix-Version: 2022-02-01'

link to /subscriptions/removesubscription#subscriptions/removesubscription/response&c=204 Responses

Deleted. No resource to return.

Response

No content

Was this helpful?

link to Create a Subscription Balance Entry Create a Subscription Balance Entry

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

link to /subscriptions/createsubscriptionbalanceentry#subscriptions/createsubscriptionbalanceentry/request RequestExpand all

Create a Subscription Balance Entry. A Subscription Balance Entry represents a credit applied to a Subscription.

SecurityView security details

BasicAuth

link to /subscriptions/createsubscriptionbalanceentry#subscriptions/createsubscriptionbalanceentry/request/path Path

link to /subscriptions/createsubscriptionbalanceentry#subscriptions/createsubscriptionbalanceentry/t=request&in=path&path=subscription_id subscription_id string required

The ID of the Subscription.

Example: subscription_cvTpAt87A4hncnuC4rkh6

link to /subscriptions/createsubscriptionbalanceentry#subscriptions/createsubscriptionbalanceentry/request/header Headers

link to /subscriptions/createsubscriptionbalanceentry#subscriptions/createsubscriptionbalanceentry/t=request&in=header&path=finix-version Finix-Version string

Default 2022-02-01

Example: 2022-02-01

link to /subscriptions/createsubscriptionbalanceentry#subscriptions/createsubscriptionbalanceentry/t=request&in=header&path=content-type Content-Type string

The data type being sent in the request body must be application/json.

Example: application/json

link to /subscriptions/createsubscriptionbalanceentry#subscriptions/createsubscriptionbalanceentry/request/body Bodyapplication/jsonrequired

link to /subscriptions/createsubscriptionbalanceentry#subscriptions/createsubscriptionbalanceentry/t=request&path=amount amount integer (int64)

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

Example: 5000

link to /subscriptions/createsubscriptionbalanceentry#subscriptions/createsubscriptionbalanceentry/t=request&path=currency currency string

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

Value"USD"

link to /subscriptions/createsubscriptionbalanceentry#subscriptions/createsubscriptionbalanceentry/t=request&path=description description string

A description of the reason for the subscription credit. Does not support special characters.

link to /subscriptions/createsubscriptionbalanceentry#subscriptions/createsubscriptionbalanceentry/t=request&path=tags tags object or null

Include up to 50 key: value pairs to annotate requests with custom metadata.

+Show property

link to /subscriptions/createsubscriptionbalanceentry#subscriptions/createsubscriptionbalanceentry/t=request&path=type type string required

Will always be CREDIT.

Value"CREDIT"

post

/subscriptions/{subscription_id}/subscription_balance_entries

Sandbox server https://finix.sandbox-payments-api.com/subscriptions/{subscription\_id}/subscription\_balance\_entries

cURL

curl -i -X POST \
  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \
  https://finix.sandbox-payments-api.com/subscriptions/subscription_cvTpAt87A4hncnuC4rkh6/subscription_balance_entries \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -d '{
    "amount": 1000,
    "currency": "USD",
    "description": "Applying a credit since I accidentally overcharged this subscription.",
    "tags": {},
    "type": "CREDIT"
  }'

link to /subscriptions/createsubscriptionbalanceentry#subscriptions/createsubscriptionbalanceentry/response&c=201 Responses

Expand all

A single Subscription Balance Entry

link to /subscriptions/createsubscriptionbalanceentry#subscriptions/createsubscriptionbalanceentry/response&c=201/headers Headers

link to /subscriptions/createsubscriptionbalanceentry#subscriptions/createsubscriptionbalanceentry/t=response&c=201&path=date date string

A response header indicating the date and time of the API request.

Example: "Tue, 08 Jul 2025 17:38:01 GMT"

link to /subscriptions/createsubscriptionbalanceentry#subscriptions/createsubscriptionbalanceentry/t=response&c=201&path=finix-apiuser-role finix-apiuser-role string

This response header indicating the role of the user who sent the API request.

Enum"ROLE_PLATFORM""ROLE_PARTNER""ROLE_MERCHANT"

Example: "ROLE_PARTNER"

link to /subscriptions/createsubscriptionbalanceentry#subscriptions/createsubscriptionbalanceentry/t=response&c=201&path=x-request-id x-request-id string

This response header provides a unique identifier for the API request.

Example: "055972f6534f92a896fbb61b11313ebb"

link to /subscriptions/createsubscriptionbalanceentry#subscriptions/createsubscriptionbalanceentry/response&c=201/body Bodyapplication/json

link to /subscriptions/createsubscriptionbalanceentry#subscriptions/createsubscriptionbalanceentry/t=response&c=201&path=id id string non-empty

The ID of the resource.

link to /subscriptions/createsubscriptionbalanceentry#subscriptions/createsubscriptionbalanceentry/t=response&c=201&path=created_at created_at string (date-time)

Timestamp of when the object was created.

link to /subscriptions/createsubscriptionbalanceentry#subscriptions/createsubscriptionbalanceentry/t=response&c=201&path=updated_at updated_at string (date-time)

Timestamp of when the object was last updated.

link to /subscriptions/createsubscriptionbalanceentry#subscriptions/createsubscriptionbalanceentry/t=response&c=201&path=amount amount integer (int64)

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

Example: 5000

link to /subscriptions/createsubscriptionbalanceentry#subscriptions/createsubscriptionbalanceentry/t=response&c=201&path=currency currency string

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

Value"USD"

link to /subscriptions/createsubscriptionbalanceentry#subscriptions/createsubscriptionbalanceentry/t=response&c=201&path=description description string

Describes the circumstances for the subscription credit.

link to /subscriptions/createsubscriptionbalanceentry#subscriptions/createsubscriptionbalanceentry/t=response&c=201&path=subscription_id subscription_id string

The Subscription that was credited.

link to /subscriptions/createsubscriptionbalanceentry#subscriptions/createsubscriptionbalanceentry/t=response&c=201&path=type type string

The value of this field will always be CREDIT.

link to /subscriptions/createsubscriptionbalanceentry#subscriptions/createsubscriptionbalanceentry/t=response&c=201&path=tags tags object or null

Include up to 50 key: value pairs to annotate requests with custom metadata.

+Show property

Response

application/json

{
  "id": "subscription_balance_entry_9Hom3R92btyMXKqh4JFyEw",
  "type": "CREDIT",
  "subscription_id": "subscription_abcxxxsadasdasd",
  "amount": 1000,
  "currency": "USD",
  "description": "Credit because I accidentally overcharged this subscription",
  "created_at": "2024-11-01T01:01:30",
  "updated_at": "2024-11-01T01:01:30",
  "tags": {
    "internal_code": "1234E"
  }
}

Was this helpful?

link to List Subscription Balance Entries List Subscription Balance Entries

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

link to /subscriptions/listsubscriptionbalanceentries#subscriptions/listsubscriptionbalanceentries/request Request

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.

SecurityView security details

BasicAuth

link to /subscriptions/listsubscriptionbalanceentries#subscriptions/listsubscriptionbalanceentries/request/path Path

link to /subscriptions/listsubscriptionbalanceentries#subscriptions/listsubscriptionbalanceentries/t=request&in=path&path=subscription_id subscription_id string required

The ID of the Subscription.

Example: subscription_cvTpAt87A4hncnuC4rkh6

link to /subscriptions/listsubscriptionbalanceentries#subscriptions/listsubscriptionbalanceentries/request/query Query

link to /subscriptions/listsubscriptionbalanceentries#subscriptions/listsubscriptionbalanceentries/t=request&in=query&path=after_cursor after_cursor string

Return every resource created after the cursor value.

link to /subscriptions/listsubscriptionbalanceentries#subscriptions/listsubscriptionbalanceentries/t=request&in=query&path=amount amount integer

Filter by an amount equal to the given value.

Example: amount=100

link to /subscriptions/listsubscriptionbalanceentries#subscriptions/listsubscriptionbalanceentries/t=request&in=query&path=amount.gt amount.gt integer

Filter by an amount greater than.

Example: amount.gt=100

link to /subscriptions/listsubscriptionbalanceentries#subscriptions/listsubscriptionbalanceentries/t=request&in=query&path=amount.gte amount.gte integer

Filter by an amount greater than or equal.

Example: amount.gte=100

link to /subscriptions/listsubscriptionbalanceentries#subscriptions/listsubscriptionbalanceentries/t=request&in=query&path=amount.lt amount.lt integer

Filter by an amount less than.

Example: amount.lt=100

link to /subscriptions/listsubscriptionbalanceentries#subscriptions/listsubscriptionbalanceentries/t=request&in=query&path=amount.lte amount.lte integer

Filter by an amount less than or equal.

Example: amount.lte=100

link to /subscriptions/listsubscriptionbalanceentries#subscriptions/listsubscriptionbalanceentries/t=request&in=query&path=before_cursor before_cursor string

Return every resource created before the cursor value.

link to /subscriptions/listsubscriptionbalanceentries#subscriptions/listsubscriptionbalanceentries/t=request&in=query&path=created_at.gte created_at.gte string (date-time)

Filter where created_at is after the given date.

Example: created_at.gte=2022-09-27T11:21:23

link to /subscriptions/listsubscriptionbalanceentries#subscriptions/listsubscriptionbalanceentries/t=request&in=query&path=created_at.lte created_at.lte string (date-time)

Filter where created_at is before the given date.

Example: created_at.lte=2026-09-27T11:21:23

link to /subscriptions/listsubscriptionbalanceentries#subscriptions/listsubscriptionbalanceentries/t=request&in=query&path=limit limit integer <= 100

The numbers of items to return.

Example: limit=10

link to /subscriptions/listsubscriptionbalanceentries#subscriptions/listsubscriptionbalanceentries/t=request&in=query&path=sort sort string

Specify the key to be used for sorting the collection. Acceptable values are:

updated_at
created_at

link to /subscriptions/listsubscriptionbalanceentries#subscriptions/listsubscriptionbalanceentries/t=request&in=query&path=tags.key tags.key string

Filter by the tag's key. For more information, see Tags.

Example: tags.key=card_type

link to /subscriptions/listsubscriptionbalanceentries#subscriptions/listsubscriptionbalanceentries/t=request&in=query&path=tags.value tags.value string

Filter by the tag's value. For more information, see Tags.

Example: tags.value=business_card

link to /subscriptions/listsubscriptionbalanceentries#subscriptions/listsubscriptionbalanceentries/t=request&in=query&path=updated_at.gte updated_at.gte string (date-time)

Filter where updated_at is after the given date.

Example: updated_at.gte=2022-09-27T11:21:23

link to /subscriptions/listsubscriptionbalanceentries#subscriptions/listsubscriptionbalanceentries/t=request&in=query&path=updated_at.lte updated_at.lte string (date-time)

Filter where updated_at is before the given date.

Example: updated_at.lte=2026-09-27T11:21:23

link to /subscriptions/listsubscriptionbalanceentries#subscriptions/listsubscriptionbalanceentries/request/header Headers

link to /subscriptions/listsubscriptionbalanceentries#subscriptions/listsubscriptionbalanceentries/t=request&in=header&path=finix-version Finix-Version string

Default 2022-02-01

Example: 2022-02-01

get

/subscriptions/{subscription_id}/subscription_balance_entries

Sandbox server https://finix.sandbox-payments-api.com/subscriptions/{subscription\_id}/subscription\_balance\_entries

curl

curl "https://finix.sandbox-payments-api.com/subscriptions/subscription_cvTpAt87A4hncnuC4rkh6/subscription_balance_entries" \
  -H "Content-Type: application/json" \
  -H "Finix-Version: 2022-02-01" \
  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda

link to /subscriptions/listsubscriptionbalanceentries#subscriptions/listsubscriptionbalanceentries/response&c=200 Responses

Expand all

List of Subscription Balance Entry resources

link to /subscriptions/listsubscriptionbalanceentries#subscriptions/listsubscriptionbalanceentries/response&c=200/headers Headers

link to /subscriptions/listsubscriptionbalanceentries#subscriptions/listsubscriptionbalanceentries/t=response&c=200&path=date date string

A response header indicating the date and time of the API request.

Example: "Tue, 08 Jul 2025 17:38:01 GMT"

link to /subscriptions/listsubscriptionbalanceentries#subscriptions/listsubscriptionbalanceentries/t=response&c=200&path=finix-apiuser-role finix-apiuser-role string

This response header indicating the role of the user who sent the API request.

Enum"ROLE_PLATFORM""ROLE_PARTNER""ROLE_MERCHANT"

Example: "ROLE_PARTNER"

link to /subscriptions/listsubscriptionbalanceentries#subscriptions/listsubscriptionbalanceentries/t=response&c=200&path=x-request-id x-request-id string

This response header provides a unique identifier for the API request.

Example: "055972f6534f92a896fbb61b11313ebb"

link to /subscriptions/listsubscriptionbalanceentries#subscriptions/listsubscriptionbalanceentries/response&c=200/body Bodyapplication/json

link to /subscriptions/listsubscriptionbalanceentries#subscriptions/listsubscriptionbalanceentries/t=response&c=200&path=page page object

Details the page that's returned.

+Show 2 properties

link to /subscriptions/listsubscriptionbalanceentries#subscriptions/listsubscriptionbalanceentries/t=response&c=200&path=_embedded_embedded object

+Show property

link to /subscriptions/listsubscriptionbalanceentries#subscriptions/listsubscriptionbalanceentries/t=response&c=200&path=_links_links object

+Show 2 properties

Response

application/json

{
  "_embedded": {
    "subscription_balance_entries": [ … ]
  },
  "_links": {
    "self": { … },
    "next": { … }
  },
  "page": {
    "limit": 100,
    "next_cursor": "subscription_balance_entry_9Hom3R92btyMXKqh4JFyrea"
  }
}

Was this helpful?

link to Update Subscription Balance Entry Update Subscription Balance Entry

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

link to /subscriptions/updatesubscriptionbalanceentry#subscriptions/updatesubscriptionbalanceentry/request RequestExpand all

Update the tags for an existing Subscription Balance Entry.

SecurityView security details

BasicAuth

link to /subscriptions/updatesubscriptionbalanceentry#subscriptions/updatesubscriptionbalanceentry/request/path Path

link to /subscriptions/updatesubscriptionbalanceentry#subscriptions/updatesubscriptionbalanceentry/t=request&in=path&path=subscription_id subscription_id string required

The ID of the Subscription.

Example: subscription_cvTpAt87A4hncnuC4rkh6

link to /subscriptions/updatesubscriptionbalanceentry#subscriptions/updatesubscriptionbalanceentry/t=request&in=path&path=subscription_balance_entry_id subscription_balance_entry_id string required

The ID of the Subscription Balance Entry.

link to /subscriptions/updatesubscriptionbalanceentry#subscriptions/updatesubscriptionbalanceentry/request/header Headers

link to /subscriptions/updatesubscriptionbalanceentry#subscriptions/updatesubscriptionbalanceentry/t=request&in=header&path=finix-version Finix-Version string

Default 2022-02-01

Example: 2022-02-01

link to /subscriptions/updatesubscriptionbalanceentry#subscriptions/updatesubscriptionbalanceentry/t=request&in=header&path=content-type Content-Type string

The data type being sent in the request body must be application/json.

Example: application/json

link to /subscriptions/updatesubscriptionbalanceentry#subscriptions/updatesubscriptionbalanceentry/request/body Bodyapplication/jsonrequired

link to /subscriptions/updatesubscriptionbalanceentry#subscriptions/updatesubscriptionbalanceentry/t=request&path=tags tags object or null

Include up to 50 key: value pairs to annotate requests with custom metadata.

+Show property

put

/subscriptions/{subscription_id}/subscription_balance_entries/{subscription_balance_entry_id}

Sandbox server https://finix.sandbox-payments-api.com/subscriptions/{subscription\_id}/subscription\_balance\_entries/{subscription\_balance\_entry\_id}

curl

curl "https://finix.sandbox-payments-api.com/subscriptions/subscription_cvTpAt87A4hncnuC4rkh6/subscription_balance_entries/subscription_balance_entry_czM1i9keffyXNVr3J9TzA" \
  -H "Content-Type: application/json" \
  -H "Finix-Version: 2022-02-01" \
  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \
  -X PUT \
  -d '
  {
    "tags": {
      "internal_code": "1234E"
    }
  }'

link to /subscriptions/updatesubscriptionbalanceentry#subscriptions/updatesubscriptionbalanceentry/response&c=200 Responses

Expand all

A single Subscription Balance Entry

link to /subscriptions/updatesubscriptionbalanceentry#subscriptions/updatesubscriptionbalanceentry/response&c=200/headers Headers

link to /subscriptions/updatesubscriptionbalanceentry#subscriptions/updatesubscriptionbalanceentry/t=response&c=200&path=date date string

A response header indicating the date and time of the API request.

Example: "Tue, 08 Jul 2025 17:38:01 GMT"

link to /subscriptions/updatesubscriptionbalanceentry#subscriptions/updatesubscriptionbalanceentry/t=response&c=200&path=finix-apiuser-role finix-apiuser-role string

This response header indicating the role of the user who sent the API request.

Enum"ROLE_PLATFORM""ROLE_PARTNER""ROLE_MERCHANT"

Example: "ROLE_PARTNER"

link to /subscriptions/updatesubscriptionbalanceentry#subscriptions/updatesubscriptionbalanceentry/t=response&c=200&path=x-request-id x-request-id string

This response header provides a unique identifier for the API request.

Example: "055972f6534f92a896fbb61b11313ebb"

link to /subscriptions/updatesubscriptionbalanceentry#subscriptions/updatesubscriptionbalanceentry/response&c=200/body Bodyapplication/json

link to /subscriptions/updatesubscriptionbalanceentry#subscriptions/updatesubscriptionbalanceentry/t=response&c=200&path=id id string non-empty

The ID of the resource.

link to /subscriptions/updatesubscriptionbalanceentry#subscriptions/updatesubscriptionbalanceentry/t=response&c=200&path=created_at created_at string (date-time)

Timestamp of when the object was created.

link to /subscriptions/updatesubscriptionbalanceentry#subscriptions/updatesubscriptionbalanceentry/t=response&c=200&path=updated_at updated_at string (date-time)

Timestamp of when the object was last updated.

link to /subscriptions/updatesubscriptionbalanceentry#subscriptions/updatesubscriptionbalanceentry/t=response&c=200&path=amount amount integer (int64)

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

Example: 5000

link to /subscriptions/updatesubscriptionbalanceentry#subscriptions/updatesubscriptionbalanceentry/t=response&c=200&path=currency currency string

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

Value"USD"

link to /subscriptions/updatesubscriptionbalanceentry#subscriptions/updatesubscriptionbalanceentry/t=response&c=200&path=description description string

Describes the circumstances for the subscription credit.

link to /subscriptions/updatesubscriptionbalanceentry#subscriptions/updatesubscriptionbalanceentry/t=response&c=200&path=subscription_id subscription_id string

The Subscription that was credited.

link to /subscriptions/updatesubscriptionbalanceentry#subscriptions/updatesubscriptionbalanceentry/t=response&c=200&path=type type string

The value of this field will always be CREDIT.

link to /subscriptions/updatesubscriptionbalanceentry#subscriptions/updatesubscriptionbalanceentry/t=response&c=200&path=tags tags object or null

Include up to 50 key: value pairs to annotate requests with custom metadata.

+Show property

Response

application/json

Was this helpful?

link to Subscription Plans Subscription Plans

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

A Subscription Plan resource is a template with set recurring costs and frequencies that can be reused across multiple Subscription resources.

Related Guides:

Operations

post

/subscription_plans

get

/subscription_plans

get

/subscription_plans/{subscription_plan_id}

put

/subscription_plans/{subscription_plan_id}

+ Show

link to Transfer Attempts Transfer Attempts

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

When a user attempts to make a payment using a Checkout Form or Payment Link, or a recipient submitting details with a Payout Link—a Transfer Attempt is created.

Using transfer attempts, you can track the lifecycle of a payment or a series of payments if you are using a multi-use Payment Link.

Checkout Forms and Payment Links support authorizations. If a payment made with them is an authorization, the Transfer Attempt result shows is_authorization: true and references the authorization (authorization_id).

Each Transfer Attempt has as reference to a transfer_id to allow you to query it for additional data.

Related Guides:

Transfer Attempts

Operations

get

/transfer_attempts

get

/transfer_attempts/{transfer_attempt_id}

+ Show

link to Balances Balances

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

A Balance resource represents the current financial state of an Application identified by the linked_to query parameter.

It tracks the state of funds processed through the system, including amounts that are:

available_amount for immediate use or disbursement.
pending_amount due to processing times, holds, or other constraints.
posted_amount, which reflects the total sum (including both available and pending funds).

Operations

get

/balances

get

/balances/{balance_id}

get

/balances/{balance_id}/balance_entries

get

/balance_entries/{balance_entry_id}

+ Show

link to Balance Adjustments Balance Adjustments

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

A Balance Adjustment modifies the account Balance by adding funds (a 'top-up') or reducing funds for Payouts. Each adjustment is linked to a specific payment rail (e.g., ACH, card, wire).

Related Guides:

Adding Funds to your Finix Balance

Operations

post

/balance_adjustments

get

/balance_adjustments

+ Show

link to Disbursement Rules Disbursement Rules

Copy

Copy for LLM

Copy page as Markdown for LLMs

Install MCP server on Cursor

Connect to VS Code

Install MCP server on VS Code

For the Payouts product, when a payout is executed, such as a Push-To-Card or ACH transaction, Finix checks the transaction against velocity rules and balance rules.

Rules establish limits on transactions. For example, there may be a daily transaction limit of 100 transactions (count_limit) or a monthly volume limit of $100,000 (volume_limit). If a transaction exceeds any defined limit, the transaction is rejected.

Rules are set for entities involved in transactions, including the application, senders, and recipients.

The "Application" represents the customer to whom Finix is applying the rules. Application rules are set solely by Finix and are applied to every single transaction.

You can establish rules for "senders" and "recipients," referring to the parties involved in transactions:

In the case of a PULL_FROM_CARD or PULL_FROM_ACH transaction, sender rules are applied (either card or ACH rules). The "target" of the pull is referred to as the "sender," specifically the customer of Finix's client.
Conversely, in the case of a PUSH_FROM_CARD or PUSH_FROM_ACH transaction, the recipient rules are applied (either card or ACH rules). The "target" of the push is referred to as the "recipient," which is, in turn, the customer of Finix's client.

Operations

get

/disbursement_rules

get

/disbursement_rules/current_usages

+ Show