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>"
}
'
{
  "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'). 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. Sample values: '200.00' requires minimum $200 balance for metered LLM usage, '1000.00' requires minimum $1000 balance for data processing services, '50.00' requires minimum $50 balance for API call consumption

​
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.

Response

Subscription already exists

​
id
string
​
object
enum<string>
Available options:
subscription
​
autoCharge
boolean
default:false

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

​
createdAt
string<date-time>
​
customerId
string
​
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%.

​
name
string
​
payment
object

Payment session details when upfront payment is required

​
planId
string
​
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. The system calculates the difference between this minimum and the customer's current balance, charging only what's needed to reach the minimum. Sample values: '200000000000' equals $200.00 minimum, '1000000000000' equals $1000.00 minimum

​
startedAt
string<date-time>
​
status
enum<string>
Available options:
pending_payment,
active,
terminated
​
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.

​
updatedAt
string<date-time>
​
walletId
string

Optional (virtual) wallet ID for the subscription