Payments

Create subscription plan

Creates a recurring-payment subscription plan record. This stores SDP backend state and Solana subscriptions program identifiers; it does not by itself create the on-chain plan.

post/v1/payments/subscription-plans

Headers

x-project-idstring

Selects the active project for this request. Required for session/dashboard callers. Ignored when authenticating with an API key, whose scope is fixed to the key's project.

Example:prj_example

Selects the active project for this request. Required for session/dashboard callers. Ignored when authenticating with an API key, whose scope is fixed to the key's project.

Request body

ownerWalletIdstring required

Custody wallet that owns the Solana subscription plan.

tokenstring required

Token mint address. Native SOL is not expected for program-backed subscriptions.

amountstring required

Recurring charge amount in UI units.

periodHoursinteger required

Billing period length in hours.

programPlanIdstring

Unsigned 64-bit decimal program plan identifier used in the Solana subscriptions PDA seed. Defaults to a generated nonzero value.

planPdastring

On-chain plan PDA once created.

destinationAddressstring

Optional destination owner address allowed by the on-chain plan.

pullerWalletIdstring

Optional SDP custody wallet allowed to pull subscription payments.

metadataUristring uri

Optional plan metadata URI.

status'draft' | 'active' | 'archived'

Subscription plan status.

Example request

{
  "ownerWalletId": "wal_merchant",
  "token": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "amount": "25.00",
  "periodHours": 720,
  "programPlanId": "17014118346046923173",
  "planPda": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
  "destinationAddress": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
  "pullerWalletId": "wal_collector",
  "metadataUri": "https://example.com/subscriptions/monthly-usdc.json",
  "status": "active"
}

Response

Subscription plan created

Example response

{
  "data": {
    "subscriptionPlan": {
      "id": "psp_example",
      "organizationId": "org_example",
      "projectId": "prj_example",
      "ownerWalletId": "privy_wallet_123",
      "ownerAddress": "So11111111111111111111111111111111111111112",
      "amount": "100.00",
      "periodHours": 720,
      "programPlanId": "17014118346046923173",
      "planPda": "So11111111111111111111111111111111111111112",
      "destinationAddress": "So11111111111111111111111111111111111111112",
      "pullerWalletId": "privy_wallet_123",
      "pullerAddress": "So11111111111111111111111111111111111111112",
      "status": "active",
      "createdAt": "2025-01-01T00:00:00.000Z",
      "updatedAt": "2025-01-01T00:00:00.000Z"
    }
  },
  "meta": {
    "requestId": "req_example",
    "timestamp": "2025-01-01T00:00:00.000Z"
  }
}

Changes

Changed in 1 of the 9 revisions of this API.6

Aug 15, 20263e302bba53866See the full diff
- ●
  added the new SERVICE_UNAVAILABLE enum value to the error/code response property for the response status 400
  response-property-enum-value-added
- ●
  added the new SERVICE_UNAVAILABLE enum value to the error/code response property for the response status 401
  response-property-enum-value-added
- ●
  added the new SERVICE_UNAVAILABLE enum value to the error/code response property for the response status 403
  response-property-enum-value-added
- ●
  added the new SERVICE_UNAVAILABLE enum value to the error/code response property for the response status 404
  response-property-enum-value-added
- ●
  added the new SERVICE_UNAVAILABLE enum value to the error/code response property for the response status 409
  response-property-enum-value-added
- ●
  added the new SERVICE_UNAVAILABLE enum value to the error/code response property for the response status 500
  response-property-enum-value-added

Full history