---
title: "Create a subscription"
method: POST
path: "/subscriptions"
tags: ["Subscriptions"]
---

# Create a subscription

`POST /subscriptions`

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. Fintoc charges each subscription automatically using `payment_method`, so the `collection_method` is always `charge_automatically`. The `payment_method` must be active and have a type of `pac` or `card`; subscriptions do not support `bank_transfer`. Without `trial_end`, Fintoc sets the `billing_cycle_anchor` to the creation time and finalizes an initial invoice immediately. The subscription starts `incomplete` and becomes `active` once that first payment succeeds. 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.

## Request body

- object
  - `customer` string, required — ID of the customer to bill.
  - `payment_method` string, required — Payment method to charge automatically on every billing cycle. Must belong to the specified `customer`.
  - `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.
    - `price_data` object, required — Definition of the price the item bills for. Fintoc creates a new price for the item.
      - `currency` 'CLF' | 'CLP' | 'MXN', required — Three-letter ISO 4217 currency code, in uppercase. One of `CLP`, `MXN`, or `CLF`. A `CLF` (UF) item bills within a `CLP` subscription: it is converted to `CLP` using the exchange rate at the billing period start.
      - `recurring` object, required — Billing cadence of the price.
        - `interval` 'month' | 'year', required — Frequency at which the price bills. One of `month` or `year`.
        - `interval_count` integer, required — Number of intervals between each billing cycle. For example, `interval: "month"` with `interval_count: 3` bills every 3 months.
      - `unit_amount` integer, required — Amount the price bills per unit, in the smallest unit of the currency. CLP has no decimals, so `10000` is $10,000 CLP; MXN uses centavos, so `10000` is $100.00 MXN.
      - `product` string — ID of an existing product the price belongs to. Mutually exclusive with `product_data`; exactly one of the two is required.
      - `product_data` object — Inline definition of a new product for the price. Mutually exclusive with `product`; exactly one of the two is required.
        - `name` string, required — Name of the product.
        - `description` string — Free-text description of the product.
        - `image_url` string — HTTPS URL of an image of the product.
        - `metadata` object — Set of key-value pairs to attach to the product. Nested objects and arrays are not allowed as values.
    - `quantity` integer, required — Number of units of the price the item bills for. Must be greater than zero.
  - `metadata` object — Set of key-value pairs to attach to the subscription. Nested objects and arrays are not allowed as values.
  - `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.

## Response `201`

Subscription created. Fintoc generates and finalizes the initial invoice for the first billing period immediately.

- Subscription
  - `id` string, required — Unique identifier of the subscription.
  - `object` 'subscription', required — Type of the object. Always `subscription`.
  - `billing_cycle_anchor` string, 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_at` string, date-time, required — ISO 8601 timestamp of when the subscription was created.
  - `customer` string, required — ID of the customer the subscription bills.
  - `items` SubscriptionItem[], required — Items the subscription bills for on every billing cycle.
    - `id` string, required — Unique identifier of the subscription item.
    - `object` 'subscription_item', required — Type of the object. Always `subscription_item`.
    - `price` object, required — Price the item bills for on every billing cycle.
      - `currency` 'CLF' | 'CLP' | 'MXN', required — Three-letter ISO 4217 currency code, returned in uppercase. One of `CLP`, `MXN` or `CLF`.
      - `product` object, required — Product the price belongs to.
        - `id` string, required — Unique identifier of the product.
        - `object` 'product', required — Type of the object. Always `product`.
        - `created_at` string, date-time, required — ISO 8601 timestamp of when the product was created.
        - `description` string, nullable, required — Free-text description of the product.
        - `image_url` string, nullable, required — HTTPS URL of an image of the product.
        - `metadata` object, required — Set of key-value pairs attached to the product.
        - `mode` 'live' | 'test', required — Mode of the object. One of `live` or `test`. `test` products use fake data for integration testing.
        - `name` string, required — Name of the product.
      - `recurring` object, required — Billing cadence of the price.
        - `interval` 'month' | 'year', required — Frequency at which the price bills. One of `month` or `year`.
        - `interval_count` integer, required — Number of intervals between each billing cycle. For example, `interval: "month"` with `interval_count: 3` bills every 3 months.
      - `unit_amount` integer, required — Amount the price bills per unit, in the smallest unit of the currency. CLP has no decimals, so `10000` is $10,000 CLP; MXN uses centavos, so `10000` is $100.00 MXN.
    - `quantity` integer, required — Number of units of the price the item bills for.
  - `metadata` object, 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_method` string, 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_end` string, date-time, nullable, required — ISO 8601 timestamp at which the trial period ends, or `null` if the subscription has no trial.

## Other responses

- `400` — Invalid request: a required parameter is missing, the items are invalid or inconsistent, or there are more than 10 items.
- `401` — Invalid or missing API key.
- `404` — The referenced payment method does not exist or does not belong to the customer.
- `409` — Conflict: the items use currencies that cannot be billed together.
- `422` — The `payment_method` cannot be used for a subscription because the payment method is inactive or has an unsupported type. Subscriptions only accept `pac` or `card`, not `bank_transfer`.

---

[API](https://skmtc.net/fintoc/apis/fintoc-api.md) · [All operations](https://skmtc.net/fintoc/apis/fintoc-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/fintoc/fintoc-api/versions/9dafa63688a3/schema)