curl --request POST \
--url https://api.fintoc.com/v2/subscriptions \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--data '
{
"customer": "cus_2c4mDe9NJyGmMzvCqLkXqAtjnRu",
"payment_method": "pm_2c4mDhAbCdEfGhIjKlMnOpQrStu",
"items": [
{
"price_data": {
"currency": "CLP",
"recurring": {
"interval": "month",
"interval_count": 1
},
"unit_amount": 450000,
"product_data": {
"name": "Arriendo unidad A-401"
}
},
"quantity": 1
}
],
"split": [
{
"entity_id": "ent_6Qd3kZvNxL8r",
"type": "percentage",
"amount": 8500,
"charge_processing_fee": true
},
{
"entity_id": "ent_1Ys8cRpMvD2w",
"type": "percentage",
"amount": 1000
},
{
"entity_id": "ent_4Pq7sLwXy2Nc",
"type": "percentage",
"amount": 500
}
]
}
'{
"id": "sub_2c4mDcMaVxDx7nT3o5GbPMQbS2v",
"object": "subscription",
"billing_cycle_anchor": "2026-06-01T15:00:00Z",
"cancel_at": null,
"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
}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. The collection_method decides how Fintoc collects every invoice the subscription generates. With charge_automatically, the default, Fintoc charges payment_method on every billing cycle, so the payment method is required. With send_invoice, Fintoc leaves each invoice open for you to collect, and payment_method is optional. A payment_method must be active and have a type of pac or card; subscriptions do not support bank_transfer. Without trial_end or billing_cycle_anchor, Fintoc anchors the billing cycle at the creation time and finalizes an initial invoice immediately. With charge_automatically, the subscription starts incomplete and becomes active once that first payment succeeds. With send_invoice, the subscription starts active and the initial invoice stays open. 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. With billing_cycle_anchor, the subscription starts active. Fintoc issues no invoice until the anchor, then generates the first invoice for the full billing period that starts there. The anchor must be in the future and cannot be combined with trial_end. With cancel_at, Fintoc invoices every billing period that starts before cancel_at, with no proration, and cancels the subscription at that timestamp. To bill a fixed number of periods, set cancel_at to the start of the first period you do not want to bill.
curl --request POST \
--url https://api.fintoc.com/v2/subscriptions \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--data '
{
"customer": "cus_2c4mDe9NJyGmMzvCqLkXqAtjnRu",
"payment_method": "pm_2c4mDhAbCdEfGhIjKlMnOpQrStu",
"items": [
{
"price_data": {
"currency": "CLP",
"recurring": {
"interval": "month",
"interval_count": 1
},
"unit_amount": 450000,
"product_data": {
"name": "Arriendo unidad A-401"
}
},
"quantity": 1
}
],
"split": [
{
"entity_id": "ent_6Qd3kZvNxL8r",
"type": "percentage",
"amount": 8500,
"charge_processing_fee": true
},
{
"entity_id": "ent_1Ys8cRpMvD2w",
"type": "percentage",
"amount": 1000
},
{
"entity_id": "ent_4Pq7sLwXy2Nc",
"type": "percentage",
"amount": 500
}
]
}
'{
"id": "sub_2c4mDcMaVxDx7nT3o5GbPMQbS2v",
"object": "subscription",
"billing_cycle_anchor": "2026-06-01T15:00:00Z",
"cancel_at": null,
"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
}Cuerpo
The way Fintoc collects every invoice the subscription generates. One of charge_automatically (Fintoc charges payment_method on every billing cycle) or send_invoice (Fintoc leaves each invoice open for you to collect). Defaults to charge_automatically.
charge_automatically, send_invoice "send_invoice"
ISO 8601 timestamp in UTC of the first invoice and the start of every following billing period. Must be in the future. Fintoc issues no invoice before the anchor and does not charge for the time until then. Cannot be combined with trial_end. Omit to anchor the cycle at the creation time.
"2030-07-01T00:00:00Z"
ISO 8601 timestamp in UTC of the scheduled cancellation. Must be in the future and after trial_end or billing_cycle_anchor. Fintoc cancels the subscription at this timestamp and issues no invoice for a billing period that starts at or after it. Omit to keep the subscription active until you cancel it.
"2031-07-01T00:00:00Z"
Rules for dividing every charge of the subscription between entities. Each invoice inherits these rules when Fintoc creates the invoice. Available for organizations with splits enabled. Provide 1 to 10 entries. All entries must use the same type, and each entity_id can appear only once. When Fintoc deducts processing fees from your payouts, at least one entry must pay the processing fee. When Fintoc invoices you for processing fees, no entry can pay the fee. For flat splits, amounts must add up to the total of the subscription items, and flat is not allowed when an item is priced in CLF. For percentage splits, amounts must add up to 10000 basis points (100%).
Show child attributes
Show child attributes
Respuesta
Subscription created. Without trial_end or billing_cycle_anchor, Fintoc generates and finalizes the initial invoice immediately. Otherwise, Fintoc issues the first invoice at the trial end or at the anchor.
ISO 8601 timestamp that anchors the billing cycle. Fintoc measures every billing period from this anchor. Unless you set the anchor when creating the subscription, Fintoc uses the creation time, or trial_end when a trial applies. Fintoc issues no invoice before the anchor.
"2026-06-01T15:00:00Z"
ISO 8601 timestamp in UTC of the scheduled cancellation, or null if the subscription renews until you cancel it. Fintoc cancels the subscription at this timestamp and issues no invoice for a billing period that starts at or after it.
"2027-06-01T15:00:00Z"
Method Fintoc uses to collect the invoices the subscription generates. One of charge_automatically (Fintoc charges the saved payment method) or send_invoice (Fintoc leaves each invoice open for you to collect).
charge_automatically, send_invoice "charge_automatically"
Reason the subscription reports inconsistent. split_amount_mismatch means the flat split amounts do not add up to the total of the items, or a percentage split leaves an entity with no amount. Fintoc skips this check when an item is priced in a currency other than the subscription's. The invoice amount depends on the exchange rate of each billing cycle. null for every other status.
split_amount_mismatch, null null
Current status of the subscription. One of active, incomplete, trialing, paused, inconsistent, or canceled. incomplete means the first invoice payment has not yet succeeded. trialing means the trial period has not ended. paused means Fintoc stops generating invoices while the organization cannot access subscriptions, but still charges invoices that are already open. inconsistent means the split can no longer be applied to the total of the items. Update the split or the items before the next invoice. Fintoc cannot finalize the invoice until the totals match, and reason explains the mismatch. canceled means the subscription stopped generating invoices.
active, canceled, incomplete, paused, trialing, inconsistent "active"
¿Esta página le ayudó?