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

# Create Subscription

> Create a subscription and initiate its first payment. Provide an existing payment instrument, or omit paymentInstrumentId for payment methods that support automatic payment instrument creation. You can provide billingAddress for the payment instrument and first-invoice tax calculation.



## OpenAPI

````yaml POST /subscription
openapi: 3.1.0
info:
  title: Clink API
  description: >-
    Official API documentation for Clink's payment processing platform. This API
    enables merchants to create and manage payment sessions, handle
    subscriptions, and process transactions.
  version: 1.0.0
servers:
  - url: https://uat-api.clinkbill.com/api/
security:
  - ApiKeyAuth: []
paths:
  /subscription:
    post:
      summary: Create Subscription
      description: >-
        Create a subscription and initiate its first payment. Provide an
        existing payment instrument, or omit paymentInstrumentId for payment
        methods that support automatic payment instrument creation. You can
        provide billingAddress for the payment instrument and first-invoice tax
        calculation.
      operationId: createSubscription
      parameters:
        - $ref: '#/components/parameters/TimestampHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSubscriptionApiRequest'
            examples:
              cardSubscription:
                summary: Create a subscription with an existing payment instrument
                value:
                  customerId: cus_xxxxx
                  productId: prd_xxxxx
                  priceId: price_xxxxx
                  paymentInstrumentId: pi_xxxxx
                  paymentMethodType: CARD
                  paymentCurrency: USD
                  returnUrl: https://merchant.example.com/subscription/return
                  merchantReferenceId: sub_ref_123
                  metadata:
                    orderNo: SO-10001
                  billingAddress:
                    city: San Francisco
                    region: CA
                    country: US
                    line1: 123 Market Street
                    line2: Suite 100
                    postalCode: '94105'
                  scheduledPhases:
                    - sequence: 1
                      effectiveCycle: 2
                      priceSnapshotId: ps_xxxxx
                      quantity: 1
                      metadata:
                        plan: pro
                  platformType: WEB
                  deviceType: Android
              applePaySubscription:
                summary: Apple Pay subscription (self-decrypt)
                value:
                  customerId: cus_xxxxx
                  productId: prd_xxxxx
                  priceId: price_xxxxx
                  paymentMethodType: APPLEPAY
                  paymentCurrency: USD
                  additionalPaymentInstrument:
                    tokenValue: >-
                      {"paymentData":{"version":"EC_v1","data":"...","signature":"...","header":{}}
                      ,"paymentMethod":{"displayName":"Visa
                      1234","network":"Visa","type":"debit"},"transactionIdentifier":"..."}
                  platformType: WEB
                  deviceType: iOS
              googlePaySubscription:
                summary: Google Pay subscription (self-decrypt)
                value:
                  customerId: cus_xxxxx
                  productId: prd_xxxxx
                  priceId: price_xxxxx
                  paymentMethodType: GOOGLEPAY
                  paymentCurrency: USD
                  additionalPaymentInstrument:
                    tokenValue: >-
                      {"protocolVersion":"ECv2","signature":"...","intermediateSigningKey":{},"signedMessage":"..."}
                  platformType: WEB
                  deviceType: Android
              cashappSubscriptionAutoPaymentInstrument:
                summary: >-
                  Create a Cash App subscription and automatically create the
                  payment instrument
                value:
                  customerId: cus_xxxxx
                  productId: prd_xxxxx
                  priceId: price_xxxxx
                  paymentMethodType: CASHAPP
                  paymentCurrency: USD
                  returnUrl: https://merchant.example.com/subscription/return
                  merchantReferenceId: sub_ref_124
                  metadata:
                    orderNo: SO-10002
                  platformType: WEB
                  deviceType: Android
      responses:
        '200':
          description: Subscription created successfully
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/CreateSubscriptionApiResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/CreateSubscriptionApiResponse'
        '401':
          description: Unauthorized
          content:
            '*/*':
              schema:
                type: string
components:
  parameters:
    TimestampHeader:
      name: X-Timestamp
      in: header
      required: true
      description: >-
        Current timestamp in milliseconds since Unix epoch (required for request
        signing)
      schema:
        type: string
        example: '1783513683000'
  schemas:
    CreateSubscriptionApiRequest:
      required:
        - priceId
        - productId
        - paymentMethodType
        - paymentCurrency
      type: object
      allOf:
        - if:
            properties:
              paymentMethodType:
                enum:
                  - APPLEPAY
                  - GOOGLEPAY
            required:
              - paymentMethodType
          then:
            required:
              - additionalPaymentInstrument
            properties:
              additionalPaymentInstrument:
                required:
                  - tokenValue
          else:
            required:
              - returnUrl
      description: >-
        Parameters required to create a subscription by API. Provide at least
        one of customerId, customerEmail, or referenceCustomerId.
      properties:
        customerId:
          type: string
          description: Existing customer ID. At least one customer identifier is required.
        customerEmail:
          type: string
          description: >-
            Customer email. Used to resolve or create a customer when customerId
            is not provided.
        referenceCustomerId:
          type: string
          description: >-
            Merchant-side customer ID used to resolve, create, or bind a
            customer.
        merchantReferenceId:
          type: string
          description: Merchant-side reference ID for reconciliation.
        priceId:
          type: string
          description: Recurring price ID.
        productId:
          type: string
          description: Product ID for the subscription.
        paymentInstrumentId:
          type: string
          description: >-
            Existing payment instrument ID used for the initial payment and
            renewals. Required for CARD and other methods that do not support
            automatic creation. For APPLEPAY and GOOGLEPAY it is optional: when
            omitted, Clink creates the wallet payment instrument from
            additionalPaymentInstrument.tokenValue and binds it to the
            subscription for renewals.
        paymentMethodType:
          type: string
          description: >-
            Payment method type (uppercase). CARD requires a previously saved
            card and its paymentInstrumentId. APPLEPAY and GOOGLEPAY require
            additionalPaymentInstrument.tokenValue; the first invoice is paid
            with the wallet token and later renewals are charged as CARD with
            the bound instrument. The payment method must be enabled for
            subscriptions for your merchant account.
          enum:
            - APPLEPAY
            - CARD
            - CASHAPP
            - GCASH
            - GOOGLEPAY
            - PIX
            - UPI
        paymentCurrency:
          type: string
          description: Payment currency. The value is normalized to uppercase.
        promotionCode:
          type: string
          description: Promotion code to apply.
        returnUrl:
          type: string
          description: >-
            URL where the customer is redirected after required payment actions.
            Required for all payment methods except APPLEPAY and GOOGLEPAY,
            which are settled synchronously and do not redirect.
        additionalPaymentInstrument:
          $ref: '#/components/schemas/WalletTokenPayload'
        metadata:
          type: object
          description: Merchant metadata. Values must be strings.
          additionalProperties:
            type: string
        billingAddress:
          $ref: '#/components/schemas/BillingAddressJson'
          description: >-
            Optional billing address used for the payment instrument and
            first-invoice tax calculation. This address takes precedence over
            the existing payment instrument address, customer billing address,
            and request IP country for the first invoice. When Clink
            automatically creates a payment instrument, the address is saved to
            the new payment instrument. When paymentInstrumentId references an
            existing payment instrument, this address does not update that
            payment instrument.
        platformType:
          type: string
          description: Platform type. Supported values are WEB and WAP.
          enum:
            - WEB
            - WAP
        deviceType:
          type: string
          description: Device type. Supported values are Android and iOS.
          enum:
            - Android
            - iOS
        scheduledPhases:
          type: array
          description: >-
            Optional scheduled subscription plan changes. Each phase takes
            effect at a future billing period boundary.
          maxItems: 10
          items:
            $ref: '#/components/schemas/ScheduledPhase'
    CreateSubscriptionApiResponse:
      type: object
      properties:
        code:
          type: integer
          description: Response status code, 200 when success
          format: int32
          example: 200
        msg:
          type: string
          example: success
          description: Brief description of what happened, 'success' when happy case
        data:
          $ref: '#/components/schemas/CreateSubscriptionApiVo'
    WalletTokenPayload:
      type: object
      description: >-
        Complete wallet token for APPLEPAY / GOOGLEPAY, as returned by the
        wallet SDK. The token is single-use: generate a new one for every
        payment attempt.
      properties:
        tokenValue:
          type: string
          minLength: 1
          description: >-
            The complete wallet token as a string. Apple Pay:
            JSON.stringify(payment.token) (the PKPaymentToken). Google Pay: the
            raw tokenizationData.token (ECv2 JSON).
    BillingAddressJson:
      type: object
      description: >-
        Billing address information used for a payment instrument and tax
        calculation.
      properties:
        city:
          type: string
          description: City.
          example: San Francisco
        country:
          type: string
          description: Country code or name.
          example: US
        line1:
          type: string
          description: First line of the street address.
          example: 123 Market Street
        line2:
          type: string
          description: Second line of the street address.
          example: Suite 100
        postalCode:
          type: string
          description: Postal or zip code.
          example: '94105'
        region:
          type: string
          description: Region, state, or province.
          example: CA
    ScheduledPhase:
      required:
        - sequence
        - effectiveCycle
        - priceSnapshotId
        - quantity
      type: object
      description: >-
        A scheduled subscription plan change that takes effect at a future
        billing period boundary.
      properties:
        sequence:
          minimum: 1
          type: integer
          description: >-
            Position of this phase in the schedule. Values must be strictly
            increasing.
          format: int32
        effectiveCycle:
          minimum: 1
          type: integer
          description: >-
            The renewal boundary when this phase takes effect, counted from
            subscription creation. Values must be strictly increasing.
          format: int32
        priceSnapshotId:
          type: string
          description: >-
            Target subscription price snapshot ID. The snapshot must exist, have
            priceType=SUBSCRIBE with valid recurring details, and support the
            subscription payment currency.
        quantity:
          minimum: 1
          type: integer
          description: Target quantity for the scheduled phase.
          format: int32
        metadata:
          type: object
          description: >-
            Optional metadata for this scheduled phase. Maximum 20 keys. Key
            length must be 40 characters or fewer and string value length must
            be 500 characters or fewer.
          maxProperties: 20
          propertyNames:
            maxLength: 40
          additionalProperties:
            type: string
            maxLength: 500
    CreateSubscriptionApiVo:
      type: object
      description: >-
        Response data returned after creating a subscription. It contains the
        subscription, order, and invoice identifiers, together with the payment
        flow result.
      properties:
        subscriptionId:
          type: string
          description: Unique identifier of the created subscription
        sessionId:
          type: string
          description: Unique identifier of the related payment session
        paymentInstrumentId:
          type: string
          description: >-
            Payment instrument ID used for the subscription. When
            paymentInstrumentId is omitted for an auto-creatable payment method,
            this is the automatically created payment instrument ID.
        status:
          type: integer
          format: int32
          description: >-
            Payment result status. `1` means success, `2` means pending, `3`
            means failure, and `5` means need next action to complete payment.
          enum:
            - 1
            - 2
            - 3
            - 5
        action:
          $ref: '#/components/schemas/Action'
          description: >-
            Next action required to complete payment when status is `5`
            (NEXT_ACTION).
        amount:
          type: number
          description: Amount charged for this subscription creation flow
        currency:
          type: string
          description: Currency used for the subscription payment
        orderId:
          type: string
          description: Unique identifier of the related order
        invoiceId:
          type: string
          description: Unique identifier of the generated invoice, if any
    Action:
      type: object
      description: >-
        Describes the next client action required to continue or complete a
        payment flow. It is typically returned when the status is NEXT_ACTION.
      properties:
        redirectUrl:
          type: string
          description: >-
            Redirect URL that the client should open or navigate to for the next
            payment step.
        method:
          type: string
          description: HTTP method used to perform the next action.
          enum:
            - GET
            - POST
        type:
          type: string
          description: Payment method or action type that triggered this next step.
          enum:
            - ALIPAY
            - CARD
            - CASHAPP
            - GCASH
            - KAKAO
            - PIX
            - PROMPTPAY
            - QRIS
            - TNG
            - UPI
            - WECHAT
        walletHandleRedirectOrDisplayQrCode:
          $ref: '#/components/schemas/WalletHandleRedirectOrDisplayQrCode'
          description: >-
            Wallet-side display or redirect payload used for QR code rendering,
            mobile auth links, hosted instructions, or fallback URLs.
        paymentMethodType:
          type: string
          description: Payment method type associated with this action.
        postData:
          type: object
          description: Form or request parameters to submit when `method` is `POST`.
          additionalProperties:
            type: string
    WalletHandleRedirectOrDisplayQrCode:
      type: object
      description: Wallet response payload for redirect flows or QR code display flows.
      properties:
        imageUrlPng:
          type: string
          description: >-
            PNG QR code image URL. This field may also contain a Base64-encoded
            image string.
        imageUrlSvg:
          type: string
          description: >-
            SVG QR code image URL. This field may also contain a Base64-encoded
            image string.
        imageDataUrl:
          type: string
          description: Base64-encoded QR code image data URL.
        hostedInstructionsUrl:
          type: string
          description: Hosted instruction or guidance URL for H5 redirection flows.
        mobileAuthUrl:
          type: string
          description: Mobile authorization URL or deeplink used by mobile redirect flows.
        fallbackUrl:
          type: string
          description: Fallback HTTPS URL used when app redirection fails.
        packageName:
          type: string
          description: Android package name used by mobile app redirect flows.
        expiresAt:
          type: integer
          format: int64
          description: Expiration time in Unix seconds.
        expiresSecond:
          type: integer
          format: int64
          description: Optional countdown in seconds until expiration.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
      description: >-
        Your secret API key obtained from the Clink dashboard (Developers
        section)

````

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