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 '{
  "autoCharge": false,
  "customer": {
    "name": "<string>",
    "email": "<string>",
    "phone": "<string>",
    "address": {
      "line1": "<string>",
      "line2": "<string>",
      "city": "<string>",
      "state": "<string>",
      "country": "<string>",
      "zipCode": "<string>"
    },
    "taxRates": {}
  },
  "customerId": "<string>",
  "endingAt": "2023-11-07T05:31:56Z",
  "items": [
    {
      "billableMetricId": "<string>",
      "quantity": 123
    }
  ],
  "name": "<string>",
  "planId": "<string>",
  "prefundAmount": "<string>",
  "redirectUrls": {
    "onSuccess": "<string>",
    "onFailure": "<string>"
  },
  "startedAt": "2023-11-07T05:31:56Z",
  "testClockId": "<string>"
}'
{
  "id": "sub_z1a2b3c4d5e6f7g8",
  "object": "subscription",
  "autoCharge": false,
  "createdAt": "2024-01-10T08:00:00Z",
  "customerId": "cus_q3r4s5t6u7v8w9x0",
  "endingAt": null,
  "estimatedTaxRate": 8.5,
  "items": [],
  "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.

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

​
items
object[]

Array of upfront flat-fee items with quantities

​
prefundAmount
string

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

​
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

​
items
object[]

Array of upfront subscription items with quantities and costs

​
name
string
​
payment
object

Payment session details when upfront payment is required

​
planId
string
​
prefundAmount
string

Minimum required wallet balance in atomic units. 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