Subscription

A subscription is a recurring payment. The client authorizes a transaction at regular intervals, such as weekly, monthly, or annually.

Examples include mortgages, leases, streaming media payments, and Insurance premiums. Payments represent:

Recurring billing. The transaction happens automatically on a set schedule without the client having to re-enter payment details.
Pre-authorization. The customer approves transactions for future charges.
Fixed or variable amounts. The transaction can be the same every cycle, such as for a streaming service or vary based on usage, such as a utility bill.
Stored payment. The transaction uses a vault or stored payment method. Payment methods include a credit or debit card (only sale transactions) and ACH electronic check.

Installments may be specified as a combination of:

Days of the month, such as the 1st, 15th, or 30th
Weeks of the month, such as the first week or the third week
Months, such as 1 (January), 3 (March), or 12 (December)

Installments may either specify:

A set number of payments, such as 36, 60, 360. For example, this may be for a mortgage or car payment.
Be indefinite and not specify an end date or a number of payments. For example, this may be for a streaming media subscription.

The following endpoints are available:

GET /sub-api/v1/subscriptions
Lists subscriptions associated with the merchant.

GET /sub-api/v1/subscriptions/{{subscriptionId}}
Lists subscriptions associated with a specified subscription identifier.

POST /sub-api/v1/subscriptions
Creates a subscription.

GET /sub-api/v1/subscriptions/{{subscriptionId}}/payments
Lists the payment history from a specified subscription identifier.

PUT /sub-api/v1/subscriptions/{{subscriptionId}}/terminate
Terminate or cancels the specified subscription identifier.

Operations

Lists merchant's subscriptions

Request

GET {{baseURL}}/sub-api/v1/subscriptions

This endpoint returns a list of the merchant's subscriptions.

See Also:
To create a subscription, see POST /sub-api/v1/subscriptions.
To retrieve a subscription by ID, see GET /sub-api/v1/subscriptions/{subscriptionId}.
To retrieve a subscription's payment history, see GET /sub-api/v1/subscriptions/{subscriptionId}/payments.
To terminate a subscription, see PUT /sub-api/v1/subscriptions/{subscriptionId}/terminate.

Security

Bearer

Query

pageinteger, (int32)

Specifies the page number of the returned search results.

A page is considered each set of the pageSize value.

The maximum page value is the pageSize divided by the total count rounded up. The count is zero-based. For example, if pageSize is 50 and the total is 130, there are three pages. The maximum page value is 2.

Values above the maximum page value will complete successfully but not return any items.

Example: 0

Default:0

pageSizeinteger, (int32)

Specifies the number of items for each page of the returned search results.

A page is considered each set of the pageSize value.

Example: 50

Default:15

orderBystring

Specifies the field the results get ordered by.

The sort order is specified by the asc value.

Example: contactName

ascboolean

Specifies the sort order is ascending.

The sort field is specified by the orderBy value.

If true, the sort order is ascending.
If false, the sort order is descending.

Example: true

Default:true

searchstring

Specifies the search string.

This performs a case insensitive, matching, or partially matching search.

Fields does not have to be specified. If the results are to be sorted, the field orderby to specify the sort field.

Example:search=Peppared

customerIdsArray of strings, (uuid)

Specifies a single customer identifier.

Multiple values are not supported.

Example: 019d9cb4-c430-7b49-b232-a6a5d07c8371

Example:customerIds=019d9cb4-c430-7b49-b232-a6a5d07c8371

curl -i -X GET \
  'https://developer.flute.com/_mock/api-reference/sub-api/v1/subscriptions?page=0&pageSize=15&orderBy=string&asc=true&search=Peppared&customerIds=019d9cb4-c430-7b49-b232-a6a5d07c8371' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Bodyapplication/json

idstring, (uuid)

Indicates the subscription identifier.

Example: 35e6f7a8-9b0c-4d1e-2f3a-4b5c6d7e8f14

Example:"35e6f7a8-9b0c-4d1e-2f3a-4b5c6d7e8f14"

merchantIdstring, (uuid)

Indicates the merchant identifier.

Example: 46f7a8b9-0c1d-4e2f-3a4b-5c6d7e8f9a25

Example:"46f7a8b9-0c1d-4e2f-3a4b-5c6d7e8f9a25"

paymentProcessorIdstring, (uuid)

Indicates the payment processor identifier.

Example: 57a8b9c0-1d2e-4f3a-4b5c-6d7e8f9a0b36

Example:"57a8b9c0-1d2e-4f3a-4b5c-6d7e8f9a0b36"

statusIdinteger, (int32)

Indicates the subscription status identifier.

Possible values:

Value	Meaning
1	Active
2	Completed
3	Suspended
4	Delinquent
5	Terminated
6	Deleted

Example: 2

Example:2

statusstring or null

Indicates the subscription status.

Possible values:

Value	Meaning
Active	1
Completed	2
Suspended	3
Delinquent	4
Terminated	5
Deleted	6

Example: Completed

Example:"Completed"

transactionTypeIdinteger, (int32)

Indicates the Flute transaction type identifier code value.

Example: 6

Example:6

transactionTypestring or null

Indicates the transaction type name.

Possible values:

Value	Type
Authorization	1
Sale	2
Capture	3
Void	4
Refund	5
Verify	6

Example: Refund

Example:"Refund"

customerIdstring, (uuid)

Specifies the customer identifier.

This is used when saving the payment method.
If this value is provided, the payment method is saved to the specified customer.
If this value is not provided, a new customer record is created.

Example: fd9198a4-eb6f-4620-9603-4f4638289de5

Example:"fd9198a4-eb6f-4620-9603-4f4638289de5"

paymentMethodIdstring or null, (uuid)

Identifies the customer payment method identifier.

We recommend using paymentMethodId instead of accountNumber.

Example: b6df8625-cd25-4123-b345-638aa7b5d011

Example:"b6df8625-cd25-4123-b345-638aa7b5d011"

paymentAmountobject

Indicates the payment amount breakdown for the subscription payment.

alreadyPaidAmountnumber, (double)

Indicates the total amount the client has already paid as part of this subscription.

Example: 259.99

Example:259.99

allPaymentsAmountnumber, (double)

Indicates the total of all amounts due of the subscription.

Example: 54.92

Example:54.92

currencyIdinteger, (int32)

Indicates the Flute currency identifier.

Always set to 1.

Example: 1

Example:1

paymentFrequencyUnitIdinteger, (int32)

Indicates the payment frequency identifier.

Possible values:

ID	Label
1	Daily
2	Weekly
3	Monthly

Example: 3

Example:3

paymentFrequencyUnitinteger, (int32)

Indicates the payment frequency unit.

As examples:
With a paymentFrequencyUnit of Weekly, and paymentFrequency of 1, payments are made once a week.
With a paymentFrequencyUnit of Weekly, and paymentFrequency of 2, payments are made twice a week

Possible values:

ID	Label
1	Daily
2	Weekly
3	Monthly

Example: 3

Example:3

paymentFrequencyinteger, (int32)

Indicates the payment frequency identifier.

Possible values:

Value	Meaning
Daily	1
Weekly	2
Monthly	3

Example: Weekly

Example:"Weekly"

createdOnstring, (date-time)

Indicates the date-time (in an ISO 8601 date-time UTC format) when the subscription was created.

Examples: 2026-02-19T20:24:52.934Z

Example:"2026-02-19T20:24:52.934Z"

subscriptionStartDatestring, (date-time)

Indicates the date-time (in an ISO 8601 date-time UTC format) of the subscription's first payment.

Examples: 2026-02-19T20:24:52.934Z

Example:"2026-02-19T20:24:52.934Z"

subscriptionEndDatestring or null, (date-time)

Indicates the date-time (in an ISO 8601 date-time UTC format) of the subscription's last payment.

Examples: 2027-02-19T20:24:52.934Z

Example:"2027-02-19T20:24:52.934Z"

lastPaymentDatestring or null, (date-time)

Indicates the date-time (in an ISO 8601 date-time UTC format) of the subscription's last payment date.

Examples: 2027-02-19T20:24:52.934Z

Example:"2027-02-19T20:24:52.934Z"

nextPaymentDatestring or null, (date-time)

Indicates the date-time (in an ISO 8601 date-time UTC format) of the subscription's next payment date.

Examples: 2026-03-19T20:24:52.934Z

Example:"2026-03-19T20:24:52.934Z"

successfulPaymentsCountinteger, (int32)

Indicates the number of successful payments for the subscription.

See numberOfPayments for the total expected number of payments.

Example: 32

Example:32

numberOfPaymentsinteger, (int32)

Total number of payments for the subscription.

See successfulPaymentsCount for the current number of payments.

Example: 60

Example:60

customerobject

Indicates an object for returning subscription details.

sourceobject

Indicates the source of the subscription.

Response

{
  "id": "35e6f7a8-9b0c-4d1e-2f3a-4b5c6d7e8f14",
  "merchantId": "46f7a8b9-0c1d-4e2f-3a4b-5c6d7e8f9a25",
  "paymentProcessorId": "57a8b9c0-1d2e-4f3a-4b5c-6d7e8f9a0b36",
  "statusId": 2,
  "status": "Completed",
  "transactionTypeId": 6,
  "transactionType": "Refund",
  "customerId": "fd9198a4-eb6f-4620-9603-4f4638289de5",
  "paymentMethodId": "b6df8625-cd25-4123-b345-638aa7b5d011",
  "paymentAmount": {
    "baseAmount": 129.99,
    "percentageOffAmount": 12.5,
    "percentageOffRate": 3.5,
    "cashDiscountAmount": 10.55,
    "cashDiscountRate": 1.5,
    "surchargeAmount": 6.45,
    "surchargeRate": 1.5,
    "totalAmount": 3219.45
  },
  "alreadyPaidAmount": 259.99,
  "allPaymentsAmount": 54.92,
  "currencyId": 1,
  "paymentFrequencyUnitId": 3,
  "paymentFrequencyUnit": 3,
  "paymentFrequency": "Weekly",
  "createdOn": "2026-02-19T20:24:52.934Z",
  "subscriptionStartDate": "2026-02-19T20:24:52.934Z",
  "subscriptionEndDate": "2027-02-19T20:24:52.934Z",
  "lastPaymentDate": "2027-02-19T20:24:52.934Z",
  "nextPaymentDate": "2026-03-19T20:24:52.934Z",
  "successfulPaymentsCount": 32,
  "numberOfPayments": 60,
  "customer": {
    "customerName": "Alexandro Peppard",
    "companyName": "Example: Peppared Street Cafe",
    "panMask": "4111********1234",
    "cardTokenType": 2,
    "emailAddress": "peppared@example.com",
    "phoneNumber": "+15551234567"
  },
  "source": {
    "typeId": 1,
    "type": "Api",
    "id": "5c6d7e8f-9a0b-4c1d-8e2f-3a4b5c6d7e81",
    "name": "Terminal 12"
  }
}

Subscription

Lists merchant's subscriptions

Request

Query

Responses

Was this helpful?