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",
  "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"
}

Suscripciones

Update a subscription

Updates a subscription. Provide at least one of trial_end, payment_method, or collection_method.

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.

Canceled subscriptions cannot be updated.

PATCH

subscriptions

{id}

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",
  "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"
}

Autorizaciones

Authorization

string

header

requerido

Parámetros de ruta

string

requerido

The id of the subscription to update.

Cuerpo

application/json

Option 1
Option 2
Option 3

trial_end

string<date-time>

requerido

ISO 8601 datetime, in UTC, when the trial ends and the first paid billing period begins. Must be at least one day in the future. Fintoc sets the subscription's billing_cycle_anchor to this time.

Ejemplo:

"2026-07-01T15:00:00Z"

payment_method

string

Payment method ID to charge every next payment against, including any invoice that is already open. Must belong to the subscription's customer, be one of pac or card, and be active.

Ejemplo:

"pm_2c4mDhAbCdEfGhIjKlMnOpQrStu"

collection_method

enum<string>

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.

Opciones disponibles:

charge_automatically,

send_invoice

Ejemplo:

"charge_automatically"

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.

string

requerido

Unique identifier of the subscription.

Ejemplo:

"sub_2c4mDcMaVxDx7nT3o5GbPMQbS2v"

object

any

requerido

Type of the object. Always subscription.

billing_cycle_anchor

string<date-time>

requerido

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.

Ejemplo:

"2026-06-01T15:00:00Z"

collection_method

enum<string>

requerido

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).

Opciones disponibles:

charge_automatically,

send_invoice

Ejemplo:

"charge_automatically"

created_at

string<date-time>

requerido

ISO 8601 timestamp of when the subscription was created.

Ejemplo:

"2026-06-01T15:00:00Z"

customer

string

requerido

ID of the customer the subscription bills.

Ejemplo:

"cus_2c4mDe9NJyGmMzvCqLkXqAtjnRu"

items

object[]

requerido

Items the subscription bills for on every billing cycle.

Show child attributes

metadata

object

requerido

Set of key-value pairs attached to the subscription.

Ejemplo:

{ "order_id": "12345" }

mode

enum<string>

requerido

Mode of the object. One of live or test. test subscriptions use fake data for integration testing and do not collect real money.

Opciones disponibles:

live,

test

Ejemplo:

"live"

payment_method

string | null

requerido

ID of the payment method associated with the subscription, or null if it has none. Fintoc charges it on every billing cycle when collection_method is charge_automatically.

Ejemplo:

"pm_2c4mDhAbCdEfGhIjKlMnOpQrStu"

status

enum<string>

requerido

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).

Opciones disponibles:

active,

canceled,

incomplete,

trialing

Ejemplo:

"active"

trial_end

string<date-time> | null

requerido

ISO 8601 timestamp at which the trial period ends, or null if the subscription has no trial.

Ejemplo:

null

⌘I