curl --request PATCH \
--url https://api.fintoc.com/v2/subscriptions/{id} \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--data '
{
"trial_end": "2026-07-01T15:00:00Z"
}
'{
"id": "sub_2c4mDcMaVxDx7nT3o5GbPMQbS2v",
"object": "subscription",
"billing_cycle_anchor": "2026-07-01T15:00:00Z",
"cancel_at": null,
"collection_method": "send_invoice",
"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": "Access to every premium feature.",
"image_url": "https://example.com/image.png",
"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": null,
"status": "trialing",
"trial_end": "2026-07-01T15:00:00Z"
}Update a subscription
Updates a subscription. Provide at least one of trial_end, payment_method, collection_method, cancel_at, or split.
Provide trial_end to set when the trial ends and the first paid billing period begins. trial_end must be at least one day in the future. Fintoc aligns the subscription’s billing_cycle_anchor to trial_end and sets its status to trialing until then.
Provide payment_method to swap the payment method the subscription charges against. The payment method must belong to the subscription’s customer, be a pac or card, and be active. After the swap, Fintoc charges every next payment against the new payment method, including any invoice that is already open. Swapping does not charge the subscription immediately.
Provide collection_method to change the way Fintoc collects the invoices the subscription generates. Switching to charge_automatically requires a payment method Fintoc can charge, either in the same request or already associated. The change applies from the next billing cycle. Invoices that are already open keep their existing collection method.
Provide cancel_at to schedule when Fintoc cancels the subscription, or null to remove a scheduled cancellation. Fintoc invoices every billing period that starts before cancel_at, with no proration, and cancels the subscription at that datetime.
Provide split to replace the rules that divide every charge of the subscription between entities. The new rules apply to the invoices the subscription issues from then on. Invoices already created keep the rules they inherited, even if they are still draft.
Canceled subscriptions cannot be updated.
curl --request PATCH \
--url https://api.fintoc.com/v2/subscriptions/{id} \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--data '
{
"trial_end": "2026-07-01T15:00:00Z"
}
'{
"id": "sub_2c4mDcMaVxDx7nT3o5GbPMQbS2v",
"object": "subscription",
"billing_cycle_anchor": "2026-07-01T15:00:00Z",
"cancel_at": null,
"collection_method": "send_invoice",
"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": "Access to every premium feature.",
"image_url": "https://example.com/image.png",
"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": null,
"status": "trialing",
"trial_end": "2026-07-01T15:00:00Z"
}Cuerpo
- Option 1
- Option 2
- Option 3
- Option 4
- Option 5
The way Fintoc collects every invoice the subscription generates. One of charge_automatically or send_invoice. With charge_automatically, Fintoc charges payment_method on every billing cycle. With send_invoice, Fintoc leaves each invoice open for you to collect, through hosted_invoice_url or outside Fintoc. Switching to charge_automatically requires a payment method.
charge_automatically, send_invoice "charge_automatically"
ISO 8601 datetime, in UTC, of the scheduled cancellation. Must be in the future and after the subscription's billing_cycle_anchor. Fintoc cancels the subscription at this datetime and issues no invoice for a billing period that starts at or after it. Set to null to remove a scheduled cancellation.
"2027-06-01T15:00:00Z"
Rules for dividing every charge of the subscription between entities. Replaces the current rules as a whole, so send every entry you want to keep. Applies to the invoices the subscription issues from then on. 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
The updated subscription. When you set trial_end, status is trialing until the trial ends. When you set payment_method, the subscription points to the new payment method. When you set collection_method, the subscription uses the new collection method from the next billing cycle. When you set cancel_at, the subscription stays active until the scheduled cancellation time. When you set split, the response includes the new split rules.
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ó?