# Lists merchant's subscriptions

<span class="api-endpoint">GET {{<a href="#urlbases">baseURL</a>}}/sub-api/v1/subscriptions</span>
This endpoint returns a list of the merchant's subscriptions.

Endpoint: GET /sub-api/v1/subscriptions
Version: V1
Security: Bearer

## Query parameters:

  - `page` (integer)
    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

  - `pageSize` (integer)
    Specifies the number of items for each page 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.

Example: 50

  - `orderBy` (string)
    Specifies the field the results get ordered by.

The sort order is specified by the `asc` value.

Example: contactName

  - `asc` (boolean)
    Specifies the sort order is ascending.

The sort field is specified by the `orderBy` value.

If `true`, the sort order is ascending.<br>
If `false`, the sort order is descending.

Example: true

  - `search` (string)
    <br>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.

  - `customerIds` (array)
    <br>Specifies a single customer identifier.

Multiple values are not supported.

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

## Response 200 fields (application/json):

  - `id` (string)
    Indicates the subscription identifier.

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

  - `merchantId` (string)
    Indicates the merchant identifier.

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

  - `paymentProcessorId` (string)
    Indicates the payment processor identifier.

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

  - `statusId` (integer)
    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

  - `status` (string)
    Indicates the subscription status.
Possible values:
| Value | Meaning |
|  --- | --- |
| Active | 1 |
| Completed | 2 |
| Suspended | 3 |
| Delinquent | 4 |
| Terminated | 5 |
| Deleted | 6 |

Example: Completed
    Example: Completed

  - `transactionTypeId` (integer)
    Indicates the Flute transaction type identifier code value.
Example: 6
    Example: 6

  - `transactionType` (string)
    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

  - `customerId` (string)
    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

  - `paymentMethodId` (string)
    Identifies the customer payment method identifier.

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

  - `paymentAmount` (object)

  - `paymentAmount.baseAmount` (number)
    Identifies the original amount (in USD) of a transaction before adjustments are applied.

Example: 129.99
    Example: 129.99

  - `paymentAmount.percentageOffAmount` (number)
    Identifies the discount amount (in USD) taken off.
This discount was calculated using the preset percentage from `percentageOffRate`.
Example: 12.50
    Example: 12.5

  - `paymentAmount.percentageOffRate` (number)
    Identifies the discount percentage.
This value is percentage rate for the discount.
This discount percentage calculates the discount amount for `percentageOffAmount`.
Example: 3.5 (as 3.5%)
    Example: 3.5

  - `paymentAmount.cashDiscountAmount` (number)
    Identifies the discount amount (in USD) when a cash (or cash-equivalent) discount is applied.
This discount was calculated using the preset percentage from `cashDiscountRate`.
Example: 10.55
    Example: 10.55

  - `paymentAmount.cashDiscountRate` (number)
    Identifies the discount percentage for a cash (or cash-equivalent) discount.
This value is percentage rate for the discount.
This discount percentage calculates the discount amount for `cashDiscountAmount`.
Example: 1.5 (as 1.5%)
    Example: 1.5

  - `paymentAmount.surchargeAmount` (number)
    Identifies the amount (in USD) when a surcharge is applicable.
This is a surcharge on the base amount.
This surcharge was calculated using the preset percentage from `surchargeRate`.
Example: 6.45
    Example: 6.45

  - `paymentAmount.surchargeRate` (number)
    Identifies the surcharge percentage.
This is a surcharge on the base amount.
This value is surcharge percentage rate.
This surcharge percentage calculates the surcharge amount for `surchargeAmount`.
Example: 1.5 (as 1.5%)
    Example: 1.5

  - `paymentAmount.totalAmount` (number)
    Specifies the transaction's total amount. 

This includes the base amount, tips, taxes, shipping, discounts, and other charges.

Example: 3219.45
    Example: 3219.45

  - `alreadyPaidAmount` (number)
    Indicates the total amount the client has already paid as part of this subscription.

Example: 259.99
    Example: 259.99

  - `allPaymentsAmount` (number)
    Indicates the total of all amounts due of the subscription.

Example: 54.92
    Example: 54.92

  - `currencyId` (integer)
    Indicates the Flute currency identifier.
Always set to *1*.
Example: 1
    Example: 1

  - `paymentFrequencyUnitId` (integer)
    Indicates the payment frequency identifier.
Possible values:
| ID | Label |
|  --- | --- |
| 1 | Daily |
| 2 | Weekly |
| 3 | Monthly |

Example: 3
    Example: 3

  - `paymentFrequencyUnit` (integer)
    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

  - `paymentFrequency` (integer)
    Indicates the payment frequency identifier.
Possible values:
| Value | Meaning |
|  --- | --- |
| Daily | 1 |
| Weekly | 2 |
| Monthly | 3 |

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.
Example: Weekly
    Example: Weekly

  - `createdOn` (string)
    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

  - `subscriptionStartDate` (string)
    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

  - `subscriptionEndDate` (string)
    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

  - `lastPaymentDate` (string)
    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

  - `nextPaymentDate` (string)
    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

  - `successfulPaymentsCount` (integer)
    Indicates the number of successful payments for the subscription.
See `numberOfPayments` for the total expected number of payments.
Example: 32
    Example: 32

  - `numberOfPayments` (integer)
    Total number of payments for the subscription.
See `successfulPaymentsCount` for the current number of payments.
Example: 60
    Example: 60

  - `customer` (object)
    Indicates an object for returning subscription details.

  - `customer.customerName` (string)
    Indicates the customer's full name.

Example: Alexandro Peppared
    Example: Alexandro Peppard

  - `customer.companyName` (string)
    Indicates the name of the customer's company or organization.

Example: Peppared Street Cafe
    Example: Example: Peppared Street Cafe

  - `customer.panMask` (string)
    Indicates the masked PAN (primary account number).
This is a partially obscured representation of a card's PAN.
This value can be  safely displayed to clients without revealing the actual or full account number,
Examples:
4111********1234
************1234
****1234
    Example: 4111********1234

  - `customer.cardTokenType` (integer)
    Identifies the card token type.
Possible values:
| Id | Type | Description |
|  --- | --- | --- |
| 1 | Local | Regular |
| 2 | Network | Network |

Example: 2
    Example: 2

  - `customer.emailAddress` (string)
    Indicates the customer's email contact.
Example: peppared@example.com
    Example: peppared@example.com

  - `customer.phoneNumber` (string)
    Indicates the customer's telephone number.
Example: +15551234567
    Example: +15551234567

  - `source` (object)

  - `source.typeId` (integer)

  - `source.type` (string)

  - `source.id` (string)

  - `source.name` (string)

## Response 400 fields (application/json):

  - `details` (string)
    Indicates details about the error.

Example: Validation failed: -- Email: 'Email' is not a valid email address. Severity: Error
    Example: Validation failed: -- Email: 'Email' is not a valid email address. Severity: Error

  - `statusCode` (integer)
    Specifies the HTTP response status code.
This is the HTTP status code returned by the attempted delivery.
The following is a list of HTTP response status codes that include but are not limited to:
| HTTP Status | Meaning |
|  --- | --- |
| 200 | Delivery succeeded |
| 400 | Bad request |
| 401 | Unauthorized |
| 404 | Endpoint not found |
| 429 | Rate limited |

Example: 401
    Example: 401

  - `source` (string)
    Indicates the source of the error.
Example: <Service>
    Example: <Service>

  - `exceptionType` (string)
    Indicates the error's exception type.

Example: FluentValidation.ValidationException
    Example: FluentValidation.ValidationException

  - `correlationId` (string)
    Indicates the correlation identifier.

Example: aa6cfcd0-0295-4a4c-b074-8c901f114fef
    Example: aa6cfcd0-0295-4a4c-b074-8c901f114fef

  - `entityId` (string)
    Indicates the entity identifier.
Example:
null

  - `errorCode` (string)
    Indicates the error code.
Example:
null

## Response 404 fields (application/json):

  - `details` (string)

  - `statusCode` (integer)
    Specifies the HTTP response status code.
This is the HTTP status code returned by the attempted delivery.
The following is a list of HTTP response status codes that include but are not limited to:
| HTTP Status | Meaning |
|  --- | --- |
| 200 | Delivery succeeded |
| 400 | Bad request |
| 401 | Unauthorized |
| 404 | Endpoint not found |
| 429 | Rate limited |

Example: 401
    Example: 401

  - `source` (string)

  - `exceptionType` (string)

  - `correlationId` (string)

  - `entityId` (string)

  - `errorCode` (string)

## Response 500 fields (application/json):

  - `details` (string)

  - `statusCode` (integer)
    Specifies the HTTP response status code.
This is the HTTP status code returned by the attempted delivery.
The following is a list of HTTP response status codes that include but are not limited to:
| HTTP Status | Meaning |
|  --- | --- |
| 200 | Delivery succeeded |
| 400 | Bad request |
| 401 | Unauthorized |
| 404 | Endpoint not found |
| 429 | Rate limited |

Example: 401
    Example: 401

  - `source` (string)

  - `exceptionType` (string)

  - `correlationId` (string)

  - `entityId` (string)

  - `errorCode` (string)