> ## 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. # List ## OpenAPI ````yaml /openapi.json get /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: get: tags: - Subscriptions summary: List operationId: listSubscriptions parameters: - in: query name: consumerId schema: $ref: '#/components/schemas/OrganizationId' description: >- Return subscriptions for this consumer organization. May be combined with `merchantId` to scope to a single consumer/merchant pair. Cannot be combined with `customerId`. - in: query name: customerId schema: $ref: '#/components/schemas/CustomerId' description: >- Return subscriptions for this customer. Cannot be combined with `consumerId` or `merchantId`. - in: query name: limit schema: type: string default: '10' description: Number of subscriptions to return - in: query name: merchantId schema: $ref: '#/components/schemas/OrganizationId' description: >- Return subscriptions for this merchant organization. May be combined with `consumerId` to scope to a single consumer/merchant pair. Cannot be combined with `customerId`. - in: query name: offset schema: type: string default: '0' description: Number of subscriptions to skip - in: query name: status schema: type: string enum: - active - terminated - pending_payment - in: query name: startedBefore schema: type: string format: date-time description: Filter subscriptions started at or before this ISO 8601 date-time - in: query name: include schema: type: string enum: - customer description: >- Include related resources. When 'customer' is specified, each subscription includes merchant and consumer details. responses: '200': description: List of subscriptions content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Subscription' pagination: $ref: '#/components/schemas/OffsetPagination' example: data: - 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 - id: sub_j1k2l3m4n5o6p7q8 object: subscription autoCharge: true taxExempt: true createdAt: '2024-02-01T14:45:30Z' customerId: cus_r9s0t1u2v3w4x5y6 endingAt: '2024-12-31T23:59:59Z' estimatedTaxRate: 0 name: Analytics Co - Data Platform Enterprise payment: null planId: plan_z7a8b9c0d1e2f3g4 prefundAmount: '1000000000000' startedAt: '2024-02-01T14:45:30Z' status: active terminatedAt: null terminatedBy: null terminationReason: null updatedAt: '2024-02-15T09:20:00Z' walletId: acc_h5i6j7k8l9m0n1o2 pagination: limit: 10 offset: 0 total: 2 '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: OrganizationId: type: string pattern: ^org_[a-zA-Z0-9]+$ description: Unique identifier for an organization CustomerId: type: string pattern: ^cus_[a-zA-Z0-9]+$ description: Unique identifier for a customer 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 OffsetPagination: type: object description: Offset-based pagination response. properties: limit: type: integer description: Requested page size. offset: type: integer description: Number of items skipped. total: type: integer description: Total number of items available. required: - limit - offset - total 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 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 ````