{ "components": { "schemas": { "ActivatePlanDto": { "properties": { "customerRef": { "type": "string" }, "planRef": { "type": "string" }, "productRef": { "type": "string" } }, "required": [ "customerRef", "productRef", "planRef" ], "type": "object" }, "ActivatePlanResponseDto": { "properties": { "checkoutSessionId": { "type": "string" }, "checkoutUrl": { "type": "string" }, "creditBalance": { "type": "number" }, "creditsPerUnit": { "type": "number" }, "currency": { "type": "string" }, "message": { "type": "string" }, "purchaseRef": { "type": "string" }, "status": { "enum": [ "activated", "already_active", "topup_required", "payment_required", "invalid" ], "type": "string" } }, "required": [ "status" ], "type": "object" }, "BulkCreateUsageRequest": { "properties": { "events": { "items": { "properties": { "actionType": { "default": "api_call", "enum": [ "transaction", "api_call", "hour", "email", "storage", "custom" ], "type": "string" }, "customerRef": { "minLength": 1, "type": "string" }, "description": { "type": "string" }, "duration": { "exclusiveMinimum": false, "minimum": 0, "type": "number" }, "errorMessage": { "type": "string" }, "idempotencyKey": { "maxLength": 256, "type": "string" }, "metadata": { "additionalProperties": {}, "type": "object" }, "outcome": { "default": "success", "enum": [ "success", "paywall", "fail" ], "type": "string" }, "productRef": { "type": "string" }, "purchaseRef": { "type": "string" }, "timestamp": { "format": "date-time", "type": "string" }, "units": { "default": 1, "exclusiveMaximum": false, "exclusiveMinimum": false, "maximum": 100000, "minimum": 0, "type": "integer" } }, "required": [ "customerRef", "timestamp" ], "type": "object" }, "maxItems": 1000, "minItems": 1, "type": "array" } }, "required": [ "events" ], "type": "object" }, "CancelPurchaseRequest": { "properties": { "reason": { "type": "string" } }, "type": "object" }, "CheckLimitRequest": { "properties": { "customerRef": { "minLength": 1, "type": "string" }, "meterName": { "type": "string" }, "productRef": { "minLength": 1, "type": "string" }, "usageType": { "type": "string" } }, "required": [ "customerRef", "productRef" ], "type": "object" }, "CloneProductDto": { "properties": { "name": { "minLength": 1, "type": "string" } }, "type": "object" }, "ConfigureMcpPlansDto": { "properties": { "plans": { "items": { "properties": { "billingCycle": { "enum": [ "weekly", "monthly", "quarterly", "yearly", "custom" ], "type": "string" }, "billingModel": { "enum": [ "pre-paid", "post-paid" ], "type": "string" }, "creditsPerUnit": { "type": "number" }, "currency": { "minLength": 1, "type": "string" }, "features": { "additionalProperties": {}, "type": "object" }, "freeUnits": { "exclusiveMinimum": false, "minimum": 0, "type": "number" }, "key": { "minLength": 1, "type": "string" }, "limit": { "exclusiveMinimum": false, "minimum": 0, "type": "number" }, "name": { "minLength": 1, "type": "string" }, "price": { "exclusiveMinimum": false, "minimum": 0, "type": "number" }, "type": { "enum": [ "recurring", "one-time", "usage-based" ], "type": "string" } }, "required": [ "key", "name", "price", "currency" ], "type": "object" }, "type": "array" }, "toolMapping": { "items": { "properties": { "name": { "minLength": 1, "type": "string" }, "planKeys": { "items": { "type": "string" }, "type": "array" } }, "required": [ "name", "planKeys" ], "type": "object" }, "type": "array" } }, "type": "object" }, "ConfigureMcpPlansResult": { "properties": { "mcpServer": { "additionalProperties": true, "description": "Updated MCP server identity", "type": "object" }, "planMap": { "additionalProperties": true, "description": "Resolved plan mapping by key (includes existing free plan)", "type": "object" }, "product": { "allOf": [ { "$ref": "#/components/schemas/SdkProductResponse" } ], "description": "Updated product" } }, "required": [ "product", "mcpServer", "planMap" ], "type": "object" }, "CreateCheckoutSessionRequest": { "properties": { "customerRef": { "minLength": 1, "type": "string" }, "planRef": { "type": "string" }, "productRef": { "minLength": 1, "type": "string" }, "purpose": { "enum": [ "credit_topup" ], "type": "string" }, "returnUrl": { "type": "string" } }, "required": [ "customerRef" ], "type": "object" }, "CreateCheckoutSessionResponse": { "properties": { "checkoutUrl": { "description": "Full checkout URL based on backend configuration (ready to redirect customer)", "example": "https://solvapay.com/customer/checkout?id=e3f1c2d4b6a89f001122334455667788", "type": "string" }, "sessionId": { "description": "Checkout session ID/token", "example": "e3f1c2d4b6a89f001122334455667788", "type": "string" } }, "required": [ "sessionId", "checkoutUrl" ], "type": "object" }, "CreateCustomerRequest": { "properties": { "email": { "format": "email", "type": "string" }, "externalRef": { "type": "string" }, "metadata": { "additionalProperties": {}, "selfRequired": false, "type": "object" }, "name": { "type": "string" }, "telephone": { "type": "string" } }, "required": [ "email", "metadata" ], "type": "object" }, "CreateCustomerSessionRequest": { "properties": { "customerRef": { "minLength": 1, "type": "string" }, "productRef": { "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" }, "CreatePaymentIntentDto": { "properties": { "amount": { "exclusiveMaximum": false, "exclusiveMinimum": false, "maximum": 10000000, "minimum": 100, "type": "integer" }, "currency": { "type": "string" }, "customerRef": { "minLength": 1, "type": "string" }, "description": { "maxLength": 500, "type": "string" }, "planRef": { "minLength": 1, "type": "string" }, "pricingTier": { "type": "string" }, "productRef": { "minLength": 1, "type": "string" }, "purpose": { "default": "product", "enum": [ "product", "credit_topup", "usage_billing" ], "type": "string" } }, "required": [ "customerRef" ], "type": "object" }, "CreatePlanRequest": { "properties": { "accessExpiryDays": { "type": "number" }, "autoRenew": { "type": "boolean" }, "basePrice": { "type": "number" }, "billingCycle": { "enum": [ "weekly", "monthly", "quarterly", "yearly", "custom" ], "type": "string" }, "billingModel": { "enum": [ "pre-paid", "post-paid" ], "type": "string" }, "creditsPerUnit": { "type": "number" }, "currency": { "type": "string" }, "default": { "type": "boolean" }, "description": { "type": "string" }, "features": { "additionalProperties": {}, "selfRequired": false, "type": "object" }, "freeUnits": { "type": "number" }, "limit": { "type": "number" }, "limits": { "additionalProperties": {}, "selfRequired": false, "type": "object" }, "maxActiveUsers": { "type": "number" }, "metadata": { "additionalProperties": {}, "selfRequired": false, "type": "object" }, "name": { "minLength": 1, "type": "string" }, "price": { "type": "number" }, "rolloverUnusedUnits": { "type": "boolean" }, "setupFee": { "type": "number" }, "status": { "enum": [ "active", "inactive", "archived" ], "type": "string" }, "trialDays": { "type": "number" }, "type": { "enum": [ "recurring", "usage-based", "one-time", "hybrid" ], "type": "string" }, "usageTracking": { "properties": { "granularity": { "enum": [ "hourly", "daily", "weekly", "monthly" ], "type": "string" }, "method": { "enum": [ "automatic", "manual", "hybrid" ], "type": "string" } }, "selfRequired": false, "type": "object" } }, "required": [ "usageTracking", "limits", "metadata", "features" ], "type": "object" }, "CreateProductRequest": { "properties": { "config": { "properties": { "deliveryMethod": { "type": "string" }, "fulfillmentType": { "type": "string" }, "validityPeriod": { "type": "number" } }, "selfRequired": false, "type": "object" }, "description": { "type": "string" }, "imageUrl": { "type": "string" }, "isMcpPay": { "type": "boolean" }, "metadata": { "additionalProperties": {}, "selfRequired": false, "type": "object" }, "name": { "minLength": 1, "type": "string" }, "productType": { "type": "string" } }, "required": [ "name", "config", "metadata" ], "type": "object" }, "CreateUsageRequest": { "properties": { "actionType": { "default": "api_call", "enum": [ "transaction", "api_call", "hour", "email", "storage", "custom" ], "type": "string" }, "customerRef": { "minLength": 1, "type": "string" }, "description": { "type": "string" }, "duration": { "exclusiveMinimum": false, "minimum": 0, "type": "number" }, "errorMessage": { "type": "string" }, "idempotencyKey": { "maxLength": 256, "type": "string" }, "metadata": { "additionalProperties": {}, "selfRequired": false, "type": "object" }, "outcome": { "default": "success", "enum": [ "success", "paywall", "fail" ], "type": "string" }, "productRef": { "type": "string" }, "purchaseRef": { "type": "string" }, "timestamp": { "format": "date-time", "type": "string" }, "units": { "default": 1, "exclusiveMaximum": false, "exclusiveMinimum": false, "maximum": 100000, "minimum": 0, "type": "integer" } }, "required": [ "customerRef", "metadata", "timestamp" ], "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" }, "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" }, "LimitBalanceDto": { "properties": { "creditBalance": { "description": "Credit balance in mils", "type": "number" }, "creditsPerUnit": { "description": "Credits per usage unit", "type": "number" }, "currency": { "type": "string" }, "remainingUnits": { "description": "Estimated whole units remaining from prepaid credit balance", "type": "number" } }, "required": [ "creditBalance", "creditsPerUnit", "currency" ], "type": "object" }, "LimitPlanItemDto": { "properties": { "billingCycle": { "type": "string" }, "billingModel": { "type": "string" }, "creditsPerUnit": { "description": "Credits per usage unit (usage-based plans)", "type": "number" }, "currency": { "type": "string" }, "freeUnits": { "type": "number" }, "name": { "type": "string" }, "price": { "description": "Price in smallest currency unit (e.g. cents)", "type": "number" }, "reference": { "type": "string" }, "requiresPayment": { "type": "boolean" }, "type": { "type": "string" } }, "required": [ "reference", "type", "price", "currency", "requiresPayment" ], "type": "object" }, "LimitProductBriefDto": { "properties": { "name": { "type": "string" }, "reference": { "type": "string" } }, "required": [ "reference" ], "type": "object" }, "LimitResponse": { "properties": { "activationRequired": { "description": "True when the customer must activate a priced default plan before usage is allowed", "type": "boolean" }, "balance": { "allOf": [ { "$ref": "#/components/schemas/LimitBalanceDto" } ], "description": "Prepaid usage balance context when the default plan is usage-based" }, "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" }, "confirmationUrl": { "description": "Customer portal confirmation URL when activation is required (fallback when not starting checkout)", "type": "string" }, "creditBalance": { "description": "Credit balance in mils (for pre-paid usage-based plans)", "type": "number" }, "creditsPerUnit": { "description": "Credits per usage unit (for pre-paid usage-based plans)", "type": "number" }, "currency": { "description": "ISO 4217 currency code for credit fields", "type": "string" }, "meterName": { "description": "The meter name to use when tracking usage events", "example": "requests", "type": "string" }, "plans": { "description": "Active plans on the product available for activation or checkout", "items": { "$ref": "#/components/schemas/LimitPlanItemDto" }, "type": "array" }, "product": { "allOf": [ { "$ref": "#/components/schemas/LimitProductBriefDto" } ], "description": "Product the limit check applies to" }, "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" }, "McpBootstrapDto": { "properties": { "authApiKey": { "type": "string" }, "authHeaderName": { "type": "string" }, "description": { "type": "string" }, "imageUrl": { "type": "string" }, "mcpDomain": { "type": "string" }, "metadata": { "additionalProperties": {}, "selfRequired": false, "type": "object" }, "name": { "type": "string" }, "originUrl": { "format": "uri", "minLength": 1, "type": "string" }, "plans": { "items": { "properties": { "billingCycle": { "enum": [ "weekly", "monthly", "quarterly", "yearly", "custom" ], "type": "string" }, "billingModel": { "enum": [ "pre-paid", "post-paid" ], "type": "string" }, "creditsPerUnit": { "type": "number" }, "currency": { "minLength": 1, "type": "string" }, "features": { "additionalProperties": {}, "type": "object" }, "freeUnits": { "exclusiveMinimum": false, "minimum": 0, "type": "number" }, "key": { "minLength": 1, "type": "string" }, "limit": { "exclusiveMinimum": false, "minimum": 0, "type": "number" }, "name": { "minLength": 1, "type": "string" }, "price": { "exclusiveMinimum": false, "minimum": 0, "type": "number" }, "type": { "enum": [ "recurring", "one-time", "usage-based" ], "type": "string" } }, "required": [ "key", "name", "price", "currency" ], "type": "object" }, "type": "array" }, "productType": { "type": "string" }, "tools": { "items": { "properties": { "description": { "type": "string" }, "name": { "minLength": 1, "type": "string" }, "noPlan": { "type": "boolean" }, "planKeys": { "items": { "type": "string" }, "type": "array" } }, "required": [ "name" ], "type": "object" }, "type": "array" } }, "required": [ "originUrl", "metadata" ], "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": { "defaultPlanRef": "pln_FREE123", "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": { "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" }, "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" }, "creditsPerUnit": { "description": "Credits per usage unit (integer, >= 1)", "example": 1, "type": "number" }, "currency": { "description": "Currency code (ISO 4217)", "example": "USD", "type": "string" }, "currencySymbol": { "description": "Currency symbol (derived from currency)", "example": "$", "type": "string" }, "description": { "description": "Plan description", "example": "Best for teams getting started", "type": "string" }, "features": { "additionalProperties": true, "description": "Plan features", "type": "object" }, "freeUnits": { "description": "Number of free units included", "example": 100, "type": "number" }, "isActive": { "description": "Whether the plan is active (derived from status)", "example": true, "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" }, "meterRef": { "description": "Meter reference for usage-based plans", "example": "mtr_1A2B3C4D", "type": "string" }, "name": { "description": "Plan name", "example": "Starter", "type": "string" }, "price": { "description": "Plan price in cents", "example": 2999, "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", "usage-based", "hybrid" ], "example": "recurring", "type": "string" }, "updatedAt": { "description": "Last update timestamp", "type": "string" } }, "required": [ "type", "reference", "price", "currency", "requiresPayment", "isActive", "status", "createdAt", "updatedAt" ], "type": "object" }, "ProcessPaymentIntentDto": { "properties": { "customerRef": { "minLength": 1, "type": "string" }, "planRef": { "type": "string" }, "productRef": { "minLength": 1, "type": "string" } }, "required": [ "productRef", "customerRef" ], "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 in USD cents (normalised for aggregation)", "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": "ISO 4217 currency code of the customer-facing charge", "example": "GBP", "type": "string" }, "endDate": { "description": "End date of purchase", "example": "2025-11-27T10:00:00Z", "type": "string" }, "exchangeRate": { "description": "Exchange rate from original currency to USD", "example": 1.32, "type": "number" }, "originalAmount": { "description": "Original amount in the payment currency (minor units)", "example": 7500, "type": "number" }, "planRef": { "description": "Plan reference from the plan snapshot, for reliable plan matching", "example": "pln_abc123", "type": "string" }, "planSnapshot": { "description": "Snapshot of the plan at time of purchase", "type": "object" }, "productName": { "description": "Product name", "example": "API Gateway Manager", "type": "string" }, "productRef": { "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" }, "RecordBulkMeterEventsZodDto": { "properties": { "events": { "items": { "properties": { "customerRef": { "minLength": 1, "type": "string" }, "meterName": { "minLength": 1, "type": "string" }, "productRef": { "type": "string" }, "properties": { "additionalProperties": {}, "type": "object" }, "timestamp": { "type": "string" }, "value": { "type": "number" } }, "required": [ "meterName", "customerRef" ], "type": "object" }, "minItems": 1, "type": "array" } }, "required": [ "events" ], "type": "object" }, "RecordMeterEventZodDto": { "properties": { "customerRef": { "minLength": 1, "type": "string" }, "meterName": { "minLength": 1, "type": "string" }, "productRef": { "type": "string" }, "properties": { "additionalProperties": {}, "selfRequired": false, "type": "object" }, "timestamp": { "type": "string" }, "value": { "type": "number" } }, "required": [ "meterName", "customerRef", "properties" ], "type": "object" }, "SdkMerchantResponseDto": { "properties": { "country": { "description": "ISO-3166 alpha-2 country code of the merchant", "example": "US", "type": "string" }, "defaultCurrency": { "description": "ISO-4217 default settlement currency", "example": "usd", "type": "string" }, "displayName": { "description": "Brand name shown in UI", "example": "Acme", "type": "string" }, "iconUrl": { "description": "Absolute URL to the square app icon / logomark. Consumed by MCP host chromes, mobile avatar slots, and any surface where the landscape `logoUrl` would need letterboxing.", "example": "https://cdn.acme.com/icon.png", "type": "string" }, "legalName": { "description": "Legal entity name used in SCA mandate copy", "example": "Acme Inc.", "type": "string" }, "logoUrl": { "description": "Absolute URL to the merchant logo", "example": "https://cdn.acme.com/logo.png", "type": "string" }, "privacyUrl": { "example": "https://acme.com/privacy", "type": "string" }, "statementDescriptor": { "description": "Descriptor appearing on the customer card statement", "example": "ACME INC", "type": "string" }, "supportEmail": { "example": "support@acme.com", "type": "string" }, "supportUrl": { "example": "https://acme.com/support", "type": "string" }, "termsUrl": { "example": "https://acme.com/terms", "type": "string" } }, "required": [ "displayName", "legalName" ], "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" }, "creditsPerUnit": { "description": "Credits per usage unit (integer, >= 1)", "example": 1, "type": "number" }, "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" }, "isActive": { "description": "Whether the plan is active", "example": true, "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" }, "meterRef": { "description": "Meter reference for usage-based limits", "example": "mtr_1A2B3C4D", "type": "string" }, "price": { "description": "Plan price in cents", "example": 2999, "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": [ "reference", "price", "currency", "requiresPayment", "isActive", "status", "createdAt", "updatedAt" ], "type": "object" }, "SdkPlanSnapshotDto": { "properties": { "billingCycle": { "description": "Billing cycle", "example": "monthly", "nullable": true, "type": "string" }, "creditsPerUnit": { "description": "Credits per usage unit (integer, >= 1)", "example": 1, "type": "number" }, "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" }, "meterRef": { "description": "Meter reference", "example": "mtr_1A2B3C4D", "type": "string" }, "name": { "description": "Plan name captured at purchase time", "example": "Pro Monthly", "type": "string" }, "planType": { "description": "Plan type", "example": "recurring", "type": "string" }, "price": { "description": "Plan price in cents", "example": 2999, "type": "number" }, "reference": { "description": "Plan reference", "example": "pln_1A2B3C4D", "type": "string" } }, "required": [ "price", "currency", "planType" ], "type": "object" }, "SdkPlatformConfigResponseDto": { "properties": { "stripePublishableKey": { "description": "SolvaPay's platform Stripe publishable key for the authenticated provider's environment. Safe to expose browser-side; paired with the connected `accountId` returned from `create-payment-intent` for Stripe Connect direct charges. Omitted when not configured so callers can fall back cleanly to a hosted flow.", "example": "pk_test_...", "type": "string" } }, "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" }, "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": { "defaultPlanRef": "pln_FREE123", "mcpProxyUrl": "https://acme-docs.mcp.solvapay.com/mcp", "mcpServerRef": "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": [ "reference", "name", "status", "balance", "totalTransactions", "isMcpPay", "createdAt", "updatedAt" ], "type": "object" }, "SdkPurchaseResponse": { "properties": { "amount": { "description": "Amount in USD cents (normalised for aggregation)", "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": "Original payment currency code", "example": "GBP", "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" }, "exchangeRate": { "description": "Exchange rate from original currency to USD", "example": 1.3082, "type": "number" }, "isRecurring": { "description": "Is recurring", "example": true, "type": "boolean" }, "metadata": { "additionalProperties": true, "description": "Arbitrary metadata attached to the purchase", "type": "object" }, "nextBillingDate": { "description": "Next billing date", "type": "string" }, "originalAmount": { "description": "Original amount in the payment currency (cents/pence)", "example": 10000, "type": "number" }, "paidAt": { "description": "Paid at timestamp", "type": "string" }, "planSnapshot": { "allOf": [ { "$ref": "#/components/schemas/SdkPlanSnapshotDto" } ], "description": "Plan snapshot at time of purchase (null for credit topups)" }, "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": [ "reference", "customerRef", "customerEmail", "productRef", "status", "amount", "currency", "startDate", "isRecurring", "createdAt" ], "type": "object" }, "UpdateCustomerRequest": { "properties": { "email": { "format": "email", "type": "string" }, "externalRef": { "type": "string" }, "metadata": {}, "name": { "type": "string" }, "telephone": { "type": "string" } }, "type": "object" }, "UpdatePlanRequest": { "properties": { "accessExpiryDays": { "type": "number" }, "billingCycle": { "enum": [ "weekly", "monthly", "quarterly", "yearly", "custom" ], "type": "string" }, "billingModel": { "enum": [ "pre-paid", "post-paid" ], "type": "string" }, "creditsPerUnit": { "type": "number" }, "currency": { "type": "string" }, "default": { "type": "boolean" }, "description": { "type": "string" }, "features": { "additionalProperties": {}, "selfRequired": false, "type": "object" }, "freeUnits": { "type": "number" }, "limit": { "type": "number" }, "limits": { "additionalProperties": {}, "selfRequired": false, "type": "object" }, "maxActiveUsers": { "type": "number" }, "metadata": { "additionalProperties": {}, "selfRequired": false, "type": "object" }, "name": { "minLength": 1, "type": "string" }, "price": { "type": "number" }, "status": { "enum": [ "active", "inactive", "archived" ], "type": "string" } }, "required": [ "limits", "features", "metadata" ], "type": "object" }, "UpdateProductRequest": { "properties": { "config": { "properties": { "deliveryMethod": { "type": "string" }, "fulfillmentType": { "type": "string" }, "validityPeriod": { "type": "number" } }, "selfRequired": false, "type": "object" }, "description": { "type": "string" }, "imageUrl": { "type": "string" }, "metadata": { "additionalProperties": {}, "selfRequired": false, "type": "object" }, "name": { "type": "string" }, "productType": { "type": "string" }, "status": { "enum": [ "active", "inactive", "suspended" ], "type": "string" } }, "required": [ "config", "metadata" ], "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": { "minLength": 1, "type": "string" }, "productRef": { "minLength": 1, "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": { "meterRef": { "description": "Meter reference", "example": "meter_ABC123", "nullable": true, "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" } }, "securitySchemes": { "OAuth2": { "flows": { "authorizationCode": { "authorizationUrl": "https://api.solvapay.com/v1/customer/auth/authorize", "scopes": { "email": "Email address", "openid": "OpenID Connect scope", "profile": "Profile information" }, "tokenUrl": "https://api.solvapay.com/v1/customer/auth/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/activate": { "post": { "operationId": "ActivateSdkController_activate", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivatePlanDto" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivatePlanResponseDto" } } }, "description": "" } }, "security": [ { "bearer": [] } ], "tags": [ "Activation" ] } }, "/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": { "$ref": "#/components/schemas/CreateCheckoutSessionRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCheckoutSessionResponse" } } }, "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", "productRef": "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", "productRef": "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" ] }, "patch": { "description": "Updates an existing customer identified by reference. Use this to backfill or change fields such as `externalRef`, `name`, or `email`. Only the fields supplied in the body are modified.", "operationId": "CustomerSdkController_updateCustomer", "parameters": [ { "description": "Customer reference identifier", "in": "path", "name": "reference", "required": true, "schema": { "example": "cus_3c4d5e6f7g8h", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "linkExternalRef": { "summary": "Backfill externalRef", "value": { "externalRef": "auth_user_12345" } }, "updateProfile": { "summary": "Update name and email", "value": { "email": "jane@example.com", "name": "Jane Doe" } } }, "schema": { "$ref": "#/components/schemas/UpdateCustomerRequest" } } }, "description": "Fields to update (all optional)", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerResponse" } } }, "description": "Customer updated successfully" }, "400": { "description": "Invalid update payload" }, "404": { "description": "Customer not found" } }, "security": [ { "SecretKey": [] } ], "summary": "Update a customer", "tags": [ "Customers" ] } }, "/v1/sdk/customers/{reference}/balance": { "get": { "description": "Returns the credit balance for a customer identified by reference.", "operationId": "CustomerSdkController_getCustomerBalance", "parameters": [ { "description": "Customer reference identifier", "in": "path", "name": "reference", "required": true, "schema": { "example": "cus_3c4d5e6f7g8h", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "example": { "credits": 4200, "creditsPerMinorUnit": 100, "customerRef": "cus_3c4d5e6f7g8h", "displayCurrency": "USD" } } } }, "description": "Customer balance 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 credit balance", "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", "productRef": "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/merchant": { "get": { "description": "Returns the subset of provider data safe to render in a customer-facing checkout: display name, legal name, support contact, terms and privacy URLs, and logo. Used by SDK components like MandateText and CheckoutSummary.", "operationId": "getMerchant", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SdkMerchantResponseDto" } } }, "description": "Merchant identity" }, "404": { "description": "Provider not found" } }, "security": [ { "SecretKey": [] } ], "summary": "Get merchant identity for the authenticated provider", "tags": [ "Merchant" ] } }, "/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/RecordMeterEventZodDto" } } }, "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": "Persists each event with recordUsage (same shape as single POST), after shared meter/customer checks.", "operationId": "MeterEventsSdkController_recordBulkEvents", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordBulkMeterEventsZodDto" } } }, "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", "planRef": "pln_2b3c4d5e6f7g", "processorPaymentId": "pi_1a2b3c4d5e6f7g8h", "status": "succeeded" } ], "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. 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": { "$ref": "#/components/schemas/CreatePaymentIntentDto" } } }, "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", "customerRef": "cus_3c4d5e6f7g8h", "exchangeRate": 1, "expiresAt": "2025-10-19T10:30:00.000Z", "originalAmount": 4999, "planRef": "pln_2b3c4d5e6f7g", "processorPaymentId": "pi_1a2b3c4d5e6f7g8h", "publishableKey": "pk_test_...", "status": "requires_payment_method" } } } }, "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/{processorPaymentId}/process": { "post": { "description": "Processes a payment intent that has been confirmed on the client side. 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": "Payment processor ID returned from createPaymentIntent", "in": "path", "name": "processorPaymentId", "required": true, "schema": { "example": "pi_1a2b3c4d5e6f7g8h", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProcessPaymentIntentDto" } } }, "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 payment 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 payment 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/payment-intents/{reference}": { "get": { "description": "Retrieves detailed information about a specific payment intent including amount, currency, and client secret.", "operationId": "PaymentIntentSdkController_getPaymentIntent", "parameters": [ { "description": "Payment intent reference or processor payment ID", "in": "path", "name": "reference", "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", "tags": [ "Payment Intents" ] } }, "/v1/sdk/payment-method": { "get": { "description": "Returns the customer's default card for the authenticated provider. Sourced from stored payment-method records (no Stripe round-trip). Returns `{ kind: 'none' }` when no card is on file.", "operationId": "PaymentMethodSdkController_getPaymentMethod", "parameters": [ { "description": "Customer reference (e.g. `customer_...`).", "in": "query", "name": "customerRef", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "discriminator": { "propertyName": "kind" }, "oneOf": [ { "properties": { "brand": { "example": "visa", "type": "string" }, "expMonth": { "example": 12, "maximum": 12, "minimum": 1, "type": "integer" }, "expYear": { "example": 2030, "type": "integer" }, "kind": { "enum": [ "card" ], "type": "string" }, "last4": { "example": "4242", "type": "string" } }, "required": [ "kind", "brand", "last4", "expMonth", "expYear" ], "type": "object" }, { "properties": { "kind": { "enum": [ "none" ], "type": "string" } }, "required": [ "kind" ], "type": "object" } ] } } }, "description": "The customer's default card, or `{ kind: 'none' }` when no card is on file." } }, "security": [ { "bearer": [] } ], "summary": "Get the default payment method for a customer", "tags": [ "Payment Methods" ] } }, "/v1/sdk/platform-config": { "get": { "description": "Returns browser-safe platform values resolved against the provider environment. Today: the SolvaPay platform Stripe publishable key. This endpoint is the canonical home for future platform-wide, environment-gated SDK config (API version hints, feature flags, public hosted URLs) — additions land here instead of bloating /sdk/merchant (strictly provider identity) or /sdk/payment-intents (runs too late for pre-intent UI decisions).", "operationId": "getPlatformConfig", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SdkPlatformConfigResponseDto" } } }, "description": "Platform config" } }, "security": [ { "SecretKey": [] } ], "summary": "Get environment-aware platform config for the authenticated provider", "tags": [ "Platform Config" ] } }, "/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. In live mode, soft-deletes (preserves data but hides from listings). If the product has purchases in live mode, deactivates 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" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloneProductDto" } } }, "required": true }, "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}/mcp/plans": { "put": { "description": "Configures plans and optional tool-to-plan mappings for an MCP product.", "operationId": "ProductSdkController_configureMcpPlans", "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/ConfigureMcpPlansDto" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigureMcpPlansResult" } } }, "description": "MCP plans configured successfully" }, "400": { "description": "Invalid MCP plans request or product is not MCP-enabled" }, "404": { "description": "Product not found" } }, "security": [ { "bearer": [] } ], "summary": "Configure MCP plans on an MCP 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 with a unified plans array, configures origin URL, and maps tools to plans in one request.", "operationId": "ProductSdkController_bootstrapMcpProduct", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpBootstrapDto" } } }, "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 reference", "in": "query", "name": "productRef", "required": false, "schema": { "type": "string" } }, { "description": "Filter by customer reference", "in": "query", "name": "customerRef", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "purchases": { "items": { "$ref": "#/components/schemas/SdkPurchaseResponse" }, "type": "array" } } } } }, "description": "Purchases retrieved successfully" } }, "security": [ { "bearer": [] } ], "summary": "List purchases for provider", "tags": [ "Purchases" ] } }, "/v1/sdk/purchases/{purchaseRef}": { "get": { "description": "Retrieves a single purchase including plan snapshot, usage, and billing details.", "operationId": "PurchaseSdkController_getPurchase", "parameters": [ { "description": "Purchase reference or ID", "in": "path", "name": "purchaseRef", "required": true, "schema": { "example": "pur_1A2B3C4D", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SdkPurchaseResponse" } } }, "description": "Purchase retrieved successfully" }, "404": { "description": "Purchase not found" } }, "security": [ { "bearer": [] } ], "summary": "Get a purchase by 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/SdkPurchaseResponse" }, "success": { "type": "boolean" } } } } }, "description": "Purchase cancelled successfully" }, "404": { "description": "Purchase not found" } }, "security": [ { "bearer": [] } ], "summary": "Cancel a purchase", "tags": [ "Purchases" ] } }, "/v1/sdk/purchases/{purchaseRef}/reactivate": { "post": { "description": "Reactivates a purchase that was cancelled but has not yet reached its end date. Restores auto-renewal and clears cancellation fields.", "operationId": "PurchaseSdkController_reactivatePurchase", "parameters": [ { "description": "Purchase reference or ID", "in": "path", "name": "purchaseRef", "required": true, "schema": { "example": "pur_1A2B3C4D", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "purchase": { "$ref": "#/components/schemas/SdkPurchaseResponse" }, "success": { "type": "boolean" } } } } }, "description": "Purchase reactivated successfully" }, "400": { "description": "Purchase cannot be reactivated" }, "404": { "description": "Purchase not found" } }, "security": [ { "bearer": [] } ], "summary": "Reactivate a cancelled 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/SdkPurchaseResponse" }, "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/SdkPurchaseResponse" }, "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": { "$ref": "#/components/schemas/CreateUsageRequest" } } }, "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": "Same persistence rules as POST /sdk/usages for each item: validate batch first, then one insert per event.", "operationId": "UsageSdkController_recordBulkUsage", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkCreateUsageRequest" } } }, "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": [] }