> ## Documentation Index > Fetch the complete documentation index at: https://docs.y.uno/llms.txt > Use this file to discover all available pages before exploring further. # Create Subscription > Creates a recurring billing subscription. **Prerequisite:** Enroll a card first to obtain `vaulted_token`. **frequency.type:** `DAY` | `WEEK` | `MONTH` ## OpenAPI ````yaml openapi/yuno_sandbox_tested.json POST /v1/subscriptions openapi: 3.1.0 info: title: Yuno Payments API version: 1.0.0 description: > The Yuno Payments API is built around REST principles, using standard HTTP methods and JSON payloads. ## Authentication All requests require two headers: ``` public-api-key: YOUR_PUBLIC_KEY private-secret-key: YOUR_PRIVATE_KEY ``` ## Idempotency Payment mutations (create, capture, cancel, refund, payout) require an `X-Idempotency-Key` header (UUID). The API stores the key and returns the same response for duplicate requests within 24 hours. ## Environments | Environment | Base URL | |-------------|----------| | Sandbox | `https://api-sandbox.y.uno/v1` | | Production | `https://api.y.uno/v1` | contact: name: Yuno Support url: https://docs.y.uno license: name: Proprietary servers: - url: https://api-sandbox.y.uno description: Sandbox - url: https://api.y.uno description: Production - url: https://api.eu.y.uno description: Production (EMEA) security: - PublicApiKey: [] PrivateSecretKey: [] tags: - name: Customers description: Create and manage customer records. - name: Checkout Sessions description: Initialize the Yuno SDK on the front-end. - name: Payment Methods description: Enroll and manage vaulted payment methods. - name: Payments description: Create and manage payment transactions. - name: Payment Links description: Hosted payment pages requiring no SDK. - name: Subscriptions description: Recurring billing management. - name: Payouts description: Disburse funds to individuals or entities. - name: Reports description: Generate and download transaction reports. - name: Currency Conversion description: Dynamic currency conversion (DCC). paths: /v1/subscriptions: post: tags: - Subscriptions summary: Create Subscription description: | Creates a recurring billing subscription. **Prerequisite:** Enroll a card first to obtain `vaulted_token`. **frequency.type:** `DAY` | `WEEK` | `MONTH` operationId: create-subscription parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateSubscriptionRequest' example: account_id: YOUR_ACCOUNT_ID name: Monthly Subscription Plan description: Billed monthly merchant_reference: sub-001 country: US amount: currency: USD value: 9900 frequency: type: MONTH value: 1 billing_cycles: total: 12 customer_payer: id: CUSTOMER_UUID payment_method: type: CARD vaulted_token: VAULTED_TOKEN_UUID availability: start_at: '2026-04-01T00:00:00Z' finish_at: '2027-03-31T23:59:59Z' subscription_agreement_id: sa_6af2dfcd-44c0-4f16-a331-8bed3ed9c9fa responses: '201': description: Subscription created content: application/json: schema: $ref: '#/components/schemas/Subscription' components: parameters: IdempotencyKey: name: X-Idempotency-Key in: header required: true schema: type: string format: uuid description: Unique UUID per request. Prevents duplicate processing on retries. schemas: CreateSubscriptionRequest: type: object required: - name - account_id - country - amount - frequency - payment_method properties: account_id: type: string format: uuid name: type: string minLength: 3 maxLength: 255 description: type: string merchant_reference: type: string country: $ref: '#/components/schemas/Country' amount: $ref: '#/components/schemas/Amount' frequency: type: object required: - type properties: type: type: string enum: - DAY - WEEK - MONTH value: type: integer default: 1 billing_cycles: type: object properties: total: type: integer minimum: 1 customer_payer: type: object properties: id: type: string format: uuid payment_method: type: object required: - type - vaulted_token properties: type: type: string enum: - CARD vaulted_token: type: string format: uuid availability: type: object properties: start_at: type: string format: date-time finish_at: type: string format: date-time additional_data: $ref: '#/components/schemas/AdditionalData' subscription_agreement_id: type: string maxLength: 255 description: >- Links this subscription to the initial payment created with the same agreement ID. Used for tracking, reconciliation, and chargeback handling. Must exactly match the `subscription_agreement_id` sent in `payment_method.detail.card.stored_credentials.subscription_agreement_id` on the originating payment. Subscription: type: object properties: id: type: string format: uuid name: type: string status: type: string enum: - ACTIVE - PAUSED - CANCELLED - EXPIRED amount: $ref: '#/components/schemas/Amount' frequency: type: object properties: type: type: string value: type: integer subscription_agreement_id: type: string description: >- Links this subscription to the initial payment created with the same agreement ID. Used for tracking, reconciliation, and chargeback handling. created_at: type: string format: date-time Country: type: string enum: - AR - BO - BR - CL - CO - CR - EC - SV - GT - HN - MX - NI - PA - PY - PE - US - UY description: ISO 3166-1 alpha-2 country code Amount: type: object required: - currency - value properties: currency: $ref: '#/components/schemas/Currency' value: type: number multipleOf: 0.0001 description: Amount in cents (e.g. 10000 = $100.00) AdditionalData: type: object properties: order: type: object properties: items: type: array items: type: object required: - id - name - quantity - unit_amount - category properties: id: type: string name: type: string quantity: type: integer unit_amount: type: number category: type: string enum: - electronics - clothing - food - services - art - baby - beauty_&_personal_care - books - coupons - entertainment - health - home - sports - toys - travel brand: type: string sku_code: type: string Currency: type: string minLength: 3 maxLength: 3 description: ISO 4217 currency code (e.g. USD, BRL, MXN) ````