v1

latestOpenAPI 3.1.02026-07-228956435.8 KB

Subscriptions

Update a subscription

Updates a subscription. Provide at least one of trial_end or payment_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 be active, belong to the subscription's customer, and be a pac or card. 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.

Canceled subscriptions cannot be updated.

patch/subscriptions/{id}

Path parameters

idstring required

The id of the subscription to update.

Request body

Example request

{
  "trial_end": "2026-07-01T15:00:00Z",
  "payment_method": "pm_2c4mDhAbCdEfGhIjKlMnOpQrStu"
}

Response

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.

idstring required

Unique identifier of the subscription.

object'subscription' required

Type of the object. Always subscription.

billing_cycle_anchorstring date-time required

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.

collection_method'charge_automatically' | 'send_invoice' required

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.

created_atstring date-time required

ISO 8601 timestamp of when the subscription was created.

customerstring required

ID of the customer the subscription bills.

metadataobject required

Set of key-value pairs attached to the subscription.

mode'live' | 'test' required

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

payment_methodstring nullable required

ID of the payment method charged when collection_method is charge_automatically. Always null for subscriptions created through the API.

status'active' | 'canceled' | 'incomplete' | 'trialing' required

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

trial_endstring date-time nullable required

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

Example response

{
  "id": "sub_2c4mDcMaVxDx7nT3o5GbPMQbS2v",
  "billing_cycle_anchor": "2026-06-01T15:00:00Z",
  "collection_method": "send_invoice",
  "created_at": "2026-06-01T15:00:00Z",
  "customer": "cus_2c4mDe9NJyGmMzvCqLkXqAtjnRu",
  "items": [
    {
      "id": "si_2c4mDfkPLLrLTCJ3wPCEHGYpkVf",
      "price": {
        "currency": "CLP",
        "product": {
          "id": "prod_2c4mDgwQqkNwMHnXSc4DBjkbcWz",
          "created_at": "2026-06-01T15:00:00Z",
          "description": "Access to every premium feature.",
          "image_url": "https://example.com/image.png",
          "metadata": {
            "category": "saas"
          },
          "mode": "live",
          "name": "Premium plan"
        },
        "recurring": {
          "interval": "month",
          "interval_count": 1
        },
        "unit_amount": 10000
      },
      "quantity": 1
    }
  ],
  "metadata": {
    "order_id": "12345"
  },
  "mode": "live",
  "status": "active"
}