{ "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", "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 product this metric belongs to. Required unless `itemId` is supplied, in which case the product is derived from that item's catalog." }, "itemId": { "$ref": "#/components/schemas/ItemId", "description": "Optional item tag, used to map this metric's invoice lines to an external accounting/tax identity. When supplied, `productId` is derived from the item's catalog and a supplied `productId` that disagrees is rejected." }, "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": "itemId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter to the charges tagged with this item. Lets a surface that needs only one item's charges read exactly those, rather than reading the whole product's and filtering — which makes its completeness a function of how large the product is." }, { "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'" }, "itemId": { "type": "string", "pattern": "^itm_[a-zA-Z0-9]+$", "nullable": true, "description": "Optional item tag, used to map this metric's invoice lines to an external accounting/tax identity. Send a new id to re-tag — the item must be filed under this charge's own product, and an archived item is rejected. An item from another product is refused with `ITEM_PRODUCT_MISMATCH`: a tag is an accounting grouping and does not move the charge between products, and no field here could move it back. Re-file the item to move every charge anchored to it together. Send `null` to untag. Every line item whose invoice has not closed reports this charge's current tag, so a re-tag takes effect on the bill in progress and on any generated ahead of it — no further action, and no window to wait for. Lines on a closed invoice keep the item recorded at close and never move. Un-tagging works the same way: those lines report no item." }, "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" } } } }, "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" } } } }, "/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": 60, "platformMax": 360, "timeWindow": "6 seconds", "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" }, "429": { "description": "Too many requests. The allowance of the merchant for this operation is spent. Wait for the number of seconds in the retry-after header. Then send the request again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "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" ], "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 product this fee belongs to. Required unless `itemId` is supplied, in which case the product is derived from that item's catalog." }, "itemId": { "$ref": "#/components/schemas/ItemId", "description": "Optional item tag, used to map this fee's invoice lines to an external accounting/tax identity. When supplied, `productId` is derived from the item's catalog and a supplied `productId` that disagrees is rejected." } } } } } }, "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": "itemId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter to the charges tagged with this item. Lets a surface that needs only one item's charges read exactly those, rather than reading the whole product's and filtering — which makes its completeness a function of how large the product is." }, { "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." }, "itemId": { "type": "string", "pattern": "^itm_[a-zA-Z0-9]+$", "nullable": true, "description": "Optional item tag, used to map this fee's invoice lines to an external accounting/tax identity. Send a new id to re-tag — the item must be filed under this charge's own product, and an archived item is rejected. An item from another product is refused with `ITEM_PRODUCT_MISMATCH`: a tag is an accounting grouping and does not move the charge between products, and no field here could move it back. Re-file the item to move every charge anchored to it together. Send `null` to untag. Every line item whose invoice has not closed reports this charge's current tag, so a re-tag takes effect on the bill in progress and on any generated ahead of it — no further action, and no window to wait for. Lines on a closed invoice keep the item recorded at close and never move. Un-tagging works the same way: those lines report no item." } } } } } }, "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" } } } }, "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" } } }, "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" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "invoiceDisplayName": { "type": "string" } } } } } } } } } } } } } }, "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 is replaced by minting a new plan version and making it default. 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. Has no effect on this request's own prices field: prices carried over keep their ids, but swapping one price for another there moves the plan to the new price's id rather than keeping the original live." } } } } } }, "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" }, "409": { "$ref": "#/components/responses/Conflict" }, "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 plan version", "description": "Mint a new plan version from a price diff and make it the version the plan bills from, in one step. The diff references existing prices by id: create prices beforehand with POST /prices, then add, remove, or replace them here. To return to an earlier price set, make that version the default with a PATCH on the version.", "operationId": "mintPlanVersion", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MintPlanVersionRequest" } } } }, "responses": { "201": { "description": "The newly minted version, published and now the plan's default", "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}": { "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" } } }, "patch": { "tags": [ "Plans" ], "summary": "Set the default version", "description": "Point the plan's default at this version, so its floating subscriptions bill from it. Any version may become default, in either direction — this is how you roll a plan back to (or forward to) an earlier price set. Idempotent when the version is already the default.", "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/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'). 'standard' and 'volume' are accepted; fees only support 'standard'. For percentage/revenue-share use 'standard' with a unit-price multiplier. Legacy prices using 'dynamic'/'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)'" }, "invoiceDisplayGroup": { "type": "string", "description": "Presentation only. Prices sharing this value, within one billing period, print as a single row on the rendered invoice PDF and are described by this string. Every member still bills its own line item on the ledger, this API and the compliance document. The combined row's rate is derived from the members' own rates. Requires the 'standard' pricing model. Sample values: 'Cross Border Fees', 'FX Fees'", "nullable": true }, "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." }, "isObligation": { "type": "boolean", "default": false, "description": "A fixed amount owed whole rather than a per-period rate. An obligation is not prorated over a partial first period: when a subscription starts before its billing anchor, no truncated stub is billed and the first charge is the full amount at the next anchor. An obligation also refuses an interval boundary that falls strictly inside one of its own billing periods, since part of an amount owed whole is not a thing to bill. Defaults to false, which is a rate and is today's behaviour for every price. Not supported on a metered price, whose amount resolves from usage at close." }, "rateType": { "$ref": "#/components/schemas/RateType", "default": "amount" }, "tax": { "$ref": "#/components/schemas/PriceTax" }, "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": "merchantId", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/OrganizationId" }, "description": "Filter prices by merchant organization ID. Matches prices reached via either a billable metric or a fee belonging to that merchant. Unlike the unfiltered listing, this includes prices whose billable metric or fee has been deleted — deleting a parent does not delete its prices, and they can still bill. Returns 404 if the merchant does not exist." }, { "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": "Volume pricing for storage capacity", "invoiceDisplayName": "Storage Usage (GB)", "model": "volume", "paymentTerm": "in_arrears", "properties": { "tiers": [ { "unitPrice": "5", "upTo": "100" }, { "unitPrice": "4", "upTo": "500" }, { "unitPrice": "3", "upTo": null } ] }, "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" }, "404": { "$ref": "#/components/responses/NotFound" }, "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": "Volume pricing for storage capacity", "invoiceDisplayName": "Storage Usage (GB)", "model": "volume", "paymentTerm": "in_arrears", "properties": { "tiers": [ { "unitPrice": "5", "upTo": "100" }, { "unitPrice": "4", "upTo": "500" }, { "unitPrice": "3", "upTo": null } ] }, "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'" }, "invoiceDisplayGroup": { "type": "string", "description": "Presentation only. Prices sharing this value, within one billing period, print as a single row on the rendered invoice PDF and are described by this string. Every member still bills its own line item on the ledger, this API and the compliance document. The combined row's rate is derived from the members' own rates. Requires the 'standard' pricing model. Sample values: 'Cross Border Fees', 'FX Fees'", "nullable": true }, "model": { "allOf": [ { "$ref": "#/components/schemas/PriceModelInput" } ], "description": "The pricing model to set. 'standard' and 'volume' are accepted. Legacy 'dynamic'/'percentage' prices can still be edited (other fields) but cannot be switched back 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." }, "isObligation": { "type": "boolean", "description": "A fixed amount owed whole rather than a per-period rate. An obligation is not prorated over a partial first period: when a subscription starts before its billing anchor, no truncated stub is billed and the first charge is the full amount at the next anchor. An obligation also refuses an interval boundary that falls strictly inside one of its own billing periods, since part of an amount owed whole is not a thing to bill. Defaults to false, which is a rate and is today's behaviour for every price. Not supported on a metered price, whose amount resolves from usage at close." }, "rateType": { "$ref": "#/components/schemas/RateType" }, "tax": { "$ref": "#/components/schemas/PriceTax" }, "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" }, "409": { "description": "Price cannot be restructured because a subscription still bills it directly", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string", "examples": [ "PRICE_STRUCTURALLY_LOCKED_BY_SUBSCRIPTION", "TRANSIENT_CONTENTION" ], "description": "Machine-readable conflict code. Open set: a new code may appear, so branch on the ones you handle and treat anything else as an unhandled conflict." }, "details": { "type": "object", "properties": { "priceId": { "type": "string" }, "fields": { "type": "array", "items": { "type": "string" } }, "subscriptionCount": { "type": "integer" } } } }, "required": [ "message", "code" ] } } } }, "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" }, "409": { "description": "Price cannot be deleted because a live plan still references it", "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" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "versionNumber": { "type": "integer" }, "versionNumbers": { "type": "array", "items": { "type": "integer" } } } } } } } } } } } } } } }, "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", "startedAt": "2024-01-10T08:00:00Z", "status": "active", "terminatedAt": null, "terminatedBy": null, "terminationReason": null, "updatedAt": "2024-01-10T08:00:00Z" }, { "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", "startedAt": "2024-02-01T14:45:30Z", "status": "active", "terminatedAt": null, "terminatedBy": null, "terminationReason": null, "updatedAt": "2024-02-15T09:20:00Z" } ], "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", "deprecated": true, "description": "Deprecated. This field is ignored and has no effect." }, "minimumAccountBalance": { "type": "string", "deprecated": true, "description": "Deprecated. This field is ignored and has no effect." }, "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", "startedAt": "2024-01-10T08:00:00Z", "status": "active", "terminatedAt": null, "terminatedBy": null, "terminationReason": null, "updatedAt": "2024-01-10T08:00:00Z" } } } }, "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", "startedAt": "2024-01-15T10:30:00Z", "status": "active", "terminatedAt": null, "terminatedBy": null, "terminationReason": null, "updatedAt": "2024-01-15T10:30:00Z" } } } }, "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/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", "startedAt": "2024-02-01T14:45:30Z", "status": "active", "terminatedAt": null, "terminatedBy": null, "terminationReason": null, "updatedAt": "2024-02-15T09:20:00Z" } } } }, "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", "deprecated": true, "description": "Deprecated. This field is ignored and has no effect." }, "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", "startedAt": "2024-01-10T08:00:00Z", "status": "active", "terminatedAt": null, "terminatedBy": null, "terminationReason": null, "updatedAt": "2024-03-15T10: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/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", "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" } } } }, "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" }, "429": { "description": "Too many requests. The reconciliation allowance for this subscription is spent. Wait for the number of seconds in the retry-after header. Then send the request again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v0/subscriptions/{id}/adjustments": { "get": { "tags": [ "Subscriptions" ], "summary": "List Adjustments", "description": "Reads the adjustments on the subscription, oldest window first. A subscription with no adjustment returns an empty array. Paginated, because a long-running subscription accumulates one adjustment per rate change of every deal it has carried.", "operationId": "listSubscriptionAdjustments", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The subscription ID" }, { "in": "query", "name": "limit", "schema": { "type": "string", "default": "10" }, "description": "Number of adjustments to return" }, { "in": "query", "name": "offset", "schema": { "type": "string", "default": "0" }, "description": "Number of adjustments to skip" } ], "responses": { "200": { "description": "The subscription's adjustments.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionAdjustmentsResponse" }, "example": { "data": [ { "object": "subscriptionAdjustment", "id": "subadj_a1b2c3d4e5f6g7h8", "subscriptionId": "sub_z1a2b3c4d5e6f7g8", "type": "percentageDiscount", "percentageDiscount": "0.35", "usageDiscount": null, "targetPriceIds": [], "effectiveFrom": "2026-01-01T00:00:00Z", "effectiveTo": null, "description": "FY26 Growth", "createdAt": "2025-12-20T09:30:00Z" }, { "object": "subscriptionAdjustment", "id": "subadj_h8g7f6e5d4c3b2a1", "subscriptionId": "sub_z1a2b3c4d5e6f7g8", "type": "usageDiscount", "percentageDiscount": null, "usageDiscount": "300", "targetPriceIds": [ "price_k1l2m3n4o5p6q7r8" ], "effectiveFrom": "2026-03-01T00:00:00Z", "effectiveTo": "2026-04-01T00:00:00Z", "description": "March outage", "createdAt": "2026-04-02T11:05:00Z" } ], "pagination": { "limit": 10, "offset": 0, "total": 2 } } } } }, "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 Adjustment", "description": "Attaches an adjustment to the subscription for a dated window. A percentageDiscount reduces every discountable charge by a rate and carries one discount line per charge on the invoice. A usageDiscount takes a number of usage units off one metered price's billable quantity before that line is priced, so the line re-slots on a volume ladder and shows the corrected quantity; it emits no line of its own. Tax is assessed on the reduced amount either way. An invoice that already exists is not changed, including one still in draft — the adjustment reaches the periods that close after it is created. There is no update operation, and a window cannot be changed after it is created. To change an adjustment before any invoice has issued under it, delete it and create a replacement. Once an invoice has issued the adjustment is permanent, so set effectiveTo at creation time whenever the deal has a known end date.", "operationId": "createSubscriptionAdjustment", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The subscription ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSubscriptionAdjustmentRequest" }, "examples": { "percentageDiscount": { "summary": "A 35% deal discount, open-ended", "value": { "type": "percentageDiscount", "percentageDiscount": "0.35", "effectiveFrom": "2026-01-01T00:00:00Z", "effectiveTo": null, "description": "FY26 Growth", "idempotencyKey": "adj_fy26_growth_001" } }, "usageDiscount": { "summary": "300 erroneous units taken off one metered price for a single period", "value": { "type": "usageDiscount", "usageDiscount": "300", "targetPriceIds": [ "price_a1b2c3d4e5f6g7h8" ], "effectiveFrom": "2026-03-01T00:00:00Z", "effectiveTo": "2026-04-01T00:00:00Z", "description": "March outage — bad events", "idempotencyKey": "adj_march_outage_001" } } } } } }, "responses": { "200": { "description": "An adjustment already exists for this idempotency key, and is returned unchanged. Nothing was created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionAdjustment" } } } }, "201": { "description": "The adjustment was created and applies from its effectiveFrom date.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionAdjustment" }, "example": { "object": "subscriptionAdjustment", "id": "subadj_a1b2c3d4e5f6g7h8", "subscriptionId": "sub_z1a2b3c4d5e6f7g8", "type": "percentageDiscount", "percentageDiscount": "0.35", "effectiveFrom": "2026-01-01T00:00:00Z", "effectiveTo": null, "description": "FY26 Growth", "createdAt": "2025-12-20T09:30:00Z", "usageDiscount": null, "targetPriceIds": [] } } } }, "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}/adjustments/{adjustmentId}": { "delete": { "tags": [ "Subscriptions" ], "summary": "Delete Adjustment", "description": "Deletes an adjustment that has not yet reached an issued invoice. No invoice changes: an invoice still in draft keeps its numbers, and loses the discount only when its period is calculated again. An adjustment that has already discounted an issued invoice cannot be deleted, because the invoice records why the customer was charged that amount. Its window cannot be shortened afterwards either, so set effectiveTo at creation time whenever the deal has a known end date.", "operationId": "deleteSubscriptionAdjustment", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The subscription ID" }, { "in": "path", "name": "adjustmentId", "required": true, "schema": { "type": "string" }, "description": "The adjustment ID" } ], "responses": { "204": { "description": "The adjustment was deleted. No invoice changed." }, "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/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, "pdfSource": null, "documentWithheldReason": 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": "expand", "schema": { "type": "string" }, "description": "Comma-separated list of fields to expand. Supports: items — resolves each returned line's item and that item's external accounting codes into an `items` collection, so a line can be translated to a GL/SKU code without a second call." }, { "in": "query", "name": "provider", "schema": { "$ref": "#/components/schemas/Provider" }, "description": "Narrows which external references are returned per item when expand=items. Matched exactly against the provider stored on the reference (e.g. accountsiq); there is no allowlist of known providers, but the value must satisfy the same format every stored provider does, so a malformed one is rejected rather than answered with an empty result that reads as \"nothing is mapped\". It never removes lines or items: an item with no reference for this provider comes back with an empty list, so unmapped SKUs stay visible. Ignored when the items expansion is not requested." }, { "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. Supports: lineItems, items. `items` resolves each returned line's item and its external accounting codes into an `items` collection inside the lineItems block; because those ids come from the lines, requesting `items` also expands `lineItems` on its default paging." }, { "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": "Opaque pagination token for line items when expand=lineItems, taken from a previous response's nextPageToken. Do not construct or parse this value." }, { "in": "query", "name": "provider", "schema": { "$ref": "#/components/schemas/Provider" }, "description": "Narrows which external references are returned per item when expand=items. Matched exactly against the provider stored on the reference (e.g. accountsiq); there is no allowlist of known providers, but the value must satisfy the same format every stored provider does, so a malformed one is rejected rather than answered with an empty result that reads as \"nothing is mapped\". It never removes lines or items: an item with no reference for this provider comes back with an empty list, so unmapped SKUs stay visible. Ignored when the items expansion is not requested." } ], "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://api.paygentic.io/v2/invoices/inv_r1s2t3u4v5w6x7y8/pdf", "pdfSource": "paygentic", "documentWithheldReason": null, "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" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "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": "Opaque pagination token to fetch the next page of results, taken from a previous response's nextPageToken. Do not construct or parse this value." }, { "in": "query", "name": "expand", "schema": { "type": "string" }, "description": "Comma-separated list of fields to expand. Supports: items — resolves each returned line's item and that item's external accounting codes into an `items` collection, so a line can be translated to a GL/SKU code without a second call." }, { "in": "query", "name": "provider", "schema": { "$ref": "#/components/schemas/Provider" }, "description": "Narrows which external references are returned per item when expand=items. Matched exactly against the provider stored on the reference (e.g. accountsiq); there is no allowlist of known providers, but the value must satisfy the same format every stored provider does, so a malformed one is rejected rather than answered with an empty result that reads as \"nothing is mapped\". It never removes lines or items: an item with no reference for this provider comes back with an empty list, so unmapped SKUs stay visible. Ignored when the items expansion is not requested." } ], "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 } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v2/invoices/{id}/pdf": { "get": { "tags": [ "Invoices V2" ], "summary": "Download Invoice PDF", "description": "Downloads the Paygentic-rendered invoice document. The caller must be authenticated and entitled to the invoice; the stored document is streamed back, so no storage URL is ever handed out. Returns 404 when the invoice's document is the tax provider's rather than ours — in that case the invoice resource reports pdfSource `tax_provider` and its pdfUrl points at the provider's link instead.", "operationId": "downloadInvoicePdf", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The invoice ID" } ], "responses": { "200": { "description": "The invoice document", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "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", "description": "Whether this reference claims `(provider, externalId)` — the code resolves back to this one entity. Unique per merchant; unclaimed references are aliases. **Omitting it claims the code.** Send `false` for a code that is only ever sent outward, such as a ledger account several items post to — claiming that refuses the second item to use it. The default is not derived from the provider: what a code is for is a property of the operation recording it, and one provider can both resolve an arriving code and be sent a selected one. Declaring a schema default here would defeat the distinction, because a generated client materialises the default into the request body and the caller can no longer express \"I did not say\"." }, "isDefault": { "type": "boolean", "description": "Whether this is the code sent *to* the provider for this entity. At most one per `(entityType, entityId, provider)`. **Omit** to have the entity's first code for the provider designated automatically — see the note on `isPrimary` for why this carries no schema default." }, "moveClaim": { "type": "boolean", "description": "Take this code's claim from whichever entity currently holds it, in the same transaction.\n\nWithout it, claiming a code another entity claims is a `409` identifying the holder — the right answer to an accident, and the common case. With it, the reassignment is the point.\n\nIt exists because the alternative route — remove the old claim, then create the new one — leaves a window in which the code resolves to nothing. An arrival in that window is still recorded, untagged rather than rejected, so nothing is lost; but it is silent while it lasts and leaves work to repair.\n\nDeliberately opt-in, unlike moving a designation. A designation moves within one entity; a claim moves *between* entities and changes what future arrivals resolve to, which should never be a side effect of recording a code. Ignored when the write is not claiming the code." } } } } } }, "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" }, "catalogId": { "$ref": "#/components/schemas/ProductId", "description": "The product this item belongs to." }, "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" }, "404": { "$ref": "#/components/responses/NotFound" }, "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": "catalogId", "in": "query", "schema": { "$ref": "#/components/schemas/ProductId" }, "description": "Filter items by the product they are filed under" }, { "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." }, { "name": "includeArchived", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "Include archived items in the results. By default, archived items are omitted. This is ignored when resolving by `provider` and `externalId`, which always returns the matching item regardless of archived status." } ], "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" }, "catalogId": { "type": "string", "pattern": "^prod_[a-zA-Z0-9]+$", "nullable": true, "description": "The product this item belongs to." }, "archived": { "type": "boolean", "description": "Set to true to retire this item from your catalog, or false to restore it. Archived items remain readable and continue to resolve on historical invoices. Archiving also releases this item's claim on its external codes: any reference it holds as primary becomes non-primary, freeing that (provider, externalId) for a replacement item while the reference stays attached so this item's own invoice lines keep resolving it. Restoring the item does not reclaim primary status. Archiving is rejected while live billableMetrics or fees are anchored to the item — re-tag or retire those charges first." }, "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" } } } }, "/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", "itemId", "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", "description": "The product this metric belongs to. Always populated; derived from the item's catalog when the metric is tagged with an item." }, "itemId": { "type": "string", "pattern": "^itm_[a-zA-Z0-9]+$", "description": "The item this metric is tagged with, or null when untagged. Used to map this metric's invoice lines to an external accounting/tax identity.", "nullable": true }, "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" } }, "ItemId": { "type": "string", "pattern": "^itm_[a-zA-Z0-9]+$", "description": "Unique identifier for an item" }, "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, "maximum": 1000000000, "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", "minLength": 1, "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", "itemId", "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", "description": "The product this fee belongs to. Always populated; derived from the item's catalog when the fee is tagged with an item." }, "itemId": { "type": "string", "pattern": "^itm_[a-zA-Z0-9]+$", "description": "The item this fee is tagged with, or null when untagged. Used to map this fee's invoice lines to an external accounting/tax identity.", "nullable": true }, "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, "description": "The allowance this price declares for the feature. An empty object where the price attaches the feature without declaring one." }, "feature": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "metered", "static", "boolean" ] } } } } }, "PricingUnitId": { "type": "string", "pattern": "^pu_[a-zA-Z0-9]+$", "description": "Unique identifier for a pricing unit" }, "PriceTax": { "type": "object", "description": "A price's tax declaration. Optional on write — a price that declares nothing is `IN_SCOPE`, and is billed and taxed exactly as it was before this object existed. Always present on read. Replaced as a whole on update: send the object to change it, omit it to leave it alone.", "required": [ "supplyScope" ], "properties": { "supplyScope": { "type": "string", "enum": [ "IN_SCOPE", "OUTSIDE_SCOPE" ], "description": "Whether this price's money is consideration for a supply — the one tax fact only you can state, because it is settled when you agree the deal rather than derived from what was sold. `IN_SCOPE` (the default) is consideration: it enters the taxable amount, positive as a charge or negative as a reduction in the price of the supply it applies to. `OUTSIDE_SCOPE` money is not consideration for anything, so it does not change the taxable amount, carries no tax, does not appear on the tax document, and nets into the amount payable after tax. This means \"not consideration for a supply\" — it does NOT mean \"a supply outside this jurisdiction\": exports and place-of-supply answers are worked out from the addresses on the sale by the tax provider, and are never declared on a price. How a supply is then classified — standard, zero-rated, exempt — is the tax provider's determination and is not set here either. Omit the whole `tax` object to leave a price in scope; there is deliberately no schema default on this property, so that a misspelt key is refused rather than silently defaulted." }, "outsideScopeLabel": { "type": "string", "enum": [ "CASHBACK", null ], "nullable": true, "description": "What an `OUTSIDE_SCOPE` amount is called in the invoice totals, so the wording follows the declaration rather than being retyped per price. Required when `supplyScope` is `OUTSIDE_SCOPE`, and rejected otherwise. `CASHBACK` is the only value today, and a price declaring it must use the `standard` model and must not carry a positive `unitPrice` — a cashback is money paid back, not charged." } } }, "Price": { "type": "object", "required": [ "id", "object", "merchantId", "model", "paymentTerm", "invoiceDisplayName", "properties", "createdAt", "updatedAt", "quantity", "tax" ], "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." }, "isObligation": { "type": "boolean", "default": false, "description": "A fixed amount owed whole rather than a per-period rate. An obligation is not prorated over a partial first period: when a subscription starts before its billing anchor, no truncated stub is billed and the first charge is the full amount at the next anchor. An obligation also refuses an interval boundary that falls strictly inside one of its own billing periods, since part of an amount owed whole is not a thing to bill. Defaults to false, which is a rate and is today's behaviour for every price. Not supported on a metered price, whose amount resolves from usage at close." }, "rateType": { "type": "string", "enum": [ "amount", "proportion" ], "default": "amount", "description": "What properties.unitPrice is denominated in. 'amount' (the default) is an amount of the invoice currency for each unit metered, so the quantity is the multiplier. 'proportion' is the reverse: a dimensionless share of a currency-denominated quantity, so '0.02' is 2% and the invoice prints '2.00%'. Presentation only. Requires a standard metered price in real currency." }, "invoiceDisplayGroup": { "type": "string", "description": "Presentation only. Prices sharing this value, within one billing period, print as a single row on the rendered invoice PDF and are described by this string. Every member still bills its own line item on the ledger, this API and the compliance document. The combined row's rate is derived from the members' own rates. Requires the 'standard' pricing model. Sample values: 'Cross Border Fees', 'FX Fees'", "nullable": true }, "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." }, "tax": { "$ref": "#/components/schemas/PriceTax" }, "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" }, "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": [ "published", "archived" ], "description": "Lifecycle status of the version." }, "publishedAt": { "type": "string", "format": "date-time", "description": "When this version was published." }, "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, "minProperties": 1, "description": "A reference-by-id price diff applied to the prices of the plan's current version. Every id references an existing price created via POST /prices; inline price definitions are not accepted. A mint must carry at least one price change, so an empty body is rejected. A version must carry at least one price, so a diff that would leave none is rejected.", "properties": { "addPrices": { "type": "array", "items": { "$ref": "#/components/schemas/schemas-PriceId" }, "description": "Prices to add to the version. Each must not already be on the plan's current version." }, "removePrices": { "type": "array", "items": { "$ref": "#/components/schemas/schemas-PriceId" }, "description": "Prices to remove. Each must be on the plan's current 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 so the price keeps its identity where the plan is configured for stable price ids. replacesPriceId must be on the plan's current version; withPriceId is the new price." } } }, "PlanVersionPriceSlot": { "description": "One price slot on a plan version. Every `Price` field is present, plus `priceDeleted` layered on top.", "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." } } } ] }, "PlanVersion": { "type": "object", "description": "A single plan version, including its price slots. Extends the list summary with the version's prices.", "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": [ "published", "archived" ], "description": "Lifecycle status of the version." }, "publishedAt": { "type": "string", "format": "date-time", "description": "When this version was published." }, "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 follows on from — the version that was live when this one was created, and whose prices it was built from. Absent for versions created before this field existed." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When this version was last modified." }, "prices": { "type": "array", "items": { "$ref": "#/components/schemas/PlanVersionPriceSlot" }, "description": "The price slots that make up this version." } } }, "TransitionPlanVersionRequest": { "type": "object", "additionalProperties": false, "description": "Sets this version as the plan's default.", "properties": { "default": { "type": "boolean", "description": "Set to true to point the plan's default at this version. Idempotent on the already-default version." } } }, "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 the legacy models ('dynamic', 'percentage') retained for existing prices; 'standard' and 'volume' can be created (see PriceModelInput)." }, "PriceProperties": { "type": "object", "oneOf": [ { "title": "StandardPriceProperties", "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. A negative value defines a usage-scaled rebate: the line's subtotal is negative and reduces the invoice. A rebate never drives an invoice total below zero, so set rebate rates below the charges they offset. A negative unitPrice is only valid on a metered price (a billableMetricId is required — there is no usage to scale on a fee price) and cannot be combined with grantDiscountEnabled, a hard-limit feature, or a pricingUnitId. When a rebate and a charge price share a billable metric but attach to different features, they compute against different quantity bases: a price attached to a feature bills the overage against its allowance, while a featureless price bills the raw metered usage. That is a permitted configuration, not an error. Attach both to the same feature to bill them against one basis." } }, "required": [ "unitPrice" ] }, { "title": "DynamicPriceProperties", "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" ] }, { "title": "VolumePriceProperties", "type": "object", "description": "Volume pricing model", "properties": { "tiers": { "type": "array", "minItems": 1, "description": "Ordered ladder of bands. The band is selected by the period's total metered usage, and its rate applies to every billed unit. A band matches when the quantity is less than or equal to its `upTo`, and the first matching band wins; the previous band's `upTo` is the exclusive lower bound, and the first band's floor is 0.", "items": { "title": "VolumeTier", "type": "object", "required": [ "upTo", "unitPrice" ], "properties": { "upTo": { "type": [ "string", "null" ], "description": "Inclusive upper bound of the band, as a decimal string. Null on the last band only, which carries the remainder. Sample values: '100' bounds the band at 100 units, null leaves the top open." }, "unitPrice": { "type": "string", "description": "Per-unit cost inside this band, as a decimal string, capped at 6 decimal places. Sample values: '5' represents $5 per unit, '0.004' represents $0.004 per unit." } } } } }, "required": [ "tiers" ] }, { "title": "PercentagePriceProperties", "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" ] } ] }, "RateType": { "type": "string", "enum": [ "amount", "proportion" ], "description": "What properties.unitPrice is denominated in. 'amount' (the default) is an amount of the invoice currency for each unit metered, so the quantity is the multiplier. 'proportion' is the reverse: a dimensionless share of a currency-denominated quantity, so '0.02' is 2% and the invoice prints '2.00%'. Presentation only. Requires a standard metered price in real currency." }, "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", "tax" ], "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" }, "invoiceDisplayGroup": { "type": "string", "description": "Presentation only. Prices sharing this value, within one billing period, print as a single row on the rendered invoice PDF and are described by this string. Every member still bills its own line item on the ledger, this API and the compliance document. The combined row's rate is derived from the members' own rates. Requires the 'standard' pricing model. Sample values: 'Cross Border Fees', 'FX Fees'", "nullable": true }, "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." }, "isObligation": { "type": "boolean", "default": false, "description": "A fixed amount owed whole rather than a per-period rate. An obligation is not prorated over a partial first period: when a subscription starts before its billing anchor, no truncated stub is billed and the first charge is the full amount at the next anchor. An obligation also refuses an interval boundary that falls strictly inside one of its own billing periods, since part of an amount owed whole is not a thing to bill. Defaults to false, which is a rate and is today's behaviour for every price. Not supported on a metered price, whose amount resolves from usage at close." }, "rateType": { "$ref": "#/components/schemas/RateType", "default": "amount" }, "tax": { "$ref": "#/components/schemas/PriceTax" }, "quantity": { "$ref": "#/components/schemas/PriceQuantity" } } }, "PriceModelInput": { "type": "string", "enum": [ "standard", "volume" ], "description": "Pricing model accepted when creating or updating a price. 'standard' takes a single rate in properties.unitPrice; 'volume' takes a ladder of bands in properties.tiers. Percentage-style and revenue-share pricing are expressed with 'standard' plus a unit-price multiplier (e.g. 10% ⇒ unitPrice '0.1'). The legacy 'dynamic' 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. Omit the field to attach the feature without declaring an allowance. An explicit empty object declares an allowance with default values." } } }, "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", "deprecated": true, "description": "Deprecated. Legacy-only, not populated for new subscriptions." }, "minimumAccountBalance": { "type": "string", "deprecated": true, "description": "Deprecated. Legacy-only, not populated for new subscriptions." }, "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", "deprecated": true, "description": "Deprecated. Legacy-only, not populated for new subscriptions." }, "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", "reset_cycle_misaligned" ], "description": "Coded failure reason. `entitlement_failed` means the entitlement itself could not be created. `grant_mint_failed` means the entitlement was created but its initial metered grant could not be minted; re-running this reconciliation retries the mint. `reset_cycle_misaligned` means the feature grants a credit discount on a reset cycle that is not the window it would be billed on, so re-running cannot succeed until the plan or the price is corrected." } }, "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" ] }, "SubscriptionAdjustment": { "type": "object", "required": [ "object", "id", "subscriptionId", "type", "percentageDiscount", "usageDiscount", "targetPriceIds", "effectiveFrom", "effectiveTo", "description", "createdAt" ], "properties": { "object": { "type": "string", "enum": [ "subscriptionAdjustment" ] }, "id": { "type": "string", "description": "The adjustment ID" }, "subscriptionId": { "$ref": "#/components/schemas/SubscriptionId" }, "type": { "type": "string", "enum": [ "percentageDiscount", "usageDiscount" ] }, "percentageDiscount": { "type": [ "string", "null" ], "description": "The discount rate as a decimal fraction between 0 and 1. \"0.35\" means 35 percent. Null on a usageDiscount, which carries a unit count instead." }, "usageDiscount": { "type": [ "string", "null" ], "description": "The number of usage units taken off the targeted line's billable quantity. Null on a percentageDiscount, which carries a rate instead." }, "targetPriceIds": { "type": "array", "items": { "type": "string" }, "description": "The prices this adjustment reduces. Exactly one metered price on a usageDiscount; empty on a percentageDiscount, which reduces every discountable charge." }, "effectiveFrom": { "type": "string", "format": "date-time", "description": "Opens the window. Read per type: INCLUSIVE on a percentageDiscount, whose window is prorated by day overlap; EXCLUSIVE on a usageDiscount, which corrects a line whose period END falls strictly after this instant." }, "effectiveTo": { "type": [ "string", "null" ], "format": "date-time", "description": "Closes the window, or null for never. Read per type: EXCLUSIVE on a percentageDiscount; INCLUSIVE on a usageDiscount, which corrects a line whose period END falls on or before this instant." }, "description": { "type": [ "string", "null" ], "description": "The deal's own name. Shown on each discount line a percentageDiscount emits; a usageDiscount emits no line, so its description is carried here only." }, "createdAt": { "type": "string", "format": "date-time" } } }, "SubscriptionAdjustmentsResponse": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionAdjustment" } }, "pagination": { "$ref": "#/components/schemas/OffsetPagination" } } }, "CreatePercentageDiscountAdjustment": { "type": "object", "additionalProperties": false, "required": [ "type", "percentageDiscount", "effectiveFrom" ], "properties": { "type": { "type": "string", "enum": [ "percentageDiscount" ], "description": "Reduces every discountable charge on the invoice by a rate." }, "percentageDiscount": { "type": "string", "description": "The discount rate as a decimal fraction between 0 and 1, sent as a string. \"0.35\" means 35 percent. \"1\" means 100 percent, not 1 percent. At most 6 decimal places. A value of 0 or above 1 is rejected." }, "effectiveFrom": { "type": "string", "format": "date-time", "description": "The first instant the discount applies. Inclusive." }, "effectiveTo": { "type": [ "string", "null" ], "format": "date-time", "description": "The instant the discount stops applying. Exclusive, so a window ending on the same date another begins neither overlaps nor leaves a gap. Null means the discount never stops, and it cannot be ended later — set an instant whenever the deal has a known end date. Must be after effectiveFrom." }, "description": { "type": [ "string", "null" ], "maxLength": 255, "description": "The deal's own name, shown on each discount line of the invoice." }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 255, "description": "A key of your choosing that makes a retry safe. Sending the same key against the same subscription returns the adjustment already created and creates no second one. Without a key a retried request creates a second adjustment, and two percentage discounts compound — two of 0.35 bill 57.75 percent off, not 35 percent.", "example": "adj_fy26_growth_001" } } }, "CreateUsageDiscountAdjustment": { "type": "object", "additionalProperties": false, "required": [ "type", "usageDiscount", "targetPriceIds", "effectiveFrom" ], "properties": { "type": { "type": "string", "enum": [ "usageDiscount" ], "description": "Reduces one metered price's billable quantity by a number of usage units, before the line is priced." }, "usageDiscount": { "type": "string", "pattern": "^[0-9]+(\\.[0-9]+)?$", "description": "The number of usage units to take off the billable quantity, sent as a plain decimal string. \"300\" waives 300 units. Greater than 0, at most 6 decimal places, fewer than 35 digits before the point. Plain notation only — no sign, exponent, hex or digit separators, so \"1_000\" and \"1e3\" are rejected rather than read as 1000. Applied in full or not at all — a unit count is never prorated across a partial window — and once per matching line, so an invoice bundling several periods is corrected on each of them. The line is floored at 0, so a discount larger than the billable quantity zeroes it rather than crediting. On a volume ladder the corrected quantity also re-selects the band, so a waiver that crosses a boundary can bill more than the uncorrected line did: waiving 300 of 1000 units on a ladder of 2.00 up to 999 and 1.00 beyond bills 700 at 2.00 for 1400.00, where the 1000 units billed 1000.00. That is the ladder's price for the corrected usage — what a customer who genuinely used 700 units pays — so check the ladder before waiving units near a band boundary." }, "targetPriceIds": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 1, "description": "Exactly one metered price of this subscription, priced as standard or volume. Usage units are not comparable across metrics, so a usage discount names the one price it reduces. A dynamic or percentage price is refused: its quantity is a monetary amount rather than a unit count. A price billing at a negative rate (a usage-scaled rebate) is refused too, because removing its units would raise the invoice." }, "effectiveFrom": { "type": "string", "format": "date-time", "description": "Opens the window. Exclusive for this type: a metered line is corrected when its period END falls after this instant, so a window opening exactly when a period ends belongs to the next period, not that one. Set it to the start of the period you are correcting." }, "effectiveTo": { "type": [ "string", "null" ], "format": "date-time", "description": "Closes the window. INCLUSIVE for this type, unlike percentageDiscount: a metered line bills in arrears, so set this to the exact period end you are correcting and that period is covered. Null means the discount never stops — it then takes its full unit count off this price on EVERY later invoice, so set both bounds whenever you are correcting one period. Must be after effectiveFrom." }, "description": { "type": [ "string", "null" ], "maxLength": 255, "description": "Your own name for this correction. A usageDiscount emits no invoice line, so this is printed nowhere on the invoice — it is returned on the adjustment for your own records." }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 255, "description": "A key of your choosing that makes a retry safe. Sending the same key against the same subscription returns the adjustment already created and creates no second one. Without a key a retried request creates a second adjustment, and usage discounts against one price SUM — two of \"300\" waive 600 units, not 300. Nothing else detects a duplicate.", "example": "adj_mar_outage_001" } } }, "CreateSubscriptionAdjustmentRequest": { "description": "One adjustment to attach to the subscription. The type decides which number the body carries: a rate for percentageDiscount, a unit count and one target price for usageDiscount.", "oneOf": [ { "$ref": "#/components/schemas/CreatePercentageDiscountAdjustment" }, { "$ref": "#/components/schemas/CreateUsageDiscountAdjustment" } ], "discriminator": { "propertyName": "type", "mapping": { "percentageDiscount": "#/components/schemas/CreatePercentageDiscountAdjustment", "usageDiscount": "#/components/schemas/CreateUsageDiscountAdjustment" } } }, "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" }, "itemId": { "type": "string", "nullable": true, "description": "Item the line's charge was tagged with, recorded when the line was generated and not re-resolved on read. A discount line carries the same item as the charge it offsets. `null` means the charge carried no tag at that moment, the line predates item stamping, or the line has no originating charge (a grant-credit purchase) — it is an expected value, not an error. Use `priceId` to tell those cases apart." }, "priceId": { "type": "string", "nullable": true, "description": "The price this line was generated from, or `null` when the line has no originating charge. With `itemId` it says whether a missing tag is fixable: `priceId` set and `itemId` null means the charge was simply untagged, which tagging it and restamping resolves; both null means the line records a grant-credit purchase, which is deferred revenue and is never tagged. Any measure of outstanding mapping work must exclude the latter or it can never reach zero." }, "periodStart": { "type": "string", "format": "date-time", "description": "Start of the billed window this line covers, inclusive. Distinct from the invoice's own period, which is the union of its lines' windows (earliest start to latest end) and so covers time no single line bills on a mixed-timing invoice." }, "periodEnd": { "type": "string", "format": "date-time", "description": "End of the billed window this line covers, exclusive — the instant at `periodEnd` belongs to the next window. Equal to `periodStart` on a one-off charge, which bills at an instant and has no period grid." }, "paymentTerm": { "type": "string", "enum": [ "in_advance", "in_arrears", null ], "nullable": true, "description": "When this line falls due relative to the window it covers: `in_advance` at the window's start, `in_arrears` at its end. A metered line is stamped `in_arrears`, because usage is only known once the window closes — but metered rows written before that rule carry `null` and were never backfilled, so do not read a metered line's term as guaranteed. `null` also means the line is not billed on a term of its own: manual, grant-discount and adjustment lines carry no term, and an adjustment instead falls due with the charge it reduces. Treat `null` as an expected value on any line type, not an error." }, "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" } } }, "ExternalReferenceId": { "type": "string", "pattern": "^xrf_[a-zA-Z0-9]+$", "description": "Unique identifier for an external reference" }, "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`)" }, "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" } } }, "ResolvedItem": { "type": "object", "description": "An item a line was tagged with, together with its external accounting/tax codes. Deliberately narrower than the /v0/items Item resource: it carries what is needed to translate a line into a GL/SKU code, not the full record.", "required": [ "id", "name", "catalogId", "archivedAt", "externalReferences" ], "properties": { "id": { "$ref": "#/components/schemas/ItemId" }, "name": { "type": "string", "description": "Human-readable item name" }, "catalogId": { "type": "string", "nullable": true, "description": "The product this item belongs to, for grouping lines by product" }, "archivedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When this item was retired from the catalog. Archived items still resolve here — invoices that already reference them have to keep resolving — but cannot be tagged onto new pricing. Null while active." }, "externalReferences": { "type": "array", "description": "The item's external codes, narrowed to the requested provider when one is given. An empty list means the item is not yet mapped for that provider — an actionable state, not an error. More than one may be returned for a single provider, and more than one of those may carry `isPrimary: true`: the uniqueness constraint runs the other way round (an external id is the primary reference of at most one item per merchant), so it does not reduce an item's references to one per provider. Entries are ordered newest first, tie-broken by id, so the order is stable across reads — but a consumer that needs exactly one code must choose deliberately rather than assume there is only one.", "items": { "$ref": "#/components/schemas/ExternalReference" } } } }, "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, or if expand=items is, which implies it)", "properties": { "invoiceId": { "type": "string", "description": "The invoice ID" }, "lineItems": { "type": "array", "description": "Array of line items for this page", "items": { "$ref": "#/components/schemas/InvoiceLineItem" } }, "items": { "type": "array", "description": "Items the returned lines were tagged with, each appearing once, ordered by id. Only present when expand=items is requested. Scoped to the lines in THIS response, not the whole invoice — combine the collections across pages for an invoice-wide set. Join a line to its entry via the line's itemId. A line whose itemId has no entry here is a data-integrity fault — the tag points at an item that no longer resolves for this merchant. It is not the same as an untagged line and must not be counted as unmapped; report it.", "items": { "$ref": "#/components/schemas/ResolvedItem" } }, "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": "Link to the invoice document, or null when there is none. For Paygentic-rendered documents this is GET /v2/invoices/{id}/pdf, which requires authentication; for documents supplied by the tax provider it is the provider's own direct link. The URL is stable and does not expire. Branch on pdfSource rather than on the shape of this URL." }, "pdfSource": { "type": "string", "enum": [ "paygentic", "tax_provider", null ], "nullable": true, "description": "Who produced the document at pdfUrl, or null when there is none. `paygentic` means pdfUrl is this API's download endpoint and the request must carry your API key; `tax_provider` means it is the provider's own link, which opens directly in a browser." }, "documentWithheldReason": { "type": "string", "enum": [ "tax_unreconciled", "issuer_identity_incomplete", "tax_component_unpriceable", "ledger_mismatch", "tax_provider_disagrees", null ], "nullable": true, "x-speakeasy-unknown-values": "allow", "description": "Why no Paygentic-rendered document exists for this invoice, or null when none was withheld. A tax-registered merchant's document is a compliance artefact, so it is withheld unless the recorded tax reconciles with the provider exactly and the registered issuer identity is complete. Non-null therefore always accompanies pdfSource `tax_provider` or null, and never `paygentic`. Use it to tell a withheld document apart from an invoice the tax provider serves by design — both report pdfSource `tax_provider`, but only a withheld one can be repaired by POST /v2/invoices/{id}/generate-pdf. `tax_unreconciled`: the provider's tax figure was never recorded against this invoice. `issuer_identity_incomplete`: the registered legal name, tax ID or address could not be read. `tax_component_unpriceable`: a recorded tax component carried no presentable amount. `ledger_mismatch`: the recorded tax figures and the invoice's own totals disagree. `tax_provider_disagrees`: the provider re-read its filing and reported a different tax to the one this invoice was charged — terminal, because correcting an issued invoice is a credit note's job, so retrying the repair cannot clear it. New values may be added, so treat an unrecognised one as withheld rather than failing." }, "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 this line was generated from, or `null` when the line has no originating charge. With `itemId` it says whether a missing tag is fixable: `priceId` set and `itemId` null means the charge was simply untagged, which tagging it and restamping resolves; both null means the line records a grant-credit purchase, which is deferred revenue and is never tagged. Any measure of outstanding mapping work must exclude the latter or it can never reach zero." }, "itemId": { "type": "string", "nullable": true, "description": "Item the line's charge was tagged with, recorded when the line was generated and not re-resolved on read. `null` means the charge carried no tag at that moment, the line predates item stamping, or the line has no originating charge (a grant-credit purchase) — it is an expected value, not an error. Use `priceId` to tell those cases apart." }, "invoiceId": { "type": "string", "nullable": true, "description": "The invoice ID if this item has been invoiced" }, "type": { "type": "string", "enum": [ "fee", "metered", "manual", "discount", "adjustment" ], "description": "The type of line item. 'discount' and 'adjustment' line items have negative subtotal/total amounts: 'discount' is a grant discount, 'adjustment' is a discount agreed on the subscription." }, "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" }, "usageDiscountIds": { "type": "array", "items": { "type": "string" }, "description": "The subscription adjustments of type `usageDiscount` that reduced this line's billable `quantity`. Empty for every other line. Where this is non-empty, `quantity` is below `meteredQuantity` because an operator waived units, rather than because a grant covered them." }, "paymentTerm": { "type": "string", "enum": [ "in_advance", "in_arrears", null ], "nullable": true, "description": "When the line falls due relative to the window it covers. A fee line carries its price's term; a metered line is stamped `in_arrears`, though metered rows predating that rule carry `null`. Manual, grant-discount and adjustment lines are billed on no term of their own and are `null`. `null` is listed in the enum as well as via `nullable` because OpenAPI 3.0 validators check the enum independently — `nullable: true` alone does not admit it, and createLineItem (which always returns null here) was emitting a schema-violating body." }, "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" } }, "items": { "type": "array", "description": "Items the returned lines were tagged with, each appearing once, ordered by id. Only present when expand=items is requested. Scoped to the lines in THIS response, not to any invoice as a whole — combine the collections across pages for a complete set. Join a line to its entry via the line's itemId. A line whose itemId has no entry here is a data-integrity fault — the tag points at an item that no longer resolves for this merchant. It is not the same as an untagged line and must not be counted as unmapped; report it.", "items": { "$ref": "#/components/schemas/ResolvedItem" } }, "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." }, "itemId": { "type": "string", "minLength": 1, "nullable": true, "description": "Optional item to tag this line with, for accounting/GL mapping. Must belong to the caller's merchant and must not be archived. A manual line has no price, so it is never reached by a later restamp — supplying it here is the only opportunity to tag it." } } }, "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" } }, "items": { "type": "array", "description": "Items the returned lines were tagged with, each appearing once, ordered by id. Only present when expand=items is requested. Scoped to the lines in THIS response, not the whole invoice — combine the collections across pages for an invoice-wide set. Join a line to its entry via the line's itemId. A line whose itemId has no entry here is a data-integrity fault — the tag points at an item that no longer resolves for this merchant. It is not the same as an untagged line and must not be counted as unmapped; report it.", "items": { "$ref": "#/components/schemas/ResolvedItem" } }, "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." }, "unit": { "type": "string", "description": "Unit label for metered costs (e.g. 'token', 'request'). Absent when the cost defines no unit." }, "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", "rebates" ], "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" }, "rebates": { "type": "string", "description": "Gross magnitude of usage-scaled rebates (negative metered line items) on invoices issued in this bucket, in dollars. Netted into issuedInvoices; surfaced here for visibility." }, "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." }, "totalRebates": { "type": "string", "description": "Gross total of usage-scaled rebates (negative metered line items) on invoices issued in the period, in dollars. Already netted into issued invoice grandTotals, so surfaced here for visibility. Omitted when groupBy=currency is active." }, "rebateCount": { "type": "number", "description": "Number of rebate line items on invoices 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]+$" }, "schemas-ExternalId": { "type": "string", "pattern": "^[a-zA-Z0-9_-]+$", "maxLength": 255, "description": "Identifier of the record in the external system" }, "Item": { "type": "object", "required": [ "id", "object", "merchantId", "name", "metadata", "externalReferences", "catalogId", "archivedAt", "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" } }, "catalogId": { "type": "string", "pattern": "^prod_[a-zA-Z0-9]+$", "description": "The product this item belongs to.", "nullable": true }, "archivedAt": { "type": "string", "format": "date-time", "nullable": true, "readOnly": true, "description": "When this item was retired from the catalog. Null while active." }, "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": "The schedule's end date. Always present." }, "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", "description": "Not supported for creating a billing schedule. Use orderId — every billing schedule belongs to an order." }, "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", "netsuite", "accountsiq" ], "description": "External provider a merchant can connect at the tenant level. `netsuite` and `accountsiq` are returned on reads wherever a connection exists, but connecting them is accepted only in local and development environments; elsewhere the connect request is refused with 404." }, "MerchantIntegrationId": { "type": "string", "pattern": "^mint_[a-zA-Z0-9]+$", "description": "Unique identifier for a merchant integration" }, "MappingCapabilities": { "type": "object", "required": [ "resolvesItemCodes", "sendsItemCodes" ], "additionalProperties": false, "description": "What this provider does with an item's external codes.\n\nTwo independent capabilities, not one direction: the behaviours are not alternatives. An integration can resolve an incoming item code *and* be sent a selected one on a different path, so a single `inbound`/`outbound` value would have to misdescribe it or forbid one of its operations.\n\nA capability that is not declared is unavailable rather than inferred. Declaring one does not make a provider connectable — that still requires its credentials and connection lifecycle.", "properties": { "resolvesItemCodes": { "type": "boolean", "description": "A code arriving from this provider must name exactly one of the merchant's items. The lookup key is the code, so several codes may point at one item while each code resolves to one — which is why a code recorded for this purpose is claimed, and a second item claiming it is a conflict." }, "sendsItemCodes": { "type": "boolean", "description": "A consumer needs one of an item's codes to send to this provider, and takes the item's designated one (`isDefault`). Because the lookup key is the item, several items may share one code — a chart of accounts exists so that many things sold roll into one account." } } }, "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", "capabilities", "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" }, "capabilities": { "$ref": "#/components/schemas/MappingCapabilities" }, "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" } } } }, "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" } } } }