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": 10000,
        "product_data": {
          "name": "Premium plan"
        }
      },
      "quantity": 1
    }
  ],
  "metadata": {
    "internal_id": "12345"
  }
}
'

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

Subscriptions

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.

POST

subscriptions

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": 10000,
        "product_data": {
          "name": "Premium plan"
        }
      },
      "quantity": 1
    }
  ],
  "metadata": {
    "internal_id": "12345"
  }
}
'

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

Authorizations

Authorization

string

header

required

Body

application/json

customer

string

required

ID of the customer to bill.

Example:

"cus_2c4mDe9NJyGmMzvCqLkXqAtjnRu"

items

object[]

required

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.

Maximum array length: 10

Show child attributes

collection_method

enum<string>

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.

Available options:

charge_automatically,

send_invoice

Example:

"send_invoice"

payment_method

string

Payment method to associate with the subscription. Required when collection_method is charge_automatically; optional with send_invoice. Must belong to the specified customer.

Example:

"pm_2c4mDhAbCdEfGhIjKlMnOpQrStu"

metadata

object

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

string<date-time>

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"

billing_cycle_anchor

string<date-time>

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.

Example:

"2030-07-01T00:00:00Z"

business_profile

object

Business on whose behalf you collect the payment, for payment aggregators. Applied to every automatic charge of the subscription. Required if your organization identifies a business profile per payment.

Show child attributes

Response

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.

string

required

Unique identifier of the subscription.

Example:

"sub_2c4mDcMaVxDx7nT3o5GbPMQbS2v"

object

any

required

Type of the object. Always subscription.

billing_cycle_anchor

string<date-time>

required

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.

Example:

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

collection_method

enum<string>

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 leaves each invoice open for you to collect).

Available options:

charge_automatically,

send_invoice

Example:

"charge_automatically"

created_at

string<date-time>

required

ISO 8601 timestamp of when the subscription was created.

Example:

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

customer

string

required

ID of the customer the subscription bills.

Example:

"cus_2c4mDe9NJyGmMzvCqLkXqAtjnRu"

items

object[]

required

Items the subscription bills for on every billing cycle.

Show child attributes

metadata

object

required

Set of key-value pairs attached to the subscription.

Example:

{ "order_id": "12345" }

mode

enum<string>

required

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

Available options:

live,

test

Example:

"live"

payment_method

string | null

required

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.

Example:

"pm_2c4mDhAbCdEfGhIjKlMnOpQrStu"

status

enum<string>

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

Available options:

active,

canceled,

incomplete,

trialing

Example:

"active"

trial_end

string<date-time> | null

required

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

Example:

null