Prepare subscription plan creation

POST/v1/payments/subscription-plans/{planId}/prepare-createRun in dashboard

This derives and stores the plan PDA but does not submit the transaction.

Requires an API key with the recurring.manage action.

Path parametersCopy Anchor Link

• planId · string · required · min length 1 · example psp_example

  SDP subscription plan record ID.

HeadersCopy Anchor Link

• x-project-id · string · min length 1 · example prj_example

  Required for dashboard sessions. API keys use their assigned project.

Request bodyCopy Anchor Link

application/json

Optional overrides used when preparing the Solana subscriptions create-plan transaction.

• destinations · string[] · max items 4

  Allowed destination addresses for the on-chain plan. Defaults to the stored plan destination.

• pullers · string[] · max items 4

  Allowed puller addresses for the on-chain plan. Defaults to the stored puller or owner address.

• endTs · string · pattern ^\d+$ · example 1770000000

  Optional unsigned 64-bit Unix timestamp when the on-chain plan ends.

• metadataUri · string · format uri · max length 128 · example https://example.com/subscriptions/monthly-usdc.json

  Optional metadata URI to embed in the on-chain plan.

ResponsesCopy Anchor Link

• 200 Subscription plan creation prepared

  • data · object · required

    Prepared Solana subscriptions create-plan response payload.

    • subscriptionPlan · object · required

      Recurring payment subscription plan record.

      • id · string · required · example psp_example

        SDP subscription plan ID.

      • organizationId · string · required · min length 1 · example org_example

        Organization identifier.

      • projectId · string · required · min length 1 · example prj_example

        Project identifier.

      • ownerWalletId · string · required · min length 1 · example privy_wallet_123

        Provider wallet ID — the walletId field returned by GET /v1/wallets.

      • ownerAddress · string · required · min length 32 · max length 44 · example So11111111111111111111111111111111111111112

        Base58-encoded Solana address.

      • token · string · required

        Token mint or normalized token identifier.

      • amount · string · required · example 100.00

        Token amount in UI units (decimal string).

      • periodHours · integer · required · greater than 0 · example 720

      • programPlanId · string · required · example 17014118346046923173

        Unsigned 64-bit decimal program plan identifier used in PDA derivation.

      • planPda · string | null · required · min length 32 · max length 44 · example So11111111111111111111111111111111111111112

        On-chain plan PDA.

      • destinationAddress · string | null · required · min length 32 · max length 44 · example So11111111111111111111111111111111111111112

        Allowed destination owner address.

      • pullerWalletId · string | null · required · min length 1 · example privy_wallet_123

        Collector wallet ID.

      • pullerAddress · string | null · required · min length 32 · max length 44 · example So11111111111111111111111111111111111111112

        Collector wallet address.

      • metadataUri · string | null · required

        Optional plan metadata URI.

      • status · string · required · one of draft, active, archived · example active

        Subscription plan status.

      • createdBy · string | null · required

        Creator user ID or API key ID.

      • createdAt · string · required · format date-time · example 2025-01-01T00:00:00.000Z

        ISO 8601 timestamp.

      • updatedAt · string · required · format date-time · example 2025-01-01T00:00:00.000Z

        ISO 8601 timestamp.

    • planPda · string · required · min length 32 · max length 44 · example So11111111111111111111111111111111111111112

      Derived Solana subscriptions plan PDA.

    • preparedTransaction · object · required

      Unsigned Solana subscriptions transaction payload for client-side signing.

      • serialized · string · required · min length 1 · example AQID

        Base64-encoded unsigned transaction.

      • blockhash · string · required · example blockhash_example

        Blockhash for the transaction.

      • lastValidBlockHeight · string · required · example 123456

        Last valid block height.

      • requiredSigners · string[] · required · each min length 32 · each max length 44 · each example So11111111111111111111111111111111111111112

        Addresses that must sign the prepared transaction. This includes the sponsored fee payer when the transaction uses one.

  • meta · object · required

    Response metadata.

    • requestId · string · required · min length 1 · example req_example

      Request identifier for tracing.

    • timestamp · string · required · format date-time · example 2025-01-01T00:00:00.000Z

      ISO 8601 timestamp.

• 400 Bad Request

  • error · object · required

    Standard error payload.

    • code · string · required

      Machine-readable error code.

    • message · string · required

      Human-readable error message.

    • details · object

      Optional error details for debugging.

      • * · any

  • meta · object

    • requestId · string · min length 1 · example req_example

      Request identifier for tracing.

• 401 Unauthorized

  Same fields as 400.

• 403 Forbidden. Requires the recurring.manage action: an API key must hold it (a module's manage or execute also covers its read), and a signed-in member's organization role must include it. Without it the error is INSUFFICIENT_PERMISSIONS and error.details.action names the action. Any other 403 names its own reason.

  Same fields as 400.

• 404 Not Found

  Same fields as 400.

• 500 Internal Server Error

  Same fields as 400.