Subscriptions

9 endpoints. Base URL https://api.paymentsonline.io, sandbox https://api.sandbox-paymentsonline.io.

Every request needs payments-api-key and payments-account.

GET/v1/subscriptions

List all Subscriptions

Returns a list of Subscriptions. The Subscriptions are sorted with the most recently created appearing first.

Query parameters

metadataobjectoptional
metadata key-value pairs to filter by. Only exact matches on the key-value pair(s) will be returned. Example: ?metadata[internal_customer_id]=7cb1159d-875e-47ae-a309-319fa7ff395b.
customer_idstringoptional
The ID of the customer whose subscriptions will be retrieved.
include_connected_accountsbooleanoptional
Whether or not to include the results from any connected accounts.
statusstring (active | canceled | past_due | paused | pending | requires_confirmation)optional
The status of the subscriptions to retrieve.
next_payment_at_ltestring date-timeoptional
Maximum next_payment_at value to filter by (inclusive).
next_payment_at_gtestring date-timeoptional
Minimum next_payment_at value to filter by (inclusive).
offsetnumberoptional
The (zero-based) offset of the first item in the collection to return.
limitnumberoptional
The maximum number of entries to return. If the value exceeds the maximum, then the maximum value will be used.

Header parameters

payments-accountstringrequired
The id of the Paydude Account (usually starting with the prefix acct_) that the request is performed on behalf of. Must be a merchant (connected) account id, not the partner account you signed up with; a partner account passes GET /v1/accounts and then fails with "not enabled for this account" on the first payment call.

Responses

200PaginatedDto | object

has_morebooleanrequired
Whether or not there are more elements available after this set. If false, this set comprises the end of the list.
limitnumberoptional
The maximum number of entries to return. If the value exceeds the maximum, then the maximum value will be used.
offsetnumberoptional
The (zero-based) offset of the first item in the collection to return.
totalnumberoptional
The total items count.
itemsarray of Subscriptionrequired

POST/v1/subscriptions

Create a Subscription

Creates a new Subscription.

Header parameters

payments-accountstringrequired
The id of the Paydude Account (usually starting with the prefix acct_) that the request is performed on behalf of. Must be a merchant (connected) account id, not the partner account you signed up with; a partner account passes GET /v1/accounts and then fails with "not enabled for this account" on the first payment call.

Request body application/jsonrequired

apply_surchargebooleanoptional
Whether to apply the account's surcharge rate to payments created by this subscription. If true, the surcharge rate set in the merchant account will be applied to payments created by this subscription. If surcharging is not enabled on the account, this field must be false or null otherwise the request will fail.
billing_cycle_anchorstring date-timerequired
Determines the date of the first payment and the day of week/month/year for subsequent payments. If a month doesn't have the anchor day, the subscription will be billed on the last day of the month. For example, a monthly subscription starting on January 31 bills on Feb 28/29, then March 31, April 30, etc. Format must be ISO8601 (e.g. '2000-01-25', '2024-02-01T04:00:00-0500', '2018-04-04T16:00:00.000Z'). UTC is assumed unless a timezone offset is supplied. The subscription will be billed close to (typically within 30 minutes) the time portion of this date-time field. Note: if no time portion was specified during the creation of the subscription (i.e. '2022-04-01') then the time is defaulted to midnight UTC (00:00:00) and the subscription will be billed around 7PM Eastern on the *previous* day.
cancel_atstring date-timeoptional
A date in the future at which the subscription will automatically get canceled.
currencystring (aud | cad | dkk | eur | hkd | jpy | nzd | nok | …)required
Three-letter ISO currency code, in lowercase.
customer_idstringrequired
The id of the customer who owns the subscription.
interval_countnumberoptional
The number of intervals (specified in the interval_unit attribute) between subscription billings. For example, interval_unit=month and interval_count=3 bills every 3 months.
interval_unitstring (week | month | year)required
The frequency at which a subscription is billed. One of week, month or year.
metadataobjectoptional
Set of [key-value pairs](#section/Metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value (i.e. '' or null) to them. All keys can be unset by posting an empty value (i.e. {} or null) to metadata.
payment_method_idstringrequired
The id of the PaymentMethod used for this subscription. It must belong to the customer associated with the subscription.
platform_fee_amountnumberoptional
The amount of the fee (if any) that will be requested to be applied to the payment and transferred to the partner account. The amount of the fee collected will be capped a the total payment amount.
pricenumberrequired
Amount intended to be collected by this subscription. A positive integer representing how much to charge in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).

Example request

{
  "billing_cycle_anchor": "2024-07-04",
  "currency": "usd",
  "customer_id": "{{CUSTOMER_ID}}",
  "interval_count": 1,
  "interval_unit": "week",
  "metadata": {
    "order_id": "100123",
    "internal_customer_id": "7cb1159d-875e-47ae-a309-319fa7ff395b"
  },
  "payment_method_id": "{{PAYMENT_METHOD_ID}}",
  "platform_fee_amount": 500,
  "price": 10000
}

Example request

{
  "billing_cycle_anchor": "2024-07-04",
  "cancel_at": "2025-07-05",
  "currency": "usd",
  "customer_id": "{{CUSTOMER_ID}}",
  "interval_count": 1,
  "interval_unit": "week",
  "metadata": {
    "order_id": "100123",
    "internal_customer_id": "7cb1159d-875e-47ae-a309-319fa7ff395b"
  },
  "payment_method_id": "{{PAYMENT_METHOD_ID}}",
  "platform_fee_amount": 500,
  "price": 10000
}

Responses

201Subscription

account_idstringrequired
The id of the associated account.
apply_surchargebooleanoptional
Whether to apply the account's surcharge rate to payments created by this subscription. If true, the percentage amount set in surcharge_rate will be applied to payments created by this subscription.
billing_cycle_anchorstring date-timerequired
Determines the date of the first payment and the day of week/month/year for subsequent payments. If a month doesn't have the anchor day, the subscription will be billed on the last day of the month. For example, a monthly subscription starting on January 31 bills on Feb 28/29, then March 31, April 30, etc. The subscription will be billed close to (typically within 30 minutes) the time portion of this date-time field. Note: if no time portion was specified during the creation of the subscription (i.e. '2022-04-01') then the time is defaulted to midnight UTC (00:00:00) and the subscription will be billed around 7PM Eastern on the *previous* day.
cancel_atstring date-timeoptional
A date in the future at which the subscription will automatically get canceled.
canceled_atstring date-timeoptional
If the subscription has been canceled, the date of that cancellation.
created_atstring date-timerequired
Time at which the object was created.
currencystring (aud | cad | dkk | eur | hkd | jpy | nzd | nok | …)required
Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase.
customer_idstringrequired
The id of the customer who owns the subscription.
idstringrequired
Unique identifier for the object.
interval_countnumberrequired
The number of intervals (specified in the interval_unit attribute) between subscription billings. For example, interval_unit=month and interval_count=3 bills every 3 months.
interval_unitstring (week | month | year)required
The frequency at which a subscription is billed. One of week, month or year.
metadataobjectoptional
Set of [key-value pairs](#section/Metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. This metadata will be copied to the payment_intent.metadata field when a payment is attempted.
next_payment_atstring date-timeoptional
The date at which payment will next be attempted. The value will be null when no more payments are to be attempted. Examples: canceled and paused statuses or cancel_at is prior to what would be the next payment date. When a payment fails and the status changes to past_due this value can be manually updated to determine the next attempt.
pause_atstring date-timeoptional
A date in the future at which the subscription will automatically get paused.
paused_atstring date-timeoptional
If the subscription has been paused, the date of the most recent pausing.
payment_method_idstringrequired
The id of the PaymentMethod used for this subscription. It must belong to the customer associated with the subscription.
platform_fee_amountnumberoptional
The amount of the fee (if any) that will be requested to be applied to the payment and transferred to the partner account. The amount of the fee collected will be capped a the total payment amount.
pricenumberrequired
Amount intended to be collected by this subscription. A positive integer representing how much to charge in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).
resume_atstring date-timeoptional
If the subscription has been paused, the date in the future at which the subscription will automatically return to active.
statusstring (active | canceled | past_due | paused | pending | requires_confirmation)required
Status of this subscription, one of active, canceled, past_due, paused, or pending.
surcharge_amountnumber int64optional
Amount (in the smallest currency unit) of the surcharge applied to the subscription.
surcharge_ratenumber floatoptional
If set, the percentage amount that will be applied to payments created by this subscription. A decimal value with up to three decimal places representing a percentage (e.g., 7.5 for 7.5%). The amount will be the surcharge rate set on the account at the time the subscription is created. In order for this to be set, surcharging must be enabled on the account and apply_surcharge must be true.
updated_atstring date-timerequired
Time at which the object was last updated.

GET/v1/subscriptions/{id}

Get a Subscription

Retrieves the details of an existing Subscription.

Path parameters

idstringrequired

Header parameters

payments-accountstringrequired
The id of the Paydude Account (usually starting with the prefix acct_) that the request is performed on behalf of. Must be a merchant (connected) account id, not the partner account you signed up with; a partner account passes GET /v1/accounts and then fails with "not enabled for this account" on the first payment call.

Responses

200Subscription

account_idstringrequired
The id of the associated account.
apply_surchargebooleanoptional
Whether to apply the account's surcharge rate to payments created by this subscription. If true, the percentage amount set in surcharge_rate will be applied to payments created by this subscription.
billing_cycle_anchorstring date-timerequired
Determines the date of the first payment and the day of week/month/year for subsequent payments. If a month doesn't have the anchor day, the subscription will be billed on the last day of the month. For example, a monthly subscription starting on January 31 bills on Feb 28/29, then March 31, April 30, etc. The subscription will be billed close to (typically within 30 minutes) the time portion of this date-time field. Note: if no time portion was specified during the creation of the subscription (i.e. '2022-04-01') then the time is defaulted to midnight UTC (00:00:00) and the subscription will be billed around 7PM Eastern on the *previous* day.
cancel_atstring date-timeoptional
A date in the future at which the subscription will automatically get canceled.
canceled_atstring date-timeoptional
If the subscription has been canceled, the date of that cancellation.
created_atstring date-timerequired
Time at which the object was created.
currencystring (aud | cad | dkk | eur | hkd | jpy | nzd | nok | …)required
Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase.
customer_idstringrequired
The id of the customer who owns the subscription.
idstringrequired
Unique identifier for the object.
interval_countnumberrequired
The number of intervals (specified in the interval_unit attribute) between subscription billings. For example, interval_unit=month and interval_count=3 bills every 3 months.
interval_unitstring (week | month | year)required
The frequency at which a subscription is billed. One of week, month or year.
metadataobjectoptional
Set of [key-value pairs](#section/Metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. This metadata will be copied to the payment_intent.metadata field when a payment is attempted.
next_payment_atstring date-timeoptional
The date at which payment will next be attempted. The value will be null when no more payments are to be attempted. Examples: canceled and paused statuses or cancel_at is prior to what would be the next payment date. When a payment fails and the status changes to past_due this value can be manually updated to determine the next attempt.
pause_atstring date-timeoptional
A date in the future at which the subscription will automatically get paused.
paused_atstring date-timeoptional
If the subscription has been paused, the date of the most recent pausing.
payment_method_idstringrequired
The id of the PaymentMethod used for this subscription. It must belong to the customer associated with the subscription.
platform_fee_amountnumberoptional
The amount of the fee (if any) that will be requested to be applied to the payment and transferred to the partner account. The amount of the fee collected will be capped a the total payment amount.
pricenumberrequired
Amount intended to be collected by this subscription. A positive integer representing how much to charge in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).
resume_atstring date-timeoptional
If the subscription has been paused, the date in the future at which the subscription will automatically return to active.
statusstring (active | canceled | past_due | paused | pending | requires_confirmation)required
Status of this subscription, one of active, canceled, past_due, paused, or pending.
surcharge_amountnumber int64optional
Amount (in the smallest currency unit) of the surcharge applied to the subscription.
surcharge_ratenumber floatoptional
If set, the percentage amount that will be applied to payments created by this subscription. A decimal value with up to three decimal places representing a percentage (e.g., 7.5 for 7.5%). The amount will be the surcharge rate set on the account at the time the subscription is created. In order for this to be set, surcharging must be enabled on the account and apply_surcharge must be true.
updated_atstring date-timerequired
Time at which the object was last updated.

PATCH/v1/subscriptions/{id}

Update a Subscription

Updates an existing Subscription by setting the values of the provided parameters. Any parameters not provided will be left unchanged.

Path parameters

idstringrequired

Header parameters

payments-accountstringrequired
The id of the Paydude Account (usually starting with the prefix acct_) that the request is performed on behalf of. Must be a merchant (connected) account id, not the partner account you signed up with; a partner account passes GET /v1/accounts and then fails with "not enabled for this account" on the first payment call.

Request body application/jsonrequired

apply_surchargebooleanoptional
Whether to apply the account's surcharge rate to payments created by this subscription. If true, the surcharge rate set in the merchant account will be applied to payments created by this subscription. If surcharging is not enabled on the account, this field must be false or null otherwise the request will fail.
cancel_atstring date-timeoptional
A date in the future at which the subscription will automatically get canceled.
metadataobjectoptional
Set of [key-value pairs](#section/Metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value (i.e. '' or null) to them. All keys can be unset by posting an empty value (i.e. {} or null) to metadata.
pause_atstring date-timeoptional
The date in the future at which the subscription will automatically be paused.
payment_method_idstringoptional
The id of the PaymentMethod used for this subscription. It must belong to the customer associated with the subscription.
platform_fee_amountnumberoptional
The amount of the fee (if any) that will be requested to be applied to the payment and transferred to the partner account. The amount of the fee collected will be capped a the total payment amount.
pricenumberoptional
Amount intended to be collected by this subscription. A positive integer representing how much to charge in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).
resume_atstring date-timeoptional
The date in the future at which the subscription will automatically return to active.

Responses

200Subscription

account_idstringrequired
The id of the associated account.
apply_surchargebooleanoptional
Whether to apply the account's surcharge rate to payments created by this subscription. If true, the percentage amount set in surcharge_rate will be applied to payments created by this subscription.
billing_cycle_anchorstring date-timerequired
Determines the date of the first payment and the day of week/month/year for subsequent payments. If a month doesn't have the anchor day, the subscription will be billed on the last day of the month. For example, a monthly subscription starting on January 31 bills on Feb 28/29, then March 31, April 30, etc. The subscription will be billed close to (typically within 30 minutes) the time portion of this date-time field. Note: if no time portion was specified during the creation of the subscription (i.e. '2022-04-01') then the time is defaulted to midnight UTC (00:00:00) and the subscription will be billed around 7PM Eastern on the *previous* day.
cancel_atstring date-timeoptional
A date in the future at which the subscription will automatically get canceled.
canceled_atstring date-timeoptional
If the subscription has been canceled, the date of that cancellation.
created_atstring date-timerequired
Time at which the object was created.
currencystring (aud | cad | dkk | eur | hkd | jpy | nzd | nok | …)required
Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase.
customer_idstringrequired
The id of the customer who owns the subscription.
idstringrequired
Unique identifier for the object.
interval_countnumberrequired
The number of intervals (specified in the interval_unit attribute) between subscription billings. For example, interval_unit=month and interval_count=3 bills every 3 months.
interval_unitstring (week | month | year)required
The frequency at which a subscription is billed. One of week, month or year.
metadataobjectoptional
Set of [key-value pairs](#section/Metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. This metadata will be copied to the payment_intent.metadata field when a payment is attempted.
next_payment_atstring date-timeoptional
The date at which payment will next be attempted. The value will be null when no more payments are to be attempted. Examples: canceled and paused statuses or cancel_at is prior to what would be the next payment date. When a payment fails and the status changes to past_due this value can be manually updated to determine the next attempt.
pause_atstring date-timeoptional
A date in the future at which the subscription will automatically get paused.
paused_atstring date-timeoptional
If the subscription has been paused, the date of the most recent pausing.
payment_method_idstringrequired
The id of the PaymentMethod used for this subscription. It must belong to the customer associated with the subscription.
platform_fee_amountnumberoptional
The amount of the fee (if any) that will be requested to be applied to the payment and transferred to the partner account. The amount of the fee collected will be capped a the total payment amount.
pricenumberrequired
Amount intended to be collected by this subscription. A positive integer representing how much to charge in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).
resume_atstring date-timeoptional
If the subscription has been paused, the date in the future at which the subscription will automatically return to active.
statusstring (active | canceled | past_due | paused | pending | requires_confirmation)required
Status of this subscription, one of active, canceled, past_due, paused, or pending.
surcharge_amountnumber int64optional
Amount (in the smallest currency unit) of the surcharge applied to the subscription.
surcharge_ratenumber floatoptional
If set, the percentage amount that will be applied to payments created by this subscription. A decimal value with up to three decimal places representing a percentage (e.g., 7.5 for 7.5%). The amount will be the surcharge rate set on the account at the time the subscription is created. In order for this to be set, surcharging must be enabled on the account and apply_surcharge must be true.
updated_atstring date-timerequired
Time at which the object was last updated.

POST/v1/subscriptions/{id}/cancel

Cancel a Subscription

Cancels a Customer's Subscription immediately. The Customer will not be charged again for the Subscription.

Path parameters

idstringrequired

Header parameters

payments-accountstringrequired
The id of the Paydude Account (usually starting with the prefix acct_) that the request is performed on behalf of. Must be a merchant (connected) account id, not the partner account you signed up with; a partner account passes GET /v1/accounts and then fails with "not enabled for this account" on the first payment call.

Responses

200Subscription

account_idstringrequired
The id of the associated account.
apply_surchargebooleanoptional
Whether to apply the account's surcharge rate to payments created by this subscription. If true, the percentage amount set in surcharge_rate will be applied to payments created by this subscription.
billing_cycle_anchorstring date-timerequired
Determines the date of the first payment and the day of week/month/year for subsequent payments. If a month doesn't have the anchor day, the subscription will be billed on the last day of the month. For example, a monthly subscription starting on January 31 bills on Feb 28/29, then March 31, April 30, etc. The subscription will be billed close to (typically within 30 minutes) the time portion of this date-time field. Note: if no time portion was specified during the creation of the subscription (i.e. '2022-04-01') then the time is defaulted to midnight UTC (00:00:00) and the subscription will be billed around 7PM Eastern on the *previous* day.
cancel_atstring date-timeoptional
A date in the future at which the subscription will automatically get canceled.
canceled_atstring date-timeoptional
If the subscription has been canceled, the date of that cancellation.
created_atstring date-timerequired
Time at which the object was created.
currencystring (aud | cad | dkk | eur | hkd | jpy | nzd | nok | …)required
Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase.
customer_idstringrequired
The id of the customer who owns the subscription.
idstringrequired
Unique identifier for the object.
interval_countnumberrequired
The number of intervals (specified in the interval_unit attribute) between subscription billings. For example, interval_unit=month and interval_count=3 bills every 3 months.
interval_unitstring (week | month | year)required
The frequency at which a subscription is billed. One of week, month or year.
metadataobjectoptional
Set of [key-value pairs](#section/Metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. This metadata will be copied to the payment_intent.metadata field when a payment is attempted.
next_payment_atstring date-timeoptional
The date at which payment will next be attempted. The value will be null when no more payments are to be attempted. Examples: canceled and paused statuses or cancel_at is prior to what would be the next payment date. When a payment fails and the status changes to past_due this value can be manually updated to determine the next attempt.
pause_atstring date-timeoptional
A date in the future at which the subscription will automatically get paused.
paused_atstring date-timeoptional
If the subscription has been paused, the date of the most recent pausing.
payment_method_idstringrequired
The id of the PaymentMethod used for this subscription. It must belong to the customer associated with the subscription.
platform_fee_amountnumberoptional
The amount of the fee (if any) that will be requested to be applied to the payment and transferred to the partner account. The amount of the fee collected will be capped a the total payment amount.
pricenumberrequired
Amount intended to be collected by this subscription. A positive integer representing how much to charge in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).
resume_atstring date-timeoptional
If the subscription has been paused, the date in the future at which the subscription will automatically return to active.
statusstring (active | canceled | past_due | paused | pending | requires_confirmation)required
Status of this subscription, one of active, canceled, past_due, paused, or pending.
surcharge_amountnumber int64optional
Amount (in the smallest currency unit) of the surcharge applied to the subscription.
surcharge_ratenumber floatoptional
If set, the percentage amount that will be applied to payments created by this subscription. A decimal value with up to three decimal places representing a percentage (e.g., 7.5 for 7.5%). The amount will be the surcharge rate set on the account at the time the subscription is created. In order for this to be set, surcharging must be enabled on the account and apply_surcharge must be true.
updated_atstring date-timerequired
Time at which the object was last updated.

POST/v1/subscriptions/{id}/confirm

Confirm a Subscription

Confirms a new Subscription. Used for subscriptions that require confirmation from the customer (e.g., when applying a surcharge).

Path parameters

idstringrequired

Header parameters

payments-accountstringrequired
The id of the Paydude Account (usually starting with the prefix acct_) that the request is performed on behalf of. Must be a merchant (connected) account id, not the partner account you signed up with; a partner account passes GET /v1/accounts and then fails with "not enabled for this account" on the first payment call.

Responses

200Subscription

account_idstringrequired
The id of the associated account.
apply_surchargebooleanoptional
Whether to apply the account's surcharge rate to payments created by this subscription. If true, the percentage amount set in surcharge_rate will be applied to payments created by this subscription.
billing_cycle_anchorstring date-timerequired
Determines the date of the first payment and the day of week/month/year for subsequent payments. If a month doesn't have the anchor day, the subscription will be billed on the last day of the month. For example, a monthly subscription starting on January 31 bills on Feb 28/29, then March 31, April 30, etc. The subscription will be billed close to (typically within 30 minutes) the time portion of this date-time field. Note: if no time portion was specified during the creation of the subscription (i.e. '2022-04-01') then the time is defaulted to midnight UTC (00:00:00) and the subscription will be billed around 7PM Eastern on the *previous* day.
cancel_atstring date-timeoptional
A date in the future at which the subscription will automatically get canceled.
canceled_atstring date-timeoptional
If the subscription has been canceled, the date of that cancellation.
created_atstring date-timerequired
Time at which the object was created.
currencystring (aud | cad | dkk | eur | hkd | jpy | nzd | nok | …)required
Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase.
customer_idstringrequired
The id of the customer who owns the subscription.
idstringrequired
Unique identifier for the object.
interval_countnumberrequired
The number of intervals (specified in the interval_unit attribute) between subscription billings. For example, interval_unit=month and interval_count=3 bills every 3 months.
interval_unitstring (week | month | year)required
The frequency at which a subscription is billed. One of week, month or year.
metadataobjectoptional
Set of [key-value pairs](#section/Metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. This metadata will be copied to the payment_intent.metadata field when a payment is attempted.
next_payment_atstring date-timeoptional
The date at which payment will next be attempted. The value will be null when no more payments are to be attempted. Examples: canceled and paused statuses or cancel_at is prior to what would be the next payment date. When a payment fails and the status changes to past_due this value can be manually updated to determine the next attempt.
pause_atstring date-timeoptional
A date in the future at which the subscription will automatically get paused.
paused_atstring date-timeoptional
If the subscription has been paused, the date of the most recent pausing.
payment_method_idstringrequired
The id of the PaymentMethod used for this subscription. It must belong to the customer associated with the subscription.
platform_fee_amountnumberoptional
The amount of the fee (if any) that will be requested to be applied to the payment and transferred to the partner account. The amount of the fee collected will be capped a the total payment amount.
pricenumberrequired
Amount intended to be collected by this subscription. A positive integer representing how much to charge in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).
resume_atstring date-timeoptional
If the subscription has been paused, the date in the future at which the subscription will automatically return to active.
statusstring (active | canceled | past_due | paused | pending | requires_confirmation)required
Status of this subscription, one of active, canceled, past_due, paused, or pending.
surcharge_amountnumber int64optional
Amount (in the smallest currency unit) of the surcharge applied to the subscription.
surcharge_ratenumber floatoptional
If set, the percentage amount that will be applied to payments created by this subscription. A decimal value with up to three decimal places representing a percentage (e.g., 7.5 for 7.5%). The amount will be the surcharge rate set on the account at the time the subscription is created. In order for this to be set, surcharging must be enabled on the account and apply_surcharge must be true.
updated_atstring date-timerequired
Time at which the object was last updated.

POST/v1/subscriptions/{id}/pause

Pause a Subscription

Pauses a Subscription from generating payments until the optionally specified resumes_at date.

Path parameters

idstringrequired

Header parameters

payments-accountstringrequired
The id of the Paydude Account (usually starting with the prefix acct_) that the request is performed on behalf of. Must be a merchant (connected) account id, not the partner account you signed up with; a partner account passes GET /v1/accounts and then fails with "not enabled for this account" on the first payment call.

Request body application/jsonrequired

resume_atstring date-timeoptional
The date in the future at which the subscription will automatically return to active.

Responses

200Subscription

account_idstringrequired
The id of the associated account.
apply_surchargebooleanoptional
Whether to apply the account's surcharge rate to payments created by this subscription. If true, the percentage amount set in surcharge_rate will be applied to payments created by this subscription.
billing_cycle_anchorstring date-timerequired
Determines the date of the first payment and the day of week/month/year for subsequent payments. If a month doesn't have the anchor day, the subscription will be billed on the last day of the month. For example, a monthly subscription starting on January 31 bills on Feb 28/29, then March 31, April 30, etc. The subscription will be billed close to (typically within 30 minutes) the time portion of this date-time field. Note: if no time portion was specified during the creation of the subscription (i.e. '2022-04-01') then the time is defaulted to midnight UTC (00:00:00) and the subscription will be billed around 7PM Eastern on the *previous* day.
cancel_atstring date-timeoptional
A date in the future at which the subscription will automatically get canceled.
canceled_atstring date-timeoptional
If the subscription has been canceled, the date of that cancellation.
created_atstring date-timerequired
Time at which the object was created.
currencystring (aud | cad | dkk | eur | hkd | jpy | nzd | nok | …)required
Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase.
customer_idstringrequired
The id of the customer who owns the subscription.
idstringrequired
Unique identifier for the object.
interval_countnumberrequired
The number of intervals (specified in the interval_unit attribute) between subscription billings. For example, interval_unit=month and interval_count=3 bills every 3 months.
interval_unitstring (week | month | year)required
The frequency at which a subscription is billed. One of week, month or year.
metadataobjectoptional
Set of [key-value pairs](#section/Metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. This metadata will be copied to the payment_intent.metadata field when a payment is attempted.
next_payment_atstring date-timeoptional
The date at which payment will next be attempted. The value will be null when no more payments are to be attempted. Examples: canceled and paused statuses or cancel_at is prior to what would be the next payment date. When a payment fails and the status changes to past_due this value can be manually updated to determine the next attempt.
pause_atstring date-timeoptional
A date in the future at which the subscription will automatically get paused.
paused_atstring date-timeoptional
If the subscription has been paused, the date of the most recent pausing.
payment_method_idstringrequired
The id of the PaymentMethod used for this subscription. It must belong to the customer associated with the subscription.
platform_fee_amountnumberoptional
The amount of the fee (if any) that will be requested to be applied to the payment and transferred to the partner account. The amount of the fee collected will be capped a the total payment amount.
pricenumberrequired
Amount intended to be collected by this subscription. A positive integer representing how much to charge in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).
resume_atstring date-timeoptional
If the subscription has been paused, the date in the future at which the subscription will automatically return to active.
statusstring (active | canceled | past_due | paused | pending | requires_confirmation)required
Status of this subscription, one of active, canceled, past_due, paused, or pending.
surcharge_amountnumber int64optional
Amount (in the smallest currency unit) of the surcharge applied to the subscription.
surcharge_ratenumber floatoptional
If set, the percentage amount that will be applied to payments created by this subscription. A decimal value with up to three decimal places representing a percentage (e.g., 7.5 for 7.5%). The amount will be the surcharge rate set on the account at the time the subscription is created. In order for this to be set, surcharging must be enabled on the account and apply_surcharge must be true.
updated_atstring date-timerequired
Time at which the object was last updated.

POST/v1/subscriptions/{id}/resume

Resume a Subscription

Resumes a paused Subscription immediately. The next charge will occur on the regular billing cycle.

Path parameters

idstringrequired

Header parameters

payments-accountstringrequired
The id of the Paydude Account (usually starting with the prefix acct_) that the request is performed on behalf of. Must be a merchant (connected) account id, not the partner account you signed up with; a partner account passes GET /v1/accounts and then fails with "not enabled for this account" on the first payment call.

Responses

200Subscription

account_idstringrequired
The id of the associated account.
apply_surchargebooleanoptional
Whether to apply the account's surcharge rate to payments created by this subscription. If true, the percentage amount set in surcharge_rate will be applied to payments created by this subscription.
billing_cycle_anchorstring date-timerequired
Determines the date of the first payment and the day of week/month/year for subsequent payments. If a month doesn't have the anchor day, the subscription will be billed on the last day of the month. For example, a monthly subscription starting on January 31 bills on Feb 28/29, then March 31, April 30, etc. The subscription will be billed close to (typically within 30 minutes) the time portion of this date-time field. Note: if no time portion was specified during the creation of the subscription (i.e. '2022-04-01') then the time is defaulted to midnight UTC (00:00:00) and the subscription will be billed around 7PM Eastern on the *previous* day.
cancel_atstring date-timeoptional
A date in the future at which the subscription will automatically get canceled.
canceled_atstring date-timeoptional
If the subscription has been canceled, the date of that cancellation.
created_atstring date-timerequired
Time at which the object was created.
currencystring (aud | cad | dkk | eur | hkd | jpy | nzd | nok | …)required
Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase.
customer_idstringrequired
The id of the customer who owns the subscription.
idstringrequired
Unique identifier for the object.
interval_countnumberrequired
The number of intervals (specified in the interval_unit attribute) between subscription billings. For example, interval_unit=month and interval_count=3 bills every 3 months.
interval_unitstring (week | month | year)required
The frequency at which a subscription is billed. One of week, month or year.
metadataobjectoptional
Set of [key-value pairs](#section/Metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. This metadata will be copied to the payment_intent.metadata field when a payment is attempted.
next_payment_atstring date-timeoptional
The date at which payment will next be attempted. The value will be null when no more payments are to be attempted. Examples: canceled and paused statuses or cancel_at is prior to what would be the next payment date. When a payment fails and the status changes to past_due this value can be manually updated to determine the next attempt.
pause_atstring date-timeoptional
A date in the future at which the subscription will automatically get paused.
paused_atstring date-timeoptional
If the subscription has been paused, the date of the most recent pausing.
payment_method_idstringrequired
The id of the PaymentMethod used for this subscription. It must belong to the customer associated with the subscription.
platform_fee_amountnumberoptional
The amount of the fee (if any) that will be requested to be applied to the payment and transferred to the partner account. The amount of the fee collected will be capped a the total payment amount.
pricenumberrequired
Amount intended to be collected by this subscription. A positive integer representing how much to charge in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).
resume_atstring date-timeoptional
If the subscription has been paused, the date in the future at which the subscription will automatically return to active.
statusstring (active | canceled | past_due | paused | pending | requires_confirmation)required
Status of this subscription, one of active, canceled, past_due, paused, or pending.
surcharge_amountnumber int64optional
Amount (in the smallest currency unit) of the surcharge applied to the subscription.
surcharge_ratenumber floatoptional
If set, the percentage amount that will be applied to payments created by this subscription. A decimal value with up to three decimal places representing a percentage (e.g., 7.5 for 7.5%). The amount will be the surcharge rate set on the account at the time the subscription is created. In order for this to be set, surcharging must be enabled on the account and apply_surcharge must be true.
updated_atstring date-timerequired
Time at which the object was last updated.

POST/v1/subscriptions/{id}/retry

Retry a Subscription

Retries a subscription payment at the optionally specified next_payment_at date.

Path parameters

idstringrequired

Header parameters

payments-accountstringrequired
The id of the Paydude Account (usually starting with the prefix acct_) that the request is performed on behalf of. Must be a merchant (connected) account id, not the partner account you signed up with; a partner account passes GET /v1/accounts and then fails with "not enabled for this account" on the first payment call.

Request body application/jsonrequired

next_payment_atstring date-timeoptional
The date in the future at which the subscription will attempt to retry payment. The default is today.

Responses

200Subscription

account_idstringrequired
The id of the associated account.
apply_surchargebooleanoptional
Whether to apply the account's surcharge rate to payments created by this subscription. If true, the percentage amount set in surcharge_rate will be applied to payments created by this subscription.
billing_cycle_anchorstring date-timerequired
Determines the date of the first payment and the day of week/month/year for subsequent payments. If a month doesn't have the anchor day, the subscription will be billed on the last day of the month. For example, a monthly subscription starting on January 31 bills on Feb 28/29, then March 31, April 30, etc. The subscription will be billed close to (typically within 30 minutes) the time portion of this date-time field. Note: if no time portion was specified during the creation of the subscription (i.e. '2022-04-01') then the time is defaulted to midnight UTC (00:00:00) and the subscription will be billed around 7PM Eastern on the *previous* day.
cancel_atstring date-timeoptional
A date in the future at which the subscription will automatically get canceled.
canceled_atstring date-timeoptional
If the subscription has been canceled, the date of that cancellation.
created_atstring date-timerequired
Time at which the object was created.
currencystring (aud | cad | dkk | eur | hkd | jpy | nzd | nok | …)required
Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase.
customer_idstringrequired
The id of the customer who owns the subscription.
idstringrequired
Unique identifier for the object.
interval_countnumberrequired
The number of intervals (specified in the interval_unit attribute) between subscription billings. For example, interval_unit=month and interval_count=3 bills every 3 months.
interval_unitstring (week | month | year)required
The frequency at which a subscription is billed. One of week, month or year.
metadataobjectoptional
Set of [key-value pairs](#section/Metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. This metadata will be copied to the payment_intent.metadata field when a payment is attempted.
next_payment_atstring date-timeoptional
The date at which payment will next be attempted. The value will be null when no more payments are to be attempted. Examples: canceled and paused statuses or cancel_at is prior to what would be the next payment date. When a payment fails and the status changes to past_due this value can be manually updated to determine the next attempt.
pause_atstring date-timeoptional
A date in the future at which the subscription will automatically get paused.
paused_atstring date-timeoptional
If the subscription has been paused, the date of the most recent pausing.
payment_method_idstringrequired
The id of the PaymentMethod used for this subscription. It must belong to the customer associated with the subscription.
platform_fee_amountnumberoptional
The amount of the fee (if any) that will be requested to be applied to the payment and transferred to the partner account. The amount of the fee collected will be capped a the total payment amount.
pricenumberrequired
Amount intended to be collected by this subscription. A positive integer representing how much to charge in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).
resume_atstring date-timeoptional
If the subscription has been paused, the date in the future at which the subscription will automatically return to active.
statusstring (active | canceled | past_due | paused | pending | requires_confirmation)required
Status of this subscription, one of active, canceled, past_due, paused, or pending.
surcharge_amountnumber int64optional
Amount (in the smallest currency unit) of the surcharge applied to the subscription.
surcharge_ratenumber floatoptional
If set, the percentage amount that will be applied to payments created by this subscription. A decimal value with up to three decimal places representing a percentage (e.g., 7.5 for 7.5%). The amount will be the surcharge rate set on the account at the time the subscription is created. In order for this to be set, surcharging must be enabled on the account and apply_surcharge must be true.
updated_atstring date-timerequired
Time at which the object was last updated.