> ## Documentation Index > Fetch the complete documentation index at: https://docs.paygentic.io/llms.txt > Use this file to discover all available pages before exploring further. # Create > Creates a subscription for an existing customer or creates a new customer as part of the action. ## OpenAPI ````yaml /openapi.json post /v0/subscriptions openapi: 3.1.0 info: title: Paygentic API version: 0.1.0 description: > The Paygentic API provides a comprehensive platform for building and scaling monetization infrastructure. ## Authentication All API requests require authentication using an API key passed in the `Authorization` header: ``` Authorization: Bearer YOUR_API_KEY ``` ## Base URL All API requests should be made to: ``` https://api.paygentic.io/v0 ``` contact: name: Paygentic Support email: support@paygentic.io license: name: Proprietary servers: - url: https://api.paygentic.io description: Production API - url: https://api.sandbox.paygentic.io description: Sandbox API security: - BearerAuth: [] tags: - name: Customers description: >- A `Customer` is an entity connected to a `Merchant` via a `Subscription`. This represents the merchant-facing perspective of `Consumers` who purchase their `Products`. - name: Billable Metrics description: >- A `Billable Metric` defines a measurable quantity tied to a `Product`'s consumption. Each metric stores details including its label, an explanatory description, and measurement units. - name: Grants description: >- Grants credit a customer's metered entitlement balance. Merchants can create grants directly or void existing ones. Use `GET /v1/entitlements?customerId={id}` or `GET /v1/entitlements?subscriptionId={id}` to find the metered entitlement `id` needed for these endpoints. - name: Features description: >- A `Feature` represents a specific capability or functionality provided by a `Product`. Features can be metered (usage-based), static (fixed allocation), or boolean (enabled/disabled). - name: Fees description: >- A `Fee` defines a recurring or one-time charge tied to a `Product`. Fees are linked to prices, and cadence is defined on the Price. - name: Plans description: >- A `Plan` links a collection of `Prices` to a `Product`. It functions as a pricing structure document for a particular feature set or service offering. - name: Prices description: >- A `Price` determines the monetary value for a single unit of a `Billable Metric`. Prices are exclusively grouped within a `Plan`. - name: Products description: >- A `Product` is an offering sold by a `Merchant`. It includes product metadata like title, summary, and pricing details. `Plans`, `Prices`, and `Subscriptions` are all associated with products. - name: Sources description: >- A `Source` is an external data provider capable of automatically creating usage events. Configuration occurs at the plan level, enabling data retrieval from third-party platforms such as Stripe to produce billable events. - name: Subscriptions description: >- A `Subscription` is a customer's commitment to purchase a `Product` following the terms of a `Plan` and its linked `Prices`. - name: Users description: >- A `User` is an entity granted access to an Organization's resources. All operations are performed by users. - name: Invoices V2 description: >- Invoice V2 operations supporting billing cycles organized by time periods. Warning: v0 invoice endpoints are no longer supported. - name: Revenue description: Revenue data from invoices and payments - name: Profitability description: Per-customer profitability summaries - name: Test Clocks description: >- Test clocks provide programmable time control to simulate subscription and billing scenarios during testing. - name: Events description: Ingest raw metering events that are processed by the meters service. - name: Payments description: >- Create and manage one-off payments. A payment represents a single charge that a merchant wants to collect from a customer. - name: Payment Sessions description: >- Handle payment session lifecycle and processing across various entity types including invoices and subscriptions - name: Costs description: >- A Cost represents the operational or infrastructure expense of serving customers for a given product. Costs are metered (driven by event-based usage) and are tracked in parallel with billable metrics to give merchants visibility into both revenue and cost per customer. - name: ExternalReferences description: >- An `ExternalReference` links a Paygentic entity (e.g. an `Item`) to a record in an external system such as Salesforce or NetSuite. Multiple external records may map to the same Paygentic entity, but each external id is the *primary* reference of at most one entity per merchant. - name: Items description: >- An `Item` is the canonical "thing you sell" that external-system mappings point at. It is fully decoupled from the billing `Product` and holds no pricing/plan/metering, and it is CRM/ERP agnostic — which providers map to it lives entirely in its `ExternalReference` rows. - name: MerchantIntegrations description: >- A `MerchantIntegration` records a merchant's connection to an external provider. One connection per `(merchant, provider)` — re-connecting upserts in place. - name: Approvals description: Submit, decide, cancel, and read maker-checker approvals. - name: Orders description: Manage Orders, their line items, and billing schedules. - name: Billing Schedules description: >- Owner-polymorphic billing schedules with intervals and staged invoice projections. A BillingSchedule belongs to exactly one Order or one Subscription (XOR). Cadence lives on ScheduleIntervals (cadence-on-the-line). paths: /v0/subscriptions: post: tags: - Subscriptions summary: Create description: >- Creates a subscription for an existing customer or creates a new customer as part of the action. operationId: createSubscription requestBody: required: true content: application/json: schema: type: object required: - planId - name - startedAt properties: autoCharge: type: boolean description: >- Enable automatic charging of invoices using stored payment methods. When true, invoices will be automatically paid using off-session payment. Defaults to false. default: false taxExempt: type: boolean description: >- When true, forces tax rate to 0%. Use for customers with verified tax-exempt status. default: false customer: type: object description: >- 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. properties: name: type: string email: type: string phone: type: string address: allOf: - $ref: '#/components/schemas/Address' - description: >- Address is required for tax calculation. Must include: country (ISO 3166-1 alpha-2) and zipCode. The state/region field is required and validated for US/CA addresses only (custom validation in API logic). Postal code format is not validated but will be normalized. required: - country - zipCode taxRates: $ref: '#/components/schemas/TaxRates' required: - name - email - address customerId: $ref: '#/components/schemas/CustomerId' endingAt: type: string format: date-time description: >- Subscription expiration timestamp in ISO 8601 format. Sample values: '2024-12-31T23:59:59Z', '2025-01-15T10:30:00Z'. Omit for indefinite subscriptions. name: type: string description: >- 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: $ref: '#/components/schemas/PlanId' prefundAmount: type: string description: >- @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: type: string description: >- 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: type: object description: >- Optional redirect URLs after payment completion or failure. If not provided, uses default platform behavior. properties: onSuccess: type: string format: uri description: >- Redirect destination after successful payment. Sample values: 'https://app.example.com/success', 'https://dashboard.company.com/welcome', 'https://portal.startup.io/complete' onFailure: type: string format: uri description: >- Redirect destination after failed payment. Sample values: 'https://app.example.com/payment-failed', 'https://dashboard.company.com/retry', 'https://portal.startup.io/error' startedAt: type: string format: date-time description: >- Subscription activation timestamp in ISO 8601 format. Sample values: '2024-01-15T10:30:00Z', '2024-02-01T00:00:00Z' testClockId: type: string description: >- 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: type: boolean nullable: true description: >- 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: type: integer nullable: true description: >- 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. minimum: 1 maximum: 30 paymentTermDays: type: integer description: >- Payment term in days ("Net X") applied to every invoice the subscription generates: invoice dueAt = invoice issue date + paymentTermDays. Defaults to 0 ("due on issue"). A non-zero value is only valid alongside bankTransferOnly=true. minimum: 0 maximum: 365 sessionExpiryMinutes: type: number description: >- Number of minutes until the payment session expires. Defaults to 240 minutes (4 hours) if not provided. minimum: 1 metadata: $ref: '#/components/schemas/SubscriptionMetadata' responses: '200': description: Subscription already exists content: application/json: schema: $ref: '#/components/schemas/Subscription' example: 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 '201': description: Subscription created successfully content: application/json: schema: $ref: '#/components/schemas/Subscription' example: id: sub_a1b2c3d4e5f6g7h8 object: subscription autoCharge: false taxExempt: false createdAt: '2024-01-15T10:30:00Z' customerId: cus_i9j0k1l2m3n4o5p6 endingAt: null estimatedTaxRate: 8.5 name: TechCorp - LLM API Access payment: amount: '250.00' breakdown: upfrontCharges: '50.00' walletCharge: '200.00' checkoutUrl: https://checkout.paygentic.com/session/ps_b3c4d5e6f7g8h9i0 paymentSessionId: ps_b3c4d5e6f7g8h9i0 planId: plan_q7r8s9t0u1v2w3x4 prefundAmount: '200000000000' startedAt: '2024-01-15T10:30:00Z' status: active terminatedAt: null terminatedBy: null terminationReason: null updatedAt: '2024-01-15T10:30:00Z' walletId: acc_y5z6a7b8c9d0e1f2 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' components: schemas: Address: type: object properties: line1: type: string line2: type: string city: type: string state: type: string country: type: string minLength: 2 maxLength: 2 description: 2 character ISO 3166 country code zipCode: type: string TaxRates: type: object description: >- An object mapping plan IDs, metric IDs, or 'default' to a tax rate percentage (e.g., 13 for 13%) additionalProperties: type: number minimum: 0 maximum: 100 CustomerId: type: string pattern: ^cus_[a-zA-Z0-9]+$ description: Unique identifier for a customer PlanId: type: string pattern: ^plan_[a-zA-Z0-9]+$ description: Unique identifier for a plan SubscriptionMetadata: type: object description: >- Free-form merchant metadata to attach to the subscription. Values must be strings, numbers, or booleans. additionalProperties: type: - string - number - boolean Subscription: type: object required: - id - object - merchantId - name - customerId - planId - status - startedAt - createdAt - updatedAt - paymentTermDays properties: id: type: string object: type: string enum: - subscription merchantId: $ref: '#/components/schemas/OrganizationId' description: >- The merchant organization that owns this subscription, equal to the customer's merchant. autoCharge: type: boolean description: >- Whether automatic charging is enabled for this subscription. When true, invoices will be automatically paid using stored payment methods. default: false createdAt: type: string format: date-time customerId: type: string endingAt: type: string format: date-time estimatedTaxRate: type: number description: >- 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: type: boolean description: When true, tax rate is forced to 0%. default: false name: type: string payment: description: >- Payment session details when upfront payment is required, or confirmation of a zero-amount paid invoice oneOf: - type: object properties: amount: type: string description: >- Total payment amount in decimal dollar format. Sample values: '250.00' equals $250.00, '99.99' equals $99.99 breakdown: type: object description: Breakdown of payment amount properties: upfrontCharges: type: string description: >- One-time flat fee charges in decimal dollar format. Sample values: '50.00' equals $50.00 setup fee, '100.00' equals $100.00 activation fee walletCharge: type: string description: Wallet charge amount in decimal dollar format. required: - upfrontCharges - walletCharge checkoutUrl: type: string description: Checkout page URL for customer payment completion. invoiceId: type: string description: ID of the invoice linked to this payment. paymentSessionId: type: string description: Payment session identifier for upfront payment processing. status: type: string description: Payment status enum: - pending required: - paymentSessionId - checkoutUrl - amount - status - breakdown - type: object description: Zero-amount Invoice 0 that completed synchronously to PAID properties: invoiceId: type: string description: The Invoice 0 id amount: type: string description: Payment amount ('0' for zero-amount subscriptions) status: type: string description: Payment status enum: - paid required: - invoiceId - amount - status - type: object description: >- Invoice 0 awaiting merchant approval before payment can proceed. The invoice is in DRAFT status with totals calculated. Approval is a platform-managed action and will be available via a public endpoint in a future release. properties: invoiceId: type: string description: The Invoice 0 id awaiting approval amount: type: string description: Total payment amount in decimal dollar format status: type: string description: Payment status enum: - awaiting_approval required: - invoiceId - amount - status planId: type: string prefundAmount: type: string description: >- @deprecated Use minimumAccountBalance instead. Minimum required wallet balance in atomic units. Sample values: '200000000000' equals $200.00 minimum, '1000000000000' equals $1000.00 minimum minimumAccountBalance: type: string description: >- 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 startedAt: type: string format: date-time status: type: string enum: - pending_payment - active - terminated terminatedAt: type: string format: date-time terminatedBy: type: string description: ID of who terminated the subscription (customer ID or merchant ID) terminationReason: type: string description: Reason for termination testClockId: type: string description: >- Test clock ID if this subscription is attached to a test clock. Only present in non-production environments. updatedAt: type: string format: date-time walletId: type: string description: Optional (virtual) wallet ID for the subscription renewalReminderEnabled: type: boolean nullable: true description: >- Whether renewal reminder emails are enabled for this subscription. Null means use plan default. renewalReminderDays: type: integer nullable: true description: >- Number of days before renewal to send the reminder. Null means use plan default. paymentTermDays: type: integer description: >- Payment term in days ("Net X") snapshotted onto every invoice the subscription generates (invoice dueAt = invoice issue date + paymentTermDays). Defaults to 0 ("due on issue"); a non-zero value is only set on bankTransferOnly subscriptions. minimum: 0 maximum: 365 autoApprove: type: boolean nullable: true description: >- Subscription-level auto-approval override. Null means plan default is used. metadata: $ref: '#/components/schemas/SubscriptionMetadata' customer: type: object description: >- Customer details with merchant and consumer information. Only included when include=customer is specified in the list query. properties: id: type: string description: Customer ID merchantId: type: string description: Merchant organization ID merchant: type: object properties: id: type: string name: type: string email: type: string required: - id - name - email consumer: type: object properties: id: type: string name: type: string email: type: string required: - id - name - email OrganizationId: type: string pattern: ^org_[a-zA-Z0-9]+$ description: Unique identifier for an organization Error: type: object required: - message properties: error: type: string description: >- Coarse HTTP error category (e.g. 'bad_request', 'forbidden'). Maps to the HTTP status code. message: type: string description: >- Human-readable error message. Clients must not parse this field programmatically. code: type: string examples: - TAX_NOT_ENABLED - PAYMENT_SESSION_EXPIRED description: >- Optional semantic business error code for machine-readable discrimination (e.g. 'TAX_NOT_ENABLED'). UPPER_SNAKE_CASE. Clients should check this field, not message. details: type: object description: Additional error details additionalProperties: true example: message: The requested resource was not found error: not_found ValidationError: type: object required: - message - errors properties: error: type: string enum: - validation_error default: validation_error description: Error type indicating validation failure message: type: string description: Human-readable error message errors: type: array items: type: object properties: field: type: string description: The field that failed validation message: type: string description: Validation error message for this field code: type: string description: Validation error code required: - field - message description: Array of field-specific validation errors example: message: Validation failed error: validation_error errors: - field: email message: Invalid email format code: invalid_format responses: BadRequest: description: >- Bad Request - The request could not be understood or was missing required parameters content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/ValidationError' Unauthorized: description: Unauthorized - Authentication failed or user does not have permissions content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: Forbidden - Request is understood but refused content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: Not Found - The requested resource could not be found content: application/json: schema: $ref: '#/components/schemas/Error' InternalServerError: description: Internal Server Error - Something went wrong on the server side content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: BearerAuth: type: http scheme: bearer description: API key authentication ````