> ## Documentation Index > Fetch the complete documentation index at: https://docs.fintoc.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a subscription item > Adds an item to an existing subscription. Fintoc creates a new price from `price_data`, referencing an existing product (`product`) or defining one inline (`product_data`). The new price must use a currency compatible with the subscription's existing items (a `CLF` price bills within a `CLP` subscription) and the same recurring `interval`. Fintoc bills the item starting from the subscription's next invoice and does not prorate the current billing period. **`v2`** ยท Base URL `https://api.fintoc.com/v2` ## OpenAPI ````yaml reference/fintoc-api-v2.json POST /subscriptions/{subscription_id}/items openapi: 3.1.0 info: title: fintoc-api-v2 version: v2026-02-01 servers: - url: https://api.fintoc.com/v2 security: [] paths: /subscriptions/{subscription_id}/items: post: tags: - Subscription items summary: Create a subscription item description: >- Adds an item to an existing subscription. Fintoc creates a new price from `price_data`, referencing an existing product (`product`) or defining one inline (`product_data`). The new price must use a currency compatible with the subscription's existing items (a `CLF` price bills within a `CLP` subscription) and the same recurring `interval`. Fintoc bills the item starting from the subscription's next invoice and does not prorate the current billing period. operationId: subscription-items-create parameters: - name: subscription_id in: path description: The `id` of the subscription to add the item to. required: true schema: type: string requestBody: content: application/json: schema: type: object properties: price_data: type: object description: >- Definition of the price the item bills for. Fintoc creates a new price for the item. properties: currency: type: string enum: - CLF - CLP - MXN description: >- Three-letter ISO 4217 currency code, in uppercase. One of `CLP`, `MXN`, or `CLF`. A `CLF` (UF) item is billable within a `CLP` subscription. example: CLP recurring: type: object description: >- Billing cadence of the price. Must match the cadence of the subscription's existing items. properties: interval: type: string enum: - month - year description: >- Frequency at which the price bills. One of `month` or `year`. example: month interval_count: type: integer description: >- Number of intervals between each billing cycle. For example, `interval: "month"` with `interval_count: 3` bills every 3 months. example: 1 required: - interval - interval_count unit_amount: type: integer description: >- 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. example: 5000 product: type: string description: >- ID of an existing product the price belongs to. Mutually exclusive with `product_data`; exactly one of the two is required. example: prod_2c4mDgwQqkNwMHnXSc4DBjkbcWz product_data: type: object description: >- Inline definition of a new product for the price. Mutually exclusive with `product`; exactly one of the two is required. properties: name: type: string description: Name of the product. example: Extra seat description: type: string description: Free-text description of the product. example: An additional seat for the workspace. image_url: type: string description: HTTPS URL of an image of the product. example: https://example.com/image.png metadata: type: object description: >- Set of key-value pairs to attach to the product. Nested objects and arrays are not allowed as values. example: category: saas required: - name required: - currency - recurring - unit_amount quantity: type: integer description: >- Number of units of the price the item bills for. Must be greater than zero. example: 2 required: - price_data - quantity examples: create_subscription_item: summary: Add an item to a subscription value: price_data: currency: CLP recurring: interval: month interval_count: 1 unit_amount: 5000 product_data: name: Extra seat quantity: 2 responses: '201': description: >- Subscription item created. Fintoc bills it starting from the subscription's next invoice. content: application/json: examples: subscription_item_created: value: 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: Extra seat recurring: interval: month interval_count: 1 unit_amount: 5000 quantity: 2 schema: $ref: '#/components/schemas/subscription_item' '400': description: >- Invalid request: a required parameter is missing or invalid, or the request does not include exactly one of `product` and `product_data`. content: application/json: examples: missing_price_data: value: error: type: invalid_request_error code: missing_parameter param: price_data message: 'Missing required param: price_data' doc_url: https://docs.fintoc.com/reference/errors schema: $ref: '#/components/schemas/error_object' '401': description: Invalid or missing API key. content: application/json: examples: invalid_api_key: value: error: type: authentication_error code: invalid_api_key message: 'Invalid API Key: invalid-*oken' schema: $ref: '#/components/schemas/error_object' '404': description: >- The subscription does not exist, belongs to another organization, or belongs to a different mode than the API key. content: application/json: examples: subscription_not_found: value: error: type: invalid_request_error code: missing_resource param: subscription_id message: >- No such invoicing/subscription: sub_2c4mDcMaVxDx7nT3o5GbPMQbS2v doc_url: https://docs.fintoc.com/reference/errors schema: $ref: '#/components/schemas/error_object' '409': description: >- The new price uses a currency incompatible with, or a recurring interval different from, the subscription's existing items. content: application/json: examples: currency_mismatch: value: error: type: invalid_request_error code: currency_mismatch message: >- Each subscription item's price currency must be compatible with the subscription's billing currency schema: $ref: '#/components/schemas/error_object' security: - api_key: [] components: schemas: subscription_item: type: object properties: id: type: string description: Unique identifier of the subscription item. example: si_2c4mDfkPLLrLTCJ3wPCEHGYpkVf object: const: subscription_item description: Type of the object. Always `subscription_item`. price: type: object description: Price the item bills for on every billing cycle. properties: currency: type: string enum: - CLF - CLP - MXN description: >- Three-letter ISO 4217 currency code, returned in uppercase. One of `CLP`, `MXN` or `CLF`. example: CLP product: type: object description: Product the price belongs to. properties: id: type: string description: Unique identifier of the product. example: prod_2c4mDgwQqkNwMHnXSc4DBjkbcWz object: const: product description: Type of the object. Always `product`. created_at: type: string format: date-time description: ISO 8601 timestamp of when the product was created. example: '2026-06-01T15:00:00Z' description: type: - string - 'null' description: Free-text description of the product. example: Access to every premium feature. image_url: type: - string - 'null' description: HTTPS URL of an image of the product. example: https://example.com/image.png metadata: type: object description: Set of key-value pairs attached to the product. example: category: saas mode: type: string enum: - live - test description: >- Mode of the object. One of `live` or `test`. `test` products use fake data for integration testing. example: live name: type: string description: Name of the product. example: Premium plan required: - id - object - created_at - description - image_url - metadata - mode - name recurring: type: object description: Billing cadence of the price. properties: interval: type: string enum: - month - year description: >- Frequency at which the price bills. One of `month` or `year`. example: month interval_count: type: integer description: >- Number of intervals between each billing cycle. For example, `interval: "month"` with `interval_count: 3` bills every 3 months. example: 1 required: - interval - interval_count unit_amount: type: integer description: >- 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. example: 10000 required: - currency - product - recurring - unit_amount quantity: type: integer description: Number of units of the price the item bills for. example: 1 required: - id - object - price - quantity error_object: type: object properties: error: type: object description: Details of the error that caused the request to fail. properties: code: type: string description: >- Machine-readable code identifying the specific error, for example `invalid_api_key`. Not returned by every error. example: invalid_api_key doc_url: type: string description: >- URL of a documentation page with more details about the error. Not returned by every error. example: https://docs.fintoc.com/reference/errors message: type: string description: Human-readable message describing the error. example: 'Invalid API Key: invalid-*oken' param: type: - string - 'null' description: >- Name of the request parameter that caused the error. `null` when the error cannot be tied to a single parameter, and not returned by every error. example: amount type: type: string description: >- Category of the error, for example `invalid_request_error`, `authentication_error`, or `api_error`. example: invalid_request_error required: - type - message securitySchemes: api_key: type: apiKey name: Authorization in: header ````