{ "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.\n\n## Authentication\nAll API requests require authentication using an API key passed in the `Authorization` header:\n```\nAuthorization: Bearer YOUR_API_KEY\n```\n\n## Base URL\nAll API requests should be made to:\n```\nhttps://api.paygentic.io/v0\n```\n", "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.\n\nUse `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/billableMetrics": { "post": { "tags": [ "Billable Metrics" ], "summary": "Create", "description": "Create a new billable metric for a merchant organization. A `Billable Metric` represents a metric that can be used to measure the usage of a `Product`. It contains information about the metric, such as its name, description, and units.", "operationId": "createBillableMetric", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "description", "unit", "merchantId", "productId", "aggregation" ], "properties": { "aggregation": { "type": "string", "enum": [ "SUM", "COUNT", "AVG", "MIN", "MAX", "UNIQUE_COUNT", "LATEST" ], "description": "Aggregation calculation method for metric values." }, "description": { "type": "string", "description": "Explanatory text describing what the metric tracks and how it's used for billing. Sample values: 'Total tokens consumed by Claude language model interactions', 'Gigabytes of cloud storage utilized', 'Count of machine learning inference requests processed', 'Quantity of AI-generated images created', 'Compute hours spent training neural networks', 'Terabytes of data transferred'" }, "merchantId": { "$ref": "#/components/schemas/OrganizationId", "description": "The unique identifier of the merchant organization associated with the billable metric." }, "name": { "type": "string", "description": "Human-readable label identifying what this metric measures. Sample values: 'Claude Tokens', 'Storage Capacity', 'Model Inference Calls', 'Generated Images', 'Training Compute Hours', 'Data Transfer Volume'" }, "productId": { "$ref": "#/components/schemas/ProductId", "description": "The unique identifier of the product associated with the billable metric." }, "unit": { "type": "string", "description": "Measurement unit used when aggregating this metric's values. Common examples: 'tokens', 'GB', 'calls', 'images', 'hours', 'TB', 'queries', 'requests'" }, "eventType": { "type": "string", "description": "CloudEvents type for meter routing. Links this billable metric to the metering service." }, "valueProperty": { "type": "string", "pattern": "^\\$\\.[a-zA-Z0-9_]+(\\.[a-zA-Z0-9_]+)*$", "description": "JSONPath to extract a numeric value from event data. Must start with `$.` (example: `$.amount` or `$.payload.bytes`). Required for SUM/AVG/MIN/MAX/LATEST aggregations." }, "groupBy": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^\\$\\.[a-zA-Z0-9_]+(\\.[a-zA-Z0-9_]+)*$" }, "description": "Map of dimension name to JSONPath for group-by queries. Each value must start with `$.` (example: `$.region`)." }, "eventFrom": { "type": "string", "format": "date-time", "description": "Only count events after this timestamp. Used for meter versioning." } } } } } }, "responses": { "201": { "description": "Billable metric created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillableMetric" }, "example": { "id": "bm_w9x0y1z2a3b4c5d6", "object": "billableMetric", "aggregation": "SUM", "createdAt": "2024-01-15T10:30:00Z", "description": "Total tokens consumed by Claude language model interactions", "merchantId": "org_e7f8g9h0i1j2k3l4", "name": "Claude Tokens", "productId": "prod_m5n6o7p8q9r0s1t2", "taxRate": 8.5, "unit": "tokens", "updatedAt": "2024-01-15T10:30:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "get": { "tags": [ "Billable Metrics" ], "summary": "List", "operationId": "listBillableMetrics", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "description": "Number of billable metrics to return." }, { "name": "merchantId", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "Filter billable metrics by merchant organization ID." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of billable metrics to skip." }, { "name": "productId", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ProductId" }, "description": "Filter billable metrics by product ID." } ], "responses": { "200": { "description": "List of billable metrics", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "pagination" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/BillableMetric" } }, "pagination": { "type": "object", "required": [ "limit", "offset", "total" ], "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer" } } } } }, "example": { "object": "list", "data": [ { "id": "bm_w9x0y1z2a3b4c5d6", "object": "billableMetric", "aggregation": "SUM", "createdAt": "2024-01-15T10:30:00Z", "description": "Total tokens consumed by Claude language model interactions", "merchantId": "org_e7f8g9h0i1j2k3l4", "name": "Claude Tokens", "productId": "prod_m5n6o7p8q9r0s1t2", "unit": "tokens", "updatedAt": "2024-01-15T10:30:00Z" }, { "id": "bm_a1b2c3d4e5f6g7h8", "object": "billableMetric", "aggregation": "SUM", "createdAt": "2024-02-01T14:45:30Z", "description": "Gigabytes of cloud storage utilized", "merchantId": "org_e7f8g9h0i1j2k3l4", "name": "Storage Capacity", "productId": "prod_m5n6o7p8q9r0s1t2", "unit": "GB", "updatedAt": "2024-02-15T09:20:00Z" } ], "pagination": { "limit": 10, "offset": 0, "total": 2 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v0/billableMetrics/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/BillableMetricId" } } ], "get": { "tags": [ "Billable Metrics" ], "summary": "Get", "operationId": "getBillableMetric", "responses": { "200": { "description": "Billable metric details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillableMetric" }, "example": { "id": "bm_u3v4w5x6y7z8a9b0", "object": "billableMetric", "aggregation": "SUM", "createdAt": "2024-02-01T14:45:30Z", "description": "Gigabytes of cloud storage utilized", "merchantId": "org_c1d2e3f4g5h6i7j8", "name": "Storage Capacity", "productId": "prod_k9l0m1n2o3p4q5r6", "taxRate": 10, "unit": "GB", "updatedAt": "2024-02-15T09:20:00Z" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "patch": { "tags": [ "Billable Metrics" ], "summary": "Update", "operationId": "updateBillableMetric", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "type": "string", "description": "Revised explanation of what the metric represents. Sample values: 'Language model token consumption', 'Database storage capacity used', 'Machine learning prediction API calls', 'AI-generated content items'" }, "name": { "type": "string", "description": "Updated label for the metric. Sample values: 'LLM Tokens', 'Database Storage', 'Prediction Requests', 'Content Generations'" }, "unit": { "type": "string", "description": "Updated measurement unit. Common examples: 'tokens', 'GB', 'requests', 'items', 'hours'" }, "eventType": { "type": "string", "nullable": true, "description": "CloudEvents type for meter routing." }, "valueProperty": { "type": "string", "nullable": true, "pattern": "^\\$\\.[a-zA-Z0-9_]+(\\.[a-zA-Z0-9_]+)*$", "description": "JSONPath to extract a numeric value from event data. Must start with `$.` (example: `$.amount` or `$.payload.bytes`)." }, "groupBy": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^\\$\\.[a-zA-Z0-9_]+(\\.[a-zA-Z0-9_]+)*$" }, "nullable": true, "description": "Map of dimension name to JSONPath for group-by queries. Each value must start with `$.` (example: `$.region`)." }, "eventFrom": { "type": "string", "format": "date-time", "nullable": true, "description": "Only count events after this timestamp." } } } } } }, "responses": { "200": { "description": "Billable metric updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillableMetric" }, "example": { "id": "bm_u3v4w5x6y7z8a9b0", "object": "billableMetric", "aggregation": "SUM", "createdAt": "2024-02-01T14:45:30Z", "description": "Language model token consumption", "merchantId": "org_c1d2e3f4g5h6i7j8", "name": "LLM Tokens", "productId": "prod_k9l0m1n2o3p4q5r6", "unit": "tokens", "updatedAt": "2024-03-15T11:30:00Z" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v0/billableMetrics/{id}/meter": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/BillableMetricId" } } ], "get": { "tags": [ "Billable Metrics" ], "summary": "Query Meter Usage", "description": "Query aggregated usage data for a billable metric from the metering service.", "operationId": "getBillableMetricMeter", "parameters": [ { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" }, "description": "Start of query window (ISO 8601)" }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" }, "description": "End of query window (ISO 8601)" }, { "name": "subject", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by customer/user ID" }, { "name": "windowSize", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "MINUTE", "HOUR", "DAY", "MONTH" ] }, "description": "Time bucket granularity" }, { "name": "filterGroupBy", "in": "query", "required": false, "schema": { "type": "string" }, "description": "JSON-encoded dimension filter (e.g. {\"key\":\"value\"})" }, { "name": "groupBy", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated dimension keys. Configure keys for the grouping on the metric. Only the \"subject\" grouping is supported by default." }, { "name": "groupLimit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500 }, "description": "Cap groupedValues to the top-N by value (descending). With windowSize, restricts the windowed series to those top-N groups. Bounds the payload for high-cardinality groupings; groupCount reports the untruncated distinct-group count." }, { "name": "groupOffset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 100000 }, "description": "Offset into the value-descending group ordering; requires groupLimit to page through grouped results. With windowSize set, pages the windowed series through the ranked groups (offset 0 yields the top-N)." } ], "responses": { "200": { "description": "Usage data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageResponse" }, "example": { "object": "meter", "billableMetricId": "bm_abc", "totalValue": 42.5, "windowedValues": [ { "windowStart": "2025-06-15T10:00:00.000Z", "windowEnd": "2025-06-15T11:00:00.000Z", "value": 12 } ], "groupedValues": [ { "groupBy": { "model": "gpt-4" }, "value": 30, "eventCount": 3 } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v0/billableMetrics/{id}/events": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/BillableMetricId" } } ], "get": { "tags": [ "Billable Metrics" ], "summary": "List Meter Events", "description": "List raw underlying events for a billable metric from the metering service. Returns events ordered by time descending.", "operationId": "listBillableMetricEvents", "parameters": [ { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" }, "description": "Start of query window (ISO 8601)" }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" }, "description": "End of query window (ISO 8601)" }, { "name": "subject", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by subject (typically the customer/user ID)" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 20 }, "description": "Maximum number of events to return" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of events to skip" }, { "name": "externalId", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ExternalId" }, "description": "Filter by external identifier. Alphanumeric characters, hyphens, and underscores only." }, { "name": "externalSubject", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ExternalId" }, "description": "Filter by the merchant's own customer identifier the event was reported with." } ], "responses": { "200": { "description": "Raw events list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeterEventList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v0/customers": { "get": { "tags": [ "Customers" ], "summary": "List by Merchant", "operationId": "listCustomers", "x-rate-limit": { "max": 10, "platformMax": 60, "timeWindow": "1 second", "errorMessage": "Too many customer list requests. Please wait before trying again." }, "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "description": "Number of customers to return" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of customers to skip" }, { "name": "name", "in": "query", "required": false, "schema": { "type": "string", "minLength": 3, "maxLength": 255 }, "description": "Filter customers by consumer name (case-insensitive substring match). Minimum 3 characters required for efficient index usage." }, { "name": "email", "in": "query", "required": false, "schema": { "type": "string", "minLength": 3, "maxLength": 255 }, "description": "Filter customers by billing email (case-insensitive substring match). Minimum 3 characters required for efficient index usage. Accepts partial values — e.g. a domain (\"acme.com\") or local part (\"billing\")." }, { "name": "externalId", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Filter customers by exact external ID match." }, { "name": "organizationId", "in": "query", "required": true, "description": "ID of the merchant organization to filter customers by", "schema": { "$ref": "#/components/schemas/OrganizationId" } } ], "responses": { "200": { "description": "List of customers retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } }, "pagination": { "$ref": "#/components/schemas/OffsetPagination" } }, "required": [ "object", "data", "pagination" ] }, "example": { "object": "list", "data": [ { "id": "cus_p1q2r3s4t5u6v7w8", "object": "customer", "consumerId": "org_x9y0z1a2b3c4d5e6", "createdAt": "2024-02-05T11:30:00Z", "merchantId": "org_f7g8h9i0j1k2l3m4", "organization": { "id": "org_x9y0z1a2b3c4d5e6", "address": { "city": "San Francisco", "country": "US", "line1": "123 Main St", "state": "CA", "zipCode": "94105" }, "billingEmails": [ "billing@techcorp.com" ], "name": "TechCorp", "phone": "+1-555-123-4567" }, "taxId": null, "taxRates": { "default": 8.5 }, "updatedAt": "2024-02-10T14:20:00Z", "validTaxAddress": { "message": null, "valid": true } } ], "pagination": { "limit": 10, "offset": 0, "total": 1 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "tags": [ "Customers" ], "summary": "Create", "description": "Create a new customer for a merchant organization. This endpoint is currently only used by the Paygentic platform as part of the subscription flow.", "operationId": "createCustomer", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "merchantId" ], "properties": { "consumer": { "type": "object", "description": "Fields to create a new consumer. Will use an existing consumer if one exists with the same email address. Required if `consumerId` 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", "format": "email", "description": "Consumer email address. Sample values: 'customer@example.com', 'billing@company.com', 'admin@startup.io'" }, "phone": { "type": "string", "description": "Consumer phone number. Sample values: '+1-555-123-4567', '+44-20-7946-0958', '+49-30-12345678'" }, "address": { "allOf": [ { "$ref": "#/components/schemas/Address" } ], "description": "Consumer address. For accurate tax calculation when using Paygentic Tax, provide complete address with country (ISO 3166-1 alpha-2), state, and zipCode. Incomplete addresses will skip tax calculation and use the plan's default tax rate instead." } }, "required": [ "name", "email", "address" ] }, "consumerId": { "description": "The unique identifier for the consumer. Required if `consumer` is not provided.", "$ref": "#/components/schemas/OrganizationId" }, "merchantId": { "description": "The unique identifier for the merchant organization.", "$ref": "#/components/schemas/OrganizationId" }, "taxId": { "type": "string", "description": "Optional business tax registration identifier. Sample values: 'GB123456789' for UK VAT, 'DE123456789' for German VAT, 'FR12345678901' for French VAT. Supplying this value enables inter-company tax handling and exemption from standard tax collection." }, "externalId": { "type": "string", "maxLength": 255, "description": "Merchant-defined identifier for this customer in their own system." }, "taxRates": { "$ref": "#/components/schemas/TaxRates" } } } } } }, "responses": { "200": { "description": "Customer already exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "customerId": { "type": "string" }, "validTaxAddress": { "$ref": "#/components/schemas/ValidTaxAddress" } }, "required": [ "customerId", "validTaxAddress" ] }, "example": { "customerId": "cus_h3i4j5k6l7m8n9o0", "validTaxAddress": { "message": null, "valid": true } } } } }, "201": { "description": "Customer created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "customerId": { "type": "string" }, "validTaxAddress": { "$ref": "#/components/schemas/ValidTaxAddress" } }, "required": [ "customerId", "validTaxAddress" ] }, "example": { "customerId": "cus_h3i4j5k6l7m8n9o0", "validTaxAddress": { "message": null, "valid": true } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Conflict. A customer with this externalId already exists for this merchant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v0/customers/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique identifier of the customer.", "schema": { "$ref": "#/components/schemas/CustomerId" } } ], "get": { "tags": [ "Customers" ], "summary": "Get", "operationId": "getCustomer", "responses": { "200": { "description": "Customer details retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" }, "example": { "id": "cus_p1q2r3s4t5u6v7w8", "object": "customer", "consumerId": "org_x9y0z1a2b3c4d5e6", "createdAt": "2024-02-05T11:30:00Z", "merchantId": "org_f7g8h9i0j1k2l3m4", "taxId": null, "taxRates": { "default": 8.5 }, "updatedAt": "2024-02-10T14:20:00Z", "validTaxAddress": { "message": null, "valid": true } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "tags": [ "Customers" ], "summary": "Delete", "operationId": "deleteCustomer", "responses": { "204": { "description": "Customer deleted successfully" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Customer cannot be deleted due to active dependencies", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "conflict" ] }, "message": { "type": "string" }, "details": { "type": "object", "properties": { "blockers": { "type": "array", "items": { "type": "object", "required": [ "type", "count", "items" ], "properties": { "type": { "type": "string", "enum": [ "subscriptions", "invoices", "disputes", "entitlements" ] }, "count": { "type": "integer" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" } } } } } } } } } } } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "patch": { "tags": [ "Customers" ], "summary": "Update", "operationId": "updateCustomer", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "taxId": { "type": "string", "nullable": true, "description": "Business tax registration identifier. Sample values: 'GB123456789' for UK VAT, 'DE123456789' for German VAT, 'FR12345678901' for French VAT. Enables inter-company tax handling and exemption from standard tax collection. Assign null to delete the identifier." }, "externalId": { "type": "string", "nullable": true, "maxLength": 255, "description": "Merchant-defined identifier for this customer in their own system. Set to null to clear." }, "taxRates": { "oneOf": [ { "type": "number", "description": "Single tax rate percentage applied across all plans and metrics. Sample values: '8.5' represents 8.5% tax rate, '12.1' represents 12.1% tax rate, '0' represents no tax", "minimum": 0, "maximum": 100 }, { "$ref": "#/components/schemas/TaxRates" } ] }, "notificationSettings": { "type": "object", "description": "Notification preferences for this customer. Only provided fields are updated.", "properties": { "invoiceIssued": { "type": "boolean", "description": "Whether to send invoice issued emails to this customer." }, "invoicePaid": { "type": "boolean", "description": "Whether to send invoice paid emails to this customer." }, "renewalReminder": { "type": "boolean", "description": "Whether to send renewal reminder emails to this customer." } } } } } } } }, "responses": { "200": { "description": "Customer updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" }, "example": { "id": "cus_n5o6p7q8r9s0t1u2", "object": "customer", "consumerId": "org_v3w4x5y6z7a8b9c0", "createdAt": "2024-01-20T09:15:00Z", "merchantId": "org_d1e2f3g4h5i6j7k8", "taxId": "GB123456789", "taxRates": { "default": 10 }, "updatedAt": "2024-03-12T16:30:00Z", "validTaxAddress": { "message": null, "valid": true } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Conflict. A customer with this externalId already exists for this merchant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v0/customers/{id}/paymentMethods": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique identifier of the customer.", "schema": { "$ref": "#/components/schemas/CustomerId" } } ], "get": { "tags": [ "Customers" ], "summary": "List payment methods", "description": "List off-session payment methods saved for this customer.", "operationId": "listCustomerPaymentMethods", "responses": { "200": { "description": "List of payment methods", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentMethod" } } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "tags": [ "Customers" ], "summary": "Set up a payment method", "description": "Create a payment session that captures a new off-session payment method for this customer without charging. The response contains a hosted-page URL — redirect the customer to it, or load it inside an iframe (when iframed, the page reports outcomes via `postMessage` to the parent window).", "operationId": "createCustomerPaymentMethod", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "successRedirectUrl": { "type": "string", "format": "uri", "description": "URL the customer is redirected to on success. When the page is iframed, success is reported via `postMessage` instead." }, "failureRedirectUrl": { "type": "string", "format": "uri", "description": "URL the customer is redirected to on failure. When the page is iframed, failure is reported via `postMessage` instead." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Arbitrary key/value pairs to attach to the session." }, "expiresAt": { "type": "string", "format": "date-time", "description": "Absolute time the generated link expires. Optional; defaults to the server's configured session expiry (30 days) when omitted. Must be in the future and no more than 30 days ahead." } } } } } }, "responses": { "201": { "description": "Payment session created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentSession" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/entitlements": { "get": { "tags": [ "Entitlements" ], "summary": "List Entitlements", "description": "Retrieve all entitlements for a customer, optionally filtered by feature or product.\n\nList items identify the entitlement with `entitlementId` (the original list contract). The get-by-id endpoint (`GET /v1/entitlements/{entitlementId}`) returns the same object but with a top-level `id` and `object: \"entitlement\"` instead — so use `item.entitlementId`, not `item.id`, when chaining a list result into a get-by-id call.\n\nFor metered entitlements, each item carries live balance/usage fields, which the API resolves with one grant-engine balance lookup per metered item (bounded concurrency, up to `limit` items per page).", "operationId": "listEntitlements", "parameters": [ { "name": "customerId", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/CustomerId" }, "description": "The Paygentic customer id to retrieve entitlements for. Supply exactly one of `customerId` or `externalCustomerId`. When combined with `merchantId`, the customer must belong to that merchant or the request resolves to not found.", "example": "cus_q3r4s5t6u7v8w9x0" }, { "name": "externalCustomerId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "The merchant's own external customer reference (`Customer.externalId`, exact match), used to retrieve entitlements without first resolving it to a `cus_` id. Matches the `externalId` filter on `GET /v1/customers` (plain string, exact match — no pattern constraint, so any stored `externalId` is addressable). Supply exactly one of `customerId` or `externalCustomerId`. `externalId` is unique only within a merchant, so an effective merchant scope is required: either pass `merchantId`, or authenticate with a single-merchant API key. With no resolvable merchant scope the request is rejected.", "example": "ext-customer-123" }, { "name": "merchantId", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "Optional merchant scope. With `externalCustomerId` it selects the merchant the external id is resolved within (required for the platform key, which has no single merchant). With `customerId` it acts as a tenant guard — the resolved customer must belong to this merchant, otherwise the request resolves to not found. A passed `merchantId` is only a filter and never grants access the caller does not already hold; authorization is always evaluated against the resolved customer's merchant.", "example": "org_a1b2c3d4e5f6g7h8" }, { "name": "featureKey", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter results to a specific feature by its key. When specified, `productId` is also required. Use this to check access to a single feature." }, { "name": "productId", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ProductId" }, "description": "Filter results to entitlements for a specific product. Required when `featureKey` is specified since feature keys are scoped to products." }, { "name": "subscriptionId", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/SubscriptionId" }, "description": "Filter results to entitlements for a specific subscription." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "description": "Maximum number of entitlements to return per page. Use with `offset` for pagination." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of entitlements to skip. Use with `limit` for pagination through large result sets." }, { "name": "at", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Evaluate balance and access at this point in time (RFC 3339 datetime with any UTC offset, e.g. 2024-01-15T10:30:00Z or 2024-01-15T15:30:00+05:30). Defaults to current time." } ], "responses": { "200": { "description": "Successfully retrieved the list of entitlements for the customer.", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "pagination" ], "properties": { "object": { "type": "string", "enum": [ "list" ], "default": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/EntitlementListItem" }, "description": "Array of entitlement list items. The shape of each item varies by featureType." }, "pagination": { "$ref": "#/components/schemas/OffsetPagination" } } }, "examples": { "multipleEntitlements": { "summary": "Multiple entitlements with different feature types", "description": "A customer with a Pro plan that includes seat limits (static) and SSO access (boolean).", "value": { "object": "list", "data": [ { "entitlementId": "ent_a7b8c9d0e1f2g3h4", "customerId": "cus_q3r4s5t6u7v8w9x0", "featureId": "feat_max_users", "featureKey": "max_users", "featureType": "static", "productId": "prod_m5n6o7p8q9r0s1t2", "subscriptionId": "sub_pro_plan", "status": "active", "activeFrom": "2024-01-01T00:00:00Z", "activeTo": "2025-01-01T00:00:00Z", "hasAccess": true, "metadata": {}, "config": { "limit": 25 } }, { "entitlementId": "ent_b8c9d0e1f2g3h4i5", "customerId": "cus_q3r4s5t6u7v8w9x0", "featureId": "feat_sso_enabled", "featureKey": "sso_enabled", "featureType": "boolean", "productId": "prod_m5n6o7p8q9r0s1t2", "subscriptionId": "sub_pro_plan", "status": "active", "activeFrom": "2024-01-01T00:00:00Z", "activeTo": null, "hasAccess": true, "metadata": {}, "config": null } ], "pagination": { "limit": 10, "offset": 0, "total": 2 } } }, "staticFeatureWithConfig": { "summary": "Static feature with configuration", "description": "An entitlement for a feature that includes configuration values the customer is entitled to.", "value": { "object": "list", "data": [ { "entitlementId": "ent_d0e1f2g3h4i5j6k7", "customerId": "cus_q3r4s5t6u7v8w9x0", "featureId": "feat_storage_quota", "featureKey": "storage_quota", "featureType": "static", "productId": "prod_storage123456", "subscriptionId": "sub_storage_plan", "status": "active", "activeFrom": "2024-03-15T00:00:00Z", "activeTo": null, "hasAccess": true, "metadata": {}, "config": { "limitGB": 500, "allowedFileTypes": [ "pdf", "doc", "xlsx", "png", "jpg" ] } } ], "pagination": { "limit": 10, "offset": 0, "total": 1 } } }, "expiredEntitlement": { "summary": "Entitlement that is no longer active", "description": "A canceled entitlement where hasAccess is false. This can happen when a subscription is canceled or expires.", "value": { "object": "list", "data": [ { "entitlementId": "ent_e1f2g3h4i5j6k7l8", "customerId": "cus_q3r4s5t6u7v8w9x0", "featureId": "feat_premium_support", "featureKey": "premium_support", "featureType": "boolean", "productId": "prod_support789012", "subscriptionId": null, "status": "expired", "activeFrom": "2023-01-01T00:00:00Z", "activeTo": "2024-01-01T00:00:00Z", "hasAccess": false, "metadata": {}, "config": null } ], "pagination": { "limit": 10, "offset": 0, "total": 1 } } }, "meteredEntitlement": { "summary": "Metered entitlement with cap and live usage", "description": "A usage-based feature with a hard cap (`isSoftLimit: false`) and live balance, usage, and period bounds from the grant engine.", "value": { "object": "list", "data": [ { "entitlementId": "ent_c9d0e1f2g3h4i5j6", "customerId": "cus_q3r4s5t6u7v8w9x0", "featureId": "feat_api_calls", "featureKey": "api_calls", "featureType": "metered", "productId": "prod_m5n6o7p8q9r0s1t2", "subscriptionId": "sub_pro_plan", "status": "active", "activeFrom": "2024-03-01T00:00:00Z", "activeTo": null, "hasAccess": true, "metadata": {}, "config": null, "isSoftLimit": false, "balance": 8340, "usageInPeriod": 1660, "overage": 0, "currentPeriodStart": "2024-03-01T00:00:00Z", "currentPeriodEnd": "2024-04-01T00:00:00Z", "pricingUnitId": null } ], "pagination": { "limit": 10, "offset": 0, "total": 1 } } }, "emptyResult": { "summary": "No entitlements found", "description": "Response when a customer has no entitlements, or no entitlements match the filter criteria.", "value": { "object": "list", "data": [], "pagination": { "limit": 10, "offset": 0, "total": 0 } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "tags": [ "Entitlements" ], "summary": "Issue Entitlement", "description": "Issue a new entitlement to a customer, granting them access to a specific feature. The feature must exist and belong to the same merchant as the customer.", "operationId": "issueEntitlement", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssueEntitlementRequest" }, "examples": { "booleanEntitlement": { "summary": "Issue a boolean feature entitlement", "description": "Grant access to a simple on/off feature like SSO.", "value": { "customerId": "cus_q3r4s5t6u7v8w9x0", "featureId": "feat_a1b2c3d4e5f6g7h8", "template": { "type": "boolean" } } }, "staticEntitlement": { "summary": "Issue a static feature entitlement with config", "description": "Grant access to a feature with configuration values like seat limits.", "value": { "customerId": "cus_q3r4s5t6u7v8w9x0", "featureId": "feat_a1b2c3d4e5f6g7h8", "template": { "type": "static", "config": { "limit": 25, "tier": "pro" } } } }, "timedEntitlement": { "summary": "Issue a time-limited entitlement", "description": "Grant access to a feature with specific start and end dates.", "value": { "customerId": "cus_q3r4s5t6u7v8w9x0", "featureId": "feat_a1b2c3d4e5f6g7h8", "template": { "type": "boolean" }, "activeFrom": "2024-01-01T00:00:00Z", "activeTo": "2025-01-01T00:00:00Z" } } } } } }, "responses": { "201": { "description": "Entitlement successfully issued. Returns the same shape as `GET /v1/entitlements/{entitlementId}` (a discriminated `EntitlementDetail`), so callers can read `featureType`, `hasAccess`, and metered balance/usage fields directly from the create response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntitlementDetail" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/entitlements/{entitlementId}": { "parameters": [ { "name": "entitlementId", "in": "path", "required": true, "description": "The unique identifier of the entitlement", "schema": { "type": "string", "pattern": "^ent_[a-zA-Z0-9]+$" } } ], "get": { "tags": [ "Entitlements" ], "summary": "Get Entitlement", "description": "Retrieve a specific entitlement by ID. For metered entitlements, the response includes live balance, usage, and access status for the current billing period.", "operationId": "getEntitlement", "parameters": [ { "name": "entitlementId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ent_[a-zA-Z0-9]+$" }, "description": "The unique identifier of the entitlement." }, { "name": "at", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Evaluate balance and access at this point in time (RFC 3339 datetime with any UTC offset, e.g. 2024-01-15T10:30:00Z or 2024-01-15T15:30:00+05:30). Defaults to current time." } ], "responses": { "200": { "description": "Successfully retrieved the entitlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntitlementDetail" }, "examples": { "booleanEntitlement": { "summary": "Boolean entitlement", "value": { "object": "entitlement", "id": "ent_a7b8c9d0e1f2g3h4", "customerId": "cus_x1y2z3a4b5c6d7e8", "featureId": "feat_p1q2r3s4t5u6v7w8", "featureKey": "sso_enabled", "featureType": "boolean", "productId": "prod_m5n6o7p8q9r0s1t2", "subscriptionId": "sub_m1n2o3p4q5r6s7t8", "status": "active", "hasAccess": true, "activeFrom": "2024-01-01T00:00:00Z", "activeTo": null, "config": null, "metadata": {} } }, "staticEntitlement": { "summary": "Static entitlement", "value": { "object": "entitlement", "id": "ent_b8c9d0e1f2g3h4i5", "customerId": "cus_x1y2z3a4b5c6d7e8", "featureId": "feat_q2r3s4t5u6v7w8x9", "featureKey": "storage_limit", "featureType": "static", "productId": "prod_m5n6o7p8q9r0s1t2", "subscriptionId": "sub_m1n2o3p4q5r6s7t8", "status": "active", "hasAccess": true, "activeFrom": "2024-01-01T00:00:00Z", "activeTo": null, "config": { "limitGB": 500, "allowedFileTypes": [ "pdf", "doc", "png" ] }, "metadata": {} } }, "meteredEntitlement": { "summary": "Metered entitlement with balance", "value": { "object": "entitlement", "id": "ent_c9d0e1f2g3h4i5j6", "customerId": "cus_x1y2z3a4b5c6d7e8", "featureId": "feat_r3s4t5u6v7w8x9y0", "featureKey": "api_calls", "featureType": "metered", "productId": "prod_m5n6o7p8q9r0s1t2", "subscriptionId": "sub_m1n2o3p4q5r6s7t8", "status": "active", "hasAccess": true, "activeFrom": "2024-01-01T00:00:00Z", "activeTo": null, "config": null, "isSoftLimit": false, "balance": 8340, "usageInPeriod": 1660, "overage": 0, "currentPeriodStart": "2024-03-01T00:00:00Z", "currentPeriodEnd": "2024-04-01T00:00:00Z", "pricingUnitId": null, "metadata": {} } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/entitlements/{entitlementId}/grants": { "parameters": [ { "name": "entitlementId", "in": "path", "required": true, "description": "The unique identifier of the entitlement", "schema": { "type": "string", "pattern": "^ent_[a-zA-Z0-9]+$" } } ], "get": { "tags": [ "Grants" ], "summary": "List Grants", "description": "List grants for a metered entitlement. Active grants are returned by default; pass `includeVoided=true` to include voided grants.", "operationId": "listEntitlementGrants", "parameters": [ { "name": "entitlementId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ent_[a-zA-Z0-9]+$" }, "description": "The unique identifier of the entitlement." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Maximum number of grants to return per page." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of grants to skip." }, { "name": "includeVoided", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "When true, voided grants are included in the response." } ], "responses": { "200": { "description": "Successfully retrieved the list of grants.", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "pagination" ], "properties": { "object": { "type": "string", "enum": [ "list" ], "default": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Grant" } }, "pagination": { "$ref": "#/components/schemas/OffsetPagination" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "tags": [ "Grants" ], "summary": "Create Grant", "description": "Create a grant directly for a metered entitlement, crediting the customer's balance immediately. The entitlement must belong to an active v1 subscription.", "operationId": "createEntitlementGrant", "parameters": [ { "name": "entitlementId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ent_[a-zA-Z0-9]+$" }, "description": "The unique identifier of the entitlement to grant credits to." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateGrantRequest" }, "examples": { "minimal": { "summary": "Minimal grant", "description": "Create a grant with an amount and idempotency key. Effective immediately, no expiration.", "value": { "amount": 100, "idempotencyKey": "grant-initial-100" } }, "withExpiry": { "summary": "Grant with expiry and idempotency key", "description": "Create a grant that expires after one month, with an idempotency key for safe retries.", "value": { "amount": 500, "effectiveAt": "2026-03-14T00:00:00Z", "expiresAt": "2026-04-14T00:00:00Z", "idempotencyKey": "grant-march-2026-promo" } } } } } }, "responses": { "201": { "description": "Grant successfully created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Grant" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/entitlements/{entitlementId}/grants/purchase": { "parameters": [ { "name": "entitlementId", "in": "path", "required": true, "description": "The unique identifier of the entitlement", "schema": { "type": "string", "pattern": "^ent_[a-zA-Z0-9]+$" } } ], "post": { "tags": [ "Grants" ], "summary": "Purchase Grant", "description": "Create an ad-hoc invoice with a payment session for a grant purchase. The customer pays via the returned payment URL; the grant is created automatically on payment completion. If payment expires, the invoice is cancelled and no grant is created.\n\nTo confirm payment completion, subscribe to the `invoice.paid.v0` webhook. The payload includes the original `invoiceId` and the created `grantId`, so you can correlate the purchase response with downstream fulfilment without an extra fetch. As a fallback if you cannot consume webhooks, poll `GET /v2/invoices/{invoiceId}` (interval 2s, timeout 60s) and check for `status === \"PAID\"`.", "operationId": "purchaseEntitlementGrant", "parameters": [ { "name": "entitlementId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ent_[a-zA-Z0-9]+$" }, "description": "The unique identifier of the entitlement to purchase credits for." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseGrantRequest" }, "examples": { "basic": { "summary": "Basic grant purchase", "description": "Purchase 1000 credits for $5.00 with a unique idempotency key.", "value": { "amount": 1000, "price": "5.00", "idempotencyKey": "purchase-march-2026-topup" } }, "withOptions": { "summary": "Grant purchase with all options", "description": "Purchase with redirect URLs, payment expiry, and grant expiration.", "value": { "amount": 500, "price": "2.50", "idempotencyKey": "purchase-promo-500", "effectiveAt": "2026-03-14T00:00:00Z", "expiresAt": "2026-04-14T00:00:00Z", "successUrl": "https://example.com/success", "cancelUrl": "https://example.com/cancel", "paymentExpiresAt": "2026-03-15T00:00:00Z" } } } } } }, "responses": { "201": { "description": "Grant purchase invoice created with payment session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseGrantResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/entitlements/{entitlementId}/grants/{grantId}": { "parameters": [ { "name": "entitlementId", "in": "path", "required": true, "description": "The unique identifier of the entitlement", "schema": { "type": "string", "pattern": "^ent_[a-zA-Z0-9]+$" } }, { "name": "grantId", "in": "path", "required": true, "description": "The unique identifier of the grant", "schema": { "type": "string" } } ], "get": { "tags": [ "Grants" ], "summary": "Get Grant", "description": "Retrieve a specific grant by ID.", "operationId": "getEntitlementGrant", "parameters": [ { "name": "entitlementId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ent_[a-zA-Z0-9]+$" }, "description": "The unique identifier of the entitlement." }, { "name": "grantId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^grt_[a-zA-Z0-9]+$" }, "description": "The unique identifier of the grant." } ], "responses": { "200": { "description": "Successfully retrieved the grant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Grant" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "tags": [ "Grants" ], "summary": "Void Grant", "description": "Void a grant, removing it from the customer's balance. This operation is idempotent — voiding an already-voided grant returns the voided grant without error.", "operationId": "voidEntitlementGrant", "parameters": [ { "name": "entitlementId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ent_[a-zA-Z0-9]+$" }, "description": "The unique identifier of the entitlement." }, { "name": "grantId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^grt_[a-zA-Z0-9]+$" }, "description": "The unique identifier of the grant to void." } ], "responses": { "200": { "description": "Grant successfully voided (or already voided).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Grant" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v0/features": { "get": { "tags": [ "Features" ], "summary": "List", "description": "List features by productId, optionally filtered by key", "operationId": "listFeatures", "parameters": [ { "name": "productId", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/ProductId" }, "description": "The product ID to filter features by" }, { "name": "key", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "description": "Optional feature key to filter by. If provided, returns only the feature matching both productId and key" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "description": "Number of features to return." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of features to skip." } ], "responses": { "200": { "description": "List of features", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Feature" } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "description": "Number of items requested" }, "offset": { "type": "integer", "description": "Number of items skipped" }, "total": { "type": "integer", "description": "Total number of items matching the query" } }, "required": [ "limit", "offset", "total" ] } }, "required": [ "object", "data", "pagination" ] }, "example": { "object": "list", "data": [ { "id": "feat_x1y2z3a4b5c6d7e8", "object": "feature", "key": "api-calls", "name": "API Calls", "type": "metered", "merchantId": "org_f9g0h1i2j3k4l5m6", "productId": "prod_a1b2c3d4e5f6g7h8", "metadata": { "unit": "requests" }, "createdAt": "2024-01-08T12:00:00.000Z", "updatedAt": "2024-01-08T12:00:00.000Z" } ], "pagination": { "limit": 10, "offset": 0, "total": 1 } } } } }, "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" } } }, "post": { "tags": [ "Features" ], "summary": "Create", "operationId": "createFeature", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "key", "name", "merchantId", "productId" ], "properties": { "key": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "description": "Unique slug identifier for the feature within the product. Must be lowercase letters, numbers, and hyphens only." }, "name": { "type": "string", "description": "Human-readable feature name shown to customers." }, "type": { "type": "string", "enum": [ "metered", "static", "boolean" ], "default": "boolean", "description": "Feature type: 'metered' for usage-based features, 'static' for fixed allocations, 'boolean' for on/off features" }, "merchantId": { "$ref": "#/components/schemas/OrganizationId", "description": "The merchant organization that owns this feature" }, "productId": { "$ref": "#/components/schemas/ProductId", "description": "The product this feature belongs to" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Optional key-value metadata storage for feature information." } } } } } }, "responses": { "201": { "description": "Feature created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Feature" }, "example": { "id": "feat_x1y2z3a4b5c6d7e8", "object": "feature", "key": "api-calls", "name": "API Calls", "type": "metered", "merchantId": "org_f9g0h1i2j3k4l5m6", "productId": "prod_a1b2c3d4e5f6g7h8", "metadata": { "unit": "requests", "display_order": "1" }, "createdAt": "2024-01-08T12:00:00.000Z", "updatedAt": "2024-01-08T12:00:00.000Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v0/features/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique identifier of the feature", "schema": { "$ref": "#/components/schemas/FeatureId" } } ], "get": { "tags": [ "Features" ], "summary": "Get", "operationId": "getFeature", "responses": { "200": { "description": "Feature details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Feature" }, "example": { "id": "feat_x1y2z3a4b5c6d7e8", "object": "feature", "key": "storage-gb", "name": "Storage (GB)", "type": "metered", "merchantId": "org_f9g0h1i2j3k4l5m6", "productId": "prod_a1b2c3d4e5f6g7h8", "metadata": { "unit": "gigabytes", "category": "storage" }, "createdAt": "2024-01-08T12:00:00.000Z", "updatedAt": "2024-01-08T12:00:00.000Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "patch": { "tags": [ "Features" ], "summary": "Update", "operationId": "updateFeature", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "description": "Updated feature key slug. Sample values: 'increased-api-limit', 'new-storage-tier'" }, "name": { "type": "string", "description": "Updated feature name." }, "type": { "type": "string", "enum": [ "metered", "static", "boolean" ], "description": "Updated feature type" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Updated metadata for the feature" } } } } } }, "responses": { "200": { "description": "Feature updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Feature" }, "example": { "id": "feat_x1y2z3a4b5c6d7e8", "object": "feature", "key": "updated-api-calls", "name": "Updated API Calls", "type": "metered", "merchantId": "org_f9g0h1i2j3k4l5m6", "productId": "prod_a1b2c3d4e5f6g7h8", "metadata": { "unit": "requests", "updated": "true" }, "createdAt": "2024-01-08T12:00:00.000Z", "updatedAt": "2024-01-08T12:30:00.000Z" } } } }, "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" } } }, "delete": { "tags": [ "Features" ], "summary": "Delete", "operationId": "deleteFeature", "responses": { "204": { "description": "Feature deleted successfully" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v0/fees": { "post": { "tags": [ "Fees" ], "summary": "Create", "description": "Create a new fee for a merchant organization. A `Fee` represents a charge that can be applied to subscriptions. Cadence is defined when creating a Price for the fee.", "operationId": "createFee", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "description", "merchantId", "productId" ], "properties": { "name": { "type": "string", "description": "Human-readable label identifying the fee. Sample values: 'Setup Fee', 'Monthly Subscription', 'Compliance Update', 'Annual License'" }, "description": { "type": "string", "description": "Explanatory text describing what the fee represents. Sample values: 'One-time setup fee for new customers', 'Monthly base subscription charge', 'Yearly compliance and security update fee'" }, "merchantId": { "$ref": "#/components/schemas/OrganizationId", "description": "The unique identifier of the merchant organization associated with the fee." }, "productId": { "$ref": "#/components/schemas/ProductId", "description": "The unique identifier of the product associated with the fee." } } } } } }, "responses": { "201": { "description": "Fee created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fee" }, "example": { "id": "fee_w9x0y1z2a3b4c5d6", "object": "fee", "createdAt": "2024-01-15T10:30:00Z", "description": "One-time setup fee for new customers", "merchantId": "org_e7f8g9h0i1j2k3l4", "name": "Setup Fee", "productId": "prod_m5n6o7p8q9r0s1t2", "updatedAt": "2024-01-15T10:30:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "get": { "tags": [ "Fees" ], "summary": "List", "operationId": "listFees", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "description": "Number of fees to return." }, { "name": "merchantId", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "Filter fees by merchant organization ID." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of fees to skip." }, { "name": "productId", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ProductId" }, "description": "Filter fees by product ID." } ], "responses": { "200": { "description": "List of fees", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "pagination" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Fee" } }, "pagination": { "type": "object", "required": [ "limit", "offset", "total" ], "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer" } } } } }, "example": { "object": "list", "data": [ { "id": "fee_w9x0y1z2a3b4c5d6", "object": "fee", "createdAt": "2024-01-15T10:30:00Z", "description": "One-time setup fee for new customers", "merchantId": "org_e7f8g9h0i1j2k3l4", "name": "Setup Fee", "productId": "prod_m5n6o7p8q9r0s1t2", "updatedAt": "2024-01-15T10:30:00Z" }, { "id": "fee_a1b2c3d4e5f6g7h8", "object": "fee", "createdAt": "2024-02-01T14:45:30Z", "description": "Monthly base subscription charge", "merchantId": "org_e7f8g9h0i1j2k3l4", "name": "Monthly Subscription", "productId": "prod_m5n6o7p8q9r0s1t2", "updatedAt": "2024-02-15T09:20:00Z" } ], "pagination": { "limit": 10, "offset": 0, "total": 2 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v0/fees/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique identifier of the fee", "schema": { "$ref": "#/components/schemas/FeeId" } } ], "get": { "tags": [ "Fees" ], "summary": "Get", "operationId": "getFee", "responses": { "200": { "description": "Fee details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fee" }, "example": { "id": "fee_u3v4w5x6y7z8a9b0", "object": "fee", "createdAt": "2024-02-01T14:45:30Z", "description": "Yearly compliance and security update fee", "merchantId": "org_c1d2e3f4g5h6i7j8", "name": "Compliance Update", "productId": "prod_k9l0m1n2o3p4q5r6", "updatedAt": "2024-02-15T09:20:00Z" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "patch": { "tags": [ "Fees" ], "summary": "Update", "operationId": "updateFee", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "type": "string", "description": "Revised explanation of what the fee represents." }, "name": { "type": "string", "description": "Updated label for the fee." } } } } } }, "responses": { "200": { "description": "Fee updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fee" }, "example": { "id": "fee_u3v4w5x6y7z8a9b0", "object": "fee", "createdAt": "2024-02-01T14:45:30Z", "description": "Updated yearly compliance fee", "merchantId": "org_c1d2e3f4g5h6i7j8", "name": "Compliance Update", "productId": "prod_k9l0m1n2o3p4q5r6", "updatedAt": "2024-03-15T11:30:00Z" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "tags": [ "Fees" ], "summary": "Delete", "operationId": "deleteFee", "responses": { "204": { "description": "Fee deleted successfully" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Fee cannot be deleted because it has associated prices", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "properties": { "blockers": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "count": { "type": "integer" } } } } } } } } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v0/plans": { "post": { "tags": [ "Plans" ], "summary": "Create", "operationId": "createPlan", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "merchantId", "currency", "productId" ], "properties": { "billingCadence": { "type": "string", "enum": [ "P1M", "P3M", "P1Y" ], "description": "ISO 8601 duration for the billing period. Takes precedence over billingInterval when both are provided." }, "billingInterval": { "type": "string", "enum": [ "monthly", "quarterly", "yearly", "annual" ], "description": "Recurring billing period frequency. Sample values: 'monthly' for monthly billing, 'quarterly' for quarterly billing, 'yearly' for annual billing" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "pattern": "^[A-Z]{3}$", "description": "Three-letter ISO 4217 currency code for plan pricing. Must be one of the merchant's supported currencies. Sample values: 'USD' for US dollars, 'EUR' for euros, 'GBP' for British pounds" }, "defaultTaxCode": { "type": "string", "description": "Default tax code for plan line items. Common values: 'eservice' (electronically supplied services), 'saas' (software as a service), 'consulting', 'ebook', 'standard', 'reduced', 'exempt'. Full list available via GET /tax/codes endpoint.", "default": "eservice" }, "defaultTaxRate": { "type": "number", "description": "Fallback tax rate percentage when automatic tax calculation fails. Sample values: 8.5 represents 8.5% tax, 10.0 represents 10% tax, 0 represents no tax", "default": 0 }, "description": { "type": "string", "description": "Plan details explaining included features and limits. Sample values: 'Claude API access with 500K tokens monthly allowance', 'Unlimited cloud storage plus real-time analytics tools', 'Complete machine learning infrastructure with GPU access', 'Flexible usage-based pricing with no monthly commitment'" }, "invoiceDisplayName": { "type": "string", "description": "Plan name shown on billing statements. Sample values: 'LLM API Basic Plan', 'Data Warehouse Business', 'ML Platform Enterprise', 'Pay-Per-Use Model'" }, "merchantId": { "$ref": "#/components/schemas/OrganizationId", "description": "The merchant organization that will own this plan" }, "name": { "type": "string", "description": "Plan identifier visible to customers. Sample values: 'Basic Tier', 'Business Package', 'Enterprise Solution', 'Metered Billing', 'Free Tier', 'Premium Access'" }, "prices": { "type": "array", "items": { "$ref": "#/components/schemas/schemas-PriceId" }, "description": "Array of price IDs to associate with this plan" }, "productId": { "$ref": "#/components/schemas/ProductId", "description": "The product this plan belongs to" }, "taxBehavior": { "type": "string", "enum": [ "exclusive", "inclusive" ], "description": "Whether tax is added on top of the price (exclusive) or included in the price (inclusive)", "default": "exclusive" }, "renewalReminderEnabled": { "type": "boolean", "description": "Whether to send renewal reminder emails to customers before their subscription renews", "default": true }, "renewalReminderDays": { "type": "integer", "description": "Number of days before renewal to send the reminder email", "minimum": 1, "maximum": 30, "default": 3 }, "billingVersion": { "type": "integer", "enum": [ 0, 1 ], "default": 1, "description": "Billing engine version. Only 1 (Standard, line-item billing with metered usage support) is accepted for new plans; omitting the field defaults to 1. 0 (Legacy, fee-schedule billing) is rejected — it exists only on plans created before this restriction." }, "billingAnchor": { "type": "string", "format": "date-time", "nullable": true, "description": "ISO 8601 datetime reference point for billing period alignment. Must be in the past or present. When set, subscriptions created under this plan align their first billing period to the next recurrence of this anchor." }, "creditAllocations": { "type": "array", "items": { "$ref": "#/components/schemas/PlanCreditAllocation" }, "description": "Credit-pool funding declarations for this plan. Each entry funds a distinct pricing unit's credit pool when a subscription to this plan activates: the allocated amount is minted as a credit grant on the customer's pool for that pricing unit, once at activation, or on a recurring basis only when that allocation explicitly sets recurrencePeriod. A plan may declare zero or more allocations; no two allocations on the same plan may target the same pricingUnitId." }, "stablePriceIds": { "type": "boolean", "default": true, "description": "Governs price identity when a price on this plan's default version is replaced. When true (default), replacing a price at make-default keeps the original price id live (its value changes) and the superseded value is preserved under a new id. When false, the replacement price's id goes live instead and the superseded value stays under the original id." } } } } } }, "responses": { "201": { "description": "Plan created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" }, "example": { "id": "plan_t9u0v1w2x3y4z5a6", "object": "plan", "billingCadence": "P1M", "billingInterval": "monthly", "createdAt": "2024-01-12T10:00:00Z", "currency": "USD", "defaultTaxCode": "eservice", "defaultTaxRate": 8.5, "description": "Claude API access with 500K tokens monthly allowance", "invoiceDisplayName": "LLM API Basic Plan", "merchantId": "org_b7c8d9e0f1g2h3i4", "name": "Basic Tier", "prices": [ "price_r3s4t5u6v7w8x9y0" ], "productId": "prod_j5k6l7m8n9o0p1q2", "taxBehavior": "exclusive", "updatedAt": "2024-01-12T10:00:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "get": { "tags": [ "Plans" ], "summary": "List", "operationId": "listPlans", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "description": "Number of plans to return" }, { "name": "merchantId", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "Filter plans by merchant organization ID" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of plans to skip" }, { "name": "productId", "in": "query", "schema": { "$ref": "#/components/schemas/ProductId" }, "description": "Filter plans by product ID" } ], "responses": { "200": { "description": "List of plans", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Plan" } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer" } } } } }, "example": { "data": [ { "id": "plan_t9u0v1w2x3y4z5a6", "object": "plan", "billingCadence": "P1M", "billingInterval": "monthly", "createdAt": "2024-01-12T10:00:00Z", "currency": "USD", "defaultTaxCode": "eservice", "defaultTaxRate": 8.5, "description": "Claude API access with 500K tokens monthly allowance", "invoiceDisplayName": "LLM API Basic Plan", "merchantId": "org_b7c8d9e0f1g2h3i4", "name": "Basic Tier", "prices": [ { "id": "price_r3s4t5u6v7w8x9y0", "object": "price", "billableMetricId": "bm_y1z2a3b4c5d6e7f8", "createdAt": "2024-01-12T10:00:00Z", "invoiceDisplayName": "Token Usage", "model": "standard", "paymentTerm": "in_arrears", "updatedAt": "2024-01-12T10:00:00Z" } ], "productId": "prod_j5k6l7m8n9o0p1q2", "taxBehavior": "exclusive", "updatedAt": "2024-01-12T10:00:00Z" }, { "id": "plan_z1a2b3c4d5e6f7g8", "object": "plan", "billingCadence": "P1M", "billingInterval": "monthly", "createdAt": "2024-02-15T12:30:00Z", "currency": "USD", "defaultTaxCode": "eservice", "defaultTaxRate": 10, "description": "Unlimited cloud storage plus real-time analytics tools", "invoiceDisplayName": "Data Warehouse Business", "merchantId": "org_h9i0j1k2l3m4n5o6", "name": "Business Package", "prices": [ { "id": "price_x5y6z7a8b9c0d1e2", "object": "price", "billableMetricId": "bm_a1b2c3d4e5f6g7h8", "createdAt": "2024-02-15T12:30:00Z", "invoiceDisplayName": "Storage Usage", "model": "volume", "paymentTerm": "in_arrears", "updatedAt": "2024-02-20T10:15:00Z" } ], "productId": "prod_p7q8r9s0t1u2v3w4", "taxBehavior": "exclusive", "updatedAt": "2024-02-20T10:15:00Z" } ], "pagination": { "limit": 10, "offset": 0, "total": 2 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v0/plans/available": { "get": { "tags": [ "Plans" ], "summary": "List Available Plans", "description": "Retrieves all plans for a merchant that the customer does not have an active or pending subscription for. When a customer has a subscription for any plan within a product, all plans from that product are excluded.", "operationId": "listAvailablePlans", "parameters": [ { "name": "customerId", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/CustomerId" }, "description": "The customer to check subscriptions for. The merchant is derived from the customer record." }, { "name": "productId", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ProductId" }, "description": "Optional filter by product ID" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional search text to filter plan names (case-insensitive)" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "description": "Number of plans to return" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of plans to skip" } ], "responses": { "200": { "description": "List of available plans", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Plan" } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer" } } } } }, "example": { "data": [ { "id": "plan_t9u0v1w2x3y4z5a6", "object": "plan", "billingCadence": "P1M", "billingInterval": "monthly", "createdAt": "2024-01-12T10:00:00Z", "currency": "USD", "defaultTaxCode": "eservice", "defaultTaxRate": 8.5, "description": "Claude API access with 500K tokens monthly allowance", "invoiceDisplayName": "LLM API Basic Plan", "merchantId": "org_b7c8d9e0f1g2h3i4", "name": "Basic Tier", "prices": [], "productId": "prod_j5k6l7m8n9o0p1q2", "taxBehavior": "exclusive", "updatedAt": "2024-01-12T10:00:00Z" } ], "pagination": { "limit": 10, "offset": 0, "total": 1 } } } } }, "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" } } } }, "/v0/plans/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique identifier of the plan", "schema": { "$ref": "#/components/schemas/PlanId" } } ], "get": { "tags": [ "Plans" ], "summary": "Get", "operationId": "getPlan", "responses": { "200": { "description": "Plan details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" }, "example": { "id": "plan_z1a2b3c4d5e6f7g8", "object": "plan", "billingCadence": "P1M", "billingInterval": "monthly", "createdAt": "2024-02-15T12:30:00Z", "currency": "USD", "defaultTaxCode": "eservice", "defaultTaxRate": 10, "description": "Unlimited cloud storage plus real-time analytics tools", "invoiceDisplayName": "Data Warehouse Business", "merchantId": "org_h9i0j1k2l3m4n5o6", "name": "Business Package", "prices": [ "price_x5y6z7a8b9c0d1e2" ], "productId": "prod_p7q8r9s0t1u2v3w4", "taxBehavior": "exclusive", "updatedAt": "2024-02-20T10:15:00Z" } } } }, "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" } } }, "patch": { "tags": [ "Plans" ], "summary": "Update", "operationId": "updatePlan", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "billingCadence": { "type": "string", "enum": [ "P1M", "P3M", "P1Y" ], "description": "ISO 8601 duration for the billing period. Takes precedence over billingInterval when both are provided." }, "billingInterval": { "type": "string", "enum": [ "monthly", "quarterly", "yearly", "annual" ], "description": "Recurring billing period frequency. Sample values: 'monthly' for monthly billing, 'quarterly' for quarterly billing, 'yearly' for annual billing" }, "defaultTaxCode": { "type": "string", "description": "Default tax code for plan line items. Common values: 'eservice' (electronically supplied services), 'saas' (software as a service), 'consulting', 'ebook', 'standard', 'reduced', 'exempt'. Full list available via GET /tax/codes endpoint." }, "defaultTaxRate": { "type": "number", "description": "Fallback tax rate (as percentage) if automatic tax calculation is unavailable" }, "description": { "type": "string", "description": "Plan details explaining included features and limits. Sample values: 'Claude API access with 500K tokens monthly allowance', 'Unlimited cloud storage plus real-time analytics tools', 'Complete machine learning infrastructure with GPU access', 'Flexible usage-based pricing with no monthly commitment'" }, "invoiceDisplayName": { "type": "string", "description": "Plan name shown on billing statements. Sample values: 'LLM API Basic Plan', 'Data Warehouse Business', 'ML Platform Enterprise', 'Pay-Per-Use Model'" }, "name": { "type": "string", "description": "Plan identifier visible to customers. Sample values: 'Basic Tier', 'Business Package', 'Enterprise Solution', 'Metered Billing', 'Free Tier', 'Premium Access'" }, "prices": { "type": "array", "items": { "$ref": "#/components/schemas/schemas-PriceId" }, "description": "Array of price IDs to associate with this plan" }, "taxBehavior": { "type": "string", "enum": [ "exclusive", "inclusive" ], "description": "Whether tax is added on top of the price (exclusive) or included in the price (inclusive)" }, "renewalReminderEnabled": { "type": "boolean", "description": "Whether to send renewal reminder emails to customers before their subscription renews" }, "renewalReminderDays": { "type": "integer", "description": "Number of days before renewal to send the reminder email", "minimum": 1, "maximum": 30 }, "billingAnchor": { "type": "string", "format": "date-time", "nullable": true, "description": "ISO 8601 datetime reference point for billing period alignment. Must be in the past or present. Set to null to clear the anchor and revert to start-time-based anchoring." }, "creditAllocations": { "type": "array", "items": { "$ref": "#/components/schemas/PlanCreditAllocation" }, "description": "Credit-pool funding declarations for this plan. Each entry funds a distinct pricing unit's credit pool when a subscription to this plan activates: the allocated amount is minted as a credit grant on the customer's pool for that pricing unit, once at activation, or on a recurring basis only when that allocation explicitly sets recurrencePeriod. A plan may declare zero or more allocations; no two allocations on the same plan may target the same pricingUnitId." }, "stablePriceIds": { "type": "boolean", "description": "Governs price identity when a price on this plan's default version is replaced. When true (default), replacing a price at make-default keeps the original price id live (its value changes) and the superseded value is preserved under a new id. When false, the replacement price's id goes live instead and the superseded value stays under the original id." } } } } } }, "responses": { "200": { "description": "Plan updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" }, "example": { "id": "plan_f3g4h5i6j7k8l9m0", "object": "plan", "billingCadence": "P1Y", "billingInterval": "yearly", "createdAt": "2024-01-20T09:00:00Z", "currency": "USD", "defaultTaxCode": "eservice", "defaultTaxRate": 8.5, "description": "Complete machine learning infrastructure with GPU access", "invoiceDisplayName": "ML Platform Enterprise", "merchantId": "org_n1o2p3q4r5s6t7u8", "name": "Enterprise Solution", "prices": [ "price_d7e8f9g0h1i2j3k4" ], "productId": "prod_v9w0x1y2z3a4b5c6", "taxBehavior": "exclusive", "updatedAt": "2024-03-01T15:30:00Z" } } } }, "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" } } } }, "/v0/plans/{id}/versions": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/PlanId" } } ], "get": { "tags": [ "Plans" ], "summary": "List versions", "description": "List the versions of a plan, newest first. Only accounts that can manage this plan may list its versions; versions can expose in-progress pricing, so read-only access is not sufficient.", "operationId": "listPlanVersions", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "description": "Maximum number of versions to return" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of versions to skip" } ], "responses": { "200": { "description": "List of plan versions", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "pagination" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PlanVersionSummary" } }, "pagination": { "$ref": "#/components/schemas/OffsetPagination" } } } } } }, "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" } } }, "post": { "tags": [ "Plans" ], "summary": "Mint a draft version", "description": "Mint a new plan version in draft status from a price diff. The diff references existing prices by id: create prices beforehand with POST /prices, then add, remove, or replace them here. Minting does not publish the version and does not change which version the plan bills from — publish and set-default are a separate PATCH on the version.", "operationId": "mintPlanVersion", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MintPlanVersionRequest" } } } }, "responses": { "201": { "description": "The newly minted draft version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanVersion" } } } }, "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" } } } }, "/v0/plans/{id}/versions/{versionNumber}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/PlanId" } }, { "name": "versionNumber", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "The version number within the plan (1-based)." } ], "get": { "tags": [ "Plans" ], "summary": "Get a version", "description": "Get a single plan version, including its price slots. Only accounts that can manage this plan may read its versions; versions can expose in-progress pricing, so read-only access is not sufficient.", "operationId": "getPlanVersion", "responses": { "200": { "description": "The requested plan version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanVersion" } } } }, "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" } } }, "delete": { "tags": [ "Plans" ], "summary": "Discard a draft version", "description": "Discard a draft plan version, deleting it and its price slots. Only a draft can be discarded; publishing or archiving supersedes this. Clears the one-open-draft-per-plan limit, so a subsequent mint on this plan succeeds.", "operationId": "discardPlanVersion", "responses": { "204": { "description": "Draft discarded" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "patch": { "tags": [ "Plans" ], "summary": "Transition a version", "description": "Transition a plan version's lifecycle. Set status to published to promote a draft; set default to true to point the plan at this version so its floating subscriptions bill from it. The two are independent — publishing does not change the default. Setting default requires the version to be (or become in the same request) published. Both fields are idempotent.", "operationId": "transitionPlanVersion", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransitionPlanVersionRequest" } } } }, "responses": { "200": { "description": "The transitioned plan version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanVersion" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v0/plans/{id}/versions/{versionNumber}/prices": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/PlanId" } }, { "name": "versionNumber", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "The version number within the plan (1-based)." }, { "name": "If-Match", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional optimistic-concurrency precondition — the draft version's `updatedAt` timestamp as read from a prior GET. If present and it no longer matches the version's current `updatedAt`, the request is rejected with 412 (`draft_modified`). Omit to skip the check." } ], "post": { "tags": [ "Plans" ], "summary": "Add a price to a draft", "description": "Add a single price to a draft version's own current slots. The version must be a draft — editing a published or archived version is rejected.", "operationId": "addDraftVersionPrice", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddDraftVersionPriceRequest" } } } }, "responses": { "201": { "description": "The updated draft version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanVersion" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "patch": { "tags": [ "Plans" ], "summary": "Batch-edit a draft's prices", "description": "Apply a batch add/remove/replace price diff to a draft version's own current slots. The version must be a draft. An empty diff is a no-op.", "operationId": "editDraftVersionPrices", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditDraftVersionPricesRequest" } } } }, "responses": { "200": { "description": "The updated draft version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanVersion" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v0/plans/{id}/versions/{versionNumber}/prices/{priceId}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/PlanId" } }, { "name": "versionNumber", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "The version number within the plan (1-based)." }, { "name": "priceId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/schemas-PriceId" } }, { "name": "If-Match", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional optimistic-concurrency precondition — the draft version's `updatedAt` timestamp as read from a prior GET. If present and it no longer matches the version's current `updatedAt`, the request is rejected with 412 (`draft_modified`). Omit to skip the check." } ], "delete": { "tags": [ "Plans" ], "summary": "Remove a price from a draft", "description": "Remove a single price from a draft version's own current slots. The version must be a draft.", "operationId": "removeDraftVersionPrice", "responses": { "204": { "description": "Price removed from the draft" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "patch": { "tags": [ "Plans" ], "summary": "Replace a price on a draft", "description": "Swap the price at this slot for withPriceId on a draft version, preserving the slot's lineage. The version must be a draft.", "operationId": "replaceDraftVersionPrice", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplaceDraftVersionPriceRequest" } } } }, "responses": { "200": { "description": "The updated draft version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanVersion" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v0/prices": { "post": { "tags": [ "Prices" ], "summary": "Create", "operationId": "createPrice", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "invoiceDisplayName", "paymentTerm", "properties" ], "properties": { "billableMetricId": { "$ref": "#/components/schemas/BillableMetricId", "description": "The unique identifier for the billable metric referred to by this price. Either billableMetricId or feeId must be provided." }, "feeId": { "type": "string", "pattern": "^fee_[a-zA-Z0-9]+$", "description": "The unique identifier for the fee referred to by this price. Either billableMetricId or feeId must be provided." }, "pricingUnitId": { "$ref": "#/components/schemas/PricingUnitId", "description": "Denominate this metered price in a pricing unit (credits) instead of real currency. When set, the price draws down the customer's credit pool for that unit. Only valid on metered prices that carry a metered feature. Omit for a normal currency price." }, "model": { "allOf": [ { "$ref": "#/components/schemas/PriceModelInput" } ], "description": "Pricing calculation model. Required for billable metrics, optional for fees (defaults to 'standard'). Only 'standard' is accepted; for percentage/revenue-share use 'standard' with a unit-price multiplier. Legacy prices using 'dynamic'/'volume'/'percentage' stay readable and billable but cannot be created." }, "invoiceDisplayName": { "type": "string", "description": "Line item label shown on customer invoices. Sample values: 'Claude Token Consumption', 'Storage Usage (GB)', 'Inference API Calls', 'Image Generation Count', 'Training Compute Hours', 'Data Transfer (TB)'" }, "paymentTerm": { "type": "string", "enum": [ "in_arrears", "in_advance" ], "description": "Billing timing preference: 'in_advance' (prepaid — charged upfront or drawn from a prepaid commitment) or 'in_arrears' (charged at period end)." }, "billingCadence": { "type": "string", "description": "ISO 8601 duration for recurring charges (e.g., 'P1M' for monthly, 'P1Y' for yearly) or 'P0D' for one-time charges. Required for fees, optional for billable metrics. Sample values: 'P0D' for one-time, 'P1M' for monthly recurring, 'P1Y' for yearly recurring", "nullable": true }, "properties": { "$ref": "#/components/schemas/PriceProperties" }, "feature": { "$ref": "#/components/schemas/PriceFeatureInput", "description": "Optional feature to associate with this price" }, "grantDiscountEnabled": { "type": "boolean", "default": false, "description": "When true, grants applied to a subscription will discount usage charged by this price. Only supported for standard metered prices." }, "quantity": { "$ref": "#/components/schemas/PriceQuantity", "default": 1 } } } } } }, "responses": { "201": { "description": "Price created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/schemas-Price" }, "example": { "id": "price_l5m6n7o8p9q0r1s2", "object": "price", "billableMetricId": "bm_t3u4v5w6x7y8z9a0", "createdAt": "2024-01-18T11:20:00Z", "currency": "USD", "description": "Per-token pricing for Claude API", "invoiceDisplayName": "Claude Token Consumption", "model": "standard", "paymentTerm": "in_arrears", "properties": { "unitPrice": "0.00002" }, "unitAmount": "20000000", "updatedAt": "2024-01-18T11:20:00Z" } } } }, "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" } } }, "get": { "tags": [ "Prices" ], "summary": "List", "operationId": "listPrices", "parameters": [ { "name": "billableMetricId", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/BillableMetricId" }, "description": "Filter prices by billable metric ID" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "description": "Number of prices to return" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of prices to skip" } ], "responses": { "200": { "description": "List of prices", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/schemas-Price" } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer" } } } } }, "example": { "data": [ { "id": "price_l5m6n7o8p9q0r1s2", "object": "price", "billableMetricId": "bm_t3u4v5w6x7y8z9a0", "createdAt": "2024-01-18T11:20:00Z", "currency": "USD", "description": "Per-token pricing for Claude API", "invoiceDisplayName": "Claude Token Consumption", "model": "standard", "paymentTerm": "in_arrears", "properties": { "unitPrice": "0.00002" }, "unitAmount": "20000000", "updatedAt": "2024-01-18T11:20:00Z" }, { "id": "price_b1c2d3e4f5g6h7i8", "object": "price", "billableMetricId": "bm_j9k0l1m2n3o4p5q6", "createdAt": "2024-02-10T13:45:00Z", "currency": "USD", "description": "Tiered pricing for storage capacity", "invoiceDisplayName": "Storage Usage (GB)", "model": "volume", "paymentTerm": "in_arrears", "properties": { "maxPrice": "0.25", "minPrice": "0.05" }, "unitAmount": "50000000000", "updatedAt": "2024-02-25T09:30:00Z" } ], "pagination": { "limit": 10, "offset": 0, "total": 2 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v0/prices/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique identifier of the price", "schema": { "$ref": "#/components/schemas/PriceId" } } ], "get": { "tags": [ "Prices" ], "summary": "Get", "operationId": "getPrice", "responses": { "200": { "description": "Price details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/schemas-Price" }, "example": { "id": "price_b1c2d3e4f5g6h7i8", "object": "price", "billableMetricId": "bm_j9k0l1m2n3o4p5q6", "createdAt": "2024-02-10T13:45:00Z", "currency": "USD", "description": "Tiered pricing for storage capacity", "invoiceDisplayName": "Storage Usage (GB)", "model": "volume", "paymentTerm": "in_arrears", "properties": { "maxPrice": "0.25", "minPrice": "0.05" }, "unitAmount": "50000000000", "updatedAt": "2024-02-25T09:30:00Z" } } } }, "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" } } }, "patch": { "tags": [ "Prices" ], "summary": "Update", "operationId": "updatePrice", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "billableMetricId": { "$ref": "#/components/schemas/BillableMetricId", "description": "The unique identifier for the billable metric referred to by this price." }, "pricingUnitId": { "oneOf": [ { "$ref": "#/components/schemas/PricingUnitId" }, { "type": "null" } ], "description": "Denominate this metered price in a pricing unit (credits). Set to a pricing unit ID to draw down a credit pool, null to revert to real currency, or omit to leave unchanged." }, "invoiceDisplayName": { "type": "string", "description": "Updated invoice line item label. Sample values: 'LLM Token Usage', 'Storage Charges', 'API Call Fees'" }, "model": { "allOf": [ { "$ref": "#/components/schemas/PriceModelInput" } ], "description": "The pricing model to set. Only 'standard' is accepted. Legacy 'dynamic'/'volume'/'percentage' prices can still be edited (other fields) but cannot be switched to those models. Percentage/revenue-share is expressed via 'standard' with a unit-price multiplier." }, "properties": { "$ref": "#/components/schemas/PriceProperties" }, "paymentTerm": { "type": "string", "enum": [ "in_arrears", "in_advance" ], "description": "Billing timing preference: 'in_advance' (prepaid — charged upfront or drawn from a prepaid commitment) or 'in_arrears' (charged at period end)." }, "billingCadence": { "type": "string", "nullable": true, "description": "ISO 8601 duration for recurring fees (e.g., 'P1M' for monthly, 'P1Y' for yearly, or 'P0D' for one-time)" }, "feature": { "oneOf": [ { "$ref": "#/components/schemas/PriceFeatureInput" }, { "type": "null" } ], "description": "Feature to associate. Set to null to remove existing feature. Omit to leave unchanged." }, "grantDiscountEnabled": { "type": "boolean", "description": "When true, grants applied to a subscription will discount usage charged by this price. Only supported for standard metered prices." }, "quantity": { "$ref": "#/components/schemas/PriceQuantity" } } } } } }, "responses": { "200": { "description": "Price updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/schemas-Price" }, "example": { "id": "price_r7s8t9u0v1w2x3y4", "object": "price", "billableMetricId": "bm_z5a6b7c8d9e0f1g2", "createdAt": "2024-01-25T10:00:00Z", "currency": "USD", "description": "Per-call pricing for ML inference", "invoiceDisplayName": "Inference API Calls", "model": "standard", "paymentTerm": "in_arrears", "properties": { "unitPrice": "0.05" }, "unitAmount": "50000000", "updatedAt": "2024-03-05T14:20:00Z" } } } }, "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" } } }, "delete": { "tags": [ "Prices" ], "summary": "Delete", "operationId": "deletePrice", "responses": { "204": { "description": "Price deleted successfully" }, "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" } } } }, "/v0/products": { "post": { "tags": [ "Products" ], "summary": "Create", "operationId": "createProduct", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "description", "merchantId" ], "properties": { "description": { "type": "string", "description": "Customer-visible product summary explaining capabilities and use cases. Sample values: 'Enterprise access to advanced language models for natural language tasks', 'Scalable data warehousing with real-time query capabilities', 'On-demand AI image generation using diffusion models', 'Distributed computing infrastructure for training deep learning models', 'High-performance vector similarity search database', 'Production-ready speech-to-text conversion service'" }, "merchantId": { "$ref": "#/components/schemas/OrganizationId", "description": "The merchant organization that will own this product" }, "metadata": { "type": "object", "description": "Optional key-value metadata storage for product information. Sample values: {\"category\": \"ai_services\", \"tier\": \"enterprise\"}, {\"region\": \"global\", \"support_level\": \"premium\"}" }, "name": { "type": "string", "description": "Customer-facing product title shown in invoices and dashboards. Sample values: 'Large Language Model Service', 'Cloud Data Warehouse', 'AI Image Creator', 'Neural Network Training Platform', 'Vector Database', 'Speech Recognition API'" } } } } } }, "responses": { "201": { "description": "Product created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" }, "example": { "id": "prod_x1y2z3a4b5c6d7e8", "object": "product", "createdAt": "2024-01-10T08:15:00Z", "description": "Enterprise access to advanced language models for natural language tasks", "merchantId": "org_f9g0h1i2j3k4l5m6", "metadata": { "category": "ai_services", "tier": "enterprise" }, "name": "Large Language Model Service", "updatedAt": "2024-01-10T08:15:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "get": { "tags": [ "Products" ], "summary": "List", "operationId": "listProducts", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "description": "Number of products to return" }, { "name": "merchantId", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "Filter products by merchant organization ID" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of products to skip" } ], "responses": { "200": { "description": "List of products", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "pagination": { "$ref": "#/components/schemas/OffsetPagination" } } }, "example": { "data": [ { "id": "prod_x1y2z3a4b5c6d7e8", "object": "product", "createdAt": "2024-01-10T08:15:00Z", "description": "Enterprise access to advanced language models for natural language tasks", "merchantId": "org_f9g0h1i2j3k4l5m6", "metadata": { "category": "ai_services", "tier": "enterprise" }, "name": "Large Language Model Service", "updatedAt": "2024-01-10T08:15:00Z" }, { "id": "prod_n7o8p9q0r1s2t3u4", "object": "product", "createdAt": "2024-02-20T11:30:00Z", "description": "Scalable data warehousing with real-time query capabilities", "merchantId": "org_v5w6x7y8z9a0b1c2", "metadata": { "region": "global", "support_level": "premium" }, "name": "Cloud Data Warehouse", "updatedAt": "2024-03-05T16:45:00Z" } ], "pagination": { "limit": 10, "offset": 0, "total": 2 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v0/products/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique identifier of the product", "schema": { "$ref": "#/components/schemas/ProductId" } } ], "get": { "tags": [ "Products" ], "summary": "Get", "operationId": "getProduct", "responses": { "200": { "description": "Product details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" }, "example": { "id": "prod_n7o8p9q0r1s2t3u4", "object": "product", "createdAt": "2024-02-20T11:30:00Z", "description": "Scalable data warehousing with real-time query capabilities", "merchantId": "org_v5w6x7y8z9a0b1c2", "metadata": { "region": "global", "support_level": "premium" }, "name": "Cloud Data Warehouse", "updatedAt": "2024-03-05T16:45:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "patch": { "tags": [ "Products" ], "summary": "Update", "operationId": "updateProduct", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "type": "string", "description": "Revised product summary shown to customers. Sample values: 'Language model API access', 'Data processing and analytics service', 'AI-powered content creation platform'" }, "name": { "type": "string", "description": "Updated product title visible to customers. Sample values: 'LLM API Service', 'Data Platform', 'AI Content Generator'" } } } } } }, "responses": { "200": { "description": "Product updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" }, "example": { "id": "prod_d3e4f5g6h7i8j9k0", "object": "product", "createdAt": "2024-01-05T09:00:00Z", "description": "Language model API access", "merchantId": "org_l1m2n3o4p5q6r7s8", "metadata": { "category": "ai_services", "tier": "standard" }, "name": "LLM API Service", "updatedAt": "2024-03-10T14:20:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v0/sources": { "post": { "tags": [ "Sources" ], "summary": "Create", "description": "Create a new source for automated usage event generation from external data sources.", "operationId": "createSource", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "planId", "type", "name" ], "properties": { "config": { "type": "object", "additionalProperties": true, "description": "Configuration specific to the source type. For stripe_revenue, must include ampersandProjectId." }, "description": { "type": "string", "description": "Optional explanation of the source's purpose. Sample values: 'Automated usage tracking from Stripe revenue data', 'Language model token consumption monitoring', 'Data warehouse query tracking', 'Machine learning inference usage collection'" }, "enabled": { "type": "boolean", "default": true, "description": "Whether the source is enabled" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Metadata for the source. For stripe_revenue, must include billableMetricMapping with revenue (billable metric ID)." }, "name": { "type": "string", "description": "Display label for the external data source. Sample values: 'Stripe Revenue Integration', 'LLM Usage Tracker', 'Data Processing Monitor', 'ML Compute Usage Source'" }, "planId": { "$ref": "#/components/schemas/PlanId", "description": "The plan to associate this source with" }, "processingMode": { "type": "string", "enum": [ "automatic", "manual" ], "default": "automatic", "description": "How events are processed - automatic (immediate) or manual (requires approval)" }, "type": { "type": "string", "enum": [ "stripe_revenue" ], "description": "The type of source. Currently only 'stripe_revenue' is supported." } } } } } }, "responses": { "201": { "description": "Source created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Source" }, "example": { "id": "src_x3y4z5a6b7c8d9e0", "config": { "ampersandProjectId": "proj_123456" }, "createdAt": "2024-01-25T12:00:00Z", "description": "Automated usage tracking from Stripe revenue data", "enabled": true, "metadata": { "billableMetricMapping": { "revenue": "bm_n9o0p1q2r3s4t5u6" } }, "name": "Stripe Revenue Integration", "planId": "plan_f1g2h3i4j5k6l7m8", "processingMode": "automatic", "type": "stripe_revenue", "updatedAt": "2024-01-25T12:00:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "get": { "tags": [ "Sources" ], "summary": "List", "operationId": "listSources", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } }, { "name": "merchantId", "in": "query", "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "Filter sources by merchant ID" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "planId", "in": "query", "schema": { "$ref": "#/components/schemas/PlanId" }, "description": "Filter sources by plan ID" } ], "responses": { "200": { "description": "List of sources", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Source" } }, "pagination": { "$ref": "#/components/schemas/OffsetPagination" } } }, "example": { "data": [ { "id": "src_c5d6e7f8g9h0i1j2", "config": { "ampersandProjectId": "proj_567890" }, "createdAt": "2024-02-20T13:15:00Z", "description": "Machine learning inference usage collection", "enabled": true, "metadata": { "billableMetricMapping": { "revenue": "bm_s1t2u3v4w5x6y7z8" } }, "name": "ML Compute Usage Source", "planId": "plan_k3l4m5n6o7p8q9r0", "processingMode": "automatic", "type": "stripe_revenue", "updatedAt": "2024-02-20T13:15:00Z" } ], "pagination": { "limit": 10, "offset": 0, "total": 1 } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v0/sources/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique identifier of the source", "schema": { "$ref": "#/components/schemas/SourceId" } } ], "get": { "tags": [ "Sources" ], "summary": "Get", "operationId": "getSource", "responses": { "200": { "description": "Source details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Source" }, "example": { "id": "src_v7w8x9y0z1a2b3c4", "config": { "ampersandProjectId": "proj_789012" }, "createdAt": "2024-02-15T10:30:00Z", "description": "Language model token consumption monitoring", "enabled": true, "metadata": { "billableMetricMapping": { "revenue": "bm_l3m4n5o6p7q8r9s0" } }, "name": "LLM Usage Tracker", "planId": "plan_d5e6f7g8h9i0j1k2", "processingMode": "manual", "type": "stripe_revenue", "updatedAt": "2024-03-01T14:20:00Z" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "patch": { "tags": [ "Sources" ], "summary": "Update", "operationId": "updateSource", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "config": { "type": "object", "additionalProperties": true, "description": "Configuration specific to the source type" }, "description": { "type": "string", "description": "Description of the source" }, "enabled": { "type": "boolean", "description": "Whether the source is enabled" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Metadata for the source" }, "name": { "type": "string", "description": "Display name for the source" }, "processingMode": { "type": "string", "enum": [ "automatic", "manual" ], "description": "How events are processed - automatic (immediate) or manual (requires approval)" } } } } } }, "responses": { "200": { "description": "Source updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Source" }, "example": { "id": "src_t1u2v3w4x5y6z7a8", "config": { "ampersandProjectId": "proj_345678" }, "createdAt": "2024-01-10T08:00:00Z", "description": "Data warehouse query tracking", "enabled": false, "metadata": { "billableMetricMapping": { "revenue": "bm_j7k8l9m0n1o2p3q4" } }, "name": "Data Processing Monitor", "planId": "plan_b9c0d1e2f3g4h5i6", "processingMode": "automatic", "type": "stripe_revenue", "updatedAt": "2024-03-05T16:45:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v0/sources/{id}/events": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SourceId" } } ], "get": { "tags": [ "Sources" ], "summary": "List Events", "description": "List events for a specific source with optional status filtering", "operationId": "listSourceEvents", "parameters": [ { "name": "customerId", "in": "query", "schema": { "type": "string" }, "description": "Filter events by customer ID" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "processed", "failed", "rejected" ] }, "description": "Filter events by status" }, { "name": "subscriptionId", "in": "query", "schema": { "type": "string" }, "description": "Filter events by subscription ID" } ], "responses": { "200": { "description": "List of source events", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SourceEvent" } }, "pagination": { "$ref": "#/components/schemas/OffsetPagination" } } }, "example": { "data": [ { "id": "sev_a1b2c3d4e5f6g7h8", "createdAt": "2024-03-10T14:30:00Z", "customerId": "cus_q3r4s5t6u7v8w9x0", "errorMessage": null, "externalEventId": "evt_stripe_123456", "processedAt": null, "processedBy": null, "rawData": { "amount": 10000, "currency": "usd", "description": "Stripe revenue event" }, "sourceId": "src_x3y4z5a6b7c8d9e0", "status": "pending", "subscriptionId": "sub_z1a2b3c4d5e6f7g8", "updatedAt": "2024-03-10T14:30:00Z", "usageEventIds": [] }, { "id": "sev_b2c3d4e5f6g7h8i9", "createdAt": "2024-03-10T14:45:00Z", "customerId": "cus_q3r4s5t6u7v8w9x0", "errorMessage": null, "externalEventId": "evt_stripe_789012", "processedAt": "2024-03-10T15:00:00Z", "processedBy": "usr_platform", "rawData": { "amount": 25000, "currency": "usd", "description": "Stripe revenue event" }, "sourceId": "src_x3y4z5a6b7c8d9e0", "status": "processed", "subscriptionId": "sub_z1a2b3c4d5e6f7g8", "updatedAt": "2024-03-10T15:00:00Z", "usageEventIds": [ "usg_y1z2a3b4c5d6e7f8" ] } ], "pagination": { "limit": 10, "offset": 0, "total": 2 } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v0/sources/{id}/events/{eventId}/approve": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SourceId" } }, { "name": "eventId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SourceEventId" } } ], "post": { "tags": [ "Sources" ], "summary": "Approve", "description": "Approve a pending source event to create a usage event", "operationId": "approveSourceEvent", "responses": { "200": { "description": "Event approved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceEvent" }, "example": { "id": "sev_c3d4e5f6g7h8i9j0", "createdAt": "2024-03-10T15:30:00Z", "customerId": "cus_q3r4s5t6u7v8w9x0", "errorMessage": null, "externalEventId": "evt_stripe_345678", "processedAt": "2024-03-10T16:00:00Z", "processedBy": "usr_platform", "rawData": { "amount": 50000, "currency": "usd", "description": "Stripe revenue event" }, "sourceId": "src_x3y4z5a6b7c8d9e0", "status": "processed", "subscriptionId": "sub_z1a2b3c4d5e6f7g8", "updatedAt": "2024-03-10T16:00:00Z", "usageEventIds": [ "usg_a1b2c3d4e5f6g7h8" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v0/sources/{id}/events/{eventId}/reject": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SourceId" } }, { "name": "eventId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SourceEventId" } } ], "post": { "tags": [ "Sources" ], "summary": "Reject", "description": "Reject a pending source event", "operationId": "rejectSourceEvent", "responses": { "200": { "description": "Event rejected successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceEvent" }, "example": { "id": "sev_d4e5f6g7h8i9j0k1", "createdAt": "2024-03-10T16:30:00Z", "customerId": "cus_q3r4s5t6u7v8w9x0", "errorMessage": null, "externalEventId": "evt_stripe_901234", "processedAt": "2024-03-10T17:00:00Z", "processedBy": "usr_merchant", "rawData": { "amount": 15000, "currency": "usd", "description": "Stripe revenue event" }, "sourceId": "src_x3y4z5a6b7c8d9e0", "status": "rejected", "subscriptionId": "sub_z1a2b3c4d5e6f7g8", "updatedAt": "2024-03-10T17:00:00Z", "usageEventIds": [] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v0/sources/{id}/events/bulk-approve": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SourceId" } } ], "post": { "tags": [ "Sources" ], "summary": "Bulk Approve", "description": "Approve multiple pending source events at once", "operationId": "bulkApproveSourceEvents", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "eventIds" ], "properties": { "eventIds": { "type": "array", "items": { "$ref": "#/components/schemas/SourceEventId" }, "description": "IDs of events to approve" } } } } } }, "responses": { "200": { "description": "Bulk approval results", "content": { "application/json": { "schema": { "type": "object", "properties": { "processed": { "type": "integer", "description": "Number of successfully approved events" }, "failed": { "type": "integer", "description": "Number of events that failed to process" }, "details": { "type": "object", "properties": { "processed": { "type": "array", "items": { "type": "string" }, "description": "IDs of successfully processed events" }, "failed": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "error": { "type": "string" } } }, "description": "Failed events with error messages" } } } } }, "example": { "details": { "failed": [], "processed": [ "sev_a1b2c3d4e5f6g7h8", "sev_b2c3d4e5f6g7h8i9" ] }, "failed": 0, "processed": 2 } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v0/sources/{id}/events/bulk-reject": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SourceId" } } ], "post": { "tags": [ "Sources" ], "summary": "Bulk Reject", "description": "Reject multiple pending source events at once", "operationId": "bulkRejectSourceEvents", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "eventIds" ], "properties": { "eventIds": { "type": "array", "items": { "$ref": "#/components/schemas/SourceEventId" }, "description": "IDs of events to reject" } } } } } }, "responses": { "200": { "description": "Bulk rejection results", "content": { "application/json": { "schema": { "type": "object", "properties": { "rejected": { "type": "integer", "description": "Number of rejected events" } } }, "example": { "rejected": 1 } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v0/sourceRules": { "get": { "tags": [ "Sources" ], "summary": "List Rules", "description": "List all auto-acceptance rules for a source. These rules automatically approve pending source events when all conditions are met.", "operationId": "listSourceRules", "parameters": [ { "name": "sourceId", "in": "query", "required": true, "description": "Filter rules by source ID", "schema": { "$ref": "#/components/schemas/SourceId" } } ], "responses": { "200": { "description": "List of rules", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SourceRule" } } } }, "example": { "data": [ { "id": "rule_123456", "conditions": [ { "operator": "domain", "type": "customerEmail", "value": "@trusted.com" } ], "createdAt": "2024-03-01T10:00:00Z", "createdBy": "usr_platform", "description": "Automatically approve events from customers with @trusted.com email domain", "enabled": true, "evaluationCount": 150, "lastEvaluatedAt": "2024-03-10T14:30:00Z", "matchCount": 45, "name": "Auto-approve trusted customers", "order": 0, "sourceId": "src_x3y4z5a6b7c8d9e0", "updatedAt": "2024-03-01T10:00:00Z" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "tags": [ "Sources" ], "summary": "Create Rule", "description": "Create a rule for automatically approving source events. When a pending source event matches ALL conditions in a rule, it will be automatically approved and converted to a usage event. Rules are evaluated in order (lowest order number first), and the first matching rule triggers auto-approval. Maximum 10 rules per source.", "operationId": "createSourceRule", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRuleRequest" } } } }, "responses": { "201": { "description": "Rule created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceRule" }, "example": { "id": "rule_789012", "conditions": [ { "operator": "lessThan", "type": "amount", "value": 100 } ], "createdAt": "2024-03-05T12:00:00Z", "createdBy": "usr_merchant", "description": "Automatically approve events with amount less than $100", "enabled": true, "evaluationCount": 0, "lastEvaluatedAt": null, "matchCount": 0, "name": "Auto-approve small amounts", "order": 1, "sourceId": "src_x3y4z5a6b7c8d9e0", "updatedAt": "2024-03-05T12:00:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v0/sourceRules/{ruleId}": { "get": { "tags": [ "Sources" ], "summary": "Get Rule", "operationId": "getSourceRule", "parameters": [ { "name": "ruleId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Rule details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceRule" }, "example": { "id": "rule_345678", "conditions": [ { "operator": "domain", "type": "customerEmail", "value": "@trusted.com" } ], "createdAt": "2024-03-01T10:00:00Z", "createdBy": "usr_platform", "description": "Automatically approve events from customers with @trusted.com email domain", "enabled": true, "evaluationCount": 200, "lastEvaluatedAt": "2024-03-10T14:30:00Z", "matchCount": 60, "name": "Auto-approve trusted customers", "order": 0, "sourceId": "src_x3y4z5a6b7c8d9e0", "updatedAt": "2024-03-10T14:00:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "patch": { "tags": [ "Sources" ], "summary": "Update Rule", "operationId": "updateSourceRule", "parameters": [ { "name": "ruleId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRuleRequest" } } } }, "responses": { "200": { "description": "Rule updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceRule" }, "example": { "id": "rule_901234", "conditions": [ { "operator": "lessThan", "type": "amount", "value": 100 } ], "createdAt": "2024-03-05T12:00:00Z", "createdBy": "usr_merchant", "description": "Automatically approve events with amount less than $100", "enabled": false, "evaluationCount": 50, "lastEvaluatedAt": "2024-03-10T15:00:00Z", "matchCount": 10, "name": "Auto-approve small amounts", "order": 1, "sourceId": "src_x3y4z5a6b7c8d9e0", "updatedAt": "2024-03-10T16:00:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "tags": [ "Sources" ], "summary": "Delete Rule", "operationId": "deleteSourceRule", "parameters": [ { "name": "ruleId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Rule deleted" }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/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" } } }, "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" } } } }, "/v0/subscriptions/{id}": { "get": { "tags": [ "Subscriptions" ], "summary": "Get", "operationId": "getSubscription", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Subscription details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" }, "example": { "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" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "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" } } } }, "/v0/subscriptions/{id}/portal": { "post": { "tags": [ "Subscriptions" ], "summary": "Generate Portal Link", "description": "Generates a secure, time-limited URL that allows customers to access their subscription data without authentication.", "operationId": "generatePortalLink", "x-rate-limit": { "max": 1, "platformMax": 100, "timeWindow": "1 second", "errorMessage": "Too many portal link generation requests. Please wait before trying again." }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The subscription ID" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "expiresIn": { "type": "string", "format": "duration", "description": "Token lifetime as an ISO 8601 duration. Defaults to PT10M (10 minutes). Maximum is P7D (7 days). Examples: PT10M, PT1H, P1D, P7D." } } } } } }, "responses": { "200": { "description": "Portal link generated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionPortal" }, "example": { "object": "subscriptionPortal", "expiresAt": "2024-03-15T23:59:59Z", "url": "https://portal.paygentic.com/sub/sub_z1a2b3c4d5e6f7g8?token=xyz789abc123def456" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v0/subscriptions/{id}/termination": { "post": { "tags": [ "Subscriptions" ], "summary": "Terminate", "description": "Terminates a subscription with a required reason. This endpoint is for merchant-initiated termination only.", "operationId": "terminateSubscription", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The subscription ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "reason" ], "properties": { "reason": { "type": "string", "description": "Cancellation explanation text. Sample values: 'Customer requested cancellation', 'Payment failure', 'Service migration', 'Contract expiration'", "minLength": 1, "maxLength": 1000 } } } } } }, "responses": { "200": { "description": "Subscription terminated successfully", "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": "terminated", "terminatedAt": "2024-03-15T14:20:00Z", "terminatedBy": "org_f7g8h9i0j1k2l3m4", "terminationReason": "Customer requested cancellation", "updatedAt": "2024-03-15T14:20:00Z", "walletId": "acc_b7c8d9e0f1g2h3i4" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Subscription already terminated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v0/subscriptions/{id}/reconciliations": { "post": { "tags": [ "Subscriptions" ], "summary": "Reconcile Features", "description": "Creates a reconciliation that converges a subscription's feature entitlements to its current plan. Provisions a missing entitlement (and, for metered features, its initial grant) for every plan feature the subscription does not already have; cancels the entitlement and voids the grants of any feature no longer on the plan; then synchronizes the corresponding prices' billing. An already-present feature is left unchanged. Restricted to active subscriptions billed on their plan's line-item schedule.", "operationId": "reconcileSubscriptionFeatures", "x-rate-limit": { "max": 2, "platformMax": 100, "timeWindow": "1 second", "errorMessage": "Too many reconciliation requests. Please wait before trying again." }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The subscription ID" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "dryRun": { "type": "boolean", "description": "Preview the outcome without creating any entitlement, grant, or line item.", "default": false } } } } } }, "responses": { "200": { "description": "The reconciliation did not create a full set of resources: a dry-run preview (nothing is created), a run in which one or more features could not be fully provisioned (billing is withheld until they succeed), or a run whose entitlements provisioned but whose line-item synchronization failed. Safe to retry — re-invoking this operation will not duplicate any entitlements or grants already provisioned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionReconciliation" } } } }, "201": { "description": "Reconciliation applied. Feature entitlements now match the plan — features were added, removed, or left unchanged as needed — and billing was synchronized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionReconciliation" }, "example": { "object": "subscriptionReconciliation", "dryRun": false, "features": { "added": [ { "featureId": "feat_a1b2c3d4e5f6g7h8", "featureKey": "advanced_reporting", "billed": true } ], "skipped": [ { "featureId": "feat_i9j0k1l2m3n4o5p6", "featureKey": "basic_dashboard" } ], "removed": [ { "featureId": "feat_q7r8s9t0u1v2w3x4", "featureKey": "legacy_export" } ], "failed": [] }, "lineItems": { "created": 1, "removed": 1 } } } } }, "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" } } } }, "/v0/users/{id}": { "get": { "tags": [ "Users" ], "summary": "Get", "operationId": "getUser", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/UserId" } } ], "responses": { "200": { "description": "User details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" }, "example": { "id": "usr_e7f8g9h0i1j2k3l4", "object": "user", "address": { "city": "Berlin", "country": "DE", "line1": "789 Innovation Road", "zipCode": "10115" }, "createdAt": "2024-01-20T09:00:00Z", "dateOfBirth": "1985-05-20", "email": "bob@mlinfra.net", "firstName": "Bob", "lastName": "Johnson", "organizations": [ { "id": "org_m5n6o7p8q9r0s1t2", "state": "active" }, { "id": "org_u3v4w5x6y7z8a9b0", "state": "invited" } ], "oryId": "ory_user_def456", "phone": "+49-30-12345678", "type": "INDIVIDUAL", "updatedAt": "2024-03-10T16:00:00Z" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "patch": { "tags": [ "Users" ], "summary": "Update", "operationId": "updateUser", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/UserId" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "address": { "$ref": "#/components/schemas/Address", "description": "The address of the user." }, "dateOfBirth": { "type": "string", "format": "date", "description": "The date of birth of the user." }, "firstName": { "type": "string", "description": "The first name of the user." }, "lastName": { "type": "string", "description": "The last name of the user." }, "phone": { "type": "string", "description": "The phone number of the user." }, "type": { "type": "string", "enum": [ "COMPANY", "INDIVIDUAL" ], "description": "Type of entity the user represents." } } } } } }, "responses": { "200": { "description": "User updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" }, "example": { "id": "usr_c1d2e3f4g5h6i7j8", "object": "user", "address": { "city": "New York", "country": "US", "line1": "321 Corporate Drive", "state": "NY", "zipCode": "10001" }, "createdAt": "2024-01-05T08:00:00Z", "dateOfBirth": null, "email": "alice@techcorp.com", "firstName": "Alice", "lastName": "Williams", "organizations": [ { "id": "org_k9l0m1n2o3p4q5r6", "state": "active" } ], "oryId": "ory_user_ghi789", "phone": "+1-555-987-6543", "type": "COMPANY", "updatedAt": "2024-03-15T11:30:00Z" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v2/invoices": { "get": { "tags": [ "Invoices V2" ], "summary": "List", "description": "List invoices with optional filters. Platform users can use nextActionAt=ready to get invoices ready for processing.", "operationId": "listInvoices", "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 10, "minimum": 1, "maximum": 100 }, "description": "Maximum number of invoices to return" }, { "in": "query", "name": "offset", "schema": { "type": "integer", "default": 0, "minimum": 0, "maximum": 10000 }, "description": "Number of invoices to skip for pagination" }, { "in": "query", "name": "nextActionAt", "schema": { "type": "string", "enum": [ "ready" ] }, "description": "Filter for invoices ready for processing (platform only)" }, { "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "ACTIVE", "CLOSING", "CLOSED", "CALCULATING", "DRAFT", "ISSUED", "PAYMENT_FAILED", "PAID", "CANCELLED", "WRITTEN_OFF", "FAILED" ] }, "description": "Filter invoices by status" }, { "in": "query", "name": "subscriptionId", "schema": { "$ref": "#/components/schemas/SubscriptionId" }, "description": "Filter invoices by subscription ID" }, { "in": "query", "name": "customerId", "schema": { "$ref": "#/components/schemas/CustomerId" }, "description": "Filter invoices by customer ID. Authorizes against the customer's merchant; takes precedence as the merchant source when combined with other filters." }, { "in": "query", "name": "merchantId", "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "Filter invoices by merchant ID" } ], "responses": { "200": { "description": "List of invoices", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" } }, "pagination": { "$ref": "#/components/schemas/OffsetPagination" } }, "required": [ "object", "data", "pagination" ] }, "example": { "object": "list", "data": [ { "id": "inv_b5c6d7e8f9g0h1i2", "autoApprove": true, "billingAnchor": "2024-03-01T00:00:00Z", "billingCadence": "P1M", "gracePeriodEnd": "2024-04-01T23:59:59Z", "grandTotal": "0.00", "invoiceNumber": null, "itemCount": 0, "lineItems": null, "nextActionAt": null, "paidAmount": "0.00", "paymentUrl": null, "pdfUrl": null, "periodEnd": "2024-03-31T23:59:59Z", "periodStart": "2024-03-01T00:00:00Z", "permalink": null, "sequenceNumber": 1, "status": "ACTIVE", "subscriptionId": "sub_j3k4l5m6n7o8p9q0", "subtotal": "0.00", "tax": null, "totalTax": "0.00", "unpaidAmount": "0.00" } ], "pagination": { "limit": 10, "offset": 0, "total": 1 } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v2/invoices/lineItems": { "get": { "tags": [ "Invoices V2" ], "summary": "List Line Items", "description": "List pending and invoiced line items for a subscription from the billing database. Returns exact fee amounts and estimated metered charges.", "operationId": "listLineItems", "parameters": [ { "in": "query", "name": "subscriptionId", "required": false, "schema": { "$ref": "#/components/schemas/SubscriptionId" }, "description": "Filter by subscription ID. At least one of subscriptionId or invoiceId must be provided." }, { "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "pending", "invoiced" ] }, "description": "Filter by line item status. 'pending' returns items not yet on an invoice, 'invoiced' returns items already assigned to an invoice. Omit to return both. Cannot be combined with invoiceId — when filtering by invoice ID all statuses are returned." }, { "in": "query", "name": "invoiceId", "schema": { "type": "string", "pattern": "^inv_[a-zA-Z0-9]+$" }, "description": "Filter by invoice ID. When provided without subscriptionId, returns all line items for that invoice. At least one of subscriptionId or invoiceId must be provided." }, { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 100, "minimum": 1, "maximum": 1000 }, "description": "Maximum number of line items to return" }, { "in": "query", "name": "offset", "schema": { "type": "integer", "default": 0, "minimum": 0, "maximum": 10000 }, "description": "Number of line items to skip for pagination" } ], "responses": { "200": { "description": "Paginated list of line items with summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LineItemsResponse" }, "example": { "object": "list", "data": [ { "id": "li_abc123", "subscriptionId": "sub_xyz789", "priceId": "price_fee_001", "invoiceId": null, "type": "fee", "status": "pending", "displayName": "Monthly Platform Fee", "description": null, "currency": "USD", "periodStart": "2024-01-01T00:00:00.000Z", "periodEnd": "2024-02-01T00:00:00.000Z", "invoiceAt": "2024-01-01T00:00:00.000Z", "calculatedAt": null, "quantity": "1", "unitPrice": "29.99", "meteredQuantity": null, "paymentTerm": "in_advance", "subtotal": "29.99", "total": "29.99", "createdAt": "2024-01-01T00:00:00.000Z", "updatedAt": "2024-01-01T00:00:00.000Z" } ], "totalCount": 1, "summary": { "feeSubtotal": "29.99", "meteredEstimatedSubtotal": "0.00", "currency": "USD" } } } } }, "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" } } }, "post": { "tags": [ "Invoices V2" ], "summary": "Create Manual Line Item", "description": "Create a manual line item for a billing v1 subscription. Manual line items are ad-hoc charges or credits that flow through the same collection pipeline as auto-generated items. Exactly one of subscriptionId or invoiceId must be provided.", "operationId": "createLineItem", "x-rate-limit": { "max": 60, "timeWindow": "1 minute" }, "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string", "maxLength": 255 }, "description": "Optional idempotency key. If provided, duplicate requests with the same key return the previously created item." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateManualLineItemRequest" } } } }, "responses": { "200": { "description": "Idempotent retry — returns previously created item", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LineItem" } } } }, "201": { "description": "Manual line item created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LineItem" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v2/invoices/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique identifier of the invoice", "schema": { "type": "string" } } ], "get": { "tags": [ "Invoices V2" ], "summary": "Get", "description": "Retrieve a single invoice with real-time aggregates (for ACTIVE/CLOSING/CLOSED) or cached aggregates (for finalized invoices). Optionally include line items with expand=lineItems.", "operationId": "getInvoice", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The invoice ID" }, { "in": "query", "name": "expand", "schema": { "type": "string" }, "description": "Comma-separated list of fields to expand. Currently supports: lineItems" }, { "in": "query", "name": "lineItemsLimit", "schema": { "type": "integer", "default": 100, "minimum": 1, "maximum": 1000 }, "description": "Page size for line items when expand=lineItems" }, { "in": "query", "name": "lineItemsPageToken", "schema": { "type": "string" }, "description": "Pagination token for line items when expand=lineItems" } ], "responses": { "200": { "description": "Invoice details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" }, "example": { "id": "inv_r1s2t3u4v5w6x7y8", "autoApprove": true, "billingAnchor": "2024-02-01T00:00:00Z", "billingCadence": "P1M", "gracePeriodEnd": "2024-03-01T23:59:59Z", "grandTotal": "1345.61", "invoiceNumber": "INV-2024-02-001", "itemCount": 15, "lineItems": null, "nextActionAt": null, "paidAmount": "0.00", "paymentUrl": "https://checkout.paygentic.com/invoice/inv_r1s2t3u4v5w6x7y8", "pdfUrl": "https://quaderno.io/invoices/12345.pdf", "periodEnd": "2024-02-29T23:59:59Z", "periodStart": "2024-02-01T00:00:00Z", "permalink": "https://quaderno.io/invoices/12345", "sequenceNumber": 2, "status": "ISSUED", "subscriptionId": "sub_z9a0b1c2d3e4f5g6", "subtotal": "1234.50", "tax": { "actualTax": "111110000000", "adjustmentNeeded": true, "difference": "1110000000", "estimatedTax": "110000000000", "reconciled": true, "reconciledAt": "2024-03-01T10:00:00Z" }, "totalTax": "111.11", "unpaidAmount": "1345.61" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v2/invoices/{id}/lineItems": { "get": { "tags": [ "Invoices V2" ], "summary": "Get Line Items", "description": "Get paginated line items for an invoice", "operationId": "getInvoiceLineItems", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The invoice ID" }, { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 100, "minimum": 1, "maximum": 1000 }, "description": "Maximum number of line items to return" }, { "in": "query", "name": "pageToken", "schema": { "type": "string" }, "description": "Token for pagination to fetch the next page of results" } ], "responses": { "200": { "description": "Paginated list of invoice line items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceLineItemsResponse" }, "example": { "invoiceId": "inv_r1s2t3u4v5w6x7y8", "lineItems": [ { "eventType": "usage", "eventId": "usg_a1b2c3d4e5f6g7h8", "eventSourceId": "bm_l5m6n7o8p9q0r1s2", "invoiceDisplayName": "Claude Token Consumption", "lineItemType": "charge", "meterEventId": "me_x9y0z1a2b3c4d5e6", "metricDescription": "Language model token consumption", "metricName": "Token Usage", "metricUnit": "tokens", "quantity": 2500, "taxRate": 0.085, "totalAmount": "0.05425", "totalPrice": "0.05", "totalTax": "0.00425", "unitPrice": "0.00002" }, { "eventType": "fee", "eventId": "fee_b2c3d4e5f6g7h8i9", "eventSourceId": "fee_h3i4j5k6l7m8n9o0", "invoiceDisplayName": "Platform Fee", "meterEventId": "", "metricDescription": "Monthly platform fee", "metricName": "Platform Fee", "metricUnit": "charge", "quantity": 1, "taxRate": 0.1, "totalAmount": "5.50", "totalPrice": "5.00", "totalTax": "0.50", "unitPrice": "5.00" } ], "nextPageToken": null, "totalCount": 3 } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v2/invoices/{id}/refunds": { "post": { "tags": [ "Invoices V2" ], "summary": "Refund Invoice", "description": "Issue a full refund against a paid invoice by creating a credit note. The invoice stays PAID; the refund is recorded as a child credit note. Accessible to the owning merchant or platform operators. Only works for invoices in PAID status that have not already been refunded. Full refund only — the entire invoice (subtotal + tax) is credited.", "operationId": "createInvoiceRefund", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The invoice ID" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "Optional reason for the refund (recorded on the credit note)" } } } } } }, "responses": { "201": { "description": "Credit note created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceRefund" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "get": { "tags": [ "Invoices V2" ], "summary": "List Invoice Refunds", "description": "List the credit notes (refunds) recorded against an invoice. Accessible to the owning merchant or platform operators.", "operationId": "listInvoiceRefunds", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The invoice ID" } ], "responses": { "200": { "description": "List of refunds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceRefundList" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v2/invoices/{id}/refunds/{refundId}/void": { "post": { "tags": [ "Invoices V2" ], "summary": "Void Invoice Refund", "description": "Void a previously-issued refund (credit note). Reverses the credit note in the tax provider and excludes it from revenue. Accessible to the owning merchant or platform operators.", "operationId": "voidInvoiceRefund", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The invoice ID" }, { "in": "path", "name": "refundId", "required": true, "schema": { "type": "string" }, "description": "The refund (credit note) ID" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "Optional reason for voiding the refund (recorded on the credit note)" } } } } } }, "responses": { "200": { "description": "Refund voided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceRefund" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v0/payments": { "get": { "tags": [ "Payments" ], "summary": "List Payments", "description": "List payments for the authenticated merchant with optional filters.", "operationId": "listPayments", "parameters": [ { "name": "merchantId", "in": "query", "schema": { "type": "string" }, "description": "Merchant organization ID. Required when using an API key that is not scoped to a single merchant." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "processing", "completed", "expired", "cancelled" ] }, "description": "Filter by payment status." }, { "name": "customerId", "in": "query", "schema": { "type": "string" }, "description": "Filter by customer ID." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "description": "Number of payments to return." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of payments to skip." } ], "responses": { "200": { "description": "List of payments", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "pagination" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } }, "pagination": { "$ref": "#/components/schemas/OffsetPagination" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "tags": [ "Payments" ], "summary": "Create Payment", "description": "Create a new payment for collecting a one-off charge. Returns a payment URL that can be shared with the customer.", "operationId": "createPayment", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount", "currency" ], "properties": { "amount": { "type": "string", "description": "Payment amount in decimal format (e.g. '10.50'). Minimum 1.00, maximum 5,000.00. Contact support for higher limits.", "pattern": "^\\d+(\\.\\d{1,2})?$" }, "currency": { "type": "string", "description": "ISO 4217 currency code.", "enum": [ "USD", "EUR", "GBP", "AUD" ] }, "merchantId": { "type": "string", "description": "Merchant organization ID. Required when using an API key that is not scoped to a single merchant." }, "customerId": { "type": "string", "description": "Optional customer ID. Must belong to this merchant." }, "idempotencyKey": { "type": "string", "description": "Client-provided key for safe retries. If a payment with the same key already exists, the existing payment is returned.", "maxLength": 255 }, "reference": { "type": "string", "description": "Merchant-defined reference for this payment (e.g. order ID, invoice number).", "maxLength": 255 }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Arbitrary key-value string pairs to attach to the payment." }, "lineItems": { "type": "array", "maxItems": 100, "description": "Optional breakdown of what the customer is being charged for.", "items": { "type": "object", "required": [ "description", "amount" ], "properties": { "description": { "type": "string", "description": "Line item description." }, "amount": { "type": "string", "description": "Line item amount in decimal format (e.g. '5.00')." }, "quantity": { "type": "integer", "description": "Quantity of this line item. Defaults to 1.", "default": 1, "minimum": 1 } } } }, "successRedirectUrl": { "type": "string", "format": "uri", "description": "URL to redirect the customer to after a successful payment." }, "failureRedirectUrl": { "type": "string", "format": "uri", "description": "URL to redirect the customer to after a failed payment." }, "savePaymentMethod": { "type": "boolean", "description": "Whether to save the customer's payment method for future use. Defaults to false.", "default": false }, "expiresIn": { "type": "string", "format": "duration", "description": "ISO 8601 duration for the payment lifetime. Defaults to P30D (30 days). Maximum is P31D (31 days). Examples: PT1H, P1D, P7D, P30D." } } }, "example": { "amount": "10.50", "currency": "USD", "idempotencyKey": "order_12345", "reference": "Order #12345", "successRedirectUrl": "https://example.com/success", "savePaymentMethod": false, "expiresIn": "P7D", "metadata": { "orderId": "order_12345" } } } } }, "responses": { "200": { "description": "Existing payment returned (idempotency match)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } }, "201": { "description": "Payment created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v0/payments/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Payment session ID", "schema": { "type": "string" } } ], "get": { "tags": [ "Payments" ], "summary": "Get Payment", "description": "Retrieve a single payment by ID.", "operationId": "getPayment", "responses": { "200": { "description": "Payment details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v0/paymentSessions": { "get": { "tags": [ "Payment Sessions" ], "summary": "List", "operationId": "listPaymentSessions", "description": "List payment sessions for the authenticated merchant with optional filters. Supports filtering by subscriptionId, customerId, status, and entityType. When subscriptionId is provided the result includes both the subscription's own activation session (entityType='subscription') and any session attached to invoices for that subscription (entityType='invoice'). When customerId is provided the result covers the customer's full payment history: payment-link sessions (entityType='payment'), the activation sessions of the customer's subscriptions, and the sessions of those subscriptions' invoices.", "parameters": [ { "name": "merchantId", "in": "query", "schema": { "type": "string" }, "description": "Merchant organization ID. Required when using an API key that is not scoped to a single merchant." }, { "name": "subscriptionId", "in": "query", "schema": { "type": "string" }, "description": "Filter to sessions linked to this subscription (its own activation session plus all of its invoices' sessions)." }, { "name": "customerId", "in": "query", "schema": { "type": "string" }, "description": "Filter to sessions for this customer: payment-link sessions plus the activation and invoice sessions of the customer's subscriptions." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "processing", "completed", "failed", "expired", "cancelled" ] }, "description": "Filter by payment session status." }, { "name": "entityType", "in": "query", "schema": { "type": "string", "enum": [ "invoice", "subscription", "payment", "topup" ] }, "description": "Filter by the kind of entity the session pays for." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "description": "Number of sessions to return." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of sessions to skip." } ], "responses": { "200": { "description": "List of payment sessions", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "pagination" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/schemas-PaymentSession" } }, "pagination": { "$ref": "#/components/schemas/OffsetPagination" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v0/events": { "post": { "tags": [ "Events" ], "summary": "Ingest Event", "description": "Ingest a raw metering event. The event is published to the meter-events PubSub topic for processing by the meters service.", "operationId": "ingestEvent", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "source", "data" ], "anyOf": [ { "required": [ "subject" ] }, { "required": [ "externalSubject" ] } ], "properties": { "type": { "type": "string", "description": "CloudEvents type. Must match an eventType configured on a BillableMetric." }, "source": { "type": "string", "description": "Event source URI identifying the application." }, "subject": { "type": "string", "description": "Customer or entity ID this event relates to. Required unless externalSubject is provided." }, "externalSubject": { "description": "Your own customer identifier, matched against the customer's externalId. Fallback for when the Paygentic customer ID is not known — prefer subject when it is. Events reported before the customer exists are linked retroactively once a customer with this externalId is created. Resolution is eventually consistent: after an externalId is removed or reassigned, events may resolve to the previous customer for up to one hour. If subject is also provided, subject takes precedence and externalSubject is recorded but not used for resolution.", "allOf": [ { "$ref": "#/components/schemas/ExternalId" } ] }, "namespace": { "type": "string", "description": "Organization/merchant ID. Defaults to the authenticated user's organization. Platform users can specify a different organization." }, "timestamp": { "type": "string", "format": "date-time", "description": "Event timestamp. Defaults to server time if not provided." }, "idempotencyKey": { "type": "string", "description": "User-provided deduplication key. If not provided, a unique key is generated." }, "externalId": { "$ref": "#/components/schemas/ExternalId" }, "data": { "type": "object", "additionalProperties": true, "description": "Event payload containing the metering data." } } } } } }, "responses": { "202": { "description": "Event accepted for processing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v0/costs": { "post": { "tags": [ "Costs" ], "summary": "Create", "description": "Create a new metered cost for a product.", "operationId": "createCost", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "name", "unitCost", "currency", "productId", "eventType", "aggregation" ], "properties": { "type": { "type": "string", "enum": [ "metered" ], "description": "The cost type. Only `metered` costs are supported; they track usage via events." }, "name": { "type": "string", "description": "Human-readable name for the cost." }, "unitCost": { "type": "number", "minimum": 0, "description": "Cost per unit, multiplied by measured quantity to compute total cost. Must be non-negative." }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. USD, EUR)." }, "productId": { "$ref": "#/components/schemas/ProductId", "description": "The product ID this cost belongs to." }, "unit": { "type": "string", "description": "Unit label for metered costs (e.g. 'token', 'request'). Only valid for metered costs." }, "aggregation": { "type": "string", "enum": [ "SUM", "COUNT", "AVG", "MIN", "MAX", "UNIQUE_COUNT", "LATEST" ], "description": "Aggregation method for the metered event." }, "eventType": { "type": "string", "description": "CloudEvents type that identifies the metered event." }, "valueProperty": { "type": "string", "pattern": "^\\$\\.[a-zA-Z0-9_]+(\\.[a-zA-Z0-9_]+)*$", "description": "JSONPath to extract a numeric value from event data. Must start with `$.` (example: `$.amount` or `$.payload.bytes`). Required for SUM/AVG/MIN/MAX/LATEST aggregations." }, "groupBy": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^\\$\\.[a-zA-Z0-9_]+(\\.[a-zA-Z0-9_]+)*$" }, "description": "Map of dimension name to JSONPath for group-by queries. Each value must start with `$.` (example: `$.region`). Only valid for metered costs." }, "merchantId": { "$ref": "#/components/schemas/OrganizationId", "description": "The merchant organization ID that owns this cost." } } } } } }, "responses": { "201": { "description": "Cost created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cost" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "get": { "tags": [ "Costs" ], "summary": "List", "operationId": "listCosts", "parameters": [ { "name": "merchantId", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "Filter costs by merchant organization ID. If omitted, defaults to the merchant associated with the authenticated API key." }, { "name": "productId", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ProductId" }, "description": "Filter costs by product ID." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "description": "Number of costs to return." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of costs to skip." } ], "responses": { "200": { "description": "List of costs", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "pagination" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Cost" } }, "pagination": { "type": "object", "required": [ "limit", "offset", "total" ], "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v0/costs/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique identifier of the cost", "schema": { "$ref": "#/components/schemas/CostId" } } ], "get": { "tags": [ "Costs" ], "summary": "Get", "operationId": "getCost", "responses": { "200": { "description": "Cost details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cost" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "patch": { "tags": [ "Costs" ], "summary": "Update", "operationId": "updateCost", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Updated name for the cost." }, "unitCost": { "type": "number", "minimum": 0, "description": "Updated unit cost." }, "currency": { "type": "string", "description": "Updated ISO 4217 currency code." }, "unit": { "type": "string", "nullable": true, "description": "Updated unit label (metered costs only)." }, "aggregation": { "type": "string", "enum": [ "SUM", "COUNT", "AVG", "MIN", "MAX", "UNIQUE_COUNT", "LATEST" ], "nullable": true, "description": "Updated aggregation method (metered costs only)." }, "eventType": { "type": "string", "nullable": true, "description": "Updated CloudEvents type (metered costs only)." }, "valueProperty": { "type": "string", "nullable": true, "pattern": "^\\$\\.[a-zA-Z0-9_]+(\\.[a-zA-Z0-9_]+)*$", "description": "Updated JSONPath for value extraction. Must start with `$.` (example: `$.amount` or `$.payload.bytes`). Metered costs only." }, "groupBy": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^\\$\\.[a-zA-Z0-9_]+(\\.[a-zA-Z0-9_]+)*$" }, "nullable": true, "description": "Updated group-by dimension map. Each value must start with `$.` (example: `$.region`). Metered costs only." } } } } } }, "responses": { "200": { "description": "Cost updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cost" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "tags": [ "Costs" ], "summary": "Delete", "operationId": "deleteCost", "responses": { "204": { "description": "Cost deleted successfully" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v0/costs/{id}/summary": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique identifier of the cost", "schema": { "$ref": "#/components/schemas/CostId" } } ], "get": { "tags": [ "Costs" ], "summary": "Query Summary", "description": "Query usage data and compute cost for a specific cost configuration. To retrieve summaries for all costs belonging to a merchant, first call listCosts to obtain cost IDs, then call this endpoint in parallel for each ID.", "operationId": "getCostSummary", "parameters": [ { "name": "subject", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter usage to a specific subject (billing entity). When provided, only cost events matching this subject are included. When omitted, usage is aggregated across all subjects for the merchant." }, { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" }, "description": "Start of the query window (ISO 8601). Required together with 'to'." }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" }, "description": "End of the query window (ISO 8601). Required together with 'from'." }, { "name": "groupBy", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated dimension keys to group results by." }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "MINUTE", "HOUR", "DAY" ] }, "description": "Time window granularity for time-series breakdown." }, { "name": "filterGroupBy", "in": "query", "required": false, "schema": { "type": "string" }, "description": "JSON-encoded dimension filter (e.g. {\"model\":\"gpt-4\",\"region\":\"us-east\"}). Keys must match those defined in the cost's groupBy configuration. Retrieve the cost first to determine valid keys." } ], "responses": { "200": { "description": "Usage and cost data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CostUsageResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v0/costs/report": { "get": { "tags": [ "Costs" ], "summary": "Report", "description": "Aggregate cost data across costs and customers with grouping, filtering, and time-series breakdown.", "operationId": "getCostReport", "x-rate-limit": { "max": 600, "timeWindow": "1 minute", "errorMessage": "Too many cost report requests. Please wait before trying again." }, "parameters": [ { "name": "merchantId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The merchant organization ID. If omitted, defaults to the merchant associated with the authenticated API key." }, { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" }, "description": "Start of the query window (ISO 8601)." }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" }, "description": "End of the query window (ISO 8601)." }, { "name": "groupBy", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Dimension to group results by. Valid values: 'cost' (group by cost ID), 'customer' (group by customer ID), or any dimension key from a filtered cost's groupBy schema for dynamic dimension grouping. Dynamic dimension values require exactly one costId filter.", "examples": { "byCost": { "value": "cost" }, "byCustomer": { "value": "customer" }, "byDimension": { "value": "region" } } }, { "name": "costId", "in": "query", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } }, "description": "Filter to specific cost(s). Enables dynamic dimension grouping." }, { "name": "subject", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter to a specific subject (customer/event subject ID)." }, { "name": "filterGroupBy", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 4096 }, "description": "JSON-encoded dimension filters (e.g. {\"region\":\"us-east-1\"}). Max 4KB, max 5 keys." }, { "name": "topN", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 25, "default": 9 }, "description": "Number of top groups to return. An 'Other' bucket aggregates remaining groups." }, { "name": "comparePriorPeriod", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "When true, include prior-period comparison data in each group." }, { "name": "windowSize", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "HOUR", "DAY", "MONTH" ] }, "description": "Time window granularity for the time-series breakdown." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "totalCost", "totalQuantity" ], "default": "totalCost" }, "description": "Field to sort groups by." }, { "name": "sortDir", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Sort direction." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of groups to skip for pagination." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Maximum number of groups to return." }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter costs to a single ISO 4217 currency code (e.g. 'USD'). When omitted, defaults to the merchant's primary currency." } ], "responses": { "200": { "description": "Aggregated cost report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CostReportResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v0/revenue": { "get": { "operationId": "getRevenue", "summary": "Get revenue summary", "description": "Returns revenue summary with invoice and payment breakdowns (outstanding/paid/writtenOff), plus a time-series trend. Revenue is sourced from all issued invoices (v0 + v1) and completed payments.", "tags": [ "Revenue" ], "parameters": [ { "name": "startTime", "in": "query", "required": true, "description": "Start of the time range (ISO 8601 format)", "schema": { "type": "string", "format": "date-time" } }, { "name": "endTime", "in": "query", "required": true, "description": "End of the time range (ISO 8601 format)", "schema": { "type": "string", "format": "date-time" } }, { "name": "bucketWidth", "in": "query", "required": false, "description": "Time bucket granularity for trend data", "schema": { "type": "string", "enum": [ "hour", "day", "week" ], "default": "day" } }, { "name": "merchantId", "in": "query", "required": false, "description": "Filter by merchant ID. At least one of merchantId, subscriptionIds, or customerId must be provided.", "schema": { "$ref": "#/components/schemas/OrganizationId" } }, { "name": "customerId", "in": "query", "required": false, "description": "Filter by customer ID. At least one of merchantId, subscriptionIds, or customerId must be provided.", "schema": { "type": "string" } }, { "name": "subscriptionIds", "in": "query", "required": false, "description": "Filter by subscription IDs. At least one of merchantId, subscriptionIds, or customerId must be provided.", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true }, { "name": "currency", "in": "query", "required": false, "description": "Filter all results to a single ISO 4217 currency code (e.g. 'USD'). When omitted, results include all currencies.", "schema": { "type": "string" } }, { "name": "groupBy", "in": "query", "required": false, "description": "Group invoice data by dimension. Allowed values: 'plan' (max 5 groups, top 4 + 'other' when exceeding), 'customer' (max 25 groups, top 24 + 'other' when exceeding, sorted by revenue descending), 'currency' (one entry per currency, primary currency first then alphabetical). Note: groupBy values are mutually exclusive — combining them returns a 400 error. When groupBy=currency is active, top-level netRevenue, invoices, and payments fields are omitted; currencyBreakdown is the sole data source.", "schema": { "type": "string", "enum": [ "plan", "customer", "currency" ] } } ], "x-query-validation": { "anyOf": [ { "required": [ "merchantId" ] }, { "required": [ "customerId" ] }, { "required": [ "subscriptionIds" ] } ] }, "responses": { "200": { "description": "Revenue summary data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevenueSummaryResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v0/profitability": { "get": { "operationId": "getProfitability", "summary": "Get profitability summary", "description": "Returns a per-customer profitability summary for a merchant over a date range. Each row aggregates revenue (from issued + paid invoices), cost (from metered cost discovery), profit, and margin. Customers are ranked by profit descending and capped at topN; the remainder is rolled into a single self-consistent 'Other' row whose revenue, cost, and profit reflect the same set of customers. Rows are inner-joined against the merchant's customer list, so orphaned meter subjects from deleted or unknown customers are dropped.", "tags": [ "Profitability" ], "parameters": [ { "name": "merchantId", "in": "query", "required": true, "description": "Merchant whose customers to summarize", "schema": { "$ref": "#/components/schemas/OrganizationId" } }, { "name": "from", "in": "query", "required": true, "description": "Start of the time range (ISO 8601 format)", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": true, "description": "End of the time range (ISO 8601 format)", "schema": { "type": "string", "format": "date-time" } }, { "name": "topN", "in": "query", "required": false, "description": "Number of top customers (by profit) to return individually. The rest are rolled into a single 'Other' row.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } }, { "name": "currency", "in": "query", "required": false, "description": "ISO 4217 currency code to scope the summary. Defaults to the merchant's primary currency.", "schema": { "type": "string", "minLength": 3, "maxLength": 3 } }, { "name": "bucketWidth", "in": "query", "required": false, "description": "Time bucket granularity for the per-customer revenue trend. When omitted, the server picks a reasonable bucket from the window length.", "schema": { "type": "string", "enum": [ "hour", "day", "week" ], "default": "day" } } ], "responses": { "200": { "description": "Profitability summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfitabilitySummaryResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v0/testClocks": { "get": { "tags": [ "Test Clocks" ], "summary": "List", "description": "Retrieves a paginated list of test clocks", "operationId": "listTestClocks", "parameters": [ { "name": "limit", "in": "query", "description": "Number of items to return", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } }, { "name": "merchantId", "in": "query", "description": "Filter test clocks by merchant ID. If not provided, will be extracted from authenticated user's context.", "schema": { "type": "string" } }, { "name": "offset", "in": "query", "description": "Number of items to skip", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "List of test clocks", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TestClock" } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "description": "Number of items per page" }, "offset": { "type": "integer", "description": "Number of items skipped" }, "total": { "type": "integer", "description": "Total number of test clocks" } } } } }, "example": { "data": [ { "id": "tc_q7r8s9t0u1v2w3x4", "createdAt": "2024-01-01T00:00:00Z", "currentTime": "2024-01-01T00:00:00Z", "deletedAt": null, "description": "Test clock for annual subscription scenarios", "merchantId": "org_y5z6a7b8c9d0e1f2", "name": "Yearly Billing Test", "updatedAt": "2024-01-15T12:00:00Z" } ], "pagination": { "limit": 10, "offset": 0, "total": 1 } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Test Clocks" ], "summary": "Create", "description": "Creates a new test clock with an optional initial time. If no time is provided, uses the current time.", "operationId": "createTestClock", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "currentTime": { "type": "string", "format": "date-time", "description": "Initial time for the test clock (defaults to current time). Cannot be more than 1 hour in the past to prevent accidental backdating. The 1-hour buffer accounts for clock drift and network delays." }, "description": { "type": "string", "description": "Description of the test clock's purpose" }, "merchantId": { "type": "string", "description": "The merchant organization that will own this test clock. If not provided, will be extracted from authenticated user's context." }, "name": { "type": "string", "description": "Name of the test clock" } } } } } }, "responses": { "201": { "description": "Test clock created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestClock" }, "example": { "id": "tc_a1b2c3d4e5f6g7h8", "createdAt": "2024-02-28T10:00:00Z", "currentTime": "2024-03-01T00:00:00Z", "deletedAt": null, "description": "Test clock for monthly subscription billing scenarios", "merchantId": "org_i9j0k1l2m3n4o5p6", "name": "Monthly Billing Test", "updatedAt": "2024-02-28T10:00:00Z" } } } }, "400": { "description": "Invalid request", "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" } } } } } } }, "/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}$" } } ], "get": { "tags": [ "Test Clocks" ], "summary": "Get", "description": "Retrieves details of a specific test clock", "operationId": "getTestClock", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Test clock ID", "schema": { "type": "string", "pattern": "^tc_[a-zA-Z0-9]{16}$" } } ], "responses": { "200": { "description": "Test clock details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestClock" }, "example": { "id": "tc_g3h4i5j6k7l8m9n0", "createdAt": "2024-03-10T08:00:00Z", "currentTime": "2024-03-15T10:30:00Z", "deletedAt": null, "description": "Test clock for weekly subscription billing", "merchantId": "org_o1p2q3r4s5t6u7v8", "name": "Weekly Billing Test", "updatedAt": "2024-03-15T10:30:00Z" } } } }, "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" } } } } } }, "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" } } } } } }, "delete": { "tags": [ "Test Clocks" ], "summary": "Delete", "description": "Soft deletes a test clock. The clock will be marked as deleted but not removed from the database.", "operationId": "deleteTestClock", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Test clock ID", "schema": { "type": "string", "pattern": "^tc_[a-zA-Z0-9]{16}$" } } ], "responses": { "200": { "description": "Test clock deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestClock" }, "example": { "id": "tc_m1n2o3p4q5r6s7t8", "createdAt": "2024-01-01T00:00:00Z", "currentTime": "2024-03-31T23:59:59Z", "deletedAt": "2024-04-01T10:00:00Z", "description": "Test clock for quarterly subscription billing", "merchantId": "org_u9v0w1x2y3z4a5b6", "name": "Quarterly Billing Test", "updatedAt": "2024-03-31T23:59:59Z" } } } }, "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" } } } }, "409": { "description": "Conflict (e.g., test clock has active subscriptions)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v0/externalReferences": { "post": { "tags": [ "ExternalReferences" ], "summary": "Create", "operationId": "createExternalReference", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "merchantId", "entityType", "entityId", "provider", "externalId" ], "properties": { "merchantId": { "$ref": "#/components/schemas/schemas-OrganizationId" }, "entityType": { "$ref": "#/components/schemas/EntityType" }, "entityId": { "type": "string", "description": "Paygentic id of the entity, e.g. `itm_xxx`" }, "provider": { "$ref": "#/components/schemas/Provider" }, "externalId": { "$ref": "#/components/schemas/schemas-ExternalId" }, "externalLabel": { "type": "string", "maxLength": 255, "description": "Human-friendly name shown in UIs (e.g. a NetSuite financial-treatment name)" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Provider-specific fields (e.g. `{ \"sfObject\": \"Product2\" }`)" }, "isPrimary": { "type": "boolean", "default": true, "description": "Whether this is the canonical reference for `(provider, externalId)`. The primary is unique per merchant; non-primary references are aliases." }, "isDefault": { "type": "boolean", "default": false, "description": "Whether this is the default target for the entity + provider. At most one default per `(entityType, entityId, provider)`." } } } } } }, "responses": { "201": { "description": "External reference created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalReference" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "get": { "tags": [ "ExternalReferences" ], "summary": "List", "operationId": "listExternalReferences", "parameters": [ { "name": "merchantId", "in": "query", "schema": { "$ref": "#/components/schemas/schemas-OrganizationId" }, "description": "Restrict results to a specific merchant. All active filters AND together." }, { "name": "entityType", "in": "query", "schema": { "$ref": "#/components/schemas/EntityType" }, "description": "Filter by the Paygentic entity type the reference points at (e.g. `item`). All active filters AND together." }, { "name": "entityId", "in": "query", "schema": { "type": "string" }, "description": "Filter by the Paygentic entity id (e.g. `itm_xxx`). This is the inverse of the `GET /v0/items?provider=&externalId=` resolution endpoint — look up references from the Paygentic side. All active filters AND together." }, { "name": "provider", "in": "query", "schema": { "$ref": "#/components/schemas/Provider" }, "description": "Filter by provider (e.g. `salesforce`, `netsuite`). All active filters AND together." }, { "name": "externalId", "in": "query", "schema": { "$ref": "#/components/schemas/schemas-ExternalId" }, "description": "Filter by the external system's record id. Pair with `provider` to look up all Paygentic entities that carry a given external reference. All active filters AND together." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "List of external references", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalReference" } }, "pagination": { "$ref": "#/components/schemas/OffsetPagination" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v0/externalReferences/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique identifier of the external reference", "schema": { "type": "string", "pattern": "^xrf_[a-zA-Z0-9]+$" } } ], "get": { "tags": [ "ExternalReferences" ], "summary": "Get", "operationId": "getExternalReference", "responses": { "200": { "description": "External reference", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalReference" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "patch": { "tags": [ "ExternalReferences" ], "summary": "Update", "operationId": "updateExternalReference", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "externalLabel": { "type": "string", "maxLength": 255, "nullable": true }, "metadata": { "type": "object", "additionalProperties": true }, "isPrimary": { "type": "boolean" }, "isDefault": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "External reference updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalReference" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "tags": [ "ExternalReferences" ], "summary": "Delete", "operationId": "deleteExternalReference", "responses": { "204": { "description": "External reference deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v0/items": { "post": { "tags": [ "Items" ], "summary": "Create", "operationId": "createItem", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "merchantId" ], "properties": { "merchantId": { "$ref": "#/components/schemas/schemas-OrganizationId" }, "name": { "type": "string", "description": "Canonical sellable name for the Item" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Optional key-value metadata" } } } } } }, "responses": { "201": { "description": "Item created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Item" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "get": { "tags": [ "Items" ], "summary": "List", "operationId": "listItems", "parameters": [ { "name": "merchantId", "in": "query", "schema": { "$ref": "#/components/schemas/schemas-OrganizationId" }, "description": "Filter items by merchant organization id" }, { "name": "provider", "in": "query", "schema": { "type": "string" }, "description": "Provider whose external code to resolve (e.g. `salesforce`, `netsuite`). Must be supplied together with `externalId`." }, { "name": "externalId", "in": "query", "schema": { "type": "string" }, "description": "Resolve every live Item mapped to this `(provider, externalId)` — the canonical primary plus any non-primary aliases. The primary Item is returned first and is identifiable by its matching reference's `isPrimary: true`. Empty list on no match. Must be supplied together with `provider`." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Maximum items to return. In resolution mode (`provider`+`externalId` supplied) pagination is over the de-duplicated resolved Item set, primary Item first." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Zero-based offset for pagination. In resolution mode this paginates the de-duplicated resolved Item set." } ], "responses": { "200": { "description": "List of items", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Item" } }, "pagination": { "$ref": "#/components/schemas/OffsetPagination" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v0/items/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique identifier of the item", "schema": { "type": "string", "pattern": "^itm_[a-zA-Z0-9]+$" } } ], "get": { "tags": [ "Items" ], "summary": "Get", "operationId": "getItem", "responses": { "200": { "description": "Item details (including external references)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Item" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "patch": { "tags": [ "Items" ], "summary": "Update", "operationId": "updateItem", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "Item updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Item" } } } }, "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" } } }, "delete": { "tags": [ "Items" ], "summary": "Delete", "operationId": "deleteItem", "responses": { "204": { "description": "Item soft-deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v0/orders": { "post": { "tags": [ "Orders" ], "summary": "Create an order", "operationId": "createOrder", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrderRequest" } } } }, "responses": { "201": { "description": "Order created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "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" } } }, "get": { "tags": [ "Orders" ], "summary": "List orders", "operationId": "listOrders", "parameters": [ { "name": "merchantId", "in": "query", "schema": { "type": "string" }, "description": "Filter by merchant" }, { "name": "customerId", "in": "query", "schema": { "type": "string" }, "description": "Filter by customer" }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "draft", "pending", "approved", "rejected", "cancelled" ] }, "description": "Filter by status" }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "new_business", "renewal", "expansion" ] }, "description": "Filter by type" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "List of orders", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v0/orders/{id}": { "get": { "tags": [ "Orders" ], "summary": "Get an order", "operationId": "getOrder", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "patch": { "tags": [ "Orders" ], "summary": "Update an order", "operationId": "updateOrder", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrderRequest" } } } }, "responses": { "200": { "description": "Updated order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "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" } } }, "delete": { "tags": [ "Orders" ], "summary": "Delete an order", "operationId": "deleteOrder", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Order deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v0/orders/{orderId}/lineItems": { "post": { "tags": [ "Orders" ], "summary": "Add a line item", "operationId": "createOrderLineItem", "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrderLineItemRequest" } } } }, "responses": { "201": { "description": "Line item created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderLineItem" } } } }, "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" } } } }, "/v0/orders/{orderId}/lineItems/{id}": { "patch": { "tags": [ "Orders" ], "summary": "Update a line item", "operationId": "updateOrderLineItem", "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrderLineItemRequest" } } } }, "responses": { "200": { "description": "Updated line item", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderLineItem" } } } }, "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" } } }, "delete": { "tags": [ "Orders" ], "summary": "Delete a line item", "operationId": "deleteOrderLineItem", "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Line item deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v0/orders/{orderId}/approvals": { "post": { "operationId": "createOrderApproval", "summary": "Create an approval for the order", "description": "Submit the order for maker-checker approval. Returns 409 if a pending approval already exists.", "tags": [ "Orders" ], "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrderApprovalRequest" } } } }, "responses": { "201": { "description": "Approval created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Approval" } } } }, "404": { "description": "Order not found" }, "409": { "description": "Conflict — pending approval already exists or order has no line items" } }, "security": [ { "BearerAuth": [] } ] } }, "/v0/billingSchedules": { "get": { "tags": [ "Billing Schedules" ], "summary": "List billing schedules", "operationId": "listBillingSchedules", "parameters": [ { "name": "orderId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by owning order (XOR with subscriptionId)" }, { "name": "subscriptionId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by owning subscription (XOR with orderId)" } ], "responses": { "200": { "description": "List of billing schedules", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "pagination" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/schemas-BillingSchedule" } }, "pagination": { "$ref": "#/components/schemas/OffsetPagination" } } } } } }, "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" } } }, "post": { "tags": [ "Billing Schedules" ], "summary": "Create a billing schedule", "operationId": "createBillingSchedule", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBillingScheduleRequest" } } } }, "responses": { "201": { "description": "BillingSchedule created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/schemas-BillingSchedule" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v0/billingSchedules/{id}": { "get": { "tags": [ "Billing Schedules" ], "summary": "Get a billing schedule", "operationId": "getBillingSchedule", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "BillingSchedule", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/schemas-BillingSchedule" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "patch": { "tags": [ "Billing Schedules" ], "summary": "Update a billing schedule", "operationId": "updateBillingSchedule", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBillingScheduleRequest" } } } }, "responses": { "200": { "description": "BillingSchedule updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/schemas-BillingSchedule" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "tags": [ "Billing Schedules" ], "summary": "Delete a billing schedule", "operationId": "deleteBillingSchedule", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v0/billingSchedules/{id}/intervals": { "get": { "tags": [ "Billing Schedules" ], "summary": "List schedule intervals", "operationId": "listScheduleIntervals", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of schedule intervals", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "pagination" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduleInterval" } }, "pagination": { "$ref": "#/components/schemas/OffsetPagination" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "tags": [ "Billing Schedules" ], "summary": "Replace schedule intervals", "description": "Replace (PUT semantics) the full interval set for a schedule. Wipes existing intervals and recreates from the supplied list. Reverts any in-flight order approval for order-owned schedules.", "operationId": "replaceScheduleIntervals", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplaceScheduleIntervalsRequest" } } } }, "responses": { "200": { "description": "Intervals replaced", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "pagination" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduleInterval" } }, "pagination": { "$ref": "#/components/schemas/OffsetPagination" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v0/billingSchedules/{id}/invoices": { "get": { "tags": [ "Billing Schedules" ], "summary": "List staged invoices", "description": "List the staged invoice projections for a schedule, newest period first.", "operationId": "listScheduleInvoices", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of staged invoices", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "pagination" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduleInvoice" } }, "pagination": { "$ref": "#/components/schemas/OffsetPagination" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "tags": [ "Billing Schedules" ], "summary": "Generate staged invoices", "description": "Generate (or regenerate) staged invoice projections for a schedule from its current intervals. Idempotent — replaces any existing staged rows. Schedule must have at least one interval.", "operationId": "generateScheduleInvoices", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "Staged invoices generated", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "pagination" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduleInvoice" } }, "pagination": { "$ref": "#/components/schemas/OffsetPagination" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v0/integrations/salesforce/accounts": { "get": { "tags": [ "Salesforce" ], "summary": "List Salesforce accounts", "description": "Returns Accounts from the merchant's connected Salesforce org via live proxy SOQL.", "operationId": "listSalesforceAccounts", "x-rate-limit": { "max": 30, "timeWindow": "1 minute" }, "parameters": [ { "name": "merchantId", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "Merchant whose Salesforce connection to use." }, { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 255 }, "description": "Optional name filter (LIKE match)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "List of Salesforce accounts", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "totalSize", "done" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SalesforceAccount" } }, "totalSize": { "type": "integer" }, "done": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v0/merchantIntegrations": { "get": { "tags": [ "MerchantIntegrations" ], "summary": "List", "operationId": "listMerchantIntegrations", "parameters": [ { "name": "merchantId", "in": "query", "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "Restrict results to a specific merchant. All active filters AND together." }, { "name": "provider", "in": "query", "schema": { "$ref": "#/components/schemas/MerchantIntegrationProvider" }, "description": "Filter by provider (e.g. `salesforce`)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "List of merchant integrations", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantIntegration" } }, "pagination": { "$ref": "#/components/schemas/OffsetPagination" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "tags": [ "MerchantIntegrations" ], "summary": "Upsert", "description": "Create or re-activate a merchant's connection to a provider. Idempotent on `(merchantId, provider)` — connecting an already-connected provider re-activates the existing row, never creating a duplicate.", "operationId": "upsertMerchantIntegration", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "merchantId", "provider" ], "properties": { "merchantId": { "$ref": "#/components/schemas/OrganizationId" }, "provider": { "$ref": "#/components/schemas/MerchantIntegrationProvider" }, "externalId": { "type": "string", "maxLength": 255, "description": "Ampersand installation id." }, "status": { "$ref": "#/components/schemas/MerchantIntegrationStatus" }, "config": { "type": "object", "additionalProperties": true }, "metadata": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "Merchant integration upserted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantIntegration" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v0/merchantIntegrations/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique identifier of the merchant integration", "schema": { "type": "string", "pattern": "^mint_[a-zA-Z0-9]+$" } } ], "get": { "tags": [ "MerchantIntegrations" ], "summary": "Get", "operationId": "getMerchantIntegration", "responses": { "200": { "description": "Merchant integration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantIntegration" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v0/merchantIntegrations/{id}/disconnect": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique identifier of the merchant integration", "schema": { "type": "string", "pattern": "^mint_[a-zA-Z0-9]+$" } } ], "patch": { "tags": [ "MerchantIntegrations" ], "summary": "Disconnect", "description": "Soft-disconnect a connection (status `disconnected`, stamp `disconnectedAt`). Never hard-deletes — preserves the install id and `connectedAt` for audit.", "operationId": "disconnectMerchantIntegration", "responses": { "200": { "description": "Merchant integration disconnected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantIntegration" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v0/approvals": { "post": { "tags": [ "Approvals" ], "summary": "Submit a resource for approval", "operationId": "createApproval", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApprovalRequest" } } } }, "responses": { "201": { "description": "Approval created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/schemas-Approval" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "get": { "tags": [ "Approvals" ], "summary": "List approvals", "operationId": "listApprovals", "parameters": [ { "name": "merchantId", "in": "query", "schema": { "type": "string" }, "description": "Filter by merchant" }, { "name": "resourceType", "in": "query", "schema": { "type": "string", "enum": [ "order", "invoice" ] }, "description": "Filter by resource type" }, { "name": "resourceId", "in": "query", "schema": { "type": "string" }, "description": "Filter by resource id" }, { "name": "kind", "in": "query", "schema": { "type": "string", "enum": [ "data_review", "financial_review", "push" ] }, "description": "Filter by kind" }, { "name": "decision", "in": "query", "schema": { "type": "string", "enum": [ "pending", "approved", "rejected", "cancelled" ] }, "description": "Filter by decision" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "List of approvals", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v0/approvals/{id}": { "get": { "tags": [ "Approvals" ], "summary": "Get an approval", "operationId": "getApproval", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Approval", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/schemas-Approval" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "patch": { "tags": [ "Approvals" ], "summary": "Update an approval (approve, reject, or cancel)", "operationId": "updateApproval", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateApprovalRequest" } } } }, "responses": { "200": { "description": "Approval updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/schemas-Approval" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } } }, "components": { "schemas": { "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" } ] } }, "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" ] }, "ProductId": { "type": "string", "pattern": "^prod_[a-zA-Z0-9]+$", "description": "Unique identifier for a product" }, "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" }, "SubscriptionId": { "type": "string", "pattern": "^sub_[a-zA-Z0-9]+$", "description": "Unique identifier for a subscription" }, "PlanId": { "type": "string", "pattern": "^plan_[a-zA-Z0-9]+$", "description": "Unique identifier for a plan" }, "SourceId": { "type": "string", "pattern": "^src_[a-zA-Z0-9]+$", "description": "Unique identifier for a source" }, "SourceEventId": { "type": "string", "pattern": "^sev_[a-zA-Z0-9]+$", "description": "Unique identifier for a source event" }, "BillableMetricId": { "type": "string", "pattern": "^bm_[a-zA-Z0-9]+$", "description": "Unique identifier for a billable metric" }, "FeeId": { "type": "string", "pattern": "^fee_[a-zA-Z0-9]+$", "description": "Unique identifier for a fee" }, "FeatureId": { "type": "string", "pattern": "^feat_[a-zA-Z0-9]+$", "description": "Unique identifier for a feature" }, "CostId": { "type": "string", "pattern": "^cst_[a-zA-Z0-9]+$", "description": "Unique identifier for a cost" }, "PriceId": { "type": "string", "pattern": "^price_[a-zA-Z0-9]+$", "description": "Unique identifier for a price" }, "SalesforceAccount": { "type": "object", "description": "A Salesforce Account record. Fields vary by org and are passed through verbatim.", "additionalProperties": true }, "InvoiceRefund": { "type": "object", "required": [ "object", "id", "invoiceId", "merchantId", "amount", "taxAmount", "total", "currency", "status", "externalCreditNoteId", "createdAt" ], "properties": { "object": { "type": "string", "enum": [ "invoice_refund" ], "description": "The object type" }, "id": { "type": "string", "description": "The credit note ID (crn_*)" }, "invoiceId": { "type": "string", "description": "The invoice this refund credits" }, "merchantId": { "type": "string", "description": "The merchant that owns the invoice" }, "amount": { "type": "string", "description": "Refunded subtotal (pre-tax) in decimal dollars" }, "taxAmount": { "type": "string", "description": "Reversed tax in decimal dollars" }, "total": { "type": "string", "description": "Total refunded (amount + taxAmount) in decimal dollars" }, "currency": { "type": "string", "description": "ISO 4217 currency code" }, "status": { "type": "string", "enum": [ "ISSUED", "VOIDED" ], "description": "Credit note status" }, "externalCreditNoteId": { "type": "string", "description": "Credit note id in the tax provider" }, "permalink": { "type": "string", "nullable": true, "description": "Public URL to view the credit note document" }, "pdfUrl": { "type": "string", "nullable": true, "description": "Direct PDF download link" }, "reason": { "type": "string", "nullable": true, "description": "Optional refund reason" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the refund was issued" }, "voidedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When the refund was voided, if applicable" } } }, "InvoiceRefundList": { "type": "object", "required": [ "object", "data" ], "properties": { "object": { "type": "string", "enum": [ "list" ], "description": "The object type" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceRefund" }, "description": "The refunds for this invoice" } } }, "BillableMetric": { "type": "object", "required": [ "id", "object", "name", "description", "unit", "merchantId", "productId", "aggregation", "createdAt", "updatedAt" ], "properties": { "id": { "$ref": "#/components/schemas/BillableMetricId" }, "object": { "type": "string", "enum": [ "billableMetric" ], "default": "billableMetric" }, "aggregation": { "type": "string", "enum": [ "SUM", "COUNT", "AVG", "MIN", "MAX", "UNIQUE_COUNT", "LATEST" ] }, "createdAt": { "type": "string", "format": "date-time" }, "description": { "type": "string" }, "merchantId": { "$ref": "#/components/schemas/OrganizationId" }, "name": { "type": "string" }, "productId": { "$ref": "#/components/schemas/ProductId" }, "unit": { "type": "string" }, "updatedAt": { "type": "string", "format": "date-time" }, "eventType": { "type": "string", "nullable": true }, "valueProperty": { "type": "string", "nullable": true }, "groupBy": { "type": "object", "additionalProperties": { "type": "string" }, "nullable": true }, "eventFrom": { "type": "string", "format": "date-time", "nullable": true } } }, "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" } }, "UsageResponse": { "type": "object", "required": [ "object", "billableMetricId", "totalValue" ], "properties": { "object": { "type": "string", "enum": [ "meter" ], "default": "meter" }, "billableMetricId": { "$ref": "#/components/schemas/BillableMetricId" }, "totalValue": { "type": "number", "description": "Total aggregated value across the query window" }, "windowedValues": { "type": "array", "items": { "type": "object", "required": [ "windowStart", "windowEnd", "value" ], "properties": { "windowStart": { "type": "string", "format": "date-time" }, "windowEnd": { "type": "string", "format": "date-time" }, "value": { "type": "number" } } }, "description": "Time-bucketed values. Only present when windowSize is specified. When both windowSize and groupBy are set, windowedValues[i] is index-aligned with groupedValues[i] (same window and group)." }, "groupedValues": { "type": "array", "items": { "type": "object", "required": [ "groupBy", "value" ], "properties": { "groupBy": { "type": "object", "additionalProperties": { "type": "string" } }, "value": { "type": "number" }, "eventCount": { "type": "integer", "description": "Number of raw events in this group" } } }, "description": "Dimension-grouped values. Only present when groupBy is specified. When both windowSize and groupBy are set, groupedValues[i] is index-aligned with windowedValues[i] (same window and group)." }, "groupCount": { "type": "integer", "description": "Total distinct groups before groupLimit/groupOffset truncation. Only present when groupLimit is specified; use it to drive pagination totals." } } }, "ExternalId": { "type": "string", "pattern": "^[a-zA-Z0-9_-]+$", "maxLength": 255, "description": "Optional external identifier for cross-referencing with external systems. Alphanumeric characters, hyphens, and underscores only." }, "MeterEvent": { "type": "object", "required": [ "id", "object", "type", "source", "subject", "time", "idempotencyKey", "data" ], "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "object": { "type": "string", "enum": [ "meterEvent" ], "default": "meterEvent" }, "type": { "type": "string", "description": "CloudEvents event type (matches the meter's eventType)" }, "source": { "type": "string", "description": "CloudEvents source that published the event" }, "subject": { "type": "string", "description": "Subject of the event — typically the customer ID" }, "time": { "type": "string", "format": "date-time", "description": "Time the event occurred" }, "idempotencyKey": { "type": "string", "description": "Caller-supplied idempotency key" }, "data": { "type": "object", "additionalProperties": true, "description": "Event payload" }, "externalId": { "$ref": "#/components/schemas/ExternalId" }, "externalSubject": { "type": "string", "description": "The merchant's own customer identifier the event was reported with. Empty subject with an externalSubject means the event is not linked to a customer yet." } } }, "MeterEventList": { "type": "object", "required": [ "object", "billableMetricId", "events", "pagination" ], "properties": { "object": { "type": "string", "enum": [ "list" ], "default": "list" }, "billableMetricId": { "$ref": "#/components/schemas/BillableMetricId" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/MeterEvent" } }, "pagination": { "$ref": "#/components/schemas/OffsetPagination" } } }, "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 } }, "ValidTaxAddress": { "type": "object", "required": [ "valid" ], "properties": { "message": { "type": "string", "description": "Validation message if address is invalid. Sample values: 'Country is required for tax calculation', 'Invalid postal code format', 'State/province required for this country'" }, "valid": { "type": "boolean", "description": "Whether the consumer address is valid for tax calculation when using Paygentic Tax" } }, "description": "Indicates whether the consumer address is valid for tax calculation when using Paygentic Tax. If valid=false, tax calculation will be skipped and internal invoice flow with default tax rate will be used." }, "Customer": { "type": "object", "required": [ "id", "object", "consumerId", "merchantId", "createdAt", "updatedAt", "validTaxAddress" ], "properties": { "id": { "$ref": "#/components/schemas/CustomerId" }, "object": { "type": "string", "enum": [ "customer" ], "default": "customer" }, "consumerId": { "$ref": "#/components/schemas/OrganizationId" }, "createdAt": { "type": "string", "format": "date-time" }, "merchantId": { "$ref": "#/components/schemas/OrganizationId" }, "organization": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string" }, "address": { "$ref": "#/components/schemas/Address" }, "billingEmails": { "type": "array", "items": { "type": "string", "format": "email" } }, "name": { "type": "string" }, "phone": { "type": "string" } } }, "taxId": { "type": "string", "description": "Business tax registration identifier. Sample values: 'GB123456789' for UK VAT, 'DE123456789' for German VAT, 'FR12345678901' for French VAT. Enables inter-company tax handling and exemption from standard tax collection." }, "externalId": { "type": "string", "maxLength": 255, "description": "Merchant-defined identifier for this customer in their own system." }, "taxRates": { "$ref": "#/components/schemas/TaxRates" }, "updatedAt": { "type": "string", "format": "date-time" }, "validTaxAddress": { "$ref": "#/components/schemas/ValidTaxAddress" }, "notificationSettings": { "type": "object", "required": [ "invoiceIssued", "invoicePaid", "renewalReminder" ], "properties": { "invoiceIssued": { "type": "boolean", "description": "Whether to send invoice issued emails to this customer." }, "invoicePaid": { "type": "boolean", "description": "Whether to send invoice paid emails to this customer." }, "renewalReminder": { "type": "boolean", "description": "Whether to send renewal reminder emails to this customer." } } } } }, "PaymentMethod": { "type": "object", "required": [ "object", "id", "createdAt" ], "properties": { "object": { "type": "string", "enum": [ "paymentMethod" ] }, "id": { "type": "string", "description": "Payment method identifier." }, "type": { "type": "string", "nullable": true, "description": "Payment method type (e.g. `card`, `sepa_debit`)." }, "brand": { "type": "string", "nullable": true }, "last4": { "type": "string", "nullable": true }, "expMonth": { "type": "integer", "nullable": true }, "expYear": { "type": "integer", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" } } }, "PaymentSession": { "type": "object", "required": [ "object", "id", "mode", "status", "url", "expiresAt", "createdAt" ], "properties": { "object": { "type": "string", "enum": [ "paymentSession" ] }, "id": { "type": "string", "description": "Payment session identifier (e.g. `ps_...`)." }, "mode": { "type": "string", "enum": [ "payment", "setup" ] }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed", "expired", "cancelled" ] }, "url": { "type": "string", "format": "uri", "description": "Hosted page URL. Redirect the customer here, or load it inside an iframe — when iframed, the page reports outcomes via `postMessage` (`payment_success` / `payment_error`) to the parent window." }, "successRedirectUrl": { "type": "string", "format": "uri", "nullable": true }, "failureRedirectUrl": { "type": "string", "format": "uri", "nullable": true }, "metadata": { "type": "object", "additionalProperties": true }, "expiresAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" } } }, "EntitlementFeatureType": { "type": "string", "enum": [ "boolean", "static", "metered" ], "description": "The type of feature." }, "EntitlementStatus": { "type": "string", "enum": [ "active", "canceled", "expired" ], "description": "Current status of the entitlement." }, "EntitlementListItemBase": { "type": "object", "description": "Common fields shared by all entitlement list items. List items use `entitlementId` (not `id`) to preserve the original public field name on `/v1/entitlements`. The get-by-id endpoint returns the same object with a top-level `id` and `object: \"entitlement\"` instead.", "required": [ "entitlementId", "customerId", "featureId", "featureKey", "featureType", "productId", "subscriptionId", "status", "activeFrom", "activeTo", "hasAccess", "metadata" ], "properties": { "entitlementId": { "type": "string", "pattern": "^ent_[a-zA-Z0-9]+$", "description": "Unique identifier for the entitlement." }, "customerId": { "$ref": "#/components/schemas/CustomerId" }, "featureId": { "type": "string", "pattern": "^feat_[a-zA-Z0-9]+$", "description": "The feature this entitlement grants access to." }, "featureKey": { "type": "string", "description": "The unique key identifying the feature." }, "featureType": { "$ref": "#/components/schemas/EntitlementFeatureType" }, "productId": { "$ref": "#/components/schemas/ProductId" }, "subscriptionId": { "type": "string", "nullable": true, "description": "The subscription this entitlement is associated with, if any." }, "status": { "$ref": "#/components/schemas/EntitlementStatus" }, "activeFrom": { "type": "string", "format": "date-time", "description": "When the entitlement becomes active." }, "activeTo": { "type": "string", "format": "date-time", "nullable": true, "description": "When the entitlement expires. Null means no expiration." }, "hasAccess": { "type": "boolean", "description": "Whether the customer currently has active access to this entitlement." }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Additional metadata for the entitlement." } } }, "BooleanEntitlementListItem": { "unevaluatedProperties": false, "allOf": [ { "$ref": "#/components/schemas/EntitlementListItemBase" }, { "type": "object", "required": [ "config" ], "properties": { "featureType": { "type": "string", "enum": [ "boolean" ] }, "config": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Always `null` for boolean entitlements. Surfaced on every list item so clients can read `item.config` without first switching on `featureType`." } } } ] }, "StaticEntitlementListItem": { "unevaluatedProperties": false, "allOf": [ { "$ref": "#/components/schemas/EntitlementListItemBase" }, { "type": "object", "required": [ "config" ], "properties": { "featureType": { "type": "string", "enum": [ "static" ] }, "config": { "type": "object", "additionalProperties": true, "description": "Configuration values for this entitlement." } } } ] }, "MeteredEntitlementListItem": { "unevaluatedProperties": false, "allOf": [ { "$ref": "#/components/schemas/EntitlementListItemBase" }, { "type": "object", "required": [ "balance", "usageInPeriod", "overage", "isSoftLimit", "config", "currentPeriodStart", "currentPeriodEnd", "pricingUnitId" ], "properties": { "featureType": { "type": "string", "enum": [ "metered" ] }, "config": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Always `null` for metered entitlements. Surfaced on every list item so clients can read `item.config` without first switching on `featureType`." }, "isSoftLimit": { "type": "boolean", "description": "When false (hard limit), access is blocked when balance is exhausted and overage is not charged on invoices. When true (soft limit), access continues past the grant and overage is charged at the per-unit rate." }, "balance": { "type": "number", "description": "Remaining balance for the current period. When `pricingUnitId` is set, this is expressed in that pricing unit's credits (a balance shared across every feature drawing the same unit); otherwise it is in the feature's native metered units." }, "usageInPeriod": { "type": "number", "description": "Total usage consumed in the current billing period, in the same unit as `balance` (credits when `pricingUnitId` is set, otherwise native metered units). When `pricingUnitId` is set, this is the shared-pool aggregate across every feature drawing the same unit, not usage specific to this feature." }, "overage": { "type": "number", "description": "Amount of usage exceeding the balance, in the same unit as `balance` (credits when `pricingUnitId` is set, otherwise native metered units)." }, "pricingUnitId": { "type": "string", "nullable": true, "pattern": "^pu_[a-zA-Z0-9]+$", "description": "The pricing unit this feature is denominated in when it draws a credit pool. When set, `balance`/`usageInPeriod`/`overage` are in that unit's credits and reflect a balance shared across all features on the same unit. `null` for currency-denominated features (native metered units)." }, "currentPeriodStart": { "type": "string", "format": "date-time", "nullable": true, "description": "Start of the current usage period. These bounds describe this entitlement's own usage window (not the shared pool's), even for a pool-backed feature (`pricingUnitId` set) whose `balance` and `usageInPeriod` are shared-pool aggregates. Before the entitlement activates (the pre-activation \"dark window\", when the query time is earlier than `activeFrom`) this instead describes the pre-activation `[subscription start, activation)` window and may be `null` when there is no associated subscription." }, "currentPeriodEnd": { "type": "string", "format": "date-time", "nullable": true, "description": "End of the current usage period. These bounds describe this entitlement's own usage window (not the shared pool's), even for a pool-backed feature (`pricingUnitId` set) whose `balance` and `usageInPeriod` are shared-pool aggregates. Before the entitlement activates (the pre-activation \"dark window\", when the query time is earlier than `activeFrom`) this instead holds `activeFrom` — the end of the pre-activation `[subscription start, activation)` window." } } } ] }, "EntitlementListItem": { "oneOf": [ { "$ref": "#/components/schemas/BooleanEntitlementListItem" }, { "$ref": "#/components/schemas/StaticEntitlementListItem" }, { "$ref": "#/components/schemas/MeteredEntitlementListItem" } ], "discriminator": { "propertyName": "featureType", "mapping": { "boolean": "#/components/schemas/BooleanEntitlementListItem", "static": "#/components/schemas/StaticEntitlementListItem", "metered": "#/components/schemas/MeteredEntitlementListItem" } }, "description": "An entitlement as returned by the list endpoint. The shape varies by featureType. Uses `entitlementId` (not `id`) for backwards compatibility with the original list contract." }, "EntitlementTemplate": { "oneOf": [ { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "boolean" ] } } }, { "type": "object", "required": [ "type", "config" ], "properties": { "type": { "type": "string", "enum": [ "static" ] }, "config": { "type": "object", "additionalProperties": true, "description": "Configuration values for the entitlement." } } }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "metered" ] }, "usagePeriod": { "type": "object", "description": "Recurrence configuration. Omit for a one-time grant that does not refill.", "required": [ "interval" ], "properties": { "interval": { "type": "string", "description": "ISO 8601 duration for the usage period, e.g. P1D, P1W, P1M, P1Y." }, "anchor": { "type": "string", "format": "date-time", "description": "Optional anchor date-time for period alignment." } } }, "isSoftLimit": { "type": "boolean", "description": "When false (hard limit), access is blocked when balance is exhausted and overage is not charged on invoices. When true (soft limit), access continues past the grant and overage is charged at the per-unit rate." }, "issueAfterReset": { "type": "number", "minimum": 0, "description": "Credits issued at each period reset. Set to 0 for entitlements without included credits; top-ups may be supplied via direct grants or grant purchases." }, "issueAfterResetPriority": { "type": "integer", "description": "Priority for grants issued after reset." }, "preserveOverageAtReset": { "type": "boolean", "description": "When true, overage from the previous period carries over." }, "resetMaxRollover": { "type": "number", "description": "Maximum amount of unused balance that rolls over on reset." }, "resetMinRollover": { "type": "number", "description": "Minimum amount of balance guaranteed to roll over on reset." } } } ], "description": "Template for the entitlement. Boolean for simple on/off features, static for features with configuration, metered for usage-based features." }, "IssueEntitlementRequest": { "type": "object", "required": [ "customerId", "featureId", "template" ], "properties": { "customerId": { "$ref": "#/components/schemas/CustomerId", "description": "The customer to issue the entitlement to." }, "featureId": { "type": "string", "pattern": "^feat_[a-zA-Z0-9]+$", "description": "The feature to grant access to." }, "template": { "$ref": "#/components/schemas/EntitlementTemplate", "description": "The template defining the entitlement type and configuration." }, "activeFrom": { "type": "string", "format": "date-time", "description": "When the entitlement becomes active. Defaults to now." }, "activeTo": { "type": "string", "format": "date-time", "nullable": true, "description": "When the entitlement expires. Null means no expiration." }, "subscriptionId": { "type": "string", "nullable": true, "description": "Optional subscription ID to associate with this entitlement." }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Additional metadata for the entitlement." } } }, "EntitlementDetailBase": { "type": "object", "description": "Common fields shared by all entitlement types.", "required": [ "object", "id", "customerId", "featureId", "featureKey", "featureType", "productId", "subscriptionId", "status", "activeFrom", "activeTo", "hasAccess", "metadata" ], "properties": { "object": { "type": "string", "enum": [ "entitlement" ], "default": "entitlement" }, "id": { "type": "string", "pattern": "^ent_[a-zA-Z0-9]+$", "description": "Unique identifier for the entitlement." }, "customerId": { "$ref": "#/components/schemas/CustomerId" }, "featureId": { "type": "string", "pattern": "^feat_[a-zA-Z0-9]+$", "description": "The feature this entitlement grants access to." }, "featureKey": { "type": "string", "description": "The unique key identifying the feature." }, "featureType": { "$ref": "#/components/schemas/EntitlementFeatureType" }, "productId": { "$ref": "#/components/schemas/ProductId" }, "subscriptionId": { "type": "string", "nullable": true, "description": "The subscription this entitlement is associated with, if any." }, "status": { "$ref": "#/components/schemas/EntitlementStatus" }, "activeFrom": { "type": "string", "format": "date-time", "description": "When the entitlement becomes active." }, "activeTo": { "type": "string", "format": "date-time", "nullable": true, "description": "When the entitlement expires. Null means no expiration." }, "hasAccess": { "type": "boolean", "description": "Whether the customer currently has active access to this entitlement." }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Additional metadata for the entitlement." } } }, "BooleanEntitlementDetail": { "unevaluatedProperties": false, "allOf": [ { "$ref": "#/components/schemas/EntitlementDetailBase" }, { "type": "object", "required": [ "config" ], "properties": { "featureType": { "type": "string", "enum": [ "boolean" ] }, "config": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Always `null` for boolean entitlements. Surfaced on every entitlement so clients can read `config` without first switching on `featureType`." } } } ] }, "StaticEntitlementDetail": { "unevaluatedProperties": false, "allOf": [ { "$ref": "#/components/schemas/EntitlementDetailBase" }, { "type": "object", "required": [ "config" ], "properties": { "featureType": { "type": "string", "enum": [ "static" ] }, "config": { "type": "object", "additionalProperties": true, "description": "Configuration values for this entitlement." } } } ] }, "MeteredEntitlementDetail": { "unevaluatedProperties": false, "allOf": [ { "$ref": "#/components/schemas/EntitlementDetailBase" }, { "type": "object", "required": [ "balance", "usageInPeriod", "overage", "isSoftLimit", "config", "currentPeriodStart", "currentPeriodEnd", "pricingUnitId" ], "properties": { "featureType": { "type": "string", "enum": [ "metered" ] }, "config": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Always `null` for metered entitlements. Surfaced on every entitlement so clients can read `config` without first switching on `featureType`." }, "isSoftLimit": { "type": "boolean", "description": "When false (hard limit), access is blocked when balance is exhausted and overage is not charged on invoices. When true (soft limit), access continues past the grant and overage is charged at the per-unit rate." }, "balance": { "type": "number", "description": "Remaining balance for the current period. When `pricingUnitId` is set, this is expressed in that pricing unit's credits (a balance shared across every feature drawing the same unit); otherwise it is in the feature's native metered units." }, "usageInPeriod": { "type": "number", "description": "Total usage consumed in the current billing period, in the same unit as `balance` (credits when `pricingUnitId` is set, otherwise native metered units). When `pricingUnitId` is set, this is the shared-pool aggregate across every feature drawing the same unit, not usage specific to this feature." }, "overage": { "type": "number", "description": "Amount of usage exceeding the balance, in the same unit as `balance` (credits when `pricingUnitId` is set, otherwise native metered units)." }, "pricingUnitId": { "type": "string", "nullable": true, "pattern": "^pu_[a-zA-Z0-9]+$", "description": "The pricing unit this feature is denominated in when it draws a credit pool. When set, `balance`/`usageInPeriod`/`overage` are in that unit's credits and reflect a balance shared across all features on the same unit. `null` for currency-denominated features (native metered units)." }, "currentPeriodStart": { "type": "string", "format": "date-time", "nullable": true, "description": "Start of the current usage period. These bounds describe this entitlement's own usage window (not the shared pool's), even for a pool-backed feature (`pricingUnitId` set) whose `balance` and `usageInPeriod` are shared-pool aggregates. Before the entitlement activates (the pre-activation \"dark window\", when the query time is earlier than `activeFrom`) this instead describes the pre-activation `[subscription start, activation)` window and may be `null` when there is no associated subscription." }, "currentPeriodEnd": { "type": "string", "format": "date-time", "nullable": true, "description": "End of the current usage period. These bounds describe this entitlement's own usage window (not the shared pool's), even for a pool-backed feature (`pricingUnitId` set) whose `balance` and `usageInPeriod` are shared-pool aggregates. Before the entitlement activates (the pre-activation \"dark window\", when the query time is earlier than `activeFrom`) this instead holds `activeFrom` — the end of the pre-activation `[subscription start, activation)` window." } } } ] }, "EntitlementDetail": { "oneOf": [ { "$ref": "#/components/schemas/BooleanEntitlementDetail" }, { "$ref": "#/components/schemas/StaticEntitlementDetail" }, { "$ref": "#/components/schemas/MeteredEntitlementDetail" } ], "discriminator": { "propertyName": "featureType", "mapping": { "boolean": "#/components/schemas/BooleanEntitlementDetail", "static": "#/components/schemas/StaticEntitlementDetail", "metered": "#/components/schemas/MeteredEntitlementDetail" } }, "description": "A specific entitlement. The response shape varies by featureType." }, "Grant": { "type": "object", "required": [ "object", "id", "entitlementId", "amount", "effectiveAt", "createdAt", "recurrencePeriod", "idempotencyKey" ], "properties": { "object": { "type": "string", "enum": [ "grant" ], "default": "grant" }, "id": { "type": "string", "pattern": "^grt_[a-zA-Z0-9]+$", "description": "Unique identifier for the grant." }, "entitlementId": { "type": "string", "pattern": "^ent_[a-zA-Z0-9]+$", "description": "The entitlement this grant belongs to." }, "amount": { "type": "number", "description": "The number of credits granted." }, "effectiveAt": { "type": "string", "format": "date-time", "description": "When the grant becomes effective." }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When the grant expires. Null means no expiration." }, "voidedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When the grant was voided. Null means the grant is active." }, "createdAt": { "type": "string", "format": "date-time", "description": "When the grant was created." }, "recurrencePeriod": { "type": "string", "nullable": true, "description": "The recurrence interval (ISO 8601 duration) if this is a recurring grant. Null for one-time grants." }, "idempotencyKey": { "type": "string", "nullable": true, "description": "The idempotency key used when creating this grant. Null if not provided." }, "resetMaxRollover": { "type": "number", "description": "Maximum balance carried over at the entitlement's reset boundary. A value of 999999999999 represents effectively unlimited rollover (the default for direct and purchase grants). A value of 0 means any remaining balance is discarded at each reset." }, "resetMinRollover": { "type": "number", "description": "Minimum balance at the entitlement's reset boundary; balances below this are floored up. 0 means no floor." }, "priority": { "type": "integer", "description": "Burn-down priority. Grants with a lower priority are consumed before grants with a higher priority; ties break on earliest expiration, then creation order. Defaults to 0." } } }, "CreateGrantRequest": { "type": "object", "required": [ "amount", "idempotencyKey" ], "properties": { "amount": { "type": "number", "exclusiveMinimum": 0, "description": "The number of credits to grant." }, "effectiveAt": { "type": "string", "format": "date-time", "description": "When the grant becomes effective. Defaults to now." }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When the grant expires. If omitted, the grant does not expire." }, "idempotencyKey": { "type": "string", "maxLength": 255, "description": "Idempotency key to prevent duplicate grants. Must be unique per entitlement." }, "resetMaxRollover": { "type": "number", "minimum": 0, "maximum": 999999999999, "description": "Maximum balance carried over at the entitlement's reset boundary. If omitted, the entire balance rolls over until consumed or expired. Set to 0 to discard any remaining balance at each reset. Ignored when the target entitlement has no `usagePeriod` (one-time entitlement) — one-time entitlements have no reset boundary, so this field has no effect." }, "resetMinRollover": { "type": "number", "minimum": 0, "maximum": 999999999999, "description": "Minimum balance at the entitlement's reset boundary; balances below this are floored up. Defaults to 0 (no floor). Ignored when the target entitlement has no `usagePeriod` (one-time entitlement)." }, "priority": { "type": "integer", "minimum": -32768, "maximum": 32767, "description": "Burn-down priority. Grants with a lower priority are consumed before grants with a higher priority; ties break on earliest expiration, then creation order. Negative values are allowed and can be used to make a grant burn ahead of existing priority-0 grants (e.g. a correction grant absorbing erroneous usage before a recurring allowance). Defaults to 0." } } }, "PurchaseGrantRequest": { "type": "object", "required": [ "amount", "price", "idempotencyKey" ], "properties": { "amount": { "type": "number", "exclusiveMinimum": 0, "exclusiveMaximum": 1000000000000, "multipleOf": 1e-8, "description": "The number of credits to grant upon payment completion." }, "price": { "type": "string", "pattern": "^\\d+(\\.\\d{1,9})?$", "description": "The price in decimal format (e.g., '5.00' for $5.00 USD). A non-negative decimal with at most 9 fractional digits (nanodollar precision). Must be at least $0.50 and must not exceed 4503599.62 (the maximum supported grant purchase amount)." }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Caller-provided deduplication key. Retrying with the same key returns the existing invoice." }, "effectiveAt": { "type": "string", "format": "date-time", "description": "When the grant becomes effective. Defaults to now." }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When the grant expires. If omitted, the grant does not expire." }, "successUrl": { "type": "string", "format": "uri", "description": "URL to redirect the customer to after successful payment." }, "cancelUrl": { "type": "string", "format": "uri", "description": "URL to redirect the customer to if payment is cancelled." }, "paymentExpiresAt": { "type": "string", "format": "date-time", "description": "When the payment session expires. If omitted, uses the default expiry." }, "resetMaxRollover": { "type": "number", "minimum": 0, "maximum": 999999999999, "description": "Maximum balance carried over at the entitlement's reset boundary. If omitted, the purchased grant balance rolls over until consumed or expired. Set to 0 to discard any remaining balance at each reset. Ignored when the target entitlement has no `usagePeriod` (one-time entitlement) — one-time entitlements have no reset boundary, so this field has no effect." }, "resetMinRollover": { "type": "number", "minimum": 0, "maximum": 999999999999, "description": "Minimum balance at the entitlement's reset boundary; balances below this are floored up. Defaults to 0 (no floor). Ignored when the target entitlement has no `usagePeriod` (one-time entitlement)." } } }, "PurchaseGrantResponse": { "type": "object", "required": [ "object", "invoiceId", "entitlementId", "grantAmount", "price", "currency", "paymentSessions" ], "properties": { "object": { "type": "string", "enum": [ "grant_purchase" ], "default": "grant_purchase" }, "invoiceId": { "type": "string", "pattern": "^inv_[a-f0-9]+$", "description": "The invoice ID for this grant purchase." }, "entitlementId": { "type": "string", "pattern": "^ent_[a-zA-Z0-9]+$", "description": "The entitlement that will receive the grant." }, "grantAmount": { "type": "number", "exclusiveMinimum": 0, "description": "The number of credits that will be granted on payment." }, "price": { "type": "string", "description": "The price in decimal format (e.g., '5.00')." }, "currency": { "type": "string", "description": "The three-letter ISO 4217 currency code (e.g., 'usd')." }, "paymentSessions": { "type": "array", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "The Stripe checkout URL for the customer to complete payment." }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When the payment session expires." }, "amount": { "type": "number", "description": "The payment amount in the currency's minor unit (e.g., cents)." } } }, "description": "Payment session(s) for the customer to complete the purchase." } } }, "Feature": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/FeatureId" }, "object": { "type": "string", "enum": [ "feature" ], "default": "feature" }, "key": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "metered", "static", "boolean" ] }, "merchantId": { "$ref": "#/components/schemas/OrganizationId" }, "productId": { "$ref": "#/components/schemas/ProductId" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the feature was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the feature was last updated" } }, "required": [ "id", "object", "key", "name", "type", "merchantId", "productId", "metadata", "createdAt", "updatedAt" ] }, "Fee": { "type": "object", "required": [ "id", "object", "name", "description", "merchantId", "productId", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "pattern": "^fee_[a-zA-Z0-9]+$" }, "object": { "type": "string", "enum": [ "fee" ], "default": "fee" }, "name": { "type": "string" }, "description": { "type": "string" }, "merchantId": { "$ref": "#/components/schemas/OrganizationId" }, "productId": { "$ref": "#/components/schemas/ProductId" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "schemas-PlanId": { "type": "string", "pattern": "^plan_[a-zA-Z0-9]+$", "description": "Unique identifier for a plan" }, "schemas-PriceId": { "type": "string", "pattern": "^price_[a-zA-Z0-9]+$", "description": "Unique identifier for a price" }, "PriceFeature": { "type": "object", "required": [ "id", "featureId", "entitlementTemplate" ], "properties": { "id": { "type": "string" }, "featureId": { "type": "string" }, "entitlementTemplate": { "type": "object", "additionalProperties": true }, "feature": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "metered", "static", "boolean" ] } } } } }, "Price": { "type": "object", "required": [ "id", "object", "merchantId", "model", "paymentTerm", "invoiceDisplayName", "properties", "createdAt", "updatedAt", "quantity" ], "properties": { "id": { "$ref": "#/components/schemas/schemas-PriceId" }, "object": { "type": "string", "enum": [ "price" ], "default": "price" }, "merchantId": { "$ref": "#/components/schemas/OrganizationId", "description": "The merchant organization that owns this price, derived from the associated fee or billable metric." }, "billableMetricId": { "type": "string" }, "feeId": { "type": "string", "pattern": "^fee_[a-zA-Z0-9]+$", "description": "The unique identifier for the fee referred to by this price" }, "billingCadence": { "type": "string", "nullable": true, "description": "ISO 8601 duration for billing frequency (e.g., P1M for monthly)" }, "createdAt": { "type": "string", "format": "date-time" }, "currency": { "type": "string" }, "description": { "type": "string" }, "invoiceDisplayName": { "type": "string" }, "model": { "type": "string", "enum": [ "standard", "dynamic", "volume", "percentage" ] }, "paymentTerm": { "type": "string", "enum": [ "in_arrears", "in_advance" ] }, "properties": { "type": "object", "additionalProperties": true }, "unitAmount": { "type": "string" }, "updatedAt": { "type": "string", "format": "date-time" }, "features": { "type": "array", "items": { "$ref": "#/components/schemas/PriceFeature" }, "description": "Features associated with this price" }, "grantDiscountEnabled": { "type": "boolean", "default": false, "description": "When true, grants applied to a subscription will discount usage charged by this price. Only supported for standard metered prices." }, "quantity": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1, "description": "Quantity used when generating invoice line items for this price. Total per period = quantity × unitPrice. Only supported for fee prices; metered prices derive quantity from usage. Defaults to 1." } } }, "WalletNamespaceId": { "type": "string", "description": "Unique identifier for a wallet namespace" }, "PricingUnitId": { "type": "string", "pattern": "^pu_[a-zA-Z0-9]+$", "description": "Unique identifier for a pricing unit" }, "PlanCreditAllocation": { "type": "object", "required": [ "pricingUnitId", "amount" ], "properties": { "pricingUnitId": { "$ref": "#/components/schemas/PricingUnitId", "description": "The pricing unit whose credit pool this allocation funds. Must belong to the plan's own merchant." }, "amount": { "type": "number", "exclusiveMinimum": 0, "description": "Number of credits minted into the customer's pool for this pricing unit each time the allocation is provisioned. Must be a positive number." }, "recurrencePeriod": { "type": "string", "description": "ISO 8601 duration (e.g. 'P1M') controlling how often the allocation's credits are re-minted on the customer's pool. Recurrence is opt-in: when omitted, the allocation is minted once at subscription activation and never refills — even on a recurring plan. Set this field explicitly for credits that should replenish each period." } } }, "PlanVersionId": { "type": "string", "pattern": "^pver_[a-zA-Z0-9]+$", "description": "Unique identifier for a plan version" }, "Plan": { "type": "object", "required": [ "id", "object", "name", "billingCadence", "billingInterval", "currency", "merchantId", "productId", "createdAt", "updatedAt" ], "properties": { "id": { "$ref": "#/components/schemas/schemas-PlanId" }, "object": { "type": "string", "enum": [ "plan" ] }, "billingCadence": { "type": "string", "enum": [ "P1M", "P3M", "P1Y" ], "description": "ISO 8601 duration for the billing period.", "default": "P1M" }, "billingInterval": { "type": "string", "deprecated": true, "x-speakeasy-deprecation-message": "Use billingCadence (ISO 8601 duration: P1M, P3M, P1Y) instead.", "description": "Deprecated. Human-readable billing period derived from billingCadence. Use billingCadence instead." }, "createdAt": { "type": "string", "format": "date-time" }, "currency": { "type": "string" }, "defaultTaxCode": { "type": "string", "description": "Default tax code for plan line items. Common values: 'eservice' (electronically supplied services), 'saas' (software as a service), 'consulting', 'ebook', 'standard', 'reduced', 'exempt'. Full list available via GET /tax/codes endpoint." }, "defaultTaxRate": { "type": "number", "description": "Fallback tax rate (as percentage) if automatic tax calculation is unavailable" }, "deletedAt": { "type": "string", "format": "date-time" }, "description": { "type": "string" }, "invoiceDisplayName": { "type": "string" }, "merchantId": { "$ref": "#/components/schemas/OrganizationId", "description": "The merchant organization that owns this plan" }, "name": { "type": "string" }, "paymentTerm": { "type": "object", "properties": { "in_arrears": { "type": "boolean" }, "in_advance": { "type": "boolean" } } }, "prices": { "type": "array", "items": { "$ref": "#/components/schemas/Price" } }, "productId": { "$ref": "#/components/schemas/ProductId", "description": "The product this plan belongs to" }, "taxBehavior": { "type": "string", "enum": [ "exclusive", "inclusive" ], "description": "Whether tax is added on top of the price (exclusive) or included in the price (inclusive)" }, "updatedAt": { "type": "string", "format": "date-time" }, "walletNamespaceId": { "$ref": "#/components/schemas/WalletNamespaceId" }, "renewalReminderEnabled": { "type": "boolean", "description": "Whether renewal reminder emails are enabled for subscriptions using this plan" }, "renewalReminderDays": { "type": "integer", "description": "Number of days before renewal to send the reminder email" }, "billingVersion": { "type": "integer", "description": "Billing engine version. Managed by Paygentic support." }, "billingAnchor": { "type": "string", "format": "date-time", "nullable": true, "description": "ISO 8601 datetime reference point for billing period alignment. Must be in the past or present at the time of creation or update. When set, all subscriptions created under this plan align their first billing period to the next recurrence of this anchor. Null means each subscription uses its own start time (hour-rounded) as the anchor." }, "creditAllocations": { "type": "array", "items": { "$ref": "#/components/schemas/PlanCreditAllocation" }, "description": "Credit-pool funding declarations for this plan. Each entry funds a distinct pricing unit's credit pool when a subscription to this plan activates: the allocated amount is minted as a credit grant on the customer's pool for that pricing unit, once at activation, or on a recurring basis only when that allocation explicitly sets recurrencePeriod. A plan may declare zero or more allocations; no two allocations on the same plan target the same pricingUnitId." }, "defaultVersionId": { "$ref": "#/components/schemas/PlanVersionId", "description": "The plan version currently served as the plan's live definition. New subscriptions pin to this version. Absent for plans that have never been versioned." }, "stablePriceIds": { "type": "boolean", "default": true, "description": "Governs price identity when a price on this plan's default version is replaced. When true (default), replacing a price at make-default keeps the original price id live (its value changes) and the superseded value is preserved under a new id. When false, the replacement price's id goes live instead and the superseded value stays under the original id." } } }, "PlanVersionSummary": { "type": "object", "required": [ "id", "object", "versionNumber", "status", "isDefault", "subscriptionCount" ], "properties": { "id": { "$ref": "#/components/schemas/PlanVersionId" }, "object": { "type": "string", "enum": [ "plan_version" ] }, "versionNumber": { "type": "integer", "minimum": 1, "description": "Monotonic version number within the plan, starting at 1." }, "status": { "type": "string", "enum": [ "draft", "published", "archived" ], "description": "Lifecycle status of the version." }, "publishedAt": { "type": "string", "format": "date-time", "description": "When this version was published. Absent for draft versions." }, "isDefault": { "type": "boolean", "description": "Whether this version is the plan's current default (live) version." }, "subscriptionCount": { "type": "integer", "minimum": 0, "description": "Number of committed-status subscriptions (active or pending payment) pinned to this version at creation time. This is a count of pins recorded when each subscription was created, not a live-billing cohort: for billing, subscriptions follow the plan's current default version regardless of the version they were pinned to." } } }, "MintPlanVersionRequest": { "type": "object", "additionalProperties": false, "description": "A reference-by-id price diff applied to the plan's current default version to mint a draft. Every id references an existing price created via POST /prices; inline price definitions are not accepted. An empty body clones the current default version verbatim.", "properties": { "addPrices": { "type": "array", "items": { "$ref": "#/components/schemas/schemas-PriceId" }, "description": "Prices to add to the version. Each must not already be on the current version." }, "removePrices": { "type": "array", "items": { "$ref": "#/components/schemas/schemas-PriceId" }, "description": "Prices to remove. Each must be on the plan's current default version." }, "replacePrices": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "replacesPriceId", "withPriceId" ], "properties": { "replacesPriceId": { "$ref": "#/components/schemas/schemas-PriceId" }, "withPriceId": { "$ref": "#/components/schemas/schemas-PriceId" } } }, "description": "Prices to swap in place, preserving the slot's lineage. replacesPriceId must be on the current version; withPriceId is the new price." } } }, "PlanVersionPriceSlot": { "description": "One price slot on a plan version. Every `Price` field is present; two are addressing/repair markers layered on top. On a `stablePriceIds` plan, `id` may be the plan's stable (current-default) price id rather than this slot's own not-yet-promoted price row — address this slot in further requests using this `id`.", "allOf": [ { "$ref": "#/components/schemas/Price" }, { "type": "object", "required": [ "priceDeleted" ], "properties": { "priceDeleted": { "type": "boolean", "description": "True when the underlying price this slot references has been soft-deleted. The slot can still be removed or replaced to repair the draft; it cannot be published while any slot remains dead." } } } ] }, "PlanVersion": { "type": "object", "description": "A single plan version, including its price slots. Extends the list summary with the version's prices for draft review.", "required": [ "id", "object", "versionNumber", "status", "isDefault", "subscriptionCount", "updatedAt", "prices" ], "properties": { "id": { "$ref": "#/components/schemas/PlanVersionId" }, "object": { "type": "string", "enum": [ "plan_version" ] }, "versionNumber": { "type": "integer", "minimum": 1, "description": "Monotonic version number within the plan, starting at 1." }, "status": { "type": "string", "enum": [ "draft", "published", "archived" ], "description": "Lifecycle status of the version." }, "publishedAt": { "type": "string", "format": "date-time", "description": "When this version was published. Absent for draft versions." }, "isDefault": { "type": "boolean", "description": "Whether this version is the plan's current default (live) version." }, "subscriptionCount": { "type": "integer", "minimum": 0, "description": "Number of committed-status subscriptions pinned to this version at creation time. Not a live-billing cohort." }, "basedOnVersionId": { "$ref": "#/components/schemas/PlanVersionId", "description": "The version this one was cloned from at mint time. Absent for versions minted before this field existed or through the legacy fused write path. Used to detect a superseded base when moving the default." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When this version was last modified. Optimistic-concurrency token: read this value and echo it back as an `If-Match` header on a draft-price-mutation request to reject the write (412) if the draft changed since this read." }, "prices": { "type": "array", "items": { "$ref": "#/components/schemas/PlanVersionPriceSlot" }, "description": "The price slots that make up this version." } } }, "TransitionPlanVersionRequest": { "type": "object", "additionalProperties": false, "description": "A lifecycle transition for a plan version. Supply status and/or default.", "minProperties": 1, "properties": { "status": { "type": "string", "enum": [ "published" ], "description": "Set to published to promote a draft. Idempotent on an already-published version." }, "default": { "type": "boolean", "description": "Set to true to point the plan's default at this version. Requires the version to be (or become) published. Idempotent on the already-default version." } } }, "AddDraftVersionPriceRequest": { "type": "object", "additionalProperties": false, "description": "Adds a single price to a draft version's own current slots. The price must not already be on the draft.", "required": [ "priceId" ], "properties": { "priceId": { "$ref": "#/components/schemas/schemas-PriceId" } } }, "EditDraftVersionPricesRequest": { "type": "object", "additionalProperties": false, "description": "A batch reference-by-id price diff applied to a draft version's own current slots. Every id references an existing price created via POST /prices; inline price definitions are not accepted. An empty diff is a no-op.", "properties": { "addPrices": { "type": "array", "items": { "$ref": "#/components/schemas/schemas-PriceId" }, "description": "Prices to add to the draft. Each must not already be on the draft's current slots." }, "removePrices": { "type": "array", "items": { "$ref": "#/components/schemas/schemas-PriceId" }, "description": "Prices to remove. Each must be on the draft's current slots." }, "replacePrices": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "replacesPriceId", "withPriceId" ], "properties": { "replacesPriceId": { "$ref": "#/components/schemas/schemas-PriceId" }, "withPriceId": { "$ref": "#/components/schemas/schemas-PriceId" } } }, "description": "Prices to swap in place, preserving the slot's lineage. replacesPriceId must be on the draft's current slots; withPriceId is the new price." } } }, "ReplaceDraftVersionPriceRequest": { "type": "object", "additionalProperties": false, "description": "Swaps the price at the path's priceId slot for withPriceId on a draft version, preserving the slot's lineage. withPriceId must differ from the path priceId.", "required": [ "withPriceId" ], "properties": { "withPriceId": { "$ref": "#/components/schemas/schemas-PriceId" } } }, "PriceModel": { "type": "string", "enum": [ "standard", "dynamic", "volume", "percentage" ], "x-speakeasy-unknown-values": "allow", "description": "Pricing model of a price as returned by the API. Includes legacy models ('dynamic', 'volume', 'percentage') retained for existing prices; only 'standard' can be created (see PriceModelInput)." }, "PriceProperties": { "type": "object", "oneOf": [ { "type": "object", "description": "Standard pricing model", "properties": { "unitPrice": { "type": "string", "description": "Per-unit cost in decimal format for fixed-rate pricing. Sample values: '0.00002' represents $0.00002 per token, '0.15' represents $0.15 per gigabyte stored, '0.05' represents $0.05 per API call. Per unit. Total per period = quantity × unitPrice; see the `quantity` field." } }, "required": [ "unitPrice" ] }, { "type": "object", "description": "Dynamic pricing model", "properties": { "maxPrice": { "type": "string", "description": "Upper limit of the price range for dynamic pricing. Sample values: '0.10' means $0.10 per token for large volumes at peak times" }, "minPrice": { "type": "string", "description": "Lower limit of the price range for dynamic pricing. Sample values: '0.01' means $0.01 per token for low volumes during off-peak hours" } }, "required": [ "maxPrice", "minPrice" ] }, { "type": "object", "description": "Volume pricing model", "properties": { "default": { "type": "string", "description": "Default value for volume pricing" }, "parameters": { "type": "object", "additionalProperties": false, "required": [ "function", "gradient", "min", "max" ], "properties": { "function": { "type": "string", "enum": [ "linear" ], "description": "Function used for volume pricing calculations" }, "gradient": { "type": "string", "description": "Gradient for volume pricing calculations" }, "max": { "type": "string", "description": "Maximum value for volume pricing" }, "min": { "type": "string", "description": "Minimum value for volume pricing" } } } }, "required": [ "parameters", "default" ] }, { "type": "object", "description": "Percentage pricing model", "properties": { "maxCharge": { "type": "string", "description": "Ceiling amount limiting total charge regardless of percentage calculation. Sample values: '500.00' caps fees at $500 maximum, '2000.00' limits charges to $2000 per period" }, "minCharge": { "type": "string", "description": "Floor amount charged regardless of percentage calculation. Sample values: '5.00' ensures minimum $5 fee, '25.00' guarantees at least $25 per billing event" }, "percentage": { "type": "string", "pattern": "^([0-9](\\.[0-9]{1,4})?|10(\\.0{1,4})?)$", "description": "Rate expressed as decimal between 0 and 10, supporting up to 4 decimal precision. Sample values: '0.03' represents 3%, '0.075' represents 7.5%, '1.10' represents 110%" } }, "required": [ "percentage", "minCharge", "maxCharge" ] } ] }, "PriceQuantity": { "type": "integer", "minimum": 0, "description": "Quantity for invoice line items. Total per period = quantity × unitPrice. Only supported for fee prices; metered prices derive quantity from usage. Defaults to 1." }, "schemas-Price": { "type": "object", "required": [ "id", "object", "merchantId", "invoiceDisplayName", "paymentTerm", "properties", "createdAt", "updatedAt", "quantity" ], "properties": { "id": { "$ref": "#/components/schemas/PriceId" }, "object": { "type": "string", "enum": [ "price" ], "default": "price" }, "billableMetricId": { "$ref": "#/components/schemas/BillableMetricId" }, "feeId": { "type": "string", "pattern": "^fee_[a-zA-Z0-9]+$", "description": "The unique identifier for the fee referred to by this price. Present when price is linked to a fee." }, "pricingUnitId": { "$ref": "#/components/schemas/PricingUnitId", "description": "The pricing unit this price is denominated in (credits). Present when the price draws down a credit pool instead of charging real currency." }, "merchantId": { "$ref": "#/components/schemas/OrganizationId", "description": "The merchant organization that owns this price, derived from the associated fee or billable metric. Present on single-price reads." }, "billingCadence": { "type": "string", "description": "ISO 8601 duration. 'P0D' for one-time, 'P1M' for monthly, 'P1Y' for yearly. Required for fees, optional for billable metrics. Defaults to plan's billingCadence if not specified.", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "invoiceDisplayName": { "type": "string" }, "model": { "$ref": "#/components/schemas/PriceModel" }, "paymentTerm": { "type": "string", "enum": [ "in_arrears", "in_advance" ] }, "properties": { "$ref": "#/components/schemas/PriceProperties" }, "updatedAt": { "type": "string", "format": "date-time" }, "features": { "type": "array", "items": { "$ref": "#/components/schemas/PriceFeature" }, "description": "Features associated with this price" }, "grantDiscountEnabled": { "type": "boolean", "default": false, "description": "When true, grants applied to a subscription will discount usage charged by this price. Only supported for standard metered prices." }, "quantity": { "$ref": "#/components/schemas/PriceQuantity" } } }, "PriceModelInput": { "type": "string", "enum": [ "standard" ], "description": "Pricing model accepted when creating or updating a price. Only 'standard' is creatable. Percentage-style and revenue-share pricing are expressed with 'standard' plus a unit-price multiplier (e.g. 10% ⇒ unitPrice '0.1'). The legacy 'dynamic', 'volume', and 'percentage' models remain billable and readable on existing prices but can no longer be created." }, "PriceFeatureInput": { "type": "object", "required": [ "featureId" ], "properties": { "featureId": { "type": "string", "pattern": "^feat_[a-zA-Z0-9]+$", "description": "The feature to associate with this price" }, "entitlementTemplate": { "type": "object", "additionalProperties": true, "description": "Template for entitlement values when this feature is provisioned" } } }, "Product": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/ProductId" }, "object": { "type": "string", "enum": [ "product" ], "default": "product" }, "createdAt": { "type": "string", "format": "date-time" }, "description": { "type": "string" }, "merchantId": { "$ref": "#/components/schemas/OrganizationId", "description": "The merchant organization that owns this product" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } }, "name": { "type": "string" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "object", "name", "description", "merchantId", "metadata", "createdAt", "updatedAt" ] }, "Source": { "type": "object", "required": [ "id", "planId", "merchantId", "object", "type", "name", "enabled", "processingMode", "createdAt", "updatedAt" ], "properties": { "id": { "$ref": "#/components/schemas/SourceId" }, "object": { "type": "string", "enum": [ "source" ] }, "config": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "description": { "type": "string" }, "enabled": { "type": "boolean" }, "merchantId": { "$ref": "#/components/schemas/OrganizationId" }, "metadata": { "type": "object", "additionalProperties": true }, "name": { "type": "string" }, "planId": { "$ref": "#/components/schemas/PlanId" }, "processingMode": { "type": "string", "enum": [ "automatic", "manual" ] }, "type": { "type": "string", "enum": [ "stripe_revenue" ] }, "updatedAt": { "type": "string", "format": "date-time" } } }, "SourceEvent": { "type": "object", "required": [ "id", "sourceId", "externalEventId", "status", "rawData", "createdAt", "updatedAt" ], "properties": { "id": { "$ref": "#/components/schemas/SourceEventId" }, "createdAt": { "type": "string", "format": "date-time" }, "customerId": { "type": "string", "description": "The customer associated with this source event" }, "errorMessage": { "type": "string" }, "externalEventId": { "type": "string" }, "processedAt": { "type": "string", "format": "date-time" }, "processedBy": { "type": "string" }, "rawData": { "type": "object", "additionalProperties": true }, "sourceId": { "$ref": "#/components/schemas/SourceId" }, "status": { "type": "string", "enum": [ "pending", "processed", "failed", "rejected" ] }, "subscriptionId": { "type": "string", "description": "The subscription associated with this source event" }, "updatedAt": { "type": "string", "format": "date-time" }, "usageEventIds": { "type": "array", "items": { "type": "string" } } } }, "RuleCondition": { "type": "object", "description": "A single condition that must be met for a rule to trigger auto-acceptance. Multiple conditions in a rule use AND logic.", "required": [ "type", "operator", "value" ], "properties": { "operator": { "type": "string", "enum": [ "equals", "contains", "between", "greaterThan", "lessThan", "domain" ], "description": "The comparison operator to use" }, "type": { "type": "string", "enum": [ "date", "customerName", "customerEmail", "amount" ], "description": "The type of field to evaluate" }, "value": { "description": "The value to compare against", "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "object", "properties": { "from": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "to": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "required": [ "from", "to" ], "additionalProperties": false } ] } } }, "SourceRule": { "type": "object", "description": "An auto-acceptance rule that automatically approves source events matching specified conditions. Rules help automate the approval process for trusted customers or specific transaction patterns.", "required": [ "id", "sourceId", "name", "description", "conditions", "enabled", "order", "evaluationCount", "matchCount", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "description": "Unique identifier for the rule" }, "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/RuleCondition" }, "description": "List of conditions that must ALL be met (AND logic)" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the rule was created" }, "createdBy": { "type": "string", "nullable": true, "description": "User ID who created the rule" }, "description": { "type": "string", "description": "Detailed description of what this source rule does" }, "enabled": { "type": "boolean", "description": "Whether this rule is currently active" }, "evaluationCount": { "type": "integer", "description": "Total number of times this rule has been evaluated" }, "lastEvaluatedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Last time this rule was evaluated against an invoice" }, "matchCount": { "type": "integer", "description": "Number of times this rule has matched and auto-accepted an invoice" }, "name": { "type": "string", "description": "Human-readable name for the source rule" }, "order": { "type": "integer", "description": "Priority order for rule evaluation (lower numbers are evaluated first)" }, "sourceId": { "type": "string", "description": "ID of the source this rule belongs to" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the rule was last updated" } } }, "CreateRuleRequest": { "type": "object", "required": [ "sourceId", "name", "conditions" ], "properties": { "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/RuleCondition" }, "minItems": 1, "maxItems": 10, "description": "Conditions that must ALL be met (AND logic) for auto-acceptance. Sample values: customerEmail domain='@trusted.com' AND amount lessThan=1000, customerId equals='org_abc123' AND billableMetricId equals='bm_tokens', subscriptionId equals='sub_xyz789' AND quantity greaterThan=100" }, "description": { "type": "string", "description": "Detailed description of what this source rule does" }, "enabled": { "type": "boolean", "default": true, "description": "Whether this rule should be active immediately" }, "name": { "type": "string", "description": "Human-readable name for the source rule" }, "order": { "type": "integer", "default": 0, "minimum": 0, "description": "Evaluation priority (0-999). Lower numbers are evaluated first. First matching rule triggers auto-acceptance." }, "sourceId": { "$ref": "#/components/schemas/SourceId" } } }, "UpdateRuleRequest": { "type": "object", "properties": { "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/RuleCondition" }, "description": "List of conditions that must ALL be met (AND logic)" }, "description": { "type": "string", "description": "Detailed description of what this source rule does" }, "enabled": { "type": "boolean", "description": "Whether this rule should be active" }, "name": { "type": "string", "description": "Human-readable name for the source rule" }, "order": { "type": "integer", "description": "Priority order for rule evaluation (lower numbers are evaluated first)" } } }, "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" }, "planVersionId": { "type": "string", "description": "The plan version pinned to this subscription at creation." }, "versionNumber": { "type": "integer", "minimum": 1, "description": "The version number of the plan version referenced by planVersionId, as of subscription creation." }, "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" ] } } } } }, "SubscriptionPortal": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "subscriptionPortal" ] }, "expiresAt": { "type": "string", "format": "date-time", "description": "Portal link expiration timestamp in ISO 8601 format. Sample values: '2024-01-15T23:59:59Z', '2024-02-01T12:00:00Z'" }, "url": { "type": "string", "format": "uri", "description": "Secure portal access URL for customer subscription management. Sample values: 'https://portal.paygentic.com/sub/abc123?token=xyz789', 'https://customer.example.com/portal/sub_456def'" } }, "required": [ "object", "url", "expiresAt" ] }, "ReconciledFeatureAdded": { "type": "object", "properties": { "featureId": { "type": "string" }, "featureKey": { "type": "string" }, "billed": { "type": "boolean", "description": "False when this feature's price never produces a recurring line item (a credit-denominated price, or an already-elapsed one-time charge) — the feature is entitled but not billed by this reconciliation." } }, "required": [ "featureId", "featureKey", "billed" ] }, "ReconciledFeatureSkipped": { "type": "object", "properties": { "featureId": { "type": "string" }, "featureKey": { "type": "string" } }, "required": [ "featureId", "featureKey" ] }, "ReconciledFeatureRemoved": { "type": "object", "properties": { "featureId": { "type": "string" }, "featureKey": { "type": "string" } }, "required": [ "featureId", "featureKey" ] }, "ReconciledFeatureFailed": { "type": "object", "properties": { "featureId": { "type": "string" }, "featureKey": { "type": "string" }, "reason": { "type": "string", "enum": [ "entitlement_failed", "grant_mint_failed" ], "description": "Coded failure reason. `grant_mint_failed` means the entitlement was created but its initial metered grant could not be minted; re-running this reconciliation retries the mint." } }, "required": [ "featureId", "featureKey", "reason" ] }, "SubscriptionReconciliation": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "subscriptionReconciliation" ] }, "dryRun": { "type": "boolean", "description": "True when this reconciliation was a preview — no entitlement, grant, or line item was created." }, "features": { "type": "object", "properties": { "added": { "type": "array", "items": { "$ref": "#/components/schemas/ReconciledFeatureAdded" } }, "skipped": { "type": "array", "description": "Features the subscription already had an active entitlement for — left unchanged.", "items": { "$ref": "#/components/schemas/ReconciledFeatureSkipped" } }, "removed": { "type": "array", "description": "Features no longer on the plan: their entitlement was canceled and grants voided so the subscription matches the plan's current features.", "items": { "$ref": "#/components/schemas/ReconciledFeatureRemoved" } }, "failed": { "type": "array", "description": "Features that could not be fully provisioned. Never billed by this call.", "items": { "$ref": "#/components/schemas/ReconciledFeatureFailed" } } }, "required": [ "added", "skipped", "removed", "failed" ] }, "lineItems": { "type": "object", "properties": { "created": { "type": "integer", "description": "Number of features newly billed on the subscription by this reconciliation. A dry-run preview returns the same count as the applied run." }, "removed": { "type": "integer", "description": "Number of features whose billing was removed from the subscription's upcoming (not-yet-invoiced) invoice because their price is no longer on the plan." }, "syncFailed": { "type": "boolean", "description": "True when entitlements were provisioned successfully but the line-item synchronization step failed. Safe to retry." } }, "required": [ "created", "removed" ] } }, "required": [ "object", "dryRun", "features", "lineItems" ] }, "UserId": { "type": "string", "pattern": "^usr_[a-zA-Z0-9]+$", "description": "Unique identifier for a user" }, "User": { "type": "object", "required": [ "id", "object", "email", "oryId", "createdAt", "updatedAt", "organizations" ], "properties": { "id": { "$ref": "#/components/schemas/UserId" }, "object": { "type": "string", "enum": [ "user" ], "default": "user" }, "address": { "$ref": "#/components/schemas/Address" }, "createdAt": { "type": "string", "format": "date-time" }, "dateOfBirth": { "type": "string", "format": "date" }, "email": { "type": "string", "format": "email" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "organizations": { "type": "array", "items": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/OrganizationId" }, "state": { "type": "string", "enum": [ "invited", "active", "suspended", "declined" ] }, "roles": { "type": "array", "items": { "type": "string" }, "description": "Roles assigned to the user in this organization." } } } }, "oryId": { "type": "string" }, "phone": { "type": "string" }, "type": { "type": "string", "enum": [ "COMPANY", "INDIVIDUAL" ] }, "updatedAt": { "type": "string", "format": "date-time" } } }, "InvoiceLineItem": { "type": "object", "required": [ "eventType", "eventId", "eventSourceId", "billableMetricId", "quantity", "unitPrice", "totalPrice", "taxRate", "totalTax", "totalAmount", "meterEventId", "metricName", "metricDescription", "metricUnit", "invoiceDisplayName", "lineItemType" ], "properties": { "eventType": { "type": "string", "enum": [ "usage", "fee", "discount" ], "description": "Type of event: 'usage' for billable metric events, 'fee' for fee events, 'discount' for grant discount line items (subtotal/total are negative, representing a credit)" }, "eventId": { "type": "string", "description": "The event ID (usage_event_id or fee_event_id)" }, "eventSourceId": { "type": "string", "description": "Source ID: billable_metric_id for usage events, fee_id for fee events" }, "billableMetricId": { "type": "string", "description": "HOTFIX: Mirrors eventSourceId for backward compatibility" }, "invoiceDisplayName": { "type": "string", "description": "Display name for this line item on invoices" }, "lineItemType": { "type": "string", "enum": [ "charge", "refund" ], "description": "Type of line item: 'charge' for regular billing, 'refund' for refunded items (amounts are negated)" }, "meterEventId": { "type": "string", "description": "The meter event ID (usage events only)" }, "metricDescription": { "type": "string", "description": "Description of what this metric or fee measures" }, "metricName": { "type": "string", "description": "Human-readable name of the billable metric or fee" }, "metricUnit": { "type": "string", "description": "Measurement unit label. Sample values: 'calls' for API calls, 'GB' for storage, 'hours' for compute time, 'tokens' for LLM tokens, 'charge' for fees" }, "quantity": { "type": "number", "description": "Quantity of usage. Negative for refunds." }, "taxRate": { "type": "number", "description": "Tax rate as decimal (0.10 = 10%)" }, "totalAmount": { "type": "string", "description": "Total amount (totalPrice + totalTax) in decimal dollars. Negative for refunds." }, "totalPrice": { "type": "string", "description": "Total price (tax-exclusive) in decimal dollars. Negative for refunds." }, "totalTax": { "type": "string", "description": "Total tax in decimal dollars. Negative for refunds." }, "unitPrice": { "type": "string", "description": "Unit price in decimal dollars" } } }, "Invoice": { "type": "object", "properties": { "id": { "type": "string", "description": "The invoice ID" }, "object": { "type": "string", "enum": [ "invoice" ], "description": "The object type" }, "autoApprove": { "type": "boolean", "description": "Whether this invoice auto-approves after calculation" }, "billingAnchor": { "type": "string", "format": "date-time", "description": "The billing anchor date used for period calculations" }, "billingCadence": { "type": "string", "description": "ISO 8601 duration string for billing frequency" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the invoice was created" }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g., USD, EUR)" }, "failureReason": { "type": "string", "description": "Machine-readable reason code for the most recent failure (e.g. CALCULATION_FAILED). Present only when status is FAILED or PAYMENT_FAILED." }, "paymentInFlight": { "type": "boolean", "description": "Whether a payment for this invoice is currently being processed (the payment session is in the 'processing' state). Clients should not offer manual 'mark as paid' while true. Only populated by GET /invoices/{id}." }, "gracePeriodEnd": { "type": "string", "format": "date-time", "description": "The end of the grace period for accepting usage events" }, "grandTotal": { "type": "string", "description": "Grand total (subtotal + tax) in decimal dollars (real-time for ACTIVE/CLOSING/CLOSED, cached otherwise)" }, "invoiceNumber": { "type": "string", "nullable": true, "description": "The invoice number" }, "itemCount": { "type": "integer", "description": "Number of billing items (real-time for ACTIVE/CLOSING/CLOSED, cached otherwise)" }, "lineItems": { "type": "object", "nullable": true, "description": "Line items (only present if expand=lineItems query parameter is provided)", "properties": { "invoiceId": { "type": "string", "description": "The invoice ID" }, "lineItems": { "type": "array", "description": "Array of line items for this page", "items": { "$ref": "#/components/schemas/InvoiceLineItem" } }, "nextPageToken": { "type": "string", "nullable": true, "description": "Token for fetching the next page, null if no more pages" }, "totalCount": { "type": "integer", "description": "Total number of line items across all pages" } }, "required": [ "invoiceId", "lineItems", "totalCount" ] }, "merchantId": { "type": "string", "description": "The merchant organization ID" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Additional metadata including transition history" }, "nextActionAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When the next scheduled action should occur" }, "paidAmount": { "type": "string", "description": "Amount already paid via wallet (account_type='main') in decimal dollars" }, "paidAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When the invoice was paid (null if not yet paid)" }, "dueAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Payment due date snapshotted at invoice-create time as the issue date + subscription.paymentTermDays, anchored to midnight UTC. Null only for invoices created before this feature shipped (no backfill)." }, "paymentUrl": { "type": "string", "format": "uri", "nullable": true, "description": "Payment URL for completing payment (only present when status is ISSUED and unpaidAmount > 0)" }, "pdfUrl": { "type": "string", "format": "uri", "nullable": true, "description": "Direct PDF download link for tax invoice" }, "periodEnd": { "type": "string", "format": "date-time", "description": "The end of the billing period" }, "periodStart": { "type": "string", "format": "date-time", "description": "The start of the billing period" }, "permalink": { "type": "string", "format": "uri", "nullable": true, "description": "Public URL to view tax invoice" }, "sequenceNumber": { "type": "integer", "description": "The sequence number of this invoice period" }, "status": { "type": "string", "enum": [ "ACTIVE", "CLOSING", "CLOSED", "CALCULATING", "DRAFT", "ISSUED", "PAYMENT_FAILED", "PAID", "CANCELLED", "WRITTEN_OFF", "FAILED" ], "description": "The current status of the invoice" }, "subscriptionId": { "type": "string", "description": "The subscription ID this invoice belongs to" }, "customerId": { "type": "string", "description": "The customer ID that owns this invoice" }, "subtotal": { "type": "string", "description": "Subtotal in decimal dollars (real-time for ACTIVE/CLOSING/CLOSED, cached otherwise)" }, "tax": { "type": "object", "nullable": true, "description": "Tax reconciliation metadata (only present when plan has taxEnabled)", "properties": { "actualTax": { "type": "string", "description": "Actual tax calculated (in atomic units)" }, "adjustmentApplied": { "type": "boolean", "description": "Whether wallet adjustment was applied during tax reconciliation" }, "adjustmentNeeded": { "type": "boolean", "description": "Whether wallet adjustment is needed (difference >= $0.01)" }, "difference": { "type": "string", "description": "Difference between actual and estimated (in atomic units)" }, "estimatedTax": { "type": "string", "description": "Tax estimated from subscription rate (in atomic units)" }, "reconciled": { "type": "boolean", "description": "Whether reconciliation was performed" }, "reconciledAt": { "type": "string", "format": "date-time", "description": "When reconciliation occurred" } } }, "totalTax": { "type": "string", "description": "Total tax in decimal dollars (real-time for ACTIVE/CLOSING/CLOSED, cached otherwise)" }, "unpaidAmount": { "type": "string", "description": "Amount accrued as liability (account_type='usage') in decimal dollars" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the invoice was last updated" } }, "required": [ "id", "merchantId", "object", "subscriptionId", "customerId", "sequenceNumber", "status", "currency", "periodStart", "periodEnd", "gracePeriodEnd", "billingAnchor", "billingCadence", "autoApprove", "itemCount", "subtotal", "totalTax", "grandTotal", "paidAmount", "unpaidAmount", "createdAt", "updatedAt" ] }, "LineItem": { "type": "object", "required": [ "id", "subscriptionId", "customerId", "type", "status", "displayName", "currency", "periodStart", "periodEnd", "invoiceAt", "unitPrice", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "description": "The line item ID" }, "subscriptionId": { "type": "string", "description": "The subscription this line item belongs to" }, "customerId": { "type": "string", "description": "The customer ID that owns this line item" }, "priceId": { "type": "string", "nullable": true, "description": "The price ID associated with this line item" }, "invoiceId": { "type": "string", "nullable": true, "description": "The invoice ID if this item has been invoiced" }, "type": { "type": "string", "enum": [ "fee", "metered", "manual", "discount" ], "description": "The type of line item. 'discount' line items represent grant discounts with negative subtotal/total amounts." }, "status": { "type": "string", "enum": [ "pending", "invoiced" ], "description": "Whether this item is pending or already on an invoice" }, "displayName": { "type": "string", "description": "Human-readable label shown on the invoice" }, "description": { "type": "string", "nullable": true, "description": "Optional longer description" }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g., USD)" }, "periodStart": { "type": "string", "format": "date-time", "description": "Start of the billing period (inclusive)" }, "periodEnd": { "type": "string", "format": "date-time", "description": "End of the billing period (exclusive)" }, "invoiceAt": { "type": "string", "format": "date-time", "description": "When this line item should be collected into an invoice" }, "calculatedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When metered quantity was last computed" }, "quantity": { "type": "string", "nullable": true, "description": "Units sold. Null for metered lines until invoice close" }, "unitPrice": { "type": "string", "description": "Price per unit in invoice currency" }, "meteredQuantity": { "type": "string", "nullable": true, "description": "Raw metered usage. Null for fee/manual lines" }, "paymentTerm": { "type": "string", "enum": [ "in_advance", "in_arrears" ], "nullable": true, "description": "Payment term for fee items. Null for metered/manual lines" }, "subtotal": { "type": "string", "description": "quantity × unitPrice, before discounts and taxes. For prorated lines, may differ from `quantity × unitPrice` by display precision; subtotal is the authoritative billed amount. Defaults to '0.00' when not yet calculated." }, "taxesTotal": { "type": "string", "nullable": true, "description": "Total tax amount for this line item in decimal format. Null until invoice calculation is complete" }, "total": { "type": "string", "description": "Final total after discounts and taxes. Defaults to '0.00' when not yet calculated" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the line item was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the line item was last updated" }, "estimatedMeteredQuantity": { "type": "string", "nullable": true, "description": "Real-time estimated metered usage quantity. Only present for type=metered items during an active billing period. Null for fee/manual items or when estimation is unavailable." }, "estimatedSubtotal": { "type": "string", "nullable": true, "description": "Real-time estimated subtotal based on current metered usage. Only present for type=metered items during an active billing period. Null for fee/manual items or when estimation is unavailable." } } }, "LineItemsSummary": { "type": "object", "required": [ "feeSubtotal", "meteredEstimatedSubtotal", "currency" ], "properties": { "feeSubtotal": { "type": "string", "description": "Sum of fee items with known subtotals in decimal format" }, "meteredEstimatedSubtotal": { "type": "string", "description": "Sum of estimated metered amounts in decimal format" }, "currency": { "type": "string", "description": "ISO 4217 currency code" } } }, "LineItemsResponse": { "type": "object", "required": [ "object", "data", "totalCount", "summary" ], "properties": { "object": { "type": "string", "enum": [ "list" ], "description": "The object type" }, "data": { "type": "array", "description": "Array of line items", "items": { "$ref": "#/components/schemas/LineItem" } }, "totalCount": { "type": "integer", "description": "Total number of matching line items" }, "summary": { "$ref": "#/components/schemas/LineItemsSummary", "description": "Aggregate summary of line item amounts" } } }, "CreateManualLineItemRequest": { "type": "object", "required": [ "displayName", "currency", "quantity", "unitPrice" ], "properties": { "subscriptionId": { "type": "string", "description": "The subscription ID. Exactly one of subscriptionId or invoiceId must be provided." }, "invoiceId": { "type": "string", "pattern": "^inv_[a-zA-Z0-9]+$", "description": "The invoice ID to attach this item directly to. Exactly one of subscriptionId or invoiceId must be provided. The invoice must be in ACTIVE or CLOSING state." }, "displayName": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Human-readable label shown on the invoice." }, "description": { "type": "string", "maxLength": 1000, "nullable": true, "description": "Optional longer description shown on the invoice." }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code (e.g., USD). Must match the subscription or invoice currency." }, "quantity": { "type": "number", "exclusiveMinimum": 0, "description": "Number of units." }, "unitPrice": { "type": "number", "description": "Price per unit as a decimal amount (e.g., 29.99 for $29.99). Can be negative for credits or adjustments." }, "invoiceAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When to collect this item into an invoice. Defaults to now. Ignored when invoiceId is provided." }, "periodStart": { "type": "string", "format": "date-time", "nullable": true, "description": "Start of the billing period for display purposes. Defaults to now." }, "periodEnd": { "type": "string", "format": "date-time", "nullable": true, "description": "End of the billing period for display purposes. Defaults to now." }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 255, "nullable": true, "description": "Optional caller-provided idempotency key. Auto-generated if not provided." } } }, "InvoiceLineItemsResponse": { "type": "object", "required": [ "invoiceId", "lineItems", "totalCount" ], "properties": { "invoiceId": { "type": "string", "description": "The invoice ID" }, "lineItems": { "type": "array", "description": "Array of line items for this page", "items": { "$ref": "#/components/schemas/InvoiceLineItem" } }, "nextPageToken": { "type": "string", "nullable": true, "description": "Token for fetching the next page, null if no more pages" }, "totalCount": { "type": "integer", "description": "Total number of line items across all pages" } } }, "Payment": { "type": "object", "required": [ "id", "object", "amount", "currency", "status", "createdAt" ], "properties": { "id": { "type": "string", "description": "Unique payment identifier (pay_* prefixed)." }, "object": { "type": "string", "enum": [ "payment" ], "default": "payment" }, "amount": { "type": "string", "description": "Payment amount in decimal format (e.g. '10.50')." }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. 'USD')." }, "paymentUrl": { "type": "string", "description": "URL for the customer to complete the payment." }, "customerId": { "type": "string", "description": "Customer ID if provided." }, "idempotencyKey": { "type": "string", "description": "Client-provided idempotency key." }, "reference": { "type": "string", "description": "Merchant-defined reference for this payment." }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Merchant-provided key-value metadata." }, "lineItems": { "type": "array", "description": "Breakdown of what the customer is being charged for.", "items": { "type": "object", "properties": { "description": { "type": "string" }, "amount": { "type": "string" }, "quantity": { "type": "integer" } } } }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "expired", "cancelled" ], "description": "Current status of the payment." }, "expiresAt": { "type": "string", "format": "date-time", "description": "When the payment expires." }, "createdAt": { "type": "string", "format": "date-time", "description": "When the payment was created." } } }, "schemas-PaymentSession": { "type": "object", "required": [ "object", "id", "entityType", "entityId", "amount", "currency", "status", "createdAt", "updatedAt" ], "properties": { "object": { "type": "string", "enum": [ "payment_session" ] }, "id": { "type": "string", "description": "Payment session ID (ps_*)." }, "entityType": { "type": "string", "description": "Type of entity the session pays for (invoice, subscription, payment, topup)." }, "entityId": { "type": "string", "description": "ID of the entity the session pays for." }, "entityLabel": { "type": "string", "nullable": true, "description": "Display label for the entity — invoice number, payment-link reference, or subscription name. Null when no label is available." }, "amount": { "type": "string", "description": "Amount in decimal dollars." }, "currency": { "type": "string", "description": "ISO 4217 currency code." }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed", "expired", "cancelled" ], "description": "Lifecycle status of the session." }, "merchantPaymentAccountId": { "type": "string", "nullable": true, "description": "Stripe Connect account ID (acct_*) when the session is routed to a connected account." }, "providerPaymentRef": { "type": "string", "nullable": true, "description": "Provider payment intent reference — Stripe PaymentIntent ID (pi_*) or Airwallex intent ID (int_*). Null until the intent is created on first checkout load." }, "completedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp the session reached terminal completion. Null until the session completes." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "EventResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Server-generated event ID." }, "object": { "type": "string", "enum": [ "event" ], "default": "event" }, "type": { "type": "string" }, "source": { "type": "string" }, "subject": { "type": "string", "description": "Resolved customer ID. Absent when the event was reported with an externalSubject that does not match a customer yet." }, "externalSubject": { "type": "string", "description": "The merchant's own customer identifier the event was reported with." }, "namespace": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "idempotencyKey": { "type": "string" }, "externalId": { "$ref": "#/components/schemas/ExternalId" } } }, "Cost": { "type": "object", "required": [ "id", "object", "type", "name", "currency", "unitCost", "productId", "merchantId", "createdAt", "updatedAt" ], "properties": { "id": { "$ref": "#/components/schemas/CostId" }, "object": { "type": "string", "enum": [ "cost" ], "default": "cost" }, "type": { "type": "string", "enum": [ "metered" ] }, "name": { "type": "string" }, "currency": { "type": "string" }, "unitCost": { "type": "string", "description": "Decimal as string to avoid floating point precision loss." }, "unit": { "type": "string", "nullable": true }, "aggregation": { "type": "string", "enum": [ "SUM", "COUNT", "AVG", "MIN", "MAX", "UNIQUE_COUNT", "LATEST" ], "nullable": true }, "eventType": { "type": "string", "nullable": true }, "valueProperty": { "type": "string", "nullable": true }, "groupBy": { "type": "object", "additionalProperties": { "type": "string" }, "nullable": true }, "productId": { "$ref": "#/components/schemas/ProductId" }, "merchantId": { "$ref": "#/components/schemas/OrganizationId" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Soft-delete timestamp. Always null for active costs returned by the API." } } }, "CostUsageResponse": { "type": "object", "required": [ "object", "id", "name", "type", "currency", "totalCost" ], "properties": { "object": { "type": "string", "enum": [ "cost" ], "default": "cost" }, "id": { "$ref": "#/components/schemas/CostId" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "metered" ] }, "currency": { "type": "string" }, "eventType": { "type": "string", "description": "CloudEvents type for metered costs." }, "totalCost": { "type": [ "number", "null" ], "description": "Total cost for the query window. Null if usage data could not be computed." }, "totalQuantity": { "type": [ "number", "null" ], "description": "Total usage quantity (metered costs only). Null when usage was not computed." }, "groups": { "type": "array", "items": { "type": "object", "required": [ "dimensions", "quantity", "cost" ], "properties": { "dimensions": { "type": "object", "additionalProperties": { "type": "string" } }, "quantity": { "type": "number" }, "cost": { "type": "number" } } }, "description": "Per-group breakdown (present when groupBy is specified)." }, "timeSeries": { "type": "array", "items": { "type": "object", "required": [ "windowStart", "windowEnd", "quantity", "cost" ], "properties": { "windowStart": { "type": "string", "format": "date-time" }, "windowEnd": { "type": "string", "format": "date-time" }, "quantity": { "type": "number" }, "cost": { "type": "number" } } }, "description": "Time-series breakdown (present when window is specified)." } } }, "CostReportGroup": { "type": "object", "required": [ "key", "label", "totalCost", "totalQuantity", "percentOfTotal", "isOther" ], "properties": { "key": { "type": "string", "description": "Group identifier (cost ID, customer ID, or dimension value). '__other__' for the aggregated remainder bucket." }, "label": { "type": "string", "description": "Human-readable display name for the group." }, "totalCost": { "type": "number" }, "totalQuantity": { "type": "number" }, "unit": { "type": "string", "nullable": true, "description": "Unit label for the quantity (e.g. 'token', 'request')." }, "percentOfTotal": { "type": "number", "description": "This group's share of total cost, 0–100." }, "priorPeriod": { "type": "object", "nullable": true, "required": [ "cost", "changePercent" ], "properties": { "cost": { "type": "number" }, "changePercent": { "type": [ "number", "null" ], "description": "Percentage change vs prior period. Null when prior period cost is 0." } }, "description": "Prior-period comparison data. Present only when comparePriorPeriod=true." }, "isOther": { "type": "boolean", "description": "True for the aggregated 'Other' bucket." } } }, "CostReportTimeSeries": { "type": "object", "required": [ "windowStart", "windowEnd", "groups" ], "properties": { "windowStart": { "type": "string", "format": "date-time" }, "windowEnd": { "type": "string", "format": "date-time" }, "groups": { "type": "object", "additionalProperties": { "type": "number" }, "description": "Map of group key → cost value for this time window. Keys match CostReportGroup.key." } } }, "CostReportResponse": { "type": "object", "required": [ "object", "currency", "period", "groupBy", "totalCost", "totalQuantity", "groups", "timeSeries", "availableDimensions", "pagination" ], "properties": { "object": { "type": "string", "enum": [ "cost_report" ], "default": "cost_report" }, "currency": { "type": "string", "description": "ISO 4217 currency code for all monetary values in this response." }, "period": { "type": "object", "required": [ "from", "to" ], "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" } } }, "groupBy": { "type": "string", "description": "The active grouping dimension (e.g. 'cost', 'customer', or a dynamic dimension key)." }, "totalCost": { "type": "number", "description": "Sum of cost across all groups (not just top N)." }, "totalQuantity": { "type": "number", "description": "Sum of quantity across all groups." }, "groups": { "type": "array", "items": { "$ref": "#/components/schemas/CostReportGroup" }, "description": "Top N groups plus an 'Other' bucket aggregating the remainder." }, "timeSeries": { "type": "array", "items": { "$ref": "#/components/schemas/CostReportTimeSeries" }, "description": "Time-bucketed breakdown per group. Keys in each window's 'groups' object correspond to CostReportGroup.key. The 'Other' bucket key is '__other__'." }, "availableDimensions": { "type": "array", "items": { "type": "string" }, "description": "Dimension keys available for further drill-down (populated when a single cost is filtered)." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal warnings, e.g. costs that could not be queried." }, "pagination": { "type": "object", "required": [ "total", "limit", "offset" ], "properties": { "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } } } }, "InvoiceCategorySummary": { "type": "object", "required": [ "count", "amount" ], "properties": { "count": { "type": "integer", "description": "Number of invoices in this category" }, "amount": { "type": "string", "description": "Total amount of invoices in this category in dollars" } } }, "InvoiceSummary": { "type": "object", "required": [ "issued", "outstanding", "paid", "writtenOff" ], "properties": { "issued": { "$ref": "#/components/schemas/InvoiceCategorySummary" }, "outstanding": { "$ref": "#/components/schemas/InvoiceCategorySummary" }, "paid": { "$ref": "#/components/schemas/InvoiceCategorySummary" }, "writtenOff": { "$ref": "#/components/schemas/InvoiceCategorySummary" } } }, "PaymentSummary": { "type": "object", "required": [ "completedCount", "completedAmount", "pendingCount", "pendingAmount", "expiredCount", "expiredAmount" ], "properties": { "completedCount": { "type": "integer", "description": "Number of completed payment links in the period" }, "completedAmount": { "type": "string", "description": "Total amount of completed payment links in dollars" }, "pendingCount": { "type": "integer", "description": "Number of pending payment links in the period" }, "pendingAmount": { "type": "string", "description": "Total amount of pending payment links in dollars" }, "expiredCount": { "type": "integer", "description": "Number of expired payment links in the period" }, "expiredAmount": { "type": "string", "description": "Total amount of expired payment links in dollars" } } }, "GroupTrendEntry": { "type": "object", "required": [ "groupKey", "groupLabel", "issuedInvoices" ], "properties": { "groupKey": { "type": "string", "description": "Unique identifier for the group (e.g. plan ID, or 'other')" }, "groupLabel": { "type": "string", "description": "Human-readable label for the group (e.g. plan name)" }, "issuedInvoices": { "type": "string", "description": "Total issued invoice amount in dollars for this group in this bucket" } } }, "RevenueTrendBucket": { "type": "object", "required": [ "timestamp", "issuedInvoices", "writtenOffInvoices", "completedPayments" ], "properties": { "timestamp": { "type": "string", "format": "date-time", "description": "Start time of this bucket" }, "issuedInvoices": { "type": "string", "description": "Total amount of all invoices issued in this bucket (all statuses, by issuedAt)" }, "writtenOffInvoices": { "type": "string", "description": "Amount of written-off invoices in dollars for this bucket (by writtenOffAt)" }, "completedPayments": { "type": "string", "description": "Revenue from completed payments in dollars for this bucket" }, "groupBreakdown": { "type": "array", "description": "Per-group trend entries (present when groupBy=plan or groupBy=customer)", "items": { "$ref": "#/components/schemas/GroupTrendEntry" } } } }, "GroupInvoiceSummary": { "type": "object", "required": [ "groupKey", "groupLabel", "outstanding", "paid", "writtenOff" ], "properties": { "groupKey": { "type": "string", "description": "Unique identifier for the group (e.g. plan ID, or 'other')" }, "groupLabel": { "type": "string", "description": "Human-readable label for the group (e.g. plan name)" }, "outstanding": { "$ref": "#/components/schemas/InvoiceCategorySummary" }, "paid": { "$ref": "#/components/schemas/InvoiceCategorySummary" }, "writtenOff": { "$ref": "#/components/schemas/InvoiceCategorySummary" } } }, "CurrencyBreakdownEntry": { "type": "object", "required": [ "currency", "netRevenue", "invoices", "payments", "trend" ], "properties": { "currency": { "type": "string", "description": "ISO 4217 currency code (uppercase, e.g. USD, EUR, GBP)" }, "netRevenue": { "type": "string", "description": "Net collected revenue in dollars for this currency (issued invoices + completed payments)" }, "invoices": { "$ref": "#/components/schemas/InvoiceSummary" }, "payments": { "$ref": "#/components/schemas/PaymentSummary" }, "trend": { "type": "array", "description": "Time-bucketed revenue trend data for this currency", "items": { "$ref": "#/components/schemas/RevenueTrendBucket" } } } }, "RevenueSummaryResponse": { "type": "object", "required": [ "object" ], "properties": { "object": { "type": "string", "const": "revenue_summary", "description": "Object type identifier" }, "netRevenue": { "type": "string", "description": "Net collected revenue in dollars (paid invoices + completed payments), already net of non-voided refunds. Omitted when groupBy=currency is active." }, "totalRefunds": { "type": "string", "description": "Gross total of non-voided refunds (credit notes) issued in the period, in dollars. Already subtracted from netRevenue and invoice totals. Omitted when groupBy=currency is active." }, "refundCount": { "type": "number", "description": "Number of non-voided refunds (credit notes) issued in the period. Omitted when groupBy=currency is active." }, "invoices": { "$ref": "#/components/schemas/InvoiceSummary", "description": "Invoice breakdown. Omitted when groupBy=currency is active." }, "payments": { "$ref": "#/components/schemas/PaymentSummary", "description": "Payment breakdown. Omitted when groupBy=currency is active." }, "trend": { "type": "array", "description": "Time-bucketed revenue trend data. Omitted when groupBy=currency is active.", "items": { "$ref": "#/components/schemas/RevenueTrendBucket" } }, "groupBreakdown": { "type": "array", "description": "Invoice breakdown by group dimension (only present when groupBy=plan or groupBy=customer is specified)", "items": { "$ref": "#/components/schemas/GroupInvoiceSummary" } }, "currencyBreakdown": { "type": "array", "description": "Per-currency revenue aggregates (only present when groupBy=currency is specified). Primary currency appears first, then alphabetical by ISO code. When present, top-level netRevenue, invoices, payments, and trend fields are omitted.", "items": { "$ref": "#/components/schemas/CurrencyBreakdownEntry" } } } }, "ProfitabilityTrend": { "type": "object", "required": [ "values", "periodChange" ], "properties": { "values": { "type": "array", "description": "Revenue values per time bucket, oldest first, in unit currency with two decimals.", "items": { "type": "string" } }, "periodChange": { "type": [ "number", "null" ], "description": "Period-over-period % change (current half vs prior half). Null when prior is zero." } } }, "ProfitabilityRow": { "type": "object", "required": [ "customerId", "customerName", "netRevenue", "totalCost", "profit", "marginPct", "trend" ], "properties": { "customerId": { "type": "string", "description": "Customer ID, or the literal 'other' for the overflow row." }, "customerName": { "type": "string", "description": "Display name for the row. 'Other' for the overflow row." }, "netRevenue": { "type": "string", "description": "Net revenue (paid + outstanding) in unit currency, with two decimals." }, "totalCost": { "type": "string", "description": "Aggregated cost in unit currency, with two decimals." }, "profit": { "type": "string", "description": "Profit (revenue − cost) in unit currency, with two decimals. May be negative." }, "marginPct": { "type": [ "string", "null" ], "description": "Margin percent (profit / revenue × 100), with two decimals. Null when revenue is zero." }, "trend": { "oneOf": [ { "$ref": "#/components/schemas/ProfitabilityTrend" }, { "type": "null" } ], "description": "Per-customer revenue trend over the period. Null for the 'Other' row and when there's insufficient data." } } }, "ProfitabilitySummaryResponse": { "type": "object", "required": [ "object", "currency", "rows" ], "properties": { "object": { "type": "string", "const": "profitability_summary", "description": "Object type identifier" }, "currency": { "type": "string", "description": "ISO 4217 currency code applied to revenue and cost values" }, "rows": { "type": "array", "description": "Top-N customer rows by profit descending, optionally followed by a single 'Other' row when more than topN customers contributed.", "maxItems": 101, "items": { "$ref": "#/components/schemas/ProfitabilityRow" } }, "warnings": { "type": "array", "description": "Non-fatal warnings collected during cost discovery (e.g. an individual cost query failed). Empty array on a clean run.", "maxItems": 100, "items": { "type": "string" } } } }, "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" ] }, "schemas-OrganizationId": { "type": "string", "pattern": "^org_[a-zA-Z0-9]+$" }, "EntityType": { "type": "string", "enum": [ "item", "customer" ], "description": "The type of Paygentic entity this external reference points at" }, "Provider": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$", "maxLength": 64, "description": "Lowercase snake_case provider identifier (e.g. `salesforce`, `netsuite`)" }, "schemas-ExternalId": { "type": "string", "pattern": "^[a-zA-Z0-9_-]+$", "maxLength": 255, "description": "Identifier of the record in the external system" }, "ExternalReferenceId": { "type": "string", "pattern": "^xrf_[a-zA-Z0-9]+$", "description": "Unique identifier for an external reference" }, "ExternalReference": { "type": "object", "description": "Links a Paygentic entity to a record in an external system such as Salesforce or NetSuite.", "required": [ "id", "object", "merchantId", "entityType", "entityId", "provider", "externalId", "metadata", "isPrimary", "isDefault", "createdAt", "updatedAt" ], "properties": { "id": { "$ref": "#/components/schemas/ExternalReferenceId" }, "object": { "type": "string", "enum": [ "externalReference" ], "default": "externalReference" }, "merchantId": { "$ref": "#/components/schemas/OrganizationId" }, "entityType": { "$ref": "#/components/schemas/EntityType" }, "entityId": { "type": "string" }, "provider": { "$ref": "#/components/schemas/Provider" }, "externalId": { "$ref": "#/components/schemas/ExternalId" }, "externalLabel": { "type": "string", "nullable": true }, "metadata": { "type": "object", "additionalProperties": true }, "isPrimary": { "type": "boolean" }, "isDefault": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "ItemId": { "type": "string", "pattern": "^itm_[a-zA-Z0-9]+$" }, "Item": { "type": "object", "required": [ "id", "object", "merchantId", "name", "metadata", "externalReferences", "createdAt", "updatedAt" ], "properties": { "id": { "$ref": "#/components/schemas/ItemId" }, "object": { "type": "string", "enum": [ "item" ], "default": "item" }, "merchantId": { "$ref": "#/components/schemas/schemas-OrganizationId" }, "name": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true }, "externalReferences": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalReference" } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "OrderLineItem": { "type": "object", "required": [ "id", "object", "orderId", "quantity", "listUnitPrice", "discountUnitAmount", "unitPrice", "totalPrice", "metadata", "createdAt", "updatedAt", "termStartDate", "termEndDate" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "order_line_item" ] }, "orderId": { "type": "string" }, "itemId": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "quantity": { "type": "string", "description": "Decimal string" }, "listUnitPrice": { "type": "string", "description": "Decimal string" }, "discountUnitAmount": { "type": "string", "description": "Decimal string" }, "unitPrice": { "type": "string", "description": "Decimal string" }, "totalPrice": { "type": "string", "description": "Decimal string" }, "termStartDate": { "type": "string", "format": "date-time", "nullable": true }, "termEndDate": { "type": "string", "format": "date-time", "nullable": true }, "metadata": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "BillingSchedule": { "type": "object", "description": "Summary of a billing schedule owned by this order. The full schedule (with intervals + staged invoices) is served under /billingSchedules. Owner-polymorphic: a schedule belongs to exactly one Order or one Subscription (XOR); cadence lives on ScheduleIntervals, not the header.", "required": [ "id", "object", "merchantId", "status", "startDate", "endDate", "billingAnchor", "alignmentPolicy", "prorationPolicy", "periodPreset", "metadata", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "billing_schedule" ] }, "orderId": { "type": "string", "nullable": true }, "subscriptionId": { "type": "string", "nullable": true }, "merchantId": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "active", "completed", "cancelled" ] }, "startDate": { "type": "string", "format": "date-time" }, "endDate": { "type": "string", "format": "date-time" }, "billingAnchor": { "type": "string", "format": "date-time" }, "alignmentPolicy": { "type": "string", "enum": [ "anchor", "calendar", "coterm" ] }, "prorationPolicy": { "type": "string", "enum": [ "none", "daily" ] }, "paymentTermDays": { "type": "integer", "nullable": true }, "periodPreset": { "type": "string", "enum": [ "single", "P1M", "P3M", "P6M", "P1Y", "custom" ] }, "metadata": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "Order": { "type": "object", "required": [ "id", "object", "merchantId", "customerId", "currency", "termStartDate", "termEndDate", "totalAmount", "defaultPaymentTermDays", "metadata", "lineItems", "billingSchedules", "createdAt", "updatedAt", "resellerId", "taxExempt", "sellingEntity", "approvalStatus", "cancelledAt" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "order" ] }, "merchantId": { "type": "string" }, "customerId": { "type": "string" }, "resellerId": { "type": "string", "nullable": true }, "taxExempt": { "type": "boolean" }, "sellingEntity": { "type": "string", "nullable": true }, "currency": { "type": "string" }, "approvalStatus": { "type": "string", "enum": [ "draft", "pending", "approved", "rejected" ] }, "cancelledAt": { "type": "string", "format": "date-time", "nullable": true }, "type": { "type": "string", "enum": [ "new_business", "renewal", "expansion" ], "nullable": true }, "termStartDate": { "type": "string", "format": "date-time" }, "termEndDate": { "type": "string", "format": "date-time" }, "closeDate": { "type": "string", "format": "date-time", "nullable": true }, "totalAmount": { "type": "string", "description": "Decimal string (TCV)" }, "defaultPaymentTermDays": { "type": "integer" }, "metadata": { "type": "object", "additionalProperties": true }, "lineItems": { "type": "array", "items": { "$ref": "#/components/schemas/OrderLineItem" } }, "billingSchedules": { "type": "array", "items": { "$ref": "#/components/schemas/BillingSchedule" } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "OrderList": { "type": "object", "required": [ "object", "data", "pagination" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } }, "pagination": { "$ref": "#/components/schemas/OffsetPagination" } } }, "CreateOrderLineItemRequest": { "type": "object", "required": [ "quantity", "listUnitPrice", "unitPrice", "totalPrice" ], "properties": { "itemId": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "quantity": { "type": "string" }, "listUnitPrice": { "type": "string" }, "discountUnitAmount": { "type": "string" }, "unitPrice": { "type": "string" }, "totalPrice": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true }, "termStartDate": { "type": "string", "format": "date-time" }, "termEndDate": { "type": "string", "format": "date-time" } } }, "CreateOrderRequest": { "type": "object", "required": [ "customerId", "currency", "termStartDate", "termEndDate", "totalAmount" ], "properties": { "customerId": { "type": "string" }, "currency": { "type": "string" }, "type": { "type": "string", "enum": [ "new_business", "renewal", "expansion" ], "nullable": true }, "termStartDate": { "type": "string", "format": "date-time" }, "termEndDate": { "type": "string", "format": "date-time" }, "closeDate": { "type": "string", "format": "date-time", "nullable": true }, "totalAmount": { "type": "string" }, "defaultPaymentTermDays": { "type": "integer" }, "metadata": { "type": "object", "additionalProperties": true }, "lineItems": { "type": "array", "items": { "$ref": "#/components/schemas/CreateOrderLineItemRequest" } }, "resellerId": { "type": "string" }, "taxExempt": { "type": "boolean" }, "sellingEntity": { "type": "string" } } }, "UpdateOrderRequest": { "type": "object", "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "new_business", "renewal", "expansion" ], "nullable": true }, "termStartDate": { "type": "string", "format": "date-time" }, "termEndDate": { "type": "string", "format": "date-time" }, "closeDate": { "type": "string", "format": "date-time", "nullable": true }, "totalAmount": { "type": "string" }, "defaultPaymentTermDays": { "type": "integer" }, "metadata": { "type": "object", "additionalProperties": true }, "cancelledAt": { "type": "string", "format": "date-time", "nullable": true }, "resellerId": { "type": "string", "nullable": true }, "taxExempt": { "type": "boolean" }, "sellingEntity": { "type": "string", "nullable": true } } }, "UpdateOrderLineItemRequest": { "type": "object", "properties": { "itemId": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "quantity": { "type": "string" }, "listUnitPrice": { "type": "string" }, "discountUnitAmount": { "type": "string" }, "unitPrice": { "type": "string" }, "totalPrice": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true }, "termStartDate": { "type": "string", "format": "date-time" }, "termEndDate": { "type": "string", "format": "date-time" } } }, "CreateOrderApprovalRequest": { "type": "object", "additionalProperties": false, "properties": { "requester": { "type": "string", "minLength": 1, "description": "Optional. The maker submitting the order. Derived from the authenticated principal; only a platform key may set it explicitly." }, "note": { "type": "string", "nullable": true } } }, "Approval": { "type": "object", "required": [ "id", "object", "merchantId", "resourceType", "resourceId", "kind", "decision", "requester", "dataSnapshotHash", "createdAt" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "approval" ] }, "merchantId": { "type": "string" }, "resourceType": { "type": "string" }, "resourceId": { "type": "string" }, "kind": { "type": "string" }, "decision": { "type": "string", "enum": [ "pending", "approved", "rejected", "cancelled" ] }, "requester": { "type": "string" }, "reviewer": { "type": "string", "nullable": true }, "note": { "type": "string", "nullable": true }, "dataSnapshotHash": { "type": "string" }, "decidedAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" } } }, "schemas-BillingSchedule": { "type": "object", "required": [ "id", "object", "merchantId", "status", "startDate", "endDate", "billingAnchor", "alignmentPolicy", "prorationPolicy", "periodPreset", "customPeriodWindows", "metadata", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "billing_schedule" ] }, "orderId": { "type": "string", "nullable": true }, "subscriptionId": { "type": "string", "nullable": true }, "merchantId": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "active", "completed", "cancelled" ] }, "startDate": { "type": "string", "format": "date-time" }, "endDate": { "type": "string", "format": "date-time", "nullable": true, "description": "Null for an open-ended subscription-owned schedule; order-owned schedules always have a concrete end." }, "billingAnchor": { "type": "string", "format": "date-time" }, "alignmentPolicy": { "type": "string", "enum": [ "anchor", "calendar", "coterm" ] }, "prorationPolicy": { "type": "string", "enum": [ "none", "daily" ] }, "paymentTermDays": { "type": "integer", "nullable": true }, "periodPreset": { "type": "string", "enum": [ "single", "P1M", "P3M", "P6M", "P1Y", "custom" ] }, "customPeriodWindows": { "type": "array", "items": {} }, "metadata": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "type": "string", "format": "date-time", "nullable": true } } }, "CreateBillingScheduleRequest": { "type": "object", "required": [ "startDate", "endDate", "billingAnchor" ], "properties": { "orderId": { "type": "string" }, "subscriptionId": { "type": "string" }, "startDate": { "type": "string", "format": "date-time" }, "endDate": { "type": "string", "format": "date-time" }, "billingAnchor": { "type": "string", "format": "date-time" }, "alignmentPolicy": { "type": "string", "enum": [ "anchor", "calendar", "coterm" ] }, "prorationPolicy": { "type": "string", "enum": [ "none", "daily" ] }, "paymentTermDays": { "type": "integer", "nullable": true }, "periodPreset": { "type": "string", "enum": [ "single", "P1M", "P3M", "P6M", "P1Y", "custom" ] }, "customPeriodWindows": { "type": "array", "items": {} }, "metadata": { "type": "object", "additionalProperties": true } } }, "UpdateBillingScheduleRequest": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "draft", "active", "completed", "cancelled" ] }, "startDate": { "type": "string", "format": "date-time" }, "endDate": { "type": "string", "format": "date-time" }, "billingAnchor": { "type": "string", "format": "date-time" }, "alignmentPolicy": { "type": "string", "enum": [ "anchor", "calendar", "coterm" ] }, "prorationPolicy": { "type": "string", "enum": [ "none", "daily" ] }, "paymentTermDays": { "type": "integer", "nullable": true }, "periodPreset": { "type": "string", "enum": [ "single", "P1M", "P3M", "P6M", "P1Y", "custom" ] }, "customPeriodWindows": { "type": "array", "items": {} }, "metadata": { "type": "object", "additionalProperties": true } } }, "ScheduleInterval": { "type": "object", "required": [ "id", "object", "scheduleId", "baseQuantity", "quantityTransitions", "billingCadence", "billingMode", "startDate", "endDate", "metadata", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "schedule_interval" ] }, "scheduleId": { "type": "string" }, "orderLineItemId": { "type": "string", "nullable": true }, "itemId": { "type": "string", "nullable": true }, "priceId": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "unitPrice": { "type": "string", "nullable": true, "description": "Signed per-period net unit price as decimal string" }, "baseQuantity": { "type": "string", "description": "Quantity at interval start" }, "quantityTransitions": { "type": "array", "items": { "type": "object", "required": [ "effectiveDate", "quantity" ], "properties": { "effectiveDate": { "type": "string", "format": "date-time" }, "quantity": { "type": "string" } } } }, "billingCadence": { "type": "string", "description": "ISO-8601 duration or 'one_off'" }, "billingMode": { "type": "string", "enum": [ "advance", "arrears" ] }, "billDate": { "type": "string", "format": "date-time", "nullable": true }, "startDate": { "type": "string", "format": "date-time" }, "endDate": { "type": "string", "format": "date-time", "nullable": true, "description": "Null for an open-ended subscription-owned interval; order-owned intervals always have a concrete end." }, "usageFilter": { "type": "object", "nullable": true, "additionalProperties": true }, "metadata": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "ReplaceScheduleIntervalsRequest": { "type": "object", "required": [ "intervals" ], "properties": { "intervals": { "type": "array", "items": { "type": "object", "required": [ "baseQuantity", "billingCadence", "startDate", "endDate" ], "properties": { "orderLineItemId": { "type": "string", "nullable": true }, "itemId": { "type": "string", "nullable": true }, "priceId": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "unitPrice": { "type": "string", "nullable": true }, "baseQuantity": { "type": "string" }, "quantityTransitions": { "type": "array", "items": { "type": "object", "required": [ "effectiveDate", "quantity" ], "properties": { "effectiveDate": { "type": "string", "format": "date-time" }, "quantity": { "type": "string" } } } }, "billingCadence": { "type": "string" }, "billingMode": { "type": "string", "enum": [ "advance", "arrears" ] }, "billDate": { "type": "string", "format": "date-time", "nullable": true }, "startDate": { "type": "string", "format": "date-time" }, "endDate": { "type": "string", "format": "date-time" }, "usageFilter": { "type": "object", "nullable": true, "additionalProperties": true }, "metadata": { "type": "object", "additionalProperties": true } } } }, "orderLineItemId": { "type": "string", "description": "When set, scope the wipe to this line's intervals only (per-line cell-edit path)" } } }, "ScheduleInvoice": { "type": "object", "required": [ "id", "object", "orderId", "billingScheduleId", "merchantId", "periodStart", "periodEnd", "dueDate", "amount", "status", "lineItems", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "schedule_invoice" ] }, "orderId": { "type": "string" }, "billingScheduleId": { "type": "string" }, "merchantId": { "type": "string" }, "periodStart": { "type": "string", "format": "date-time" }, "periodEnd": { "type": "string", "format": "date-time" }, "dueDate": { "type": "string", "format": "date-time" }, "amount": { "type": "string", "description": "Net invoice amount as decimal string" }, "status": { "type": "string", "enum": [ "staged", "pushed", "cancelled" ] }, "lineItems": { "type": "array", "items": { "type": "object", "required": [ "description", "quantity", "unitPrice", "subtotal" ], "properties": { "lineKey": { "type": "string", "nullable": true }, "description": { "type": "string" }, "quantity": { "type": "string" }, "unitPrice": { "type": "string" }, "subtotal": { "type": "string" } } } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "MerchantIntegrationProvider": { "type": "string", "enum": [ "salesforce" ], "description": "External provider a merchant can connect at the tenant level" }, "MerchantIntegrationId": { "type": "string", "pattern": "^mint_[a-zA-Z0-9]+$", "description": "Unique identifier for a merchant integration" }, "MerchantIntegrationStatus": { "type": "string", "enum": [ "active", "disconnected", "error" ], "description": "Connection lifecycle state. Live Ampersand health is separate and not stored here." }, "MerchantIntegration": { "type": "object", "description": "A merchant's tenant-level connection to an external provider via Ampersand.", "required": [ "id", "object", "merchantId", "provider", "externalId", "status", "config", "metadata", "connectedAt", "disconnectedAt", "createdAt", "updatedAt" ], "properties": { "id": { "$ref": "#/components/schemas/MerchantIntegrationId" }, "object": { "type": "string", "enum": [ "merchantIntegration" ], "default": "merchantIntegration" }, "merchantId": { "$ref": "#/components/schemas/OrganizationId" }, "provider": { "$ref": "#/components/schemas/MerchantIntegrationProvider" }, "externalId": { "type": "string", "nullable": true, "description": "Ampersand installation id." }, "status": { "$ref": "#/components/schemas/MerchantIntegrationStatus" }, "config": { "type": "object", "additionalProperties": true }, "metadata": { "type": "object", "additionalProperties": true }, "connectedAt": { "type": "string", "format": "date-time" }, "disconnectedAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "schemas-Approval": { "type": "object", "required": [ "id", "object", "merchantId", "resourceType", "resourceId", "kind", "decision", "requester", "dataSnapshotHash", "createdAt" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "approval" ] }, "merchantId": { "type": "string" }, "resourceType": { "type": "string", "enum": [ "order", "invoice" ] }, "resourceId": { "type": "string" }, "kind": { "type": "string", "enum": [ "data_review", "financial_review", "push" ] }, "decision": { "type": "string", "enum": [ "pending", "approved", "rejected", "cancelled" ] }, "requester": { "type": "string" }, "reviewer": { "type": "string", "nullable": true }, "note": { "type": "string", "nullable": true }, "dataSnapshotHash": { "type": "string" }, "decidedAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" } } }, "ApprovalList": { "type": "object", "required": [ "object", "data", "pagination" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/schemas-Approval" } }, "pagination": { "$ref": "#/components/schemas/OffsetPagination" } } }, "CreateApprovalRequest": { "type": "object", "required": [ "merchantId", "resourceType", "resourceId", "dataSnapshotHash" ], "properties": { "merchantId": { "type": "string", "description": "The merchant that owns the resource being approved." }, "resourceType": { "type": "string", "enum": [ "order", "invoice" ] }, "resourceId": { "type": "string", "maxLength": 255 }, "dataSnapshotHash": { "type": "string", "maxLength": 128, "description": "A precomputed hash of the resource state being approved. The resource-owning domain builds this snapshot; approvals stays decoupled from any specific resource shape." }, "kind": { "type": "string", "enum": [ "data_review", "financial_review", "push" ], "description": "Defaults to data_review." }, "note": { "type": "string", "maxLength": 2000, "nullable": true }, "actorId": { "type": "string", "maxLength": 128, "description": "Optional. The real user id to record as the requester. Used when the request is made via a platform-level key on behalf of a human user (e.g. from the platform Next.js frontend). When supplied and the authenticated principal is 'platform', this value overrides the derived principal as the requester. Ignored when the caller is a non-platform API key." } } }, "UpdateApprovalRequest": { "type": "object", "required": [ "decision" ], "properties": { "decision": { "type": "string", "enum": [ "approved", "rejected", "cancelled" ], "description": "approved/rejected: reviewer decision (maker-checker enforced). cancelled: recall a pending approval or reopen an approved one." }, "note": { "type": "string", "maxLength": 2000, "nullable": true }, "actorId": { "type": "string", "maxLength": 128, "description": "Optional. The real user id performing the action. Used when the request is made via a platform-level key on behalf of a human user. Ignored when the caller is a non-platform API key." } } } }, "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" } } } }, "Conflict": { "description": "Conflict - The request conflicts with the current state of the resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "PreconditionFailed": { "description": "Precondition Failed - An optimistic-concurrency precondition (e.g. `If-Match`) no longer matches the resource's current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "UnprocessableEntity": { "description": "Unprocessable Entity - The request was well-formed but could not be processed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "API key authentication" } } } }