> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fincle.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Start subscription

> Starts a credit card subscription from a plan configured on the account. The subscription is created only if the first charge is authorized.



## OpenAPI

````yaml /openapi.yaml post /subscriptions
openapi: 3.0.3
info:
  title: Fincle API
  version: 1.0.0
  description: >-
    Fincle payments API: charges by Pix, credit card and boleto, subscriptions,
    transactions, refunds, infractions, notifications and transfers.
servers:
  - url: https://api.fincle.com.br
    description: Production server
security: []
tags:
  - name: Authentication
    description: Issuance of the access token from the API key.
  - name: Charges
    description: Creation of charges by Pix, credit card and boleto.
  - name: Subscriptions
    description: Recurring billing on credit card.
  - name: Transactions
    description: Retrieval and refund of transactions.
  - name: Refunds
    description: Refund requests submitted by payers.
  - name: Infractions and MED
    description: Pix infraction reports and the amounts blocked as a result.
  - name: Webhooks
    description: Registration of notification endpoints and tracking of deliveries.
  - name: Balance and transfers
    description: Balance, statement, fees and transfer of the amounts received.
paths:
  /subscriptions:
    post:
      tags:
        - Subscriptions
      summary: Start subscription
      description: >-
        Starts a credit card subscription from a plan configured on the account.
        The subscription is created only if the first charge is authorized.
      operationId: createSubscription
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            type: string
          description: >-
            Idempotency key of the request. Repeating the request with the same
            key returns the transaction already recorded, without creating a new
            charge. A universally unique identifier (UUID) is recommended.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                postbackUrl:
                  type: string
                  format: uri
                description:
                  type: string
                productId:
                  type: string
                  minLength: 1
                offerSlug:
                  type: string
                  minLength: 1
                orderBumpIds:
                  type: array
                  items:
                    type: string
                couponTag:
                  type: string
                card:
                  type: object
                  properties:
                    cardToken:
                      type: string
                    holderName:
                      type: string
                      minLength: 1
                  required:
                    - cardToken
                  additionalProperties: false
                customer:
                  type: object
                  properties:
                    name:
                      type: string
                    email:
                      type: string
                      format: email
                    documentType:
                      type: string
                      enum:
                        - cpf
                        - cnpj
                    document:
                      type: string
                    phone:
                      type: string
                    instagram:
                      type: string
                    billingAddress:
                      type: object
                      properties:
                        street:
                          type: string
                        number:
                          type: string
                        neighborhood:
                          type: string
                        city:
                          type: string
                        state:
                          type: string
                        zipCode:
                          type: string
                      required:
                        - street
                        - number
                        - neighborhood
                        - city
                        - state
                        - zipCode
                      additionalProperties: false
                  required:
                    - documentType
                    - document
                  additionalProperties: false
                seller:
                  type: object
                  properties:
                    name:
                      type: string
                    documentType:
                      type: string
                      enum:
                        - cpf
                        - cnpj
                    document:
                      type: string
                    phone:
                      type: string
                    averageTicket:
                      type: number
                    address:
                      type: object
                      properties:
                        street:
                          type: string
                        number:
                          type: string
                        neighborhood:
                          type: string
                        city:
                          type: string
                        state:
                          type: string
                        zipCode:
                          type: string
                      required:
                        - street
                        - number
                        - neighborhood
                        - city
                        - state
                        - zipCode
                      additionalProperties: false
                  required:
                    - name
                    - documentType
                    - document
                  additionalProperties: false
              required:
                - productId
                - offerSlug
                - card
                - customer
              additionalProperties: false
            example:
              productId: cmdg7h2k1000c1yjn4d8w6r3s
              offerSlug: monthly-plan
              description: License agreement no. 4587
              postbackUrl: https://api.example.com/webhooks/fincle
              card:
                cardToken: tok_9f2c1a7b4d6e
              customer:
                name: Helena Martins Andrade
                email: helena.andrade@example.com
                documentType: cpf
                document: '31845792041'
                phone: '11932104567'
      responses:
        '200':
          description: Request processed successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      transaction:
                        type: object
                        properties:
                          id:
                            type: string
                          status:
                            type: string
                          card:
                            type: object
                            properties:
                              token:
                                type: string
                              brand:
                                type: string
                              last4:
                                type: string
                            required:
                              - token
                              - brand
                              - last4
                            additionalProperties: false
                          fees:
                            type: number
                          refuseReason:
                            type: string
                            nullable: true
                          acquirerCode:
                            type: string
                            nullable: true
                          acquirerMessage:
                            type: string
                            nullable: true
                        required:
                          - id
                          - status
                          - card
                          - fees
                        additionalProperties: false
                      subscription:
                        type: object
                        properties:
                          id:
                            type: string
                          status:
                            type: string
                          nextChargeAt:
                            type: string
                            nullable: true
                        required:
                          - id
                          - status
                          - nextChargeAt
                        additionalProperties: false
                    required:
                      - transaction
                    additionalProperties: false
                required:
                  - success
                  - message
                additionalProperties: false
              example:
                success: true
                message: Assinatura criada com sucesso
                data:
                  transaction:
                    id: cmddiqpxo09zf1yju2kqkhgga
                    status: paid
                    card:
                      token: tok_9f2c1a7b4d6e
                      brand: visa
                      last4: '1111'
                    fees: 995
                  subscription:
                    id: cmdh1m4q2000e1yjn7f2z9t5v
                    status: active
                    nextChargeAt: '2026-12-12T14:08:06.000Z'
        '400':
          description: Request rejected due to a validation failure or a business rule.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                required:
                  - success
                  - message
              example:
                success: false
                message: Documento inválido para o tipo selecionado
        '401':
          description: Access token missing, invalid or expired.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                required:
                  - success
                  - message
              example:
                success: false
                message: Não autorizado
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.