> ## 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. # Update ## OpenAPI ````yaml /openapi.json patch /v0/subscriptions/{id} 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/{id}: patch: tags: - Subscriptions summary: Update operationId: updateSubscription parameters: - in: path name: id required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: endingAt: type: string format: date-time status: type: string enum: - active - terminated terminatedAt: type: string format: date-time description: >- Effective termination timestamp. Capped at the current effective time (future values are clamped). Must be strictly after the subscription's start date — values at or before startedAt are rejected with 400. terminatedBy: type: string description: >- Identifier of entity that cancelled the subscription. Sample values: 'cust_abc123' for customer-initiated cancellation, 'org_xyz789' for merchant-initiated cancellation terminationReason: type: string description: >- Explanation for subscription cancellation. Sample values: 'Customer requested cancellation', 'Payment failure', 'Service migration', 'Contract expiration' autoCharge: type: boolean description: >- Enable or disable automatic charging of invoices using stored payment methods. taxExempt: type: boolean description: When true, forces tax rate to 0%. minimumAccountBalance: type: string description: >- Minimum wallet balance requirement in decimal dollars (e.g., '100.00'). Can be set to '0' to disable. Maximum allowed is $5,000. Contact support for higher limits. Note: If the calculated charge amount at renewal is below payment processor minimums (typically $1.00), it will be automatically adjusted upward to meet the minimum requirement. Changes apply at next renewal. renewalReminderEnabled: type: boolean nullable: true description: >- Override plan setting for renewal reminder emails. Set to true to enable, false to disable, or null to use plan default. renewalReminderDays: type: integer nullable: true description: >- Override plan setting for number of days before renewal to send the reminder. Set to null to use plan default. minimum: 1 maximum: 30 paymentTermDays: type: integer description: >- Payment term in days ("Net X") applied to subsequently generated invoices: invoice dueAt = invoice issue date + paymentTermDays. A non-zero value is only valid alongside bankTransferOnly=true. Set 0 for "due on issue". Already-issued invoices keep their snapshotted dueAt. minimum: 0 maximum: 365 responses: '200': description: Subscription updated content: application/json: schema: $ref: '#/components/schemas/Subscription' example: id: sub_z1a2b3c4d5e6f7g8 object: subscription autoCharge: true taxExempt: false createdAt: '2024-01-10T08:00:00Z' customerId: cus_q3r4s5t6u7v8w9x0 endingAt: '2024-12-31T23:59:59Z' 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-03-15T10:30:00Z' walletId: acc_b7c8d9e0f1g2h3i4 '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: 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 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 ````