> ## Documentation Index > Fetch the complete documentation index at: https://docs.fintoc.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a subscription > Creates a subscription that bills a customer on a recurring cadence, in the `live` or `test` mode of the API key used. Each item defines its price through `price_data`, referencing an existing product (`product`) or defining one inline (`product_data`). All items must share a compatible currency (`CLF` items bill alongside `CLP`) and the same recurring `interval` and `interval_count`. A subscription can have up to 10 items. Fintoc charges each subscription automatically using `payment_method`, so the `collection_method` is always `charge_automatically`. The `payment_method` must be active and have a type of `pac` or `card`; subscriptions do not support `bank_transfer`. Without `trial_end`, Fintoc sets the `billing_cycle_anchor` to the creation time and finalizes an initial invoice immediately. The subscription starts `incomplete` and becomes `active` once that first payment succeeds. For a zero-amount subscription, Fintoc marks the initial invoice paid and the subscription starts `active`. With `trial_end`, the subscription's status is `trialing`. Fintoc sets the `billing_cycle_anchor` to the trial end and generates the first invoice when the trial ends. **`v2`** ยท Base URL `https://api.fintoc.com/v2` ## OpenAPI ````yaml reference/fintoc-api-v2.json POST /subscriptions openapi: 3.1.0 info: title: fintoc-api-v2 version: v2026-02-01 servers: - url: https://api.fintoc.com/v2 security: [] paths: /subscriptions: post: tags: - Subscriptions summary: Create a subscription description: >- Creates a subscription that bills a customer on a recurring cadence, in the `live` or `test` mode of the API key used. Each item defines its price through `price_data`, referencing an existing product (`product`) or defining one inline (`product_data`). All items must share a compatible currency (`CLF` items bill alongside `CLP`) and the same recurring `interval` and `interval_count`. A subscription can have up to 10 items. Fintoc charges each subscription automatically using `payment_method`, so the `collection_method` is always `charge_automatically`. The `payment_method` must be active and have a type of `pac` or `card`; subscriptions do not support `bank_transfer`. Without `trial_end`, Fintoc sets the `billing_cycle_anchor` to the creation time and finalizes an initial invoice immediately. The subscription starts `incomplete` and becomes `active` once that first payment succeeds. For a zero-amount subscription, Fintoc marks the initial invoice paid and the subscription starts `active`. With `trial_end`, the subscription's status is `trialing`. Fintoc sets the `billing_cycle_anchor` to the trial end and generates the first invoice when the trial ends. operationId: subscriptions-create parameters: [] requestBody: content: application/json: schema: type: object properties: customer: type: string description: ID of the customer to bill. example: cus_2c4mDe9NJyGmMzvCqLkXqAtjnRu payment_method: type: string description: >- Payment method to charge automatically on every billing cycle. Must belong to the specified `customer`. example: pm_2c4mDhAbCdEfGhIjKlMnOpQrStu items: type: array maxItems: 10 description: >- Items the subscription bills for on every billing cycle. All items must share a compatible currency (`CLF` bills alongside `CLP`) and the same recurring cadence. Up to 10 items. items: type: object properties: price_data: type: object description: >- Definition of the price the item bills for. Fintoc creates a new price for the item. properties: currency: type: string enum: - CLF - CLP - MXN description: >- Three-letter ISO 4217 currency code, in uppercase. One of `CLP`, `MXN`, or `CLF`. A `CLF` (UF) item bills within a `CLP` subscription: it is converted to `CLP` using the exchange rate at the billing period start. example: CLP recurring: type: object description: Billing cadence of the price. properties: interval: type: string enum: - month - year description: >- Frequency at which the price bills. One of `month` or `year`. example: month interval_count: type: integer description: >- Number of intervals between each billing cycle. For example, `interval: "month"` with `interval_count: 3` bills every 3 months. example: 1 required: - interval - interval_count unit_amount: type: integer description: >- Amount the price bills per unit, in the smallest unit of the currency. CLP has no decimals, so `10000` is $10,000 CLP; MXN uses centavos, so `10000` is $100.00 MXN. example: 10000 product: type: string description: >- ID of an existing product the price belongs to. Mutually exclusive with `product_data`; exactly one of the two is required. example: prod_2c4mDgwQqkNwMHnXSc4DBjkbcWz product_data: type: object description: >- Inline definition of a new product for the price. Mutually exclusive with `product`; exactly one of the two is required. properties: name: type: string description: Name of the product. example: Premium plan description: type: string description: Free-text description of the product. example: Access to every premium feature. image_url: type: string description: HTTPS URL of an image of the product. example: https://example.com/image.png metadata: type: object description: >- Set of key-value pairs to attach to the product. Nested objects and arrays are not allowed as values. example: category: saas required: - name required: - currency - recurring - unit_amount quantity: type: integer description: >- Number of units of the price the item bills for. Must be greater than zero. example: 1 required: - price_data - quantity metadata: type: object description: >- Set of key-value pairs to attach to the subscription. Nested objects and arrays are not allowed as values. example: internal_id: '12345' trial_end: type: string format: date-time description: >- ISO 8601 timestamp in UTC at which the trial ends, at least one day in the future. During the trial the subscription's status is `trialing` and Fintoc issues no invoice; Fintoc generates the first invoice when the trial ends. Omit for no trial. example: '2030-07-08T00:00:00Z' required: - customer - payment_method - items examples: create_subscription: summary: Create a subscription value: customer: cus_2c4mDe9NJyGmMzvCqLkXqAtjnRu payment_method: pm_2c4mDhAbCdEfGhIjKlMnOpQrStu items: - price_data: currency: CLP recurring: interval: month interval_count: 1 unit_amount: 10000 product_data: name: Premium plan quantity: 1 metadata: internal_id: '12345' responses: '201': description: >- Subscription created. Fintoc generates and finalizes the initial invoice for the first billing period immediately. content: application/json: examples: subscription_created: value: id: sub_2c4mDcMaVxDx7nT3o5GbPMQbS2v object: subscription billing_cycle_anchor: '2026-06-01T15:00:00Z' collection_method: charge_automatically created_at: '2026-06-01T15:00:00Z' customer: cus_2c4mDe9NJyGmMzvCqLkXqAtjnRu items: - id: si_2c4mDfkPLLrLTCJ3wPCEHGYpkVf object: subscription_item price: currency: CLP product: id: prod_2c4mDgwQqkNwMHnXSc4DBjkbcWz object: product created_at: '2026-06-01T15:00:00Z' description: null image_url: null metadata: {} mode: live name: Premium plan recurring: interval: month interval_count: 1 unit_amount: 10000 quantity: 1 metadata: internal_id: '12345' mode: live payment_method: pm_2c4mDhAbCdEfGhIjKlMnOpQrStu status: incomplete trial_end: null schema: $ref: '#/components/schemas/subscription' '400': description: >- Invalid request: a required parameter is missing, the items are invalid or inconsistent, or there are more than 10 items. content: application/json: examples: missing_customer: value: error: type: invalid_request_error code: missing_parameter param: customer message: 'Missing required param: customer' doc_url: https://docs.fintoc.com/reference/errors schema: $ref: '#/components/schemas/error_object' '401': description: Invalid or missing API key. content: application/json: examples: invalid_api_key: value: error: type: authentication_error code: invalid_api_key message: 'Invalid API Key: invalid-*oken' schema: $ref: '#/components/schemas/error_object' '404': description: >- The referenced payment method does not exist or does not belong to the customer. content: application/json: examples: payment_method_not_found: value: error: type: invalid_request_error code: missing_resource message: 'No such payment_method: pm_2c4mDhAbCdEfGhIjKlMnOpQrStu' doc_url: https://docs.fintoc.com/reference/errors schema: $ref: '#/components/schemas/error_object' '409': description: 'Conflict: the items use currencies that cannot be billed together.' content: application/json: examples: currency_mismatch: value: error: type: invalid_request_error code: currency_mismatch message: >- Each subscription item's price currency must be compatible with the subscription's billing currency doc_url: https://docs.fintoc.com/reference/errors schema: $ref: '#/components/schemas/error_object' '422': description: >- The `payment_method` cannot be used for a subscription because the payment method is inactive or has an unsupported type. Subscriptions only accept `pac` or `card`, not `bank_transfer`. content: application/json: examples: payment_method_inactive: value: error: type: invalid_request_error code: payment_method_inactive message: >- Payment method is not active: pm_2c4mDhAbCdEfGhIjKlMnOpQrStu doc_url: https://docs.fintoc.com/reference/errors payment_method_type_not_supported: value: error: type: invalid_request_error code: payment_method_type_not_supported message: >- Payment method type not supported for subscriptions: bank_transfer doc_url: https://docs.fintoc.com/reference/errors schema: $ref: '#/components/schemas/error_object' security: - api_key: [] components: schemas: subscription: type: object properties: id: type: string description: Unique identifier of the subscription. example: sub_2c4mDcMaVxDx7nT3o5GbPMQbS2v object: const: subscription description: Type of the object. Always `subscription`. billing_cycle_anchor: type: string format: date-time description: >- ISO 8601 timestamp that anchors the billing cycle. Fintoc sets this anchor to the subscription's creation time, or to `trial_end` when a trial applies. Fintoc measures every billing period from this anchor. example: '2026-06-01T15:00:00Z' collection_method: type: string enum: - charge_automatically - send_invoice description: >- Method Fintoc uses to collect the invoices the subscription generates. One of `charge_automatically` (Fintoc charges the saved payment method) or `send_invoice` (Fintoc sends the invoice for the customer to pay). Subscriptions created through the API always use `send_invoice`. example: send_invoice created_at: type: string format: date-time description: ISO 8601 timestamp of when the subscription was created. example: '2026-06-01T15:00:00Z' customer: type: string description: ID of the customer the subscription bills. example: cus_2c4mDe9NJyGmMzvCqLkXqAtjnRu items: type: array items: $ref: '#/components/schemas/subscription_item' description: Items the subscription bills for on every billing cycle. metadata: type: object description: Set of key-value pairs attached to the subscription. example: order_id: '12345' mode: type: string enum: - live - test description: >- Mode of the object. One of `live` or `test`. `test` subscriptions use fake data for integration testing and do not collect real money. example: live payment_method: type: - string - 'null' description: >- ID of the payment method charged when `collection_method` is `charge_automatically`. Always `null` for subscriptions created through the API. example: null status: type: string enum: - active - canceled - incomplete - trialing description: >- Current status of the subscription. One of `active`, `incomplete` (the first invoice payment has not yet succeeded), `trialing` (the trial period has not ended), or `canceled` (the subscription stopped generating invoices). example: active trial_end: type: - string - 'null' format: date-time description: >- ISO 8601 timestamp at which the trial period ends, or `null` if the subscription has no trial. example: null required: - id - object - billing_cycle_anchor - collection_method - created_at - customer - items - metadata - mode - payment_method - status - trial_end error_object: type: object properties: error: type: object description: Details of the error that caused the request to fail. properties: code: type: string description: >- Machine-readable code identifying the specific error, for example `invalid_api_key`. Not returned by every error. example: invalid_api_key doc_url: type: string description: >- URL of a documentation page with more details about the error. Not returned by every error. example: https://docs.fintoc.com/reference/errors message: type: string description: Human-readable message describing the error. example: 'Invalid API Key: invalid-*oken' param: type: - string - 'null' description: >- Name of the request parameter that caused the error. `null` when the error cannot be tied to a single parameter, and not returned by every error. example: amount type: type: string description: >- Category of the error, for example `invalid_request_error`, `authentication_error`, or `api_error`. example: invalid_request_error required: - type - message subscription_item: type: object properties: id: type: string description: Unique identifier of the subscription item. example: si_2c4mDfkPLLrLTCJ3wPCEHGYpkVf object: const: subscription_item description: Type of the object. Always `subscription_item`. price: type: object description: Price the item bills for on every billing cycle. properties: currency: type: string enum: - CLF - CLP - MXN description: >- Three-letter ISO 4217 currency code, returned in uppercase. One of `CLP`, `MXN` or `CLF`. example: CLP product: type: object description: Product the price belongs to. properties: id: type: string description: Unique identifier of the product. example: prod_2c4mDgwQqkNwMHnXSc4DBjkbcWz object: const: product description: Type of the object. Always `product`. created_at: type: string format: date-time description: ISO 8601 timestamp of when the product was created. example: '2026-06-01T15:00:00Z' description: type: - string - 'null' description: Free-text description of the product. example: Access to every premium feature. image_url: type: - string - 'null' description: HTTPS URL of an image of the product. example: https://example.com/image.png metadata: type: object description: Set of key-value pairs attached to the product. example: category: saas mode: type: string enum: - live - test description: >- Mode of the object. One of `live` or `test`. `test` products use fake data for integration testing. example: live name: type: string description: Name of the product. example: Premium plan required: - id - object - created_at - description - image_url - metadata - mode - name recurring: type: object description: Billing cadence of the price. properties: interval: type: string enum: - month - year description: >- Frequency at which the price bills. One of `month` or `year`. example: month interval_count: type: integer description: >- Number of intervals between each billing cycle. For example, `interval: "month"` with `interval_count: 3` bills every 3 months. example: 1 required: - interval - interval_count unit_amount: type: integer description: >- Amount the price bills per unit, in the smallest unit of the currency. CLP has no decimals, so `10000` is $10,000 CLP; MXN uses centavos, so `10000` is $100.00 MXN. example: 10000 required: - currency - product - recurring - unit_amount quantity: type: integer description: Number of units of the price the item bills for. example: 1 required: - id - object - price - quantity securitySchemes: api_key: type: apiKey name: Authorization in: header ````