# Create a Subscription Create a resource to charge a regularly. If there is no trial period, the subscription will create a shortly after creation (within 60 minutes). The following options are available when creating a subscription. ### Adding a trial period You can create a subscription with a trial period by providing in the request body. After creating a subscription, a will occur after the trial period has elapsed. The property in the response determines when the transfer will take place. ### Adding a discount phase To apply a discount, include in the request body. Set as the discounted price and to specify how many billing intervals the discount applies. After this period, the customer is charged the full amount from the . ### Using a Subscription Plan Think of a as a template for the resource. When creating a subscription, you can use a by providing a . Doing so lets you base a subscription on existing values for , , and more. ### Future Subscription Schedule a subscription by setting to a future timestamp. The response will show as and as , indicating it has not started. This applies to both subscriptions with or without a subscription plan. ### Fixed-Length Subscription You can set a subscription to expire by specifying the , which indicates the number of recurring billing cycles in months or weeks. You can set subscriptions created from subscription plans to expire. ### Card Validation with $0 Authorization When creating a subscription using a card-type , Finix performs a $0 to validate the card. This check confirms that the card is active and verifies the billing address and security code (AVS and CVV). If the card fails validation, the API returns a error and the subscription is not created. This protects against invalid or risky cards, helping reduce failed payments and fraud. Endpoint: POST /subscriptions Version: 2022-02-01 Security: BasicAuth ## Header parameters: - `Finix-Version` (string) Specify the API version of your request. For more details, see Versioning. Example: "2022-02-01" ## Request fields (application/json): - `amount` (integer) The total amount that will be debited in cents (e.g. 100 cents to debit $1.00). - `buyer_details` (object, required) An object containing details about the subscriber. - `buyer_details.requested_delivery_methods` (array) A list of requested delivery methods. Each method specifies the type of delivery and the destination(s) where the receipt should be sent. - `buyer_details.requested_delivery_methods.type` (string, required) The method of receipt delivery. Enum: "EMAIL", "SMS", "PRINT" - `buyer_details.requested_delivery_methods.destinations` (array, required) A list of destination addresses or identifiers where the receipt should be sent. - `buyer_details.identity_id` (string, required) The [identity ID](/api/identities) of the subscriber. - `buyer_details.instrument_id` (any, required) The ID of the [](/api/payment-instruments) from which the subscription payments get debited. - `currency` (string, required) ISO 4217 3-letter currency code. Currently, the only supported is . Enum: "USD" - `linked_to` (string, required) he ID of the [](#Merchants) resource that you wish to link to the (i.e., the merchant that the subscription belongs to). At this time, only approved merchants with one of the following processors are valid: - - - `linked_type` (string, required) The type of the resource that is specified in the field. Enum: "MERCHANT" - `nickname` (string) A human-readable name for the resource. Example: "super important thing" - `billing_interval` (string, required) How often the subscriber is billed. Enum: "DAILY", "WEEKLY", "MONTHLY", "QUARTERLY", "YEARLY" - `start_subscription_at` (string) Indicates that the subscription is scheduled to begin in the future. The timestamp specifies the exact start date for subscription billing. - `subscription_plan_id` (string) The ID of the from which to create the . - `subscription_details` (object, required) An object containing subscription details. - `subscription_details.collection_method` (string, required) The method by which subscription payments are collected. Currently, automatically billing the card on file is the only method available. Enum: "BILL_AUTOMATICALLY" - `subscription_details.trial_details` (object) Object containing trial details. - `subscription_details.trial_details.interval_type` (string, required) The unit of time for the trial period. Enum: "DAY", "WEEK", "MONTH", "YEAR" - `subscription_details.trial_details.interval_count` (integer, required) The number of intervals of used to describe the duration of the trial. - `subscription_details.discount_details` (object) Object containing discount details. - `subscription_details.discount_details.interval_type` (string, required) The unit of time for the discount period. Enum: "DAY", "WEEK", "MONTH", "YEAR" - `subscription_details.discount_details.billing_interval_count` (integer, required) The number of billing intervals the discount applies. After this period, the subscriber is charged the full from the . - `total_billing_intervals` (integer) The total number of billing intervals for the . This represents the total count of recurring billing cycles, such as months or weeks, depending on the billing frequency. - `tags` (object,null) Include up to 50 pairs to annotate requests with custom metadata. - Maximum character length for individual is 40. - Maximum character length for individual is 500. (For example, , , ) ## Response 201 fields (application/json): - `id` (string) The ID of the resource. - `created_at` (string) Timestamp of when the object was created. - `updated_at` (string) Timestamp of when the object was last updated. - `first_charge_at` (string) Timestamp when the first [](#Transfers) will occur. - `amount` (integer) The total amount that will be debited in cents (e.g. 100 cents to debit $1.00). - `buyer_details` (object) An object containing details about the subscriber. - `buyer_details.identity_id` (string) The [identity ID](/api/identities) of the subscriber. - `buyer_details.instrument_id` (any) The ID of the [](/api/payment-instruments) from which the subscription payments get debited. - `buyer_details.requested_delivery_methods` (array) A list of requested delivery methods. Each method specifies the type of delivery and the destination(s) where the receipt should be sent. - `buyer_details.requested_delivery_methods.type` (string, required) The method of receipt delivery. Enum: "EMAIL", "SMS", "PRINT" - `buyer_details.requested_delivery_methods.destinations` (array, required) A list of destination addresses or identifiers where the receipt should be sent. - `currency` (string) ISO 4217 3-letter currency code. Currently, the only supported is . Enum: "USD" - `linked_to` (string) The ID of the [](#Merchants) resource that you wish to link to the (i.e., the merchant that the subscription belongs to). At this time, only approved merchants with one of the following processors are valid: - - - `linked_type` (string) The type of the resource that is specified in the field. Enum: "MERCHANT" - `nickname` (string) A human-readable name for the resource. Example: "super important thing" - `billing_interval` (string) How often the subscriber is billed. Enum: "DAILY", "WEEKLY", "MONTHLY", "QUARTERLY", "YEARLY" - `subscription_plan_id` (string) The ID of the from which to create the . - `start_subscription_at` (string) Indicates that the subscription is scheduled to begin in the future. The timestamp specifies the exact start date for subscription billing. - `subscription_details` (object) An object containing subscription details. - `subscription_details.collection_method` (string, required) The method by which subscription payments are collected. Currently, automatically billing the card on file is the only method available. Enum: "BILL_AUTOMATICALLY" - `subscription_details.send_invoice` (boolean) Whether to send the user an invoice. - `subscription_details.send_receipt` (boolean) Whether to send the user a receipt. - `subscription_details.trial_details` (object) Object containing trial details. - `subscription_details.trial_details.interval_type` (string) The unit of time for the trial period. Enum: "DAY", "WEEK", "MONTH", "YEAR" - `subscription_details.trial_details.interval_count` (integer) The number of intervals of used to describe the duration of the trial. - `subscription_details.trial_details.trial_started_at` (string) A timestamp indicating when the trial period began. - `subscription_details.trial_details.trial_expected_end_at` (string) A timestamp indicating when the trial period ends. - `subscription_details.discount_details` (object) Object containing discount details. - `subscription_details.discount_details.interval_type` (string, required) The unit of time for the discount period. Enum: "DAY", "WEEK", "MONTH", "YEAR" - `subscription_details.discount_details.billing_interval_count` (integer, required) The number of billing intervals the discount applies. After this period, the subscriber is charged the full from the . - `subscription_phase` (string) Indicates the period within a subscription where specific rules apply. - - The subscriber is billed continuously for the subscription until the subscription is canceled. - A state is applicable to fixed-length subscriptions. - - Indicates that when the timestamp is set during subscription creation, the subscription is not yet in any phase, and billing has not started. - - The period during which the subscriber is not billed; after this phase, the subscriber will begin being billed. Enum: "EVERGREEN", "FIXED", "NONE", "TRIAL" - `state` (string) The state of the . - The state occurs when the subscription has not yet started, typically indicated by a timestamp set during creation. - A subscription in the state is unpaid but has not yet been canceled. Enum: "ACTIVE", "CANCELED", "EXPIRED", "NOT_STARTED", "PAST_DUE" - `total_billing_intervals` (integer) The total number of billing intervals for the . This represents the total count of recurring billing cycles, such as months or weeks, depending on the billing frequency. - `expires_at` (string) The date-time that the expires if is set for the . - `tags` (object,null) Include up to 50 pairs to annotate requests with custom metadata. - Maximum character length for individual is 40. - Maximum character length for individual is 500. (For example, , , ) - `_links` (object) An object containing link(s) relevant to the request. You can store these links for follow-up requests. - `_links.self` (object) - `_links.self.href` (string) The path to the new resource. ## Response 401 fields (application/json): - `total` (integer) - `_embedded` (object) - `_embedded.errors` (array) - `_embedded.errors.code` (string) Enum: "UNKNOWN" - `_embedded.errors.logref` (object) - `_embedded.errors.message` (string) - `_embedded.errors._links` (object) - `_embedded.errors._links.self` (object) - `_embedded.errors._links.self.href` (string) - `_embedded.errors._links.source` (object) ## Response 403 fields (application/json): - `total` (integer) - `_embedded` (object) - `_embedded.errors` (array) - `_embedded.errors.code` (string) Enum: "FORBIDDEN" - `_embedded.errors.logref` (object) - `_embedded.errors.message` (string) - `_embedded.errors._links` (object) - `_embedded.errors._links.source` (object) - `_embedded.errors._links.source.href` (string) ## Response 404 fields (application/json): - `total` (integer) - `_embedded` (object) - `_embedded.errors` (array) - `_embedded.errors.code` (string) Enum: "NOT_FOUND" - `_embedded.errors.logref` (object) - `_embedded.errors.message` (string) - `_embedded.errors._links` (object) - `_embedded.errors._links.source` (object) - `_embedded.errors._links.source.href` (string) ## Response 422 fields (application/json): - `total` (integer) - `_embedded` (object) - `_embedded.errors` (array) - `_embedded.errors.code` (string) Enum: "INVALID_FIELD" - `_embedded.errors.field` (string) - `_embedded.errors.logref` (object) - `_embedded.errors.message` (string) - `_embedded.errors._links` (object) - `_embedded.errors._links.source` (object) - `_embedded.errors._links.source.href` (string)