The field will be disregarded if it is marked as optional and the format provided is incorrect. However, a validation error will be displayed if the field is marked as mandatory and the format provided is incorrect.

"+" - means required (for all flows)
"-" - means not required (for any flow)
For instance, in POST Create Charge flow:
+6 means that the field is required for flow number 6
-6 means that the field is not required for flow number 6


Subscriptions are recurring billing events. These can be set up to take scheduled payments from a customer without having to re-enter the billing details.


The response is different depending on such conditions:

  1. Created with a credit card payment source
  2. Created with an existing customer
  3. Created with a one-time token

Subscription resource

fieldrequired [flow]typedescription
amount+floatAn amount of the payment
currency+string (iso4217 alpha-3)A currency code
description-stringA manually defined description for payments in payment systems
reference-stringA manually defined reference for payments in payment systems
_id+string (24 hex characters)A subscription ID for any future requests
created_at+string(ISO 8601 format - yyyy-mm-ddThh:mm:ss.sssZ)A subscription creation date
updated_at+string(ISO 8601 format - yyyy-mm-ddThh:mm:ss.sssZ)A date of the last subscription update
status+stringAn actual subscription status. See the status table
held_at+string(ISO 8601 format - yyyy-mm-ddThh:mm:ss.sssZ)The time when subscription was moved to the held status
expired_at+string(ISO 8601 format - yyyy-mm-ddThh:mm:ss.sssZ)An actual expiration time of the subscription
expired_reason+stringAn actual expiration reason of the subscription. See the Expire reason table
last_change_by+stringDefines the origin of the last change of the subscription. Values: manual or automatic
latest_charge_id+string (24 hex characters)The latest charge ID of the subscription
archived+boolFor newly created charges, it is always false, true is set after manual archivation
customer+objectAn object with the customer’s information
customer.customer_id+2string (24 hex characters)A customer ID
customer.first_name-stringA customer's first name
customer.last_name-stringA customer's last name
customer.email-stringA customer's email
customer.phone-string(E.164)A customer's phone in the E.164 international notation (Example: +12345678901)
customer.payment_source+objectAn object with payment information
customer.payment_source.source_id+2, -3string (24 hex characters)A customer's payment source ID
customer.payment_source.gateway_id+string (24 hex characters)A gateway id
customer.payment_source.gateway_type+stringA type of the gateway
customer.payment_source.gateway_name+stringA custom label of the gateway
customer.payment_source.type+stringA type of the payment source: card for payment sources created with a credit card, checkout for payment sources created with a checkout agreement (checkout button)
customer.payment_source.card_name+1stringA cardholder's name (as on card)
customer.payment_source.card_number_last4+1string(numeric)Card number last 4 digits
customer.payment_source.card_number_bin+1string(numeric)Card BIN number
customer.payment_source.card_scheme+1stringA cardholder's scheme (e.g. visa, mastercard etc...)
customer.payment_source.expire_month+1string(mm)A card expiration month
customer.payment_source.expire_year+1string(yyyy)A card expiration year
customer.payment_source.address_line1-stringA customer's address, line 1
customer.payment_source.address_line2-stringA customer's address, line 2
customer.payment_source.address_state-stringA customer's address, State
customer.payment_source.address_country-stringA customer's addresss, Country Code
customer.payment_source.address_city-stringA customer's address, City
customer.payment_source.address_postcode-stringA customer's address, Postcode
schedule+objectAn object with the subscription schedule information
schedule.interval+stringAn assessment interval: one-off, day, week, month, year
schedule.next_assessment+string(Date)A date of the next subscription assessment (payment)
schedule.first_assessment+string(Date)A date of the first subscription assessment (payment)
schedule.status+stringA schedule status. See the Schedule status table
schedule.locked+booleanDefines if the schedule is locked
schedule.completed_count+integerA count of successful transactions
schedule.retry_count+integerA count of transaction retries for unsuccessful payments
schedule.frequency+string(numeric)An assessment frequency, 1 is set by default (e.g. “3” = “Every 3 weeks”)
schedule.start_date-string(ISO 8601 format - yyyy-mm-ddThh:mm:ss.sssZ)A start date of the subscription in the ISO 8601 format (yyyy-mm-ddThh:mm:ss.sssZ) or in a short type of date (yyyy-mm-dd)
schedule.end_date-string(ISO 8601 format - yyyy-mm-ddThh:mm:ss.sssZ)An end date of the subscription in the ISO 8601 format (yyyy-mm-ddThh:mm:ss.sssZ) or in a short type of date (yyyy-mm-dd)
schedule.end_amount_after-floatA total amount of all successful transactions (equals or exceeds)
schedule.end_amount_before-floatA total amount of all successful transactions (not to exceed)
schedule.end_amount_total-floatA total amount to be paid on the subscription (equals). NOTE: If the last payment of the subscription schedule is less than $ 1.00, some gateways may respond with an error and the subscription status will become ‘failed’.
schedule.end_transactions-integerA total count of all successful transactions
statistics+objectAn object with statistics information by charge
statistics.successful_transactions+numberA number of succesfull transactions
statistics.total_collected_amount+numberA total amount by subscription
meta-objectAn optional object with specific fields for different gateways
meta.account_id-stringAn ID of the existing, connected Stripe account. It is used to create Stripe connect Direct Charges
retry-objectAn optional object with specific fields for retry settings
retry.limit-integerA maximum amount of retried payments
retry.frequency-integerA retry frequency, 1 is used by default (i.e. “3” = “Every 3 weeks”)
retry.interval-stringA retry interval. Possible values: week, month, year, day
retry.fail_status-stringA status of the subscription after all the retries have gone through (active, held, failed, deleted, etc.)##


activeA subscription is active, and there are more payments to be collected
completeA subscription is complete, and all payments have been collected
deletedA subscription has been removed
failedThis typically occurs when the number of failed payments has been exceeded (see details of an error)
expiredA subscription that is complete, and has reached its end date
heldA subscription was manually put on hold

Expire reason

manualA subscription was expired manually
end_dateA subscription was expired by the end date settings
end_amount_totalA subscription was expired by the 'total amount' settings
end_amount_beforeA subscription was expired by the 'before amount' settings
end_amount_afterA subscription was expired by the 'after amount' settings
end_transactionsA subscription was expired by the 'count of transaction' settings

Schedule status

completeThe payment on the last schedule is processed successfully
failedThe payment on the last schedule was not processed successfully
heldThe held charge on the last schedule is created successfully