List all payments

GET 
https://api.freemius.com/v1/products/{product_id}/payments.json

Auth:Bearer TokenSCOPE: PRODUCT

Product-scoped API tokens allow you to operate on the product itself. This token usually allows read-only access to the product configuration and write access to several operations on subscriptions, customers, payments, and more. For most SaaS or app integrations, this is the token you will need.

1. Go to the Freemius Developer Dashboard.
2. Open the Settings page of the relevant product.
3. Click the API & Keys tab.
4. Copy the API Bearer Authorization Token from the UI.

---

Retrieve the payment collection associated with the product.

Filtering and searching

You search and/or filter payments with these parameters:

• search - You can search by payment_id, external_payment_id, or user_email. It can be a number or string.
• user_id - If you are looking to list all payments for a specific user use this.
• billing_cycle - Filter payments by billing cycle. 0 means lifetime payments.
• currency - Filter payments by currency.
• coupon_id - Filter payments by coupon ID.
• filter - Filter payments by different types: all, refunds, not_refunded, disputed, won_disputes, chargebacks.

Please see the parameters in the responses body for more information.

Request

Path Parameters

product_id integer<int64>required
The ID of the product.
Possible values: >= 1
Example: 1234

Query Parameters

search string

Search by payment_id, external_payment_id, or user_email.

search_user_id string<int64>
User ID to filter with.
Possible values: >= 1
Example: 123456
billing_cycle number

Filter by billing cycle.

Possible values: [1, 12, 0]

currency string

Possible values: >= 3 characters and <= 3 characters, [usd, eur, gbp]

coupon_id string<int64>
Filter payments by coupon ID.
Possible values: >= 1
Example: 123456
filter string

Default value: all

Filter payments by different types

Possible values: [all, refunds, not_refunded, disputed, won_disputes, chargebacks]

extended boolean

Default value: false

If true, loads linked user, plan and subscription.

to string<date-time>
The end of the date range in YYYY-MM-DD HH:MM:SS format
Example: 2025-08-01 00:00:00
from string<date-time>
The start of the date range in YYYY-MM-DD HH:MM:SS format
Example: 2025-08-01 00:00:00
count integer
Default value: 25
The number of records to return.
Possible values: >= 1 and <= 50
Example: 10
offset integer
Default value: 0
The number of records to skip before starting to return records. Default is 0.
Possible values: >= 0
Example: 10
fields string
Comma separated list of fields to return in the response. If not specified, all fields are returned.
Example: id,name,slug

Responses

200

The payment collection.

application/json

Schema

payments object[]

Array [

user_idstring<int64>

The ID of the user the entity belongs to.

Possible values: >= 1

Example: 123456

install_idstring<int64>nullable

The ID of the installation or site the entity is associated with, a null value means it has not been associated with an installation yet.

Possible values: >= 1

Example: 123456

plan_idstring<int64>

The ID of the plan associated with the entity.

Possible values: >= 1

Example: 123456

pricing_idstring<int64>

The ID of the pricing associated with the entity.

Possible values: >= 1

Example: 123456

license_idstring<int64>

The ID of the license associated with the entity.

Possible values: >= 1

Example: 123456

ipstring<ipv4|ipv6>nullable

The IP address associated with the entity.

Example: 0.0.0.0

country_codestring

The ISO 3166-1 alpha 2 two-letter country code associated with the entity.

Example: us

zip_postal_codestringnullable

The postal/zip code of the location.

Example: 92710

vat_idstringnullable

The business VAT number (EU or UK territories) or other tax ID (for example Sales Tax ID for the US).

Example: GB12345678

coupon_idstring<int64>nullable

The ID of the coupon associated with the entity.

Possible values: >= 1

Example: 123456

user_card_idstring<int64>

The ID of the user card that was used for this payment.

Example: 12345

sourcenumber

The source of the migration data. To get support migrating from other platform please see our documentation.

• 0 - Freemius
• 1 - Other
• 2 - Easy Digital Downloads (EDD)
• 3 - WooCommerce (WC)
• 4 - Rating Widget
• 5 - Gumroad
• 6 - CodeCanyon
• 7 - ThemeForest
• 8 - AppSumo
• 9 - SendOwl
• 10 - WHMCS
• 11 - Lemon Squeezy

Possible values: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]

plugin_idstring<int64>

The ID of the product the entity belongs to.

Possible values: >= 1

Example: 123456

external_idstring

The external ID of the gateway entity.

Example: abcde12345

gatewaystringnullable

The gateway used for the purchase. The gateway will be set to null when purchasing a product with a 100% discount.

environmentnumber

The environment the entity belongs to. 0 means it belongs to the production environment, 1 means it belongs to the sandbox environment.

Possible values: [1, 0]

Example: 0

idstring<int64>

The unique identifier of the entity.

Possible values: >= 1

Example: 123456

createdstring<date-time>

The date and time the entity was created, under UTC timezone.

Example: 2025-01-01 00:00:00

updatedstring<date-time>nullable

The date and time the entity was updated, under UTC timezone. If null then the entity was never updated since its creation.

Example: 2025-01-01 00:00:00

currencystring

3-char currency code.

Possible values: >= 3 characters and <= 3 characters, [usd, eur, gbp]

refund_reasonstringnullable

If the payment is refunded, this will contain the reason.

Example: Refunded due to a bug in the plugin.

subscription_idstring<int64>nullable

The ID of the subscription associated with the entity.

Possible values: >= 1

Example: 123456

payment_presentment_idstring<int64>

The ID of the presentment payment.

Possible values: >= 1

Example: 123456

grossnumber<float>

The payment amount (not including taxes).

Example: 2075.45

bound_payment_idstring<int64>

The ID of the payment that this payment is bound to, in case of a refund or chargeback/dispute.

Possible values: >= 1

Example: 123456

gateway_feenumber<float>

Default value: 0

The fee that the gateway took for processing this payment.

Example: 2.99

vatnumber

Default value: 0

The actual tax amount. It could be any kind of tax, not necessarily VAT. For example we support US Sales Tax.

Example: 1.24

is_renewalboolean

Default value: false

If the payment is a renewal.

typestring

Default value: payment

The type of the payment.

Possible values: [payment, refund, disputed, won_dispute, lost_dispute, chargeback]

emailstring

Email address of the person.

Example: [email protected]

urlstringnullable

The site URL.

Example: https://example.com

billing_cyclenumber

The billing cycle of the subscription in number of months. 1 means monthly, 12 means annually, 0 means lifetime usually when subscriptions are created for lifetime trials.

Possible values: [1, 12, 0]

plan_namestring

Name of the plan the payment is associated with.

]

discounts object[]

Array [

idstring<int64>

The unique identifier of the entity.

Possible values: >= 1

Example: 123456

createdstring<date-time>

The date and time the entity was created, under UTC timezone.

Example: 2025-01-01 00:00:00

updatedstring<date-time>nullable

The date and time the entity was updated, under UTC timezone. If null then the entity was never updated since its creation.

Example: 2025-01-01 00:00:00

entity_idstring<int64>

The ID of the related entity.

Possible values: >= 1

entity_typestring

Default value: payment

The type of the related entity. Defaults to payment.

Possible values: [payment, subscription]

typestring

Default value: prorate

The type of discount. Possible values are prorate and subscription_cancellation. Defaults to prorate.

Possible values: [prorate, subscription_cancellation]

discountnumber<float>

Discount amount in USD.

Example: 10.0

coupon_idstring<int64>

The ID of the related coupon.

Possible values: >= 1

]

400

Bad request. The request could not be understood by the server due to malformed syntax or arguments.

application/json

Schema

pathstring

The API request path.

Example: :/products/product_id/users.json

error object

This object contains the error details.

typestring

The type of the error encountered by the server.

Example: UnauthorizedAccess

messagestring

The descriptive error message.

Example: Some error has occured.

codestring

The error code.

Example: unauthorized_access

httpinteger

The HTTP status code returned by the server.

Example: 401

timestampstring

Current timestamp.

Example: Thu, 11 May 2023 11:45:30 +0000

request object

This object sends back the request payload as received by the server (both from path and from body or query).

property name*any

This object sends back the request payload as received by the server (both from path and from body or query).

Example: {"beautify":true,"format":"json"}

401

Unauthorized access error. The request requires authentication but was not provided or the provided authentication does not satisfy the required permissions.

application/json

Schema

pathstring

The API request path.

Example: :/products/product_id/users.json

error object

This object contains the error details.

typestring

The type of the error encountered by the server.

Example: UnauthorizedAccess

messagestring

The descriptive error message.

Example: Some error has occured.

codestring

The error code.

Example: unauthorized_access

httpinteger

The HTTP status code returned by the server.

Example: 401

timestampstring

Current timestamp.

Example: Thu, 11 May 2023 11:45:30 +0000

request object

This object sends back the request payload as received by the server (both from path and from body or query).

property name*any

This object sends back the request payload as received by the server (both from path and from body or query).

Example: {"beautify":true,"format":"json"}

402

The request is missing the specified argument.

application/json

Schema

pathstring

The API request path.

Example: :/products/product_id/users.json

error object

This object contains the error details.

typestring

The type of the error encountered by the server.

Example: UnauthorizedAccess

messagestring

The descriptive error message.

Example: Some error has occured.

codestring

The error code.

Example: unauthorized_access

httpinteger

The HTTP status code returned by the server.

Example: 401

timestampstring

Current timestamp.

Example: Thu, 11 May 2023 11:45:30 +0000

request object

This object sends back the request payload as received by the server (both from path and from body or query).

property name*any

This object sends back the request payload as received by the server (both from path and from body or query).

Example: {"beautify":true,"format":"json"}

404

The requested resource was not found.

application/json

Schema

pathstring

The API request path.

Example: :/products/product_id/users.json

error object

This object contains the error details.

typestring

The type of the error encountered by the server.

Example: UnauthorizedAccess

messagestring

The descriptive error message.

Example: Some error has occured.

codestring

The error code.

Example: unauthorized_access

httpinteger

The HTTP status code returned by the server.

Example: 401

timestampstring

Current timestamp.

Example: Thu, 11 May 2023 11:45:30 +0000

request object

This object sends back the request payload as received by the server (both from path and from body or query).

property name*any

This object sends back the request payload as received by the server (both from path and from body or query).

Example: {"beautify":true,"format":"json"}