> ## 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 a subscription and initiate its first payment with an existing payment instrument. ## 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 with an existing payment instrument. operationId: createSubscription parameters: - $ref: '#/components/parameters/TimestampHeader' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateSubscriptionApiRequest' examples: example: 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 scheduledPhases: - sequence: 1 effectiveCycle: 2 priceSnapshotId: ps_xxxxx quantity: 1 metadata: plan: pro 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 - paymentInstrumentId - paymentMethodType - paymentCurrency - returnUrl type: object 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. paymentMethodType: type: string description: Payment method type. Supported values are uppercase. enum: - CARD - GCASH 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. metadata: type: object description: Merchant metadata. Values must be strings. additionalProperties: type: string 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' 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 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) ````