> ## 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. # Advance > Advances the test clock's current time. You can either specify a new absolute time or advance by a duration. ## OpenAPI ````yaml /openapi.json patch /v0/testClocks/{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/testClocks/{id}: parameters: - name: id in: path required: true description: The unique identifier of the test clock schema: type: string pattern: ^tc_[a-zA-Z0-9]{16}$ patch: tags: - Test Clocks summary: Advance description: >- Advances the test clock's current time. You can either specify a new absolute time or advance by a duration. operationId: advanceTestClock parameters: - name: id in: path required: true description: Test clock ID schema: type: string pattern: ^tc_[a-zA-Z0-9]{16}$ requestBody: required: true content: application/json: schema: type: object oneOf: - type: object properties: currentTime: type: string format: date-time description: >- New absolute time for the test clock (must be forward in time) required: - currentTime - type: object properties: advanceBy: type: string pattern: >- ^P([0-9]+Y)?([0-9]+M)?([0-9]+W)?([0-9]+D)?(T([0-9]+H)?([0-9]+M)?([0-9]+S)?)?$ description: >- ISO 8601 duration format indicating clock advancement distance. Sample values: 'P1M' moves forward one month, 'P7D' moves forward seven days, 'PT2H' moves forward two hours, 'P1Y2M3DT4H5M6S' moves forward one year, two months, three days, four hours, five minutes, and six seconds required: - advanceBy responses: '200': description: Test clock updated successfully content: application/json: schema: $ref: '#/components/schemas/TestClock' example: id: tc_w9x0y1z2a3b4c5d6 createdAt: '2024-03-01T09:00:00Z' currentTime: '2024-03-20T14:00:00Z' deletedAt: null description: Test clock for daily usage billing scenarios merchantId: org_e7f8g9h0i1j2k3l4 name: Daily Usage Test updatedAt: '2024-03-20T14:00:00Z' '400': description: >- Invalid request parameters. Sample errors: attempting to move time backward, exceeding maximum advancement limit, invalid duration format content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Test clock not found content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: TestClock: type: object properties: id: type: string pattern: ^tc_[a-zA-Z0-9]{16}$ description: Unique identifier for the test clock createdAt: type: string format: date-time description: When the test clock was created currentTime: type: string format: date-time description: The simulated current time of the test clock deletedAt: type: string format: date-time nullable: true description: When the test clock was deleted (if applicable) description: type: string nullable: true description: Description of the test clock's purpose merchantId: type: string description: The merchant organization that owns this test clock name: type: string nullable: true description: Name of the test clock updatedAt: type: string format: date-time description: When the test clock was last updated required: - id - merchantId - currentTime - createdAt - updatedAt 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 securitySchemes: BearerAuth: type: http scheme: bearer description: API key authentication ````