{ "components": { "schemas": { "AuthResponse": { "properties": {}, "type": "object" }, "CancelPurchaseRequest": { "properties": { "reason": { "description": "Reason for cancellation", "type": "string" } }, "type": "object" }, "CancelRenewalRequest": { "properties": { "reason": { "description": "Reason for cancelling renewal", "type": "string" } }, "type": "object" }, "CheckLimitRequest": { "properties": { "customerRef": { "description": "Customer reference identifier", "example": "cus_3C4D5E6F", "type": "string" }, "meterName": { "description": "Canonical usage meter name used for limit checks (for example: requests, tokens).", "example": "requests", "type": "string" }, "planRef": { "description": "Plan reference to pre-select when creating a checkout session. If provided and the customer needs to purchase, the checkout page skips plan selection and shows the payment form directly.", "example": "pln_2B3C4D5E", "type": "string" }, "productRef": { "description": "Product reference identifier", "example": "prd_1A2B3C4D", "type": "string" }, "usageType": { "description": "Usage type alias for meterName. If both are provided, meterName takes precedence.", "example": "requests", "type": "string" } }, "required": [ "customerRef", "productRef" ], "type": "object" }, "CheckoutSessionResponse": { "properties": { "amount": { "description": "Amount in cents", "example": 2999, "type": "number" }, "checkoutUrl": { "description": "Checkout URL to open the checkout page", "example": "https://solvapay.com/customer/checkout?id=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6", "type": "string" }, "currency": { "description": "Currency code", "example": "USD", "type": "string" }, "id": { "description": "Checkout session ID", "example": "507f1f77bcf86cd799439011", "type": "string" }, "sessionId": { "description": "Public session ID used in checkout URL", "example": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6", "type": "string" }, "status": { "description": "Session status", "example": "active", "type": "string" } }, "required": [ "id", "sessionId", "amount", "currency", "status", "checkoutUrl" ], "type": "object" }, "CreateCheckoutSessionRequest": { "properties": { "customerReference": { "description": "Customer reference", "example": "cus_3c4d5e6f7g8h", "type": "string" }, "planRef": { "description": "Plan reference (optional)", "example": "pln_2b3c4d5e6f7g", "type": "string" }, "productRef": { "description": "Product reference (required)", "example": "prd_1a2b3c4d5e6f", "type": "string" } }, "required": [ "customerReference", "productRef" ], "type": "object" }, "CreateCustomerRequest": { "properties": { "email": { "description": "Customer email address (required)", "example": "customer@example.com", "type": "string" }, "externalRef": { "description": "External reference ID from your auth system to map this customer to an auth user (optional)", "example": "auth_user_12345", "type": "string" }, "name": { "description": "Customer full name (optional)", "example": "John Doe", "type": "string" } }, "required": [ "email" ], "type": "object" }, "CreateCustomerSessionRequest": { "properties": { "customerRef": { "description": "Customer reference identifier", "example": "cus_3c4d5e6f7g8h", "type": "string" }, "productRef": { "description": "Optional product reference or ID to scope the customer manage page to a single product.", "example": "prd_1a2b3c4d5e6f", "type": "string" } }, "required": [ "customerRef" ], "type": "object" }, "CreateCustomerSessionResponse": { "properties": { "customerUrl": { "description": "Full customer URL based on backend configuration (ready to redirect customer)", "example": "https://solvapay.com/customer/manage?id=e3f1c2d4b6a89f001122334455667788", "type": "string" }, "sessionId": { "description": "Customer session ID/token", "example": "e3f1c2d4b6a89f001122334455667788", "type": "string" } }, "required": [ "sessionId", "customerUrl" ], "type": "object" }, "CreatePlanRequest": { "properties": { "accessExpiryDays": { "description": "Access expiry in days", "example": 30, "type": "number" }, "billingCycle": { "description": "Billing cycle (required for recurring/hybrid, optional for post-paid usage-based)", "enum": [ "weekly", "monthly", "quarterly", "yearly", "custom" ], "example": "monthly", "type": "string" }, "currency": { "description": "Currency code (ISO 4217)", "enum": [ "USD", "EUR", "GBP", "SEK", "NOK", "DKK", "CAD", "AUD", "JPY", "CHF", "PLN", "CZK", "HUF", "RON", "BGN", "HRK", "RSD", "MKD", "BAM", "ALL", "ISK", "TRY", "RUB", "UAH", "BYN", "MDL", "GEL", "AMD", "AZN", "KZT", "KGS", "TJS", "TMT", "UZS", "MNT", "CNY", "KRW", "THB", "VND", "IDR", "MYR", "SGD", "PHP", "INR", "PKR", "BDT", "LKR", "NPR", "AFN", "IRR", "IQD", "JOD", "KWD", "LBP", "OMR", "QAR", "SAR", "SYP", "AED", "YER", "ILS", "EGP", "MAD", "TND", "DZD", "LYD", "SDG", "ETB", "KES", "TZS", "UGX", "RWF", "BIF", "DJF", "SOS", "ERN", "SLL", "GMD", "GNF", "CVE", "STN", "AOA", "ZAR", "BWP", "SZL", "LSL", "NAD", "ZMW", "ZWL", "MZN", "MWK", "MGA", "MUR", "SCR", "KMF", "MVR" ], "example": "USD", "type": "string" }, "default": { "description": "Whether this is the default plan", "example": false, "type": "boolean" }, "features": { "additionalProperties": true, "description": "Plan features (generic key/value, shape is provider-defined)", "example": { "apiAccess": true, "prioritySupport": false }, "type": "object" }, "freeUnits": { "description": "Number of free units included", "example": 100, "type": "number" }, "isFreeTier": { "description": "Whether this is a free tier plan", "example": false, "type": "boolean" }, "limit": { "description": "Usage limit for the meter", "example": 10000, "type": "number" }, "limits": { "additionalProperties": true, "description": "Usage limits (shape varies by plan type)", "example": { "maxTransactions": 1000 }, "type": "object" }, "maxActiveUsers": { "description": "Maximum number of active users", "example": 10, "type": "number" }, "metadata": { "additionalProperties": true, "description": "Additional metadata", "type": "object" }, "price": { "description": "Plan price in cents", "example": 2999, "type": "number" }, "requiresPayment": { "description": "Whether payment is required", "example": true, "type": "boolean" }, "status": { "description": "Plan status", "enum": [ "active", "inactive", "archived" ], "example": "active", "type": "string" }, "type": { "description": "Plan type exposed in SDK", "enum": [ "recurring", "one-time" ], "example": "recurring", "type": "string" } }, "type": "object" }, "CreatePreregistrationDto": { "properties": { "businessType": { "example": "SaaS", "type": "string" }, "companyName": { "example": "Acme Corp", "type": "string" }, "customFields": { "additionalProperties": { "type": "string" }, "type": "object" }, "email": { "example": "jane@company.com", "type": "string" }, "fullName": { "example": "Jane Smith", "type": "string" }, "useCase": { "example": "Purchase billing for our platform", "maxLength": 500, "type": "string" } }, "required": [ "email", "fullName", "companyName" ], "type": "object" }, "CreateProductRequest": { "properties": { "config": { "allOf": [ { "$ref": "#/components/schemas/ProductConfigDto" } ], "description": "Product-specific configuration" }, "description": { "description": "Product description", "example": "AI-powered writing tool", "type": "string" }, "imageUrl": { "description": "URL to the product image", "type": "string" }, "isMcpPay": { "default": false, "description": "Whether this product uses MCP Pay proxy", "type": "boolean" }, "metadata": { "additionalProperties": true, "description": "Arbitrary key-value metadata", "type": "object" }, "name": { "description": "Product name", "example": "AI Writing Assistant", "type": "string" }, "productType": { "description": "Free-form product type defined by the provider", "example": "Coding Assistant", "type": "string" } }, "required": [ "name" ], "type": "object" }, "CreateSecretKey": { "properties": {}, "type": "object" }, "CreateUser": { "properties": {}, "type": "object" }, "CreateWebhookEndpointDto": { "properties": { "description": { "description": "Webhook endpoint description", "example": "Production webhook", "type": "string" }, "url": { "description": "Webhook endpoint URL", "example": "https://example.com/webhook", "type": "string" } }, "required": [ "url" ], "type": "object" }, "CustomerResponse": { "properties": { "email": { "description": "Customer email address", "example": "customer@example.com", "type": "string" }, "externalRef": { "description": "External reference ID from your auth system (if set during creation or update)", "example": "auth_user_12345", "type": "string" }, "name": { "description": "Customer full name", "example": "John Doe", "type": "string" }, "purchases": { "description": "Active purchases", "items": { "$ref": "#/components/schemas/PurchaseInfo" }, "type": "array" }, "reference": { "description": "Customer reference identifier", "example": "cus_3c4d5e6f7g8h", "type": "string" } }, "required": [ "reference", "name", "email" ], "type": "object" }, "CustomerSessionResponse": { "properties": { "customerUrl": { "description": "Customer URL to open the customer page", "example": "https://solvapay.com/customer/manage?id=e3f1c2d4b6a89f001122334455667788", "type": "string" }, "id": { "description": "Customer session ID", "example": "507f1f77bcf86cd799439011", "type": "string" }, "sessionId": { "description": "Public session ID used in customer URL", "example": "e3f1c2d4b6a89f001122334455667788", "type": "string" }, "status": { "description": "Session status", "example": "active", "type": "string" } }, "required": [ "id", "sessionId", "status", "customerUrl" ], "type": "object" }, "DynamicClientRegistrationDto": { "properties": { "client_name": { "example": "My AI Agent", "type": "string" }, "client_uri": { "example": "https://example.com", "type": "string" }, "grant_types": { "example": [ "authorization_code", "refresh_token" ], "items": { "type": "string" }, "type": "array" }, "logo_uri": { "example": "https://example.com/logo.png", "type": "string" }, "policy_uri": { "example": "https://example.com/policy", "type": "string" }, "redirect_uris": { "example": [ "https://agent.example.com/callback" ], "items": { "type": "string" }, "type": "array" }, "response_types": { "example": [ "code" ], "items": { "type": "string" }, "type": "array" }, "software_id": { "example": "agent-123", "type": "string" }, "software_version": { "example": "1.0.0", "type": "string" }, "tos_uri": { "example": "https://example.com/tos", "type": "string" } }, "required": [ "client_name", "redirect_uris" ], "type": "object" }, "DynamicClientRegistrationResponseDto": { "properties": { "client_id": { "example": "client-id-123", "type": "string" }, "client_id_issued_at": { "example": 1734567890, "type": "number" }, "client_name": { "example": "My AI Agent", "type": "string" }, "client_secret": { "example": "client-secret-456", "type": "string" }, "client_secret_expires_at": { "example": 0, "type": "number" }, "grant_types": { "example": [ "authorization_code", "refresh_token" ], "items": { "type": "string" }, "type": "array" }, "redirect_uris": { "example": [ "https://agent.example.com/callback" ], "items": { "type": "string" }, "type": "array" }, "response_types": { "example": [ "code" ], "items": { "type": "string" }, "type": "array" }, "scope": { "example": "openid profile email", "type": "string" }, "token_endpoint_auth_method": { "example": "client_secret_basic", "type": "string" } }, "required": [ "client_id", "client_secret", "client_id_issued_at", "client_secret_expires_at", "client_name", "redirect_uris", "grant_types", "response_types", "scope", "token_endpoint_auth_method" ], "type": "object" }, "ExecuteAnalyticsQuery": { "properties": {}, "type": "object" }, "ExecuteMultipleQueries": { "properties": {}, "type": "object" }, "ExternalAccount": { "properties": { "accountHolderName": { "description": "Account holder name", "example": "John Doe", "type": "string" }, "accountHolderType": { "description": "Account holder type", "enum": [ "individual", "company" ], "example": "individual", "type": "string" }, "accountNumber": { "description": "Account number", "example": "000123456789", "type": "string" }, "country": { "description": "Country code", "example": "US", "type": "string" }, "currency": { "description": "Currency code", "example": "usd", "type": "string" }, "routingNumber": { "description": "Routing number", "example": "110000000", "type": "string" } }, "required": [ "country", "currency", "accountHolderName", "accountHolderType", "routingNumber", "accountNumber" ], "type": "object" }, "GetCustomerSessionResponse": { "properties": { "createdAt": { "description": "Session creation date", "example": "2025-01-01T11:45:00.000Z", "type": "string" }, "customer": { "allOf": [ { "$ref": "#/components/schemas/CustomerResponse" } ], "description": "Customer object from session data" }, "customerUrl": { "description": "Full customer URL based on backend configuration (ready to redirect customer)", "example": "https://solvapay.com/customer/manage?id=e3f1c2d4b6a89f001122334455667788", "type": "string" }, "expiresAt": { "description": "Session expiration date", "example": "2025-01-01T12:00:00.000Z", "type": "string" }, "sessionId": { "description": "Customer session ID/token", "example": "e3f1c2d4b6a89f001122334455667788", "type": "string" }, "status": { "description": "Session status", "enum": [ "active", "expired", "used" ], "example": "active", "type": "string" }, "updatedAt": { "description": "Session last update date", "example": "2025-01-01T11:45:00.000Z", "type": "string" } }, "required": [ "sessionId", "status", "customerUrl", "expiresAt", "customer", "createdAt", "updatedAt" ], "type": "object" }, "GithubLoginDto": { "properties": { "code": { "description": "The authorization code returned by GitHub", "type": "string" }, "redirect_uri": { "description": "The redirect URI used in the initial authorization request", "type": "string" }, "state": { "description": "The state parameter returned by GitHub (contains client_id)", "type": "string" } }, "required": [ "code", "redirect_uri", "state" ], "type": "object" }, "GoogleLoginDto": { "properties": { "code": { "description": "The authorization code returned by Google", "type": "string" }, "redirect_uri": { "description": "The redirect URI used in the initial authorization request", "type": "string" }, "state": { "description": "The state parameter returned by Google (contains client_id)", "type": "string" } }, "required": [ "code", "redirect_uri", "state" ], "type": "object" }, "LimitResponse": { "properties": { "checkoutSessionId": { "description": "Checkout session ID if payment is required", "example": "e3f1c2d4b6a89f001122334455667788", "type": "string" }, "checkoutUrl": { "description": "Checkout URL if payment is required", "example": "https://solvapay.com/customer/checkout?id=e3f1c2d4b6a89f001122334455667788", "type": "string" }, "meterName": { "description": "The meter name to use when tracking usage events", "example": "requests", "type": "string" }, "remaining": { "description": "Remaining usage units before hitting the limit", "example": 997, "type": "number" }, "withinLimits": { "description": "Whether the customer is within their usage limits", "example": true, "type": "boolean" } }, "required": [ "withinLimits", "remaining" ], "type": "object" }, "Login": { "properties": { "email": { "description": "Email to send a 6-digit login code to", "type": "string" } }, "required": [ "email" ], "type": "object" }, "McpBootstrapFreePlanConfig": { "properties": { "freeUnits": { "description": "Included free units (default 1000)", "example": 500, "type": "number" }, "name": { "description": "Free plan display name override", "example": "Starter", "type": "string" } }, "type": "object" }, "McpBootstrapPaidPlanInput": { "properties": { "billingCycle": { "description": "Billing cycle for recurring plans", "enum": [ "weekly", "monthly", "quarterly", "yearly", "custom" ], "example": "monthly", "type": "string" }, "currency": { "description": "Currency code (ISO 4217)", "example": "USD", "type": "string" }, "features": { "additionalProperties": true, "description": "Plan features", "type": "object" }, "freeUnits": { "description": "Included free units", "example": 1000, "type": "number" }, "key": { "description": "Logical plan key (must not be \"free\")", "example": "pro", "type": "string" }, "limit": { "description": "Plan usage limit", "example": 10000, "type": "number" }, "meterId": { "description": "Meter id for usage tracking", "example": "67f90f1f1b1c9c0b8df0f001", "type": "string" }, "name": { "description": "Plan display name", "example": "Pro", "type": "string" }, "price": { "description": "Plan price in cents (must be > 0)", "example": 2000, "type": "number" }, "type": { "description": "Plan type", "enum": [ "recurring", "one-time" ], "example": "recurring", "type": "string" } }, "required": [ "key", "name", "price", "currency" ], "type": "object" }, "McpBootstrapPreviewResult": { "properties": { "derivedDescription": { "description": "Product description derived from origin server instructions", "example": "MCP toolkit for document retrieval and summarization.", "type": "string" }, "derivedName": { "description": "Product name derived from origin MCP metadata or hostname fallback", "example": "acme-origin-mcp", "type": "string" }, "discoveredTools": { "description": "Discovered tools from the origin MCP server", "items": { "properties": { "description": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "type": "array" }, "metadataSource": { "description": "Source of derived metadata", "properties": { "description": { "enum": [ "request", "instructions", "none" ], "type": "string" }, "name": { "enum": [ "request", "origin", "hostname" ], "type": "string" } }, "type": "object" }, "suggestedMapping": { "description": "Suggested default tool-to-plan mapping for UI review", "items": { "properties": { "description": { "type": "string" }, "name": { "type": "string" }, "planKey": { "type": "string" } }, "type": "object" }, "type": "array" }, "validation": { "description": "Validation status for the provided bootstrap payload", "properties": { "errors": { "items": { "$ref": "#/components/schemas/McpBootstrapPreviewValidationError" }, "type": "array" }, "valid": { "type": "boolean" } }, "type": "object" } }, "required": [ "discoveredTools", "validation", "metadataSource", "suggestedMapping" ], "type": "object" }, "McpBootstrapRequest": { "properties": { "authApiKey": { "description": "Optional auth API key forwarded to origin server", "example": "sk-origin-123", "type": "string" }, "authHeaderName": { "description": "Optional auth header name forwarded to origin server", "example": "X-API-Key", "type": "string" }, "description": { "description": "Product description", "example": "MCP toolkit with tiered access", "type": "string" }, "freePlan": { "allOf": [ { "$ref": "#/components/schemas/McpBootstrapFreePlanConfig" } ], "description": "Free plan config overrides. A free plan is always created; this just customizes name/freeUnits." }, "imageUrl": { "description": "Product image URL", "type": "string" }, "mcpDomain": { "description": "Optional final MCP subdomain override (for example, value returned by bootstrap-subdomain-checks)", "example": "acme-docs", "type": "string" }, "metadata": { "additionalProperties": true, "description": "Arbitrary product metadata", "type": "object" }, "name": { "description": "Product name (optional when derivable from origin MCP metadata)", "example": "Acme MCP Toolkit", "type": "string" }, "originUrl": { "description": "Origin MCP server URL (must be https)", "example": "https://origin.example.com/mcp", "type": "string" }, "paidPlans": { "description": "Paid plan definitions requiring price + currency", "items": { "$ref": "#/components/schemas/McpBootstrapPaidPlanInput" }, "type": "array" }, "productType": { "description": "Free-form product type", "example": "MCP Server", "type": "string" }, "tools": { "description": "Tool to plan mapping configuration", "items": { "$ref": "#/components/schemas/McpBootstrapToolInput" }, "type": "array" } }, "required": [ "originUrl" ], "type": "object" }, "McpBootstrapResult": { "properties": { "autoMappedTools": { "description": "Auto-discovered tools used during bootstrap", "items": { "properties": { "description": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "type": "array" }, "mcpServer": { "additionalProperties": true, "description": "Created or updated MCP server identity", "example": { "defaultPlanId": "67f90f1f1b1c9c0b8df0f001", "id": "67f90f1f1b1c9c0b8df0f111", "mcpProxyUrl": "https://acme-docs.mcp.solvapay.com/mcp", "reference": "mcp_ABC123", "subdomain": "acme-docs", "url": "https://origin.example.com/mcp" }, "type": "object" }, "planMap": { "additionalProperties": true, "description": "Resolved plan mapping by bootstrap key", "example": { "free": { "id": "67f90f1f1b1c9c0b8df0f001", "name": "Free", "reference": "pln_FREE123" } }, "type": "object" }, "product": { "allOf": [ { "$ref": "#/components/schemas/SdkProductResponse" } ], "description": "Created product" }, "toolsAutoMapped": { "description": "True when tools were auto-discovered from origin because the request omitted tools", "example": true, "type": "boolean" } }, "required": [ "product", "mcpServer", "planMap" ], "type": "object" }, "McpBootstrapToolInput": { "properties": { "description": { "description": "Tool description", "example": "Search indexed documents", "type": "string" }, "name": { "description": "Tool name", "example": "search_docs", "type": "string" }, "noPlan": { "description": "If true, tool is publicly available without a plan", "example": false, "type": "boolean" }, "planIds": { "description": "Direct plan IDs allowed for this tool", "example": [ "67f90f1f1b1c9c0b8df0f001" ], "items": { "type": "string" }, "type": "array" }, "planKeys": { "description": "Bootstrap plan keys allowed for this tool (for example free or starter_paid)", "example": [ "free" ], "items": { "type": "string" }, "type": "array" }, "planRefs": { "description": "Plan references allowed for this tool", "example": [ "pln_ABC123" ], "items": { "type": "string" }, "type": "array" } }, "required": [ "name" ], "type": "object" }, "McpServerDto": { "properties": { "authHeaderName": { "description": "Custom auth header name for origin requests", "example": "X-API-Key", "type": "string" }, "avatarUrl": { "description": "Avatar image URL", "example": "https://example.com/avatar.png", "type": "string" }, "balance": { "description": "Current balance in cents", "example": 1500, "type": "number" }, "defaultPlanId": { "description": "Default plan ID for tool access gating. Must belong to the linked product and be a free-tier plan (isFreeTier=true or price=0).", "example": "pln_default", "type": "string" }, "hasAuthApiKey": { "description": "Whether an auth API key is configured", "example": true, "type": "boolean" }, "id": { "description": "Server ID", "example": "507f1f77bcf86cd799439011", "type": "string" }, "mcpProxyUrl": { "description": "SolvaPay proxy URL that MCP clients connect to", "example": "https://mytelescope.mcp.solvapay.com/mcp", "type": "string" }, "name": { "description": "Domain slug used to derive the MCP endpoint subdomain", "example": "my-mcp-server", "type": "string" }, "productId": { "description": "Associated product ID", "example": "507f1f77bcf86cd799439011", "type": "string" }, "providerId": { "description": "Provider ID that owns this server", "example": "507f1f77bcf86cd799439011", "type": "string" }, "reference": { "description": "Unique server reference", "example": "mcp_abc123", "type": "string" }, "status": { "description": "Server status", "enum": [ "active", "inactive", "suspended" ], "example": "active", "type": "string" }, "subdomain": { "description": "URL-safe subdomain derived from name", "example": "my-mcp-server", "type": "string" }, "tools": { "description": "Registered tools for this server", "items": { "$ref": "#/components/schemas/McpToolDto" }, "type": "array" }, "totalTransactions": { "description": "Total number of tool-call transactions", "example": 42, "type": "number" }, "url": { "description": "Origin URL of the actual MCP server", "example": "https://origin.example.com/mcp", "type": "string" } }, "required": [ "name", "subdomain", "url", "providerId" ], "type": "object" }, "McpToolDto": { "properties": { "description": { "description": "Human-readable tool description", "example": "Search indexed documents", "type": "string" }, "isVirtual": { "description": "Whether this is a virtual platform tool handled by SolvaPay", "example": false, "type": "boolean" }, "name": { "description": "Tool name", "example": "search_documents", "type": "string" }, "noPlan": { "description": "If true, the tool is unprotected (no purchase check or usage tracking)", "example": false, "type": "boolean" }, "planIds": { "description": "Plan IDs that grant access to this tool", "example": [ "pln_abc123" ], "items": { "type": "string" }, "type": "array" } }, "required": [ "name" ], "type": "object" }, "Plan": { "properties": { "accessExpiryDays": { "description": "Access expiry in days", "type": "number" }, "billingCycle": { "description": "Billing cycle", "example": "monthly", "type": "string" }, "billingModel": { "description": "Billing model", "enum": [ "pre-paid", "post-paid" ], "example": "pre-paid", "type": "string" }, "createdAt": { "description": "Creation timestamp", "type": "string" }, "currency": { "description": "Currency code (ISO 4217)", "example": "USD", "type": "string" }, "currencySymbol": { "description": "Currency symbol (derived from currency)", "example": "$", "type": "string" }, "features": { "additionalProperties": true, "description": "Plan features", "type": "object" }, "freeUnits": { "description": "Number of free units included", "example": 100, "type": "number" }, "id": { "description": "Plan ID", "example": "507f1f77bcf86cd799439011", "type": "string" }, "isActive": { "description": "Whether the plan is active (derived from status)", "example": true, "type": "boolean" }, "isFreeTier": { "description": "Whether this is a free tier plan", "example": false, "type": "boolean" }, "limit": { "description": "Usage limit for the meter", "example": 10000, "type": "number" }, "limits": { "additionalProperties": true, "description": "Usage limits", "type": "object" }, "maxActiveUsers": { "description": "Maximum number of active users", "type": "number" }, "measures": { "description": "What the plan measures for usage tracking", "example": "requests", "type": "string" }, "price": { "description": "Plan price in cents", "example": 2999, "type": "number" }, "pricePerUnit": { "description": "Price per usage unit", "example": 0.01, "type": "number" }, "reference": { "description": "Plan reference", "example": "pln_1A2B3C4D", "type": "string" }, "requiresPayment": { "description": "Whether payment is required", "example": true, "type": "boolean" }, "rolloverUnusedUnits": { "description": "Whether unused units roll over to next period", "example": false, "type": "boolean" }, "setupFee": { "description": "One-time setup fee", "example": 500, "type": "number" }, "status": { "description": "Plan status", "example": "active", "type": "string" }, "trialDays": { "description": "Free trial period in days", "example": 14, "type": "number" }, "type": { "description": "Plan type exposed in SDK", "enum": [ "recurring", "one-time" ], "example": "recurring", "type": "string" }, "updatedAt": { "description": "Last update timestamp", "type": "string" } }, "required": [ "type", "id", "reference", "price", "currency", "isFreeTier", "requiresPayment", "isActive", "status", "createdAt", "updatedAt" ], "type": "object" }, "PlanSnapshotDto": { "properties": { "billingCycle": { "description": "Billing cycle", "example": "monthly", "nullable": true, "type": "string" }, "currency": { "description": "Currency code", "example": "USD", "type": "string" }, "features": { "additionalProperties": true, "description": "Plan features", "nullable": true, "type": "object" }, "freeUnits": { "description": "Number of free units included", "example": 100, "type": "number" }, "limit": { "description": "Usage limit for the meter", "example": 5000, "type": "number" }, "limits": { "additionalProperties": true, "description": "Usage limits", "nullable": true, "type": "object" }, "meterId": { "description": "Meter ObjectId reference", "example": "507f1f77bcf86cd799439011", "type": "string" }, "planType": { "description": "Plan type", "example": "recurring", "type": "string" }, "price": { "description": "Plan price in cents", "example": 2999, "type": "number" }, "pricePerUnit": { "description": "Price per usage unit in cents", "example": 10, "type": "number" }, "reference": { "description": "Plan reference", "example": "pln_1A2B3C4D", "type": "string" } }, "required": [ "price", "currency", "planType" ], "type": "object" }, "ProductConfigDto": { "properties": { "deliveryMethod": { "description": "Delivery method", "example": "api", "type": "string" }, "fulfillmentType": { "description": "Fulfillment type", "example": "digital", "type": "string" }, "validityPeriod": { "description": "Validity period in days", "example": 30, "type": "number" } }, "type": "object" }, "PurchaseInfo": { "properties": { "amount": { "description": "Amount paid in original currency (in cents)", "example": 9900, "type": "number" }, "cancellationReason": { "description": "Reason for cancellation", "example": "Customer request", "type": "string" }, "cancelledAt": { "description": "When purchase was cancelled", "example": "2025-10-28T10:00:00Z", "type": "string" }, "currency": { "description": "Currency code", "example": "USD", "type": "string" }, "endDate": { "description": "End date of purchase", "example": "2025-11-27T10:00:00Z", "type": "string" }, "planSnapshot": { "description": "Snapshot of the plan at time of purchase", "type": "object" }, "productName": { "description": "Product name", "example": "API Gateway Manager", "type": "string" }, "productReference": { "description": "Product reference", "example": "prd_abc123", "type": "string" }, "reference": { "description": "Purchase reference", "example": "pur_1A2B3C4D", "type": "string" }, "startDate": { "description": "Start date", "example": "2025-10-27T10:00:00Z", "type": "string" }, "status": { "description": "Purchase status", "example": "active", "type": "string" } }, "required": [ "reference", "productName", "status", "startDate", "amount", "currency" ], "type": "object" }, "PurchaseResponse": { "properties": { "amount": { "description": "Amount in cents", "example": 9900, "type": "number" }, "autoRenew": { "description": "Auto-renew enabled", "type": "boolean" }, "billingCycle": { "description": "Billing cycle", "enum": [ "weekly", "monthly", "quarterly", "yearly" ], "type": "string" }, "cancellationReason": { "description": "Cancellation reason", "type": "string" }, "cancelledAt": { "description": "Cancelled at", "type": "string" }, "createdAt": { "description": "Created at", "type": "string" }, "currency": { "description": "Currency code", "example": "USD", "type": "string" }, "customerEmail": { "description": "Customer email", "example": "customer@example.com", "type": "string" }, "customerRef": { "description": "Customer reference", "example": "cus_3C4D5E6F", "type": "string" }, "endDate": { "description": "End date", "type": "string" }, "id": { "description": "Purchase ID", "example": "507f1f77bcf86cd799439011", "type": "string" }, "isFreeTier": { "description": "Whether this is a free tier purchase", "type": "boolean" }, "isRecurring": { "description": "Is recurring", "example": true, "type": "boolean" }, "nextBillingDate": { "description": "Next billing date", "type": "string" }, "paidAt": { "description": "Paid at timestamp", "type": "string" }, "planSnapshot": { "allOf": [ { "$ref": "#/components/schemas/PlanSnapshotDto" } ], "description": "Plan snapshot at time of purchase" }, "productId": { "description": "Product ID", "example": "507f1f77bcf86cd799439012", "type": "string" }, "productName": { "description": "Product name", "example": "API Gateway Manager", "type": "string" }, "productRef": { "description": "Product reference", "example": "prd_1A2B3C4D", "type": "string" }, "reference": { "description": "Purchase reference", "example": "pur_1A2B3C4D", "type": "string" }, "startDate": { "description": "Start date", "type": "string" }, "status": { "description": "Purchase status", "example": "active", "type": "string" }, "usage": { "allOf": [ { "$ref": "#/components/schemas/UsageBillingDto" } ], "description": "Usage billing state for usage-based plans" } }, "required": [ "id", "reference", "customerRef", "customerEmail", "productRef", "planSnapshot", "status", "amount", "currency", "startDate", "isRecurring", "createdAt" ], "type": "object" }, "RecordBulkMeterEventsDto": { "properties": { "events": { "description": "Array of events to record", "items": { "$ref": "#/components/schemas/RecordMeterEventDto" }, "type": "array" } }, "required": [ "events" ], "type": "object" }, "RecordMeterEventDto": { "properties": { "customerId": { "description": "Customer reference", "example": "cus_ABC123", "type": "string" }, "meterName": { "description": "Meter name to record against", "example": "requests", "type": "string" }, "productId": { "description": "Product ID to scope the usage event to", "type": "string" }, "productReference": { "description": "Product reference to scope the usage event to", "type": "string" }, "properties": { "additionalProperties": true, "description": "Arbitrary key-value tags", "example": { "endpoint": "/api/v1/search", "region": "us-east-1" }, "type": "object" }, "timestamp": { "description": "ISO 8601 timestamp (defaults to now)", "type": "string" }, "value": { "default": 1, "description": "Numeric value (default 1)", "example": 1, "type": "number" } }, "required": [ "meterName", "customerId" ], "type": "object" }, "RequestEmailChange": { "properties": { "newEmail": { "type": "string" } }, "required": [ "newEmail" ], "type": "object" }, "SdkPlanResponse": { "properties": { "billingCycle": { "description": "Billing cycle", "example": "monthly", "type": "string" }, "billingModel": { "description": "Billing model", "example": "pre-paid", "type": "string" }, "createdAt": { "description": "Creation timestamp", "type": "string" }, "currency": { "description": "Currency code (ISO 4217)", "example": "USD", "type": "string" }, "currencySymbol": { "description": "Currency symbol", "example": "$", "type": "string" }, "features": { "additionalProperties": true, "description": "Plan features", "type": "object" }, "freeUnits": { "description": "Included free units", "example": 1000, "type": "number" }, "id": { "description": "Plan ID", "example": "507f1f77bcf86cd799439011", "type": "string" }, "isActive": { "description": "Whether the plan is active", "example": true, "type": "boolean" }, "isFreeTier": { "description": "Whether this is a free tier plan", "example": false, "type": "boolean" }, "limit": { "description": "Usage limit for the meter", "example": 10000, "type": "number" }, "limits": { "additionalProperties": true, "description": "Usage limits", "type": "object" }, "measures": { "description": "What the plan measures for usage tracking", "example": "requests", "type": "string" }, "price": { "description": "Plan price in cents", "example": 2999, "type": "number" }, "pricePerUnit": { "description": "Price per unit in cents", "example": 10, "type": "number" }, "reference": { "description": "Plan reference", "example": "pln_1A2B3C4D", "type": "string" }, "requiresPayment": { "description": "Whether payment is required", "example": true, "type": "boolean" }, "rolloverUnusedUnits": { "description": "Whether unused units roll over to next period", "example": false, "type": "boolean" }, "setupFee": { "description": "One-time setup fee", "example": 500, "type": "number" }, "status": { "description": "Plan status", "example": "active", "type": "string" }, "trialDays": { "description": "Free trial period in days", "example": 14, "type": "number" }, "updatedAt": { "description": "Last update timestamp", "type": "string" } }, "required": [ "id", "reference", "price", "currency", "isFreeTier", "requiresPayment", "isActive", "status", "createdAt", "updatedAt" ], "type": "object" }, "SdkProductResponse": { "properties": { "balance": { "description": "Product balance in cents", "example": 0, "type": "number" }, "config": { "allOf": [ { "$ref": "#/components/schemas/ProductConfigDto" } ], "description": "Product-specific configuration" }, "createdAt": { "description": "Creation timestamp", "type": "string" }, "description": { "description": "Product description", "type": "string" }, "id": { "description": "Product ID", "example": "507f1f77bcf86cd799439011", "type": "string" }, "imageUrl": { "description": "URL to the product image", "type": "string" }, "isMcpPay": { "description": "Whether this product uses MCP Pay proxy", "example": false, "type": "boolean" }, "mcp": { "additionalProperties": true, "description": "MCP linkage details for MCP-enabled products", "example": { "defaultPlanId": "67f90f1f1b1c9c0b8df0f001", "mcpProxyUrl": "https://acme-docs.mcp.solvapay.com/mcp", "mcpServerId": "67f90f1f1b1c9c0b8df0f111", "mcpServerReference": "mcp_ABC123", "mcpSubdomain": "acme-docs", "originUrl": "https://origin.example.com/mcp" }, "type": "object" }, "metadata": { "additionalProperties": true, "description": "Arbitrary key-value metadata", "type": "object" }, "name": { "description": "Product name", "example": "AI Writing Assistant", "type": "string" }, "plans": { "description": "Plans associated with this product", "items": { "$ref": "#/components/schemas/SdkPlanResponse" }, "type": "array" }, "productType": { "description": "Free-form product type", "type": "string" }, "reference": { "description": "Product reference", "example": "prd_1A2B3C4D", "type": "string" }, "status": { "description": "Product status", "example": "active", "type": "string" }, "totalTransactions": { "description": "Total number of transactions", "example": 0, "type": "number" }, "updatedAt": { "description": "Last update timestamp", "type": "string" } }, "required": [ "id", "reference", "name", "status", "balance", "totalTransactions", "isMcpPay", "createdAt", "updatedAt" ], "type": "object" }, "SelectCustomerSessionProductRequest": { "properties": { "productRef": { "description": "Product reference or ID to scope the customer manage session", "example": "prd_1a2b3c4d5e6f", "type": "string" } }, "required": [ "productRef" ], "type": "object" }, "Signup": { "properties": { "email": { "type": "string" }, "name": { "type": "string" }, "type": { "enum": [ "provider", "admin", "super_admin" ], "type": "string" } }, "required": [ "name", "email" ], "type": "object" }, "ThemeModeColorsDto": { "properties": { "background": { "description": "Page background color", "example": "#f7f7f8", "type": "string" }, "secondary": { "description": "Secondary/muted text color", "example": "#5c5c5c", "type": "string" }, "surface": { "description": "Card/surface background color", "example": "#ffffff", "type": "string" }, "text": { "description": "Primary text color", "example": "#181818", "type": "string" } }, "type": "object" }, "ThemeOverridesDto": { "properties": { "dark": { "allOf": [ { "$ref": "#/components/schemas/ThemeModeColorsDto" } ], "description": "Dark mode color overrides" }, "light": { "allOf": [ { "$ref": "#/components/schemas/ThemeModeColorsDto" } ], "description": "Light mode color overrides" } }, "type": "object" }, "TosAcceptance": { "properties": { "ip": { "description": "IP address of user accepting ToS", "example": "192.168.1.1", "type": "string" } }, "required": [ "ip" ], "type": "object" }, "UpdateBrandThemeDto": { "properties": { "brandName": { "description": "Provider's brand name displayed on hosted pages", "example": "Acme Corp", "type": "string" }, "fontFamily": { "default": "Inter", "description": "Font family for hosted pages", "example": "Inter", "type": "string" }, "fontSize": { "default": "16px", "description": "Base font size", "example": "16px", "type": "string" }, "logo": { "description": "Logo image URL displayed in hosted page headers", "example": "/ui/files/download/provider-assets/provider-123/logos/logo.png", "type": "string" }, "primaryColor": { "description": "Primary/accent color in hex format", "example": "#3182ce", "type": "string" }, "themes": { "allOf": [ { "$ref": "#/components/schemas/ThemeOverridesDto" } ], "description": "Per-mode color overrides for light and dark themes" } }, "required": [ "brandName", "primaryColor" ], "type": "object" }, "UpdateConnectedAccount": { "properties": { "externalAccount": { "allOf": [ { "$ref": "#/components/schemas/ExternalAccount" } ], "description": "External bank account" }, "tosAcceptance": { "allOf": [ { "$ref": "#/components/schemas/TosAcceptance" } ], "description": "Terms of Service acceptance" }, "website": { "description": "Business website URL", "example": "https://example.com", "type": "string" } }, "type": "object" }, "UpdatePlanRequest": { "properties": { "accessExpiryDays": { "description": "Access expiry in days", "example": 30, "type": "number" }, "billingCycle": { "description": "Billing cycle", "enum": [ "weekly", "monthly", "quarterly", "yearly", "custom" ], "example": "monthly", "type": "string" }, "currency": { "description": "Currency code (ISO 4217)", "example": "USD", "type": "string" }, "default": { "description": "Whether this is the default plan", "example": false, "type": "boolean" }, "features": { "additionalProperties": true, "description": "Plan features (generic key/value, shape is provider-defined)", "example": { "apiAccess": true, "prioritySupport": false }, "type": "object" }, "freeUnits": { "description": "Number of free units included", "example": 100, "type": "number" }, "isFreeTier": { "description": "Whether this is a free tier plan", "example": false, "type": "boolean" }, "limit": { "description": "Usage limit for the meter", "example": 10000, "type": "number" }, "limits": { "additionalProperties": true, "description": "Usage limits (shape varies by plan type)", "example": { "maxTransactions": 1000 }, "type": "object" }, "maxActiveUsers": { "description": "Maximum number of active users", "example": 10, "type": "number" }, "metadata": { "additionalProperties": true, "description": "Additional metadata", "type": "object" }, "price": { "description": "Plan price in cents", "example": 2999, "type": "number" }, "requiresPayment": { "description": "Whether payment is required", "example": true, "type": "boolean" }, "status": { "description": "Plan status", "enum": [ "active", "inactive", "archived" ], "example": "active", "type": "string" } }, "type": "object" }, "UpdatePreferences": { "properties": {}, "type": "object" }, "UpdateProductRequest": { "properties": { "config": { "allOf": [ { "$ref": "#/components/schemas/ProductConfigDto" } ], "description": "Product-specific configuration" }, "description": { "description": "Product description", "type": "string" }, "imageUrl": { "description": "URL to the product image", "type": "string" }, "metadata": { "additionalProperties": true, "description": "Arbitrary key-value metadata", "type": "object" }, "name": { "description": "Product name", "type": "string" }, "productType": { "description": "Free-form product type defined by the provider", "type": "string" }, "status": { "description": "Product status", "enum": [ "active", "inactive", "suspended" ], "type": "string" } }, "type": "object" }, "UpdateProfile": { "properties": {}, "type": "object" }, "UpdateProviderDto": { "properties": { "businessEmail": { "description": "Business email address", "example": "business@example.com", "type": "string" }, "businessType": { "description": "Business type", "enum": [ "individual", "company" ], "example": "individual", "type": "string" }, "defaultCurrency": { "description": "Default currency code", "example": "usd", "type": "string" }, "description": { "description": "Provider description", "example": "My business", "type": "string" }, "legalEntity": { "description": "Legal entity information", "type": "object" }, "metadata": { "description": "Arbitrary metadata", "type": "object" }, "supportEmail": { "description": "Support email address", "example": "support@example.com", "type": "string" }, "supportTelephone": { "description": "Support telephone number", "example": "+1234567890", "type": "string" }, "telephone": { "description": "Business telephone number", "example": "+1234567890", "type": "string" }, "tosAcceptance": { "description": "Terms of Service acceptance", "type": "object" }, "website": { "description": "Business website URL", "example": "https://example.com", "type": "string" } }, "type": "object" }, "UpdateThemePreferenceDto": { "properties": { "mode": { "description": "Selected UI theme mode", "enum": [ "light", "dark" ], "example": "dark", "type": "string" } }, "required": [ "mode" ], "type": "object" }, "UpdateUser": { "properties": {}, "type": "object" }, "UpdateWebhookEndpointDto": { "properties": { "description": { "description": "Webhook endpoint description", "example": "Updated webhook", "type": "string" }, "url": { "description": "Webhook endpoint URL", "example": "https://example.com/webhook", "type": "string" } }, "type": "object" }, "UsageBillingDto": { "properties": { "overageCost": { "description": "Overage cost in cents", "example": 0, "type": "number" }, "overageUnits": { "description": "Units exceeding the plan limit", "example": 0, "type": "number" }, "periodEnd": { "description": "Period end date", "example": "2025-11-01T00:00:00Z", "type": "string" }, "periodStart": { "description": "Period start date", "example": "2025-10-01T00:00:00Z", "type": "string" }, "used": { "description": "Units consumed in current period", "example": 150, "type": "number" } }, "required": [ "used", "overageUnits", "overageCost" ], "type": "object" }, "UserInfoPlanDto": { "properties": { "billingCycle": { "example": "monthly", "nullable": true, "type": "string" }, "currency": { "example": "USD", "type": "string" }, "features": { "items": { "type": "string" }, "nullable": true, "type": "array" }, "limits": { "additionalProperties": true, "nullable": true, "type": "object" }, "price": { "description": "Price in minor currency units (e.g. cents)", "example": 2999, "type": "number" }, "reference": { "example": "pln_2B3C4D5E", "type": "string" }, "type": { "example": "recurring", "type": "string" } }, "required": [ "reference", "price", "currency", "type" ], "type": "object" }, "UserInfoPurchaseDto": { "properties": { "endDate": { "example": "2025-11-27T10:00:00Z", "nullable": true, "type": "string" }, "plan": { "$ref": "#/components/schemas/UserInfoPlanDto" }, "planType": { "example": "recurring", "type": "string" }, "productName": { "example": "My API Product", "type": "string" }, "reference": { "example": "pur_1A2B3C4D", "type": "string" }, "startDate": { "example": "2025-10-27T10:00:00Z", "nullable": true, "type": "string" }, "status": { "example": "active", "type": "string" }, "usage": { "$ref": "#/components/schemas/UserInfoUsageDto" } }, "required": [ "reference", "status", "productName", "planType" ], "type": "object" }, "UserInfoRequest": { "properties": { "customerRef": { "description": "Customer reference", "example": "cus_3C4D5E6F", "type": "string" }, "productRef": { "description": "Product reference", "example": "prd_1A2B3C4D", "type": "string" } }, "required": [ "customerRef", "productRef" ], "type": "object" }, "UserInfoResponse": { "properties": { "purchase": { "$ref": "#/components/schemas/UserInfoPurchaseDto" }, "status": { "description": "Human-readable status summary", "example": "Active subscription: My API Product (25% usage consumed)", "type": "string" }, "user": { "$ref": "#/components/schemas/UserInfoUserDto" }, "verifyUrl": { "description": "Customer portal session URL", "example": "https://solvapay.com/customer/manage?id=abc123", "nullable": true, "type": "string" } }, "required": [ "status" ], "type": "object" }, "UserInfoUsageDto": { "properties": { "meterId": { "description": "Meter ObjectId reference", "example": "507f1f77bcf86cd799439011", "type": "string" }, "percentUsed": { "example": 25, "nullable": true, "type": "number" }, "remaining": { "example": 750, "type": "number" }, "total": { "example": 1000, "type": "number" }, "used": { "example": 250, "type": "number" } }, "required": [ "total", "used", "remaining" ], "type": "object" }, "UserInfoUserDto": { "properties": { "email": { "example": "john@example.com", "type": "string" }, "externalRef": { "example": "auth_user_12345", "nullable": true, "type": "string" }, "name": { "example": "John Doe", "nullable": true, "type": "string" }, "reference": { "example": "cus_3C4D5E6F", "type": "string" } }, "required": [ "reference", "email" ], "type": "object" }, "VerifyEmail": { "properties": { "emailVerificationCode": { "type": "string" } }, "required": [ "emailVerificationCode" ], "type": "object" }, "VerifyEmailChange": { "properties": { "code": { "type": "string" } }, "required": [ "code" ], "type": "object" }, "VerifyLoginCode": { "properties": { "code": { "description": "6-digit login code sent to email", "type": "string" }, "email": { "type": "string" } }, "required": [ "email", "code" ], "type": "object" } }, "securitySchemes": { "OAuth2": { "flows": { "authorizationCode": { "authorizationUrl": "https://api-dev.solvapay.com/v1/oauth/authorize", "scopes": { "email": "Email address", "openid": "OpenID Connect scope", "profile": "Profile information" }, "tokenUrl": "https://api-dev.solvapay.com/v1/oauth/token" } }, "type": "oauth2" } } }, "info": { "contact": {}, "description": "The SolvaPay REST API specification", "title": "SolvaPay REST API", "version": "1.0" }, "openapi": "3.0.0", "paths": { "/v1/sdk/checkout-sessions": { "post": { "description": "Creates a hosted checkout session for a customer to purchase a product plan. Returns a session ID and checkout URL for redirect.", "operationId": "CheckoutSessionSdkController_createCheckoutSession", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "customerRef": { "description": "Customer reference", "example": "cus_3C4D5E6F", "type": "string" }, "planRef": { "description": "Plan reference (optional — shows plan selector if omitted)", "example": "pln_2b3c4d5e", "type": "string" }, "productRef": { "description": "Product reference", "example": "prd_1A2B3C4D", "type": "string" }, "returnUrl": { "description": "URL to redirect after checkout", "type": "string" } }, "required": [ "customerRef", "productRef" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "checkoutUrl": { "description": "URL to redirect the customer to", "type": "string" }, "sessionId": { "description": "Checkout session ID", "type": "string" } }, "type": "object" } } }, "description": "Checkout session created" }, "400": { "description": "Missing customerRef or productRef" } }, "security": [ { "bearer": [] } ], "summary": "Create a checkout session", "tags": [ "Checkout Sessions" ] } }, "/v1/sdk/customers": { "get": { "description": "Retrieves a customer's details using their unique reference ID, externalRef, or email. Use query parameter 'reference' to look up by customer reference, 'externalRef' for external auth ID, or 'email' for customer email. Exactly one parameter must be provided. Returns the customer's name, email, and active purchases. Only customers owned by the authenticated provider can be accessed.", "operationId": "CustomerSdkController_getCustomerByQuery", "parameters": [ { "description": "Customer reference identifier (use exactly one query parameter)", "in": "query", "name": "reference", "required": false, "schema": { "example": "cus_3c4d5e6f7g8h", "type": "string" } }, { "description": "External reference ID from your auth system (use exactly one query parameter)", "in": "query", "name": "externalRef", "required": false, "schema": { "example": "auth_user_12345", "type": "string" } }, { "description": "Customer email address (use exactly one query parameter)", "in": "query", "name": "email", "required": false, "schema": { "example": "customer@example.com", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "email": "customer@example.com", "externalRef": "auth_user_12345", "name": "John Doe", "purchases": [ { "amount": 9900, "currency": "USD", "endDate": "2025-11-27T10:00:00Z", "productName": "API Gateway Manager", "productReference": "prd_abc123", "reference": "pur_1A2B3C4D", "startDate": "2025-10-27T10:00:00Z", "status": "active" } ], "reference": "cus_3c4d5e6f7g8h" }, "schema": { "$ref": "#/components/schemas/CustomerResponse" } } }, "description": "Customer retrieved successfully" }, "400": { "content": { "application/json": { "schema": { "example": { "error": "Bad Request", "message": "Must provide exactly one of reference, externalRef, or email", "statusCode": 400 } } } }, "description": "Invalid request - must provide exactly one of reference, externalRef, or email" }, "404": { "content": { "application/json": { "schema": { "example": { "error": "Not Found", "message": "Customer not found", "statusCode": 404 } } } }, "description": "Customer not found" } }, "security": [ { "SecretKey": [] } ], "summary": "Get customer by reference, externalRef, or email", "tags": [ "Customers" ] }, "post": { "description": "Creates a new customer record for the authenticated provider. Customers represent end-users who will purchase your products. Email is required and must be unique per provider. The name field is optional but recommended for better tracking.", "operationId": "CustomerSdkController_createCustomer", "parameters": [], "requestBody": { "content": { "application/json": { "examples": { "emailOnly": { "summary": "Email only", "value": { "email": "customer@example.com" } }, "withName": { "summary": "Customer with name", "value": { "email": "customer@example.com", "name": "John Doe" } } }, "schema": { "$ref": "#/components/schemas/CreateCustomerRequest" } } }, "description": "Customer creation data", "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "email": "customer@example.com", "externalRef": "auth_user_12345", "name": "John Doe", "reference": "cus_3c4d5e6f7g8h" }, "schema": { "$ref": "#/components/schemas/CustomerResponse" } } }, "description": "Customer created successfully" }, "400": { "content": { "application/json": { "schema": { "example": { "error": "Bad Request", "message": "Invalid email format", "statusCode": 400 } } } }, "description": "Invalid email or missing required fields" } }, "security": [ { "SecretKey": [] } ], "summary": "Create a new customer", "tags": [ "Customers" ] } }, "/v1/sdk/customers/{reference}": { "get": { "description": "Retrieves a customer's details using their unique reference ID. Returns the customer's name, email, and active purchases. Only customers owned by the authenticated provider can be accessed.", "operationId": "CustomerSdkController_getCustomer", "parameters": [ { "description": "Customer reference identifier", "in": "path", "name": "reference", "required": true, "schema": { "example": "cus_3c4d5e6f7g8h", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "email": "customer@example.com", "externalRef": "auth_user_12345", "name": "John Doe", "purchases": [ { "amount": 9900, "currency": "USD", "endDate": "2025-11-27T10:00:00Z", "productName": "API Gateway Manager", "productReference": "prd_abc123", "reference": "pur_1A2B3C4D", "startDate": "2025-10-27T10:00:00Z", "status": "active" } ], "reference": "cus_3c4d5e6f7g8h" }, "schema": { "$ref": "#/components/schemas/CustomerResponse" } } }, "description": "Customer retrieved successfully" }, "404": { "content": { "application/json": { "schema": { "example": { "error": "Not Found", "message": "Customer with reference cus_3c4d5e6f7g8h not found", "statusCode": 404 } } } }, "description": "Customer not found" } }, "security": [ { "SecretKey": [] } ], "summary": "Get customer by reference", "tags": [ "Customers" ] } }, "/v1/sdk/customers/customer-sessions": { "post": { "description": "Creates a customer session URL that can be used to redirect customers to the customer page. Returns the customer URL and session ID. The session is short-lived (15 minutes) for security reasons.", "operationId": "CustomerSdkController_createCustomerSession", "parameters": [], "requestBody": { "content": { "application/json": { "examples": { "basic": { "summary": "Create customer session", "value": { "customerRef": "cus_3c4d5e6f7g8h" } } }, "schema": { "$ref": "#/components/schemas/CreateCustomerSessionRequest" } } }, "description": "Customer session creation request data", "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "customerUrl": "https://solvapay.com/customer/manage?id=e3f1c2d4b6a89f001122334455667788", "sessionId": "e3f1c2d4b6a89f001122334455667788" }, "schema": { "$ref": "#/components/schemas/CreateCustomerSessionResponse" } } }, "description": "Customer session created successfully" }, "400": { "content": { "application/json": { "schema": { "example": { "error": "Bad Request", "message": "Customer not found", "statusCode": 400 } } } }, "description": "Invalid request data or customer not found" }, "404": { "content": { "application/json": { "schema": { "example": { "error": "Not Found", "message": "Customer not found", "statusCode": 404 } } } }, "description": "Customer not found" } }, "security": [ { "SecretKey": [] } ], "summary": "Create a customer session", "tags": [ "Customers" ] } }, "/v1/sdk/customers/customer-sessions/{sessionId}": { "get": { "description": "Retrieves a customer session by its sessionId with all data hydrated including customer details and purchases. The session must belong to the authenticated provider.", "operationId": "CustomerSdkController_getCustomerSession", "parameters": [ { "description": "Customer session ID/token", "in": "path", "name": "sessionId", "required": true, "schema": { "example": "e3f1c2d4b6a89f001122334455667788", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "createdAt": "2025-01-01T11:45:00.000Z", "customer": { "email": "customer@example.com", "externalRef": "auth_user_12345", "name": "John Doe", "purchases": [ { "amount": 9900, "currency": "USD", "endDate": "2025-11-27T10:00:00Z", "productName": "API Gateway Manager", "productReference": "prd_abc123", "reference": "pur_1A2B3C4D", "startDate": "2025-10-27T10:00:00Z", "status": "active" } ], "reference": "cus_3c4d5e6f7g8h" }, "customerUrl": "https://solvapay.com/customer/manage?id=e3f1c2d4b6a89f001122334455667788", "expiresAt": "2025-01-01T12:00:00.000Z", "sessionId": "e3f1c2d4b6a89f001122334455667788", "status": "active", "updatedAt": "2025-01-01T11:45:00.000Z" }, "schema": { "$ref": "#/components/schemas/GetCustomerSessionResponse" } } }, "description": "Customer session retrieved successfully" }, "404": { "content": { "application/json": { "schema": { "example": { "error": "Not Found", "message": "Customer session not found: e3f1c2d4b6a89f001122334455667788", "statusCode": 404 } } } }, "description": "Customer session not found" } }, "security": [ { "SecretKey": [] } ], "summary": "Get customer session by sessionId", "tags": [ "Customers" ] } }, "/v1/sdk/limits": { "post": { "description": "Checks whether a customer has an active purchase for a product and is within their usage limits. Returns a checkout URL if payment is required.", "operationId": "LimitsSdkController_checkLimits", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckLimitRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LimitResponse" } } }, "description": "Limit check result" }, "400": { "description": "Missing customerRef or productRef" }, "404": { "description": "Customer or product not found" } }, "security": [ { "bearer": [] } ], "summary": "Check usage limits for a customer and product", "tags": [ "Limits" ] } }, "/v1/sdk/meter-events": { "post": { "description": "Records a single usage event against a named meter.", "operationId": "MeterEventsSdkController_recordEvent", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordMeterEventDto" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "success": { "example": true, "type": "boolean" } }, "type": "object" } } }, "description": "Event recorded" }, "400": { "description": "Invalid meter name or meter is archived" } }, "security": [ { "bearer": [] } ], "summary": "Record a meter event", "tags": [ "Meter Events" ] } }, "/v1/sdk/meter-events/bulk": { "post": { "description": "Records multiple usage events in a single request for high throughput.", "operationId": "MeterEventsSdkController_recordBulkEvents", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordBulkMeterEventsDto" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "inserted": { "example": 50, "type": "number" }, "success": { "example": true, "type": "boolean" } }, "type": "object" } } }, "description": "Events recorded" }, "400": { "description": "Invalid meter name or meter is archived" } }, "security": [ { "bearer": [] } ], "summary": "Record meter events in bulk", "tags": [ "Meter Events" ] } }, "/v1/sdk/payment-intents": { "get": { "description": "Retrieves a paginated list of all payment intents created by the authenticated provider. Supports pagination through limit and offset query parameters.", "operationId": "PaymentIntentSdkController_getPaymentIntents", "parameters": [ { "description": "Maximum number of results", "in": "query", "name": "limit", "required": false, "schema": { "example": 50, "type": "number" } }, { "description": "Pagination offset", "in": "query", "name": "offset", "required": false, "schema": { "example": 0, "type": "number" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "example": { "paymentIntents": [ { "amount": 4999, "clientSecret": "pi_1a2b3c4d5e6f7g8h_secret_xxx", "createdAt": "2025-10-11T10:30:00.000Z", "currency": "usd", "id": "pi_1a2b3c4d5e6f7g8h", "planRef": "pln_2b3c4d5e6f7g", "status": "succeeded", "stripePaymentIntentId": "pi_stripe_1234567890" } ], "total": 1 } } } }, "description": "Payment intents retrieved successfully" } }, "security": [ { "SecretKey": [] } ], "summary": "List payment intents for the provider", "tags": [ "Payment Intents" ] }, "post": { "description": "Creates a new payment intent for a customer to purchase a plan. Payment intents are used with Stripe.js to process payments. Requires an idempotency key to prevent duplicate charges. Returns client secret and publishable key needed for frontend integration.", "operationId": "PaymentIntentSdkController_createPaymentIntent", "parameters": [ { "description": "Unique idempotency key to prevent duplicate payments (required)", "in": "header", "name": "idempotency-key", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "customerReference": { "description": "Customer reference identifier", "example": "cus_3c4d5e6f7g8h", "type": "string" }, "planRef": { "description": "Plan reference to purchase", "example": "pln_2b3c4d5e6f7g", "type": "string" }, "pricingTier": { "description": "Name of the pricing tier to purchase (for plans with pricingTiers). If not specified, uses the plan base price.", "example": "Pro", "type": "string" }, "productRef": { "description": "Product reference that owns the plan", "example": "prd_1A2B3C4D", "type": "string" } }, "required": [ "planRef", "productRef", "customerReference" ], "type": "object" } } }, "description": "Payment intent creation data", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "example": { "amount": 4999, "clientSecret": "pi_1a2b3c4d5e6f7g8h_secret_AbCdEf123456", "createdAt": "2025-10-18T10:30:00.000Z", "currency": "usd", "customerReference": "cus_3c4d5e6f7g8h", "exchangeRate": 1, "expiresAt": "2025-10-19T10:30:00.000Z", "id": "6743f1a2b3c4d5e6f7g8h9i0", "originalAmount": 4999, "planRef": "pln_2b3c4d5e6f7g", "publishableKey": "pk_test_...", "status": "requires_payment_method", "stripePaymentIntentId": "pi_1a2b3c4d5e6f7g8h", "transactionId": "6743f1a2b3c4d5e6f7g8h9i1" } } } }, "description": "Payment intent created successfully" }, "400": { "content": { "application/json": { "schema": { "example": { "error": "Bad Request", "message": "idempotency-key header is required", "statusCode": 400 } } } }, "description": "Missing required fields or invalid data" } }, "security": [ { "SecretKey": [] } ], "summary": "Create a payment intent", "tags": [ "Payment Intents" ] } }, "/v1/sdk/payment-intents/{id}": { "get": { "description": "Retrieves detailed information about a specific payment intent including amount, currency, and client secret for Stripe integration.", "operationId": "PaymentIntentSdkController_getPaymentIntent", "parameters": [ { "description": "Payment intent MongoDB ID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "example": { "amount": 4999, "clientSecret": "pi_1a2b3c4d5e6f7g8h_secret_xxx", "currency": "usd", "planRef": "pln_2b3c4d5e6f7g" } } } }, "description": "Payment intent retrieved successfully" }, "404": { "content": { "application/json": { "schema": { "example": { "code": "PAYMENT_INTENT_NOT_FOUND", "error": "Payment intent not found", "success": false } } } }, "description": "Payment intent not found" } }, "security": [ { "SecretKey": [] } ], "summary": "Get a specific payment intent by ID", "tags": [ "Payment Intents" ] } }, "/v1/sdk/payment-intents/{id}/process": { "post": { "description": "Processes a payment intent that has been confirmed on the client-side using Stripe.js. Polls the database for payment intent status to become succeeded (up to 10 seconds). Returns the current status of the payment intent.", "operationId": "PaymentIntentSdkController_processPaymentIntent", "parameters": [ { "description": "Stripe payment intent ID (format: pi_xxx)", "in": "path", "name": "id", "required": true, "schema": { "example": "pi_1a2b3c4d5e6f7g8h", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "customerRef": { "description": "Customer reference identifier", "example": "cus_456", "type": "string" }, "planRef": { "description": "Plan reference - helps determine if payment is for purchase", "example": "pln_789", "type": "string" }, "productRef": { "description": "Product reference that owns the plan", "example": "prd_123", "type": "string" } }, "required": [ "productRef", "customerRef" ], "type": "object" } } }, "description": "Payment processing data", "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "cancelled": { "description": "Payment intent cancelled", "value": { "status": "cancelled" } }, "failed": { "description": "Payment intent failed", "value": { "status": "failed" } }, "succeeded": { "description": "Payment intent confirmed successfully", "value": { "status": "succeeded" } }, "timeout": { "description": "Timeout waiting for payment intent confirmation", "value": { "message": "Timeout while waiting for payment intent confirmation, try again later. This could be due to Stripe webhooks not being configured correctly.", "status": "timeout" } } }, "schema": { "properties": { "message": { "description": "Optional message, only present for timeout status", "example": "Timeout while waiting for payment intent confirmation, try again later. This could be due to Stripe webhooks not being configured correctly.", "type": "string" }, "status": { "description": "Payment intent status", "enum": [ "succeeded", "timeout", "failed", "cancelled" ], "example": "succeeded", "type": "string" } }, "type": "object" } } }, "description": "Payment intent status" }, "400": { "content": { "application/json": { "schema": { "example": { "error": "Bad Request", "message": "Payment not succeeded. Status: requires_payment_method", "statusCode": 400 } } } }, "description": "Payment not succeeded, invalid request, or forbidden" } }, "security": [ { "SecretKey": [] } ], "summary": "Process payment intent after client-side confirmation", "tags": [ "Payment Intents" ] } }, "/v1/sdk/products": { "get": { "description": "Retrieves a paginated list of products for the authenticated provider. Supports filtering by status, search term, and MCP Pay flag.", "operationId": "ProductSdkController_listProducts", "parameters": [ { "description": "Max results (1-100)", "in": "query", "name": "limit", "required": false, "schema": { "example": 50, "type": "number" } }, { "description": "Pagination offset", "in": "query", "name": "offset", "required": false, "schema": { "example": 0, "type": "number" } }, { "description": "Search by name or description", "in": "query", "name": "search", "required": false, "schema": { "type": "string" } }, { "description": "Filter by status", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "active", "inactive", "suspended" ], "type": "string" } }, { "description": "Filter MCP Pay products", "in": "query", "name": "isMcpPay", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Products retrieved successfully" } }, "security": [ { "bearer": [] } ], "summary": "List products", "tags": [ "Products" ] }, "post": { "description": "Creates a new product for the authenticated provider.", "operationId": "ProductSdkController_createProduct", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProductRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SdkProductResponse" } } }, "description": "Product created successfully" }, "400": { "description": "Missing required fields or validation error" } }, "security": [ { "bearer": [] } ], "summary": "Create a product", "tags": [ "Products" ] } }, "/v1/sdk/products/{productRef}": { "delete": { "description": "Deletes a product permanently in sandbox or when no purchases exist. In live mode with purchases, the product is deactivated instead.", "operationId": "ProductSdkController_deleteProduct", "parameters": [ { "description": "Product reference or ID", "in": "path", "name": "productRef", "required": true, "schema": { "example": "prd_1A2B3C4D", "type": "string" } } ], "responses": { "200": { "description": "Product deleted or deactivated successfully" }, "404": { "description": "Product not found" } }, "security": [ { "bearer": [] } ], "summary": "Delete a product", "tags": [ "Products" ] }, "get": { "description": "Retrieves a product by its reference or ID, including embedded plans.", "operationId": "ProductSdkController_getProduct", "parameters": [ { "description": "Product reference or ID", "in": "path", "name": "productRef", "required": true, "schema": { "example": "prd_1A2B3C4D", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SdkProductResponse" } } }, "description": "Product retrieved successfully" }, "404": { "description": "Product not found" } }, "security": [ { "bearer": [] } ], "summary": "Get a product by reference", "tags": [ "Products" ] }, "put": { "description": "Updates an existing product. Only provided fields are updated.", "operationId": "ProductSdkController_updateProduct", "parameters": [ { "description": "Product reference or ID", "in": "path", "name": "productRef", "required": true, "schema": { "example": "prd_1A2B3C4D", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProductRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SdkProductResponse" } } }, "description": "Product updated successfully" }, "404": { "description": "Product not found" } }, "security": [ { "bearer": [] } ], "summary": "Update a product", "tags": [ "Products" ] } }, "/v1/sdk/products/{productRef}/clone": { "post": { "description": "Deep-copies a product including all its plans. Generates new references for the clone.", "operationId": "ProductSdkController_cloneProduct", "parameters": [ { "description": "Product reference or ID to clone", "in": "path", "name": "productRef", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SdkProductResponse" } } }, "description": "Product cloned successfully" }, "404": { "description": "Product not found" } }, "security": [ { "bearer": [] } ], "summary": "Clone a product", "tags": [ "Products" ] } }, "/v1/sdk/products/{productRef}/plans": { "get": { "operationId": "PlanSdkController_listPlans", "parameters": [ { "description": "Product reference or ID", "in": "path", "name": "productRef", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "number" } }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "number" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "limit": { "type": "number" }, "offset": { "type": "number" }, "plans": { "items": { "$ref": "#/components/schemas/Plan" }, "type": "array" }, "total": { "description": "Total number of plans for the product", "type": "number" } }, "type": "object" } } }, "description": "Plans retrieved successfully" }, "404": { "description": "Product not found" } }, "security": [ { "SecretKey": [] } ], "summary": "List plans for a product", "tags": [ "Plans" ] }, "post": { "operationId": "PlanSdkController_createPlan", "parameters": [ { "description": "Product reference or ID", "in": "path", "name": "productRef", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePlanRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" } } }, "description": "Plan created successfully" }, "404": { "description": "Product not found" } }, "security": [ { "SecretKey": [] } ], "summary": "Create a plan for a product", "tags": [ "Plans" ] } }, "/v1/sdk/products/{productRef}/plans/{planRef}": { "delete": { "operationId": "PlanSdkController_deletePlan", "parameters": [ { "description": "Product reference or ID", "in": "path", "name": "productRef", "required": true, "schema": { "type": "string" } }, { "description": "Plan reference or ID", "in": "path", "name": "planRef", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Plan deleted successfully" }, "404": { "description": "Plan or product not found" } }, "security": [ { "SecretKey": [] } ], "summary": "Delete a plan from a product", "tags": [ "Plans" ] }, "get": { "operationId": "PlanSdkController_getPlan", "parameters": [ { "description": "Product reference or ID", "in": "path", "name": "productRef", "required": true, "schema": { "type": "string" } }, { "description": "Plan reference or ID", "in": "path", "name": "planRef", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" } } }, "description": "Plan retrieved successfully" }, "404": { "description": "Plan or product not found" } }, "security": [ { "SecretKey": [] } ], "summary": "Get a plan for a product", "tags": [ "Plans" ] }, "put": { "operationId": "PlanSdkController_updatePlan", "parameters": [ { "description": "Product reference or ID", "in": "path", "name": "productRef", "required": true, "schema": { "type": "string" } }, { "description": "Plan reference or ID", "in": "path", "name": "planRef", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePlanRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" } } }, "description": "Plan updated successfully" }, "404": { "description": "Plan or product not found" } }, "security": [ { "SecretKey": [] } ], "summary": "Update a plan for a product", "tags": [ "Plans" ] } }, "/v1/sdk/products/mcp/bootstrap": { "post": { "description": "Creates an MCP-enabled product, provisions plans, configures origin URL, and maps tools to plans in one request.", "operationId": "ProductSdkController_bootstrapMcpProduct", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpBootstrapRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpBootstrapResult" } } }, "description": "MCP product bootstrapped successfully" }, "400": { "description": "Invalid bootstrap request" } }, "security": [ { "bearer": [] } ], "summary": "Bootstrap MCP product integration", "tags": [ "Products" ] } }, "/v1/sdk/purchases": { "get": { "description": "Retrieves all purchases for the authenticated provider with optional filtering by status, product, or customer.", "operationId": "PurchaseSdkController_listPurchases", "parameters": [ { "description": "Filter by purchase status", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "pending", "active", "trialing", "past_due", "cancelled", "expired", "suspended", "refunded" ], "type": "string" } }, { "description": "Filter by product ID", "in": "query", "name": "productId", "required": false, "schema": { "type": "string" } }, { "description": "Filter by customer ID", "in": "query", "name": "customerId", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "purchases": { "items": { "$ref": "#/components/schemas/PurchaseResponse" }, "type": "array" } } } } }, "description": "Purchases retrieved successfully" } }, "security": [ { "bearer": [] } ], "summary": "List purchases for provider", "tags": [ "Purchases" ] } }, "/v1/sdk/purchases/{id}": { "get": { "description": "Retrieves a single purchase including plan snapshot, usage, and billing details.", "operationId": "PurchaseSdkController_getPurchase", "parameters": [ { "description": "Purchase ID or reference", "in": "path", "name": "id", "required": true, "schema": { "example": "pur_1A2B3C4D", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseResponse" } } }, "description": "Purchase retrieved successfully" }, "404": { "description": "Purchase not found" } }, "security": [ { "bearer": [] } ], "summary": "Get a purchase by ID or reference", "tags": [ "Purchases" ] } }, "/v1/sdk/purchases/{purchaseRef}/cancel": { "post": { "description": "Cancels an active purchase. For recurring purchases, cancellation takes effect at the end of the current billing period.", "operationId": "PurchaseSdkController_cancelPurchase", "parameters": [ { "description": "Purchase reference or ID", "in": "path", "name": "purchaseRef", "required": true, "schema": { "example": "pur_1A2B3C4D", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelPurchaseRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "purchase": { "$ref": "#/components/schemas/PurchaseResponse" }, "success": { "type": "boolean" } } } } }, "description": "Purchase cancelled successfully" }, "404": { "description": "Purchase not found" } }, "security": [ { "bearer": [] } ], "summary": "Cancel a purchase", "tags": [ "Purchases" ] } }, "/v1/sdk/purchases/customer/{customerRef}": { "get": { "description": "Retrieves all purchases for a specific customer. Useful for billing history and access checks.", "operationId": "PurchaseSdkController_getPurchasesForCustomer", "parameters": [ { "description": "Customer reference or ID", "in": "path", "name": "customerRef", "required": true, "schema": { "example": "cus_3C4D5E6F", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "purchases": { "items": { "$ref": "#/components/schemas/PurchaseResponse" }, "type": "array" } } } } }, "description": "Customer purchases retrieved successfully" }, "404": { "description": "Customer not found" } }, "security": [ { "bearer": [] } ], "summary": "Get purchases for a customer", "tags": [ "Purchases" ] } }, "/v1/sdk/purchases/product/{productRef}": { "get": { "description": "Retrieves all purchases for a specific product. Each billing period creates a new purchase document.", "operationId": "PurchaseSdkController_getPurchasesForProduct", "parameters": [ { "description": "Product reference or ID", "in": "path", "name": "productRef", "required": true, "schema": { "example": "prd_1A2B3C4D", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "purchases": { "items": { "$ref": "#/components/schemas/PurchaseResponse" }, "type": "array" } } } } }, "description": "Product purchases retrieved successfully" }, "404": { "description": "Product not found" } }, "security": [ { "bearer": [] } ], "summary": "Get purchases for a product", "tags": [ "Purchases" ] } }, "/v1/sdk/usages": { "post": { "description": "Records a usage event into the Usage timeseries collection.", "operationId": "UsageSdkController_recordUsage", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "actionType": { "description": "Action type (default: api_call)", "enum": [ "transaction", "api_call", "hour", "email", "storage", "custom" ], "example": "api_call", "type": "string" }, "customerId": { "description": "Customer identifier", "example": "cus_3C4D5E6F", "type": "string" }, "idempotencyKey": { "description": "Unique key to prevent duplicate recording (max 256 chars)", "type": "string" }, "metadata": { "additionalProperties": true, "description": "Arbitrary event properties", "type": "object" }, "outcome": { "description": "Outcome (default: success)", "enum": [ "success", "paywall", "fail" ], "type": "string" }, "productReference": { "description": "Product reference", "type": "string" }, "purchaseReference": { "description": "Purchase reference", "type": "string" }, "timestamp": { "description": "ISO 8601 timestamp (defaults to now)", "format": "date-time", "type": "string" }, "units": { "description": "Number of usage units (default: 1)", "example": 1, "type": "number" } }, "required": [ "customerId" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "reference": { "example": "usage_A1B2C3D4", "type": "string" }, "success": { "example": true, "type": "boolean" } }, "type": "object" } } }, "description": "Usage recorded successfully" }, "400": { "description": "Validation failed" } }, "security": [ { "bearer": [] } ], "summary": "Record a usage event", "tags": [ "Usage" ] } }, "/v1/sdk/usages/bulk": { "post": { "description": "Records multiple usage events in a single request.", "operationId": "UsageSdkController_recordBulkUsage", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "events": { "items": { "properties": { "actionType": { "enum": [ "transaction", "api_call", "hour", "email", "storage", "custom" ], "type": "string" }, "customerId": { "type": "string" }, "idempotencyKey": { "type": "string" }, "metadata": { "additionalProperties": true, "type": "object" }, "outcome": { "enum": [ "success", "paywall", "fail" ], "type": "string" }, "productReference": { "type": "string" }, "purchaseReference": { "type": "string" }, "timestamp": { "format": "date-time", "type": "string" }, "units": { "type": "number" } }, "required": [ "customerId" ], "type": "object" }, "type": "array" } }, "required": [ "events" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Bulk usage events processed" }, "400": { "description": "Validation failed" } }, "security": [ { "bearer": [] } ], "summary": "Record bulk usage events", "tags": [ "Usage" ] } }, "/v1/sdk/user-info": { "post": { "description": "Returns customer profile, active purchase details including usage and plan info, and a customer portal URL.", "operationId": "UserInfoSdkController_getUserInfo", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserInfoRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserInfoResponse" } } }, "description": "User info with purchase status" }, "400": { "description": "Missing customerRef or productRef" }, "404": { "description": "Customer or product not found" } }, "security": [ { "bearer": [] } ], "summary": "Get user info and purchase status", "tags": [ "User Info" ] } } }, "servers": [], "tags": [] }