Skip to main content
POST
/
v0
/
subscriptions
Create
curl --request POST \
  --url https://api.paygentic.io/v0/subscriptions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "planId": "<string>",
  "startedAt": "2023-11-07T05:31:56Z",
  "autoCharge": false,
  "taxExempt": false,
  "customer": {
    "name": "<string>",
    "email": "<string>",
    "address": {
      "country": "<string>",
      "zipCode": "<string>",
      "line1": "<string>",
      "line2": "<string>",
      "city": "<string>",
      "state": "<string>"
    },
    "phone": "<string>",
    "taxRates": {}
  },
  "customerId": "<string>",
  "endingAt": "2023-11-07T05:31:56Z",
  "prefundAmount": "<string>",
  "minimumAccountBalance": "<string>",
  "redirectUrls": {
    "onSuccess": "<string>",
    "onFailure": "<string>"
  },
  "testClockId": "<string>",
  "renewalReminderEnabled": true,
  "renewalReminderDays": 15,
  "sessionExpiryMinutes": 2
}
'
{
  "id": "sub_z1a2b3c4d5e6f7g8",
  "object": "subscription",
  "autoCharge": false,
  "taxExempt": false,
  "createdAt": "2024-01-10T08:00:00Z",
  "customerId": "cus_q3r4s5t6u7v8w9x0",
  "endingAt": null,
  "estimatedTaxRate": 8.5,
  "name": "StartupXYZ - Image Generation Service",
  "payment": null,
  "planId": "plan_t9u0v1w2x3y4z5a6",
  "prefundAmount": "50000000000",
  "startedAt": "2024-01-10T08:00:00Z",
  "status": "active",
  "terminatedAt": null,
  "terminatedBy": null,
  "terminationReason": null,
  "updatedAt": "2024-01-10T08:00:00Z",
  "walletId": "acc_b7c8d9e0f1g2h3i4"
}

Authorizations

​
Authorization
string
header
required

API key authentication

Body

application/json
​
name
string
required

Subscription identifier combining customer and service details. Sample values: 'TechCorp - LLM API Access', 'Analytics Co - Data Platform Enterprise', 'StartupXYZ - Image Generation Service', 'Enterprise Inc - ML Training Platform'

​
planId
string
required

Unique identifier for a plan

​
startedAt
string<date-time>
required

Subscription activation timestamp in ISO 8601 format. Sample values: '2024-01-15T10:30:00Z', '2024-02-01T00:00:00Z'

​
autoCharge
boolean
default:false

Enable automatic charging of invoices using stored payment methods. When true, invoices will be automatically paid using off-session payment. Defaults to false.

​
taxExempt
boolean
default:false

When true, forces tax rate to 0%. Use for customers with verified tax-exempt status.

​
customer
object

Fields to create a new customer and consumer. Will use an existing consumer if one exists with the same email address. Required if customerId is not provided. Address with complete tax information (country, state, zipCode) is required for tax calculation when using Paygentic Tax.

​
customerId
string

Unique identifier for a customer

​
endingAt
string<date-time>

Subscription expiration timestamp in ISO 8601 format. Sample values: '2024-12-31T23:59:59Z', '2025-01-15T10:30:00Z'. Omit for indefinite subscriptions.

​
prefundAmount
string

@deprecated Use minimumAccountBalance instead. Required initial wallet deposit amount. Sample values: '200.00' requires $200 prepaid balance for metered LLM usage, '1000.00' requires $1000 prepaid credits for data processing services, '50.00' requires $50 minimum for API call consumption

​
minimumAccountBalance
string

Minimum wallet balance requirement in decimal dollars (e.g., '100.00'). Can be set to '0' to disable. The system will calculate the difference between this minimum and the customer's current balance, charging only what's needed to reach the minimum. If the customer already has sufficient balance, no charge is made. Note: If the calculated charge amount is below payment processor minimums (typically $1.00), it will be automatically adjusted upward to meet the minimum requirement. Sample values: '200.00' requires minimum $200 balance for metered LLM usage, '1000.00' requires minimum $1000 balance for data processing services

​
redirectUrls
object

Optional redirect URLs after payment completion or failure. If not provided, uses default platform behavior.

​
testClockId
string

Test clock identifier for simulating time-based billing scenarios. Sample values: 'tc_abc123xyz', 'tc_789def456'. Restricted to non-production environments (local, dev, sandbox). Must belong to the same merchant organization.

​
renewalReminderEnabled
boolean | null

Override plan setting for renewal reminder emails. When set, this subscription's setting takes precedence over the plan default. Set to true to enable reminders, false to disable, or null/omit to use plan default.

​
renewalReminderDays
integer | null

Override plan setting for number of days before renewal to send the reminder. Only used if renewalReminderEnabled is true (or inherited from plan). Set to null to use plan default.

Required range: 1 <= x <= 30
​
sessionExpiryMinutes
number

Number of minutes until the payment session expires. Defaults to 240 minutes (4 hours) if not provided.

Required range: x >= 1

Response

Subscription already exists

​
id
string
required
​
object
enum<string>
required
Available options:
subscription
​
createdAt
string<date-time>
required
​
customerId
string
required
​
name
string
required
​
planId
string
required
​
startedAt
string<date-time>
required
​
status
enum<string>
required
Available options:
pending_payment,
active,
terminated
​
updatedAt
string<date-time>
required
​
autoCharge
boolean
default:false

Whether automatic charging is enabled for this subscription. When true, invoices will be automatically paid using stored payment methods.

​
endingAt
string<date-time>
​
estimatedTaxRate
number

Projected tax percentage rate. Sample values: 8.875 indicates 8.875% tax rate, 10.0 indicates 10% tax rate, 0 indicates no tax applied

​
taxExempt
boolean
default:false

When true, tax rate is forced to 0%.

​
payment
object

Payment session details when upfront payment is required

​
prefundAmount
string

@deprecated Use minimumAccountBalance instead. Minimum required wallet balance in atomic units. Sample values: '200000000000' equals $200.00 minimum, '1000000000000' equals $1000.00 minimum

​
minimumAccountBalance
string

Minimum wallet balance requirement in nanodollars. Can be '0' to disable. The system calculates the difference between this minimum and the customer's current balance, charging only what's needed to reach the minimum. Note: If the calculated charge amount is below payment processor minimums (typically $1.00), the actual charged amount may be automatically adjusted upward to meet the minimum requirement. Sample values: '200000000000' equals $200.00 minimum, '1000000000000' equals $1000.00 minimum

​
terminatedAt
string<date-time>
​
terminatedBy
string

ID of who terminated the subscription (customer ID or merchant ID)

​
terminationReason
string

Reason for termination

​
testClockId
string

Test clock ID if this subscription is attached to a test clock. Only present in non-production environments.

​
walletId
string

Optional (virtual) wallet ID for the subscription

​
renewalReminderEnabled
boolean | null

Whether renewal reminder emails are enabled for this subscription. Null means use plan default.

​
renewalReminderDays
integer | null

Number of days before renewal to send the reminder. Null means use plan default.