{ "openapi": "3.1.0", "info": { "title": "Payments AI MoR Merchant Public API", "version": "1.0.0", "description": "Merchant Public API, partner onboarding, and buyer checkout endpoints. Authenticate every call with a Merchant API Key (pai_test_* / pai_live_*). The same key reaches its own merchant resources and those of any sub-merchant it has onboarded via POST /v1/public-api/merchants." }, "servers": [ { "url": "https://sandbox.managed.payments.ai/api", "description": "Sandbox API" } ], "paths": { "/v1/checkout/plans/{planId}": { "get": { "operationId": "PublicCheckout_getByPlanId", "parameters": [ { "name": "planId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The request has succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCheckoutByPlanResponse" } } } } }, "summary": "Get buyer checkout by plan", "tags": ["Buyer checkout"] } }, "/v1/checkout/plans/{planId}/confirm": { "post": { "operationId": "PublicCheckout_confirmPaymentByPlanId", "parameters": [ { "name": "planId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The request has succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCheckoutPaymentConfirmationResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmPublicCheckoutPaymentRequest" } } } }, "summary": "Confirm payment by plan id", "tags": ["Buyer checkout"] } }, "/v1/checkout/plans/{planId}/policies/{policyType}": { "get": { "operationId": "PublicCheckout_redirectPolicyByPlanId", "description": "302 to a seller https URL, a fresh presigned PDF GET, or the Whop default for unset Terms/Privacy.", "parameters": [ { "name": "planId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "policyType", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "302": { "description": "Redirection", "headers": { "location": { "required": true, "schema": { "type": "string" } } } }, "404": { "description": "The server cannot find the requested resource." } }, "summary": "Redirect policy by plan id", "tags": ["Buyer checkout"] } }, "/v1/checkout/plans/{planId}/promo-codes": { "post": { "operationId": "PublicCheckout_applyPromoCodeByPlanId", "description": "Validate a promo code for this plan and return the discounted quote. Does not charge.", "parameters": [ { "name": "planId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The request has succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplyPublicCheckoutPromoCodeResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplyPublicCheckoutPromoCodeRequest" } } } }, "summary": "Apply promo code by plan id", "tags": ["Buyer checkout"] } }, "/v1/checkout/plans/{planId}/receipts/{receiptId}": { "get": { "operationId": "PublicCheckout_getReceiptByPlanId", "parameters": [ { "name": "planId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "receiptId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The request has succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCheckoutReceiptResponse" } } } } }, "summary": "Get buyer checkout receipt", "tags": ["Buyer checkout"] } }, "/v1/checkout/plans/{planId}/session": { "post": { "operationId": "PublicCheckout_createSessionByPlanId", "parameters": [ { "name": "planId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The request has succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCheckoutSessionResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePublicCheckoutSessionRequest" } } } }, "summary": "Create buyer checkout session", "tags": ["Buyer checkout"] } }, "/v1/public-api/merchants": { "post": { "operationId": "PublicApiMerchants_create", "parameters": [], "responses": { "201": { "description": "The request has succeeded and a new resource has been created as a result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiCreateMerchantResponse" } } } } }, "tags": ["Partner Onboarding"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiCreateMerchantRequest" } } } }, "summary": "Create merchant" } }, "/v1/public-api/merchants/{merchantId}/api-keys": { "get": { "operationId": "PublicApiApiKeys_list", "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The request has succeeded.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PublicApiApiKeySummary" } } } } } }, "tags": ["API"], "summary": "List keys" }, "post": { "operationId": "PublicApiApiKeys_create", "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "The request has succeeded and a new resource has been created as a result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiCreateApiKeyResponse" } } } } }, "tags": ["API"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiCreateApiKeyRequest" } } } }, "summary": "Create key" } }, "/v1/public-api/merchants/{merchantId}/api-keys/{id}": { "delete": { "operationId": "PublicApiApiKeys_revoke", "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "There is no content to send for this request, but the headers may be useful. " } }, "tags": ["API"], "summary": "Revoke key" } }, "/v1/public-api/merchants/{merchantId}/checkout/plans/{planId}": { "get": { "operationId": "PublicApiCheckout_resolveByPlanId", "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "planId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The request has succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiCheckoutByPlanResponse" } } } } }, "summary": "Get checkout by plan", "tags": ["Checkout"] } }, "/v1/public-api/merchants/{merchantId}/checkout/plans/{planId}/confirm": { "post": { "operationId": "PublicApiCheckout_confirmPaymentByPlanId", "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "planId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The request has succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiCheckoutPaymentConfirmationResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiConfirmCheckoutPaymentRequest" } } } }, "summary": "Confirm payment by plan id", "tags": ["Checkout"] } }, "/v1/public-api/merchants/{merchantId}/checkout/plans/{planId}/promo-codes": { "post": { "operationId": "PublicApiCheckout_applyPromoCodeByPlanId", "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "planId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The request has succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiApplyCheckoutPromoCodeResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiApplyCheckoutPromoCodeRequest" } } } }, "summary": "Apply promo code by plan id", "tags": ["Checkout"] } }, "/v1/public-api/merchants/{merchantId}/checkout/plans/{planId}/receipts/{receiptId}": { "get": { "operationId": "PublicApiCheckout_getReceiptByPlanId", "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "planId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "receiptId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The request has succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiCheckoutReceiptResponse" } } } } }, "summary": "Get checkout receipt", "tags": ["Checkout"] } }, "/v1/public-api/merchants/{merchantId}/checkout/plans/{planId}/session": { "post": { "operationId": "PublicApiCheckout_createSessionByPlanId", "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "planId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The request has succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiCheckoutSessionResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiCreateCheckoutSessionRequest" } } } }, "summary": "Create checkout session", "tags": ["Checkout"] } }, "/v1/public-api/merchants/{merchantId}/customers": { "get": { "operationId": "PublicApiCustomers_listCustomers", "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32" }, "explode": false }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32" }, "explode": false }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "explode": false } ], "responses": { "200": { "description": "The request has succeeded.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } } } }, "summary": "List customers", "tags": ["Customers"] } }, "/v1/public-api/merchants/{merchantId}/customers/{id}": { "get": { "operationId": "PublicApiCustomers_getCustomer", "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The request has succeeded.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } } } }, "summary": "Get customer", "tags": ["Customers"] } }, "/v1/public-api/merchants/{merchantId}/invoices": { "get": { "operationId": "PublicApiInvoices_listInvoices", "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32" }, "explode": false }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32" }, "explode": false }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "explode": false }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "explode": false } ], "responses": { "200": { "description": "The request has succeeded.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } } } }, "summary": "List invoices", "tags": ["Invoices"] } }, "/v1/public-api/merchants/{merchantId}/invoices/{id}": { "get": { "operationId": "PublicApiInvoices_getInvoice", "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The request has succeeded.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } } } }, "summary": "Get invoice", "tags": ["Invoices"] } }, "/v1/public-api/merchants/{merchantId}/invoices/{id}/download": { "get": { "operationId": "PublicApiInvoices_downloadInvoice", "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The request has succeeded.", "headers": { "content-disposition": { "required": true, "schema": { "type": "string" } } }, "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } } }, "summary": "Download invoice", "tags": ["Invoices"] } }, "/v1/public-api/merchants/{merchantId}/join-link": { "post": { "operationId": "PublicApiMerchantJoinLink_remint", "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "The request has succeeded and a new resource has been created as a result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiMerchantJoinLinkResponse" } } } } }, "tags": ["API"], "summary": "Remint link" } }, "/v1/public-api/merchants/{merchantId}/products": { "get": { "operationId": "PublicApiProducts_list", "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "explode": false }, { "name": "status", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ProductStatus" }, "explode": false }, { "name": "type", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/PlanType" }, "explode": false }, { "name": "dateRangeStart", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "explode": false }, { "name": "dateRangeEnd", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "explode": false }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32" }, "explode": false }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32" }, "explode": false } ], "responses": { "200": { "description": "The request has succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiProductListResponse" } } } } }, "tags": ["Products"], "summary": "List products" }, "post": { "operationId": "PublicApiProducts_create", "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "The request has succeeded and a new resource has been created as a result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProductResponse" } } } } }, "tags": ["Products"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiCreateProduct" } } } }, "summary": "Create product" } }, "/v1/public-api/merchants/{merchantId}/products/{id}": { "get": { "operationId": "PublicApiProducts_getById", "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The request has succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiProduct" } } } } }, "tags": ["Products"], "summary": "Get product" } }, "/v1/public-api/merchants/{merchantId}/products/{id}/plans": { "get": { "operationId": "PublicApiProducts_listPlans", "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The request has succeeded.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PublicApiPlan" } } } } } }, "tags": ["Products"], "summary": "List plans" }, "post": { "operationId": "PublicApiProducts_createPlan", "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "The request has succeeded and a new resource has been created as a result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiPlan" } } } } }, "tags": ["Products"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePlan" } } } }, "summary": "Create plan" } }, "/v1/public-api/merchants/{merchantId}/transactions": { "post": { "operationId": "PublicApiTransactions_createTransaction", "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "idempotency-key", "in": "header", "required": false, "schema": { "type": "string" } } ], "responses": { "201": { "description": "The request has succeeded and a new resource has been created as a result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiCheckoutPaymentConfirmationResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiCreateTransactionRequest" } } } }, "summary": "Create transaction", "tags": ["Transactions"] }, "get": { "operationId": "PublicApiTransactions_listTransactions", "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32" }, "explode": false }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32" }, "explode": false }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "explode": false }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "explode": false } ], "responses": { "200": { "description": "The request has succeeded.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } } } }, "summary": "List transactions", "tags": ["Transactions"] } }, "/v1/public-api/merchants/{merchantId}/transactions/{id}": { "get": { "operationId": "PublicApiTransactions_getTransaction", "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The request has succeeded.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } } } }, "summary": "Get transaction", "tags": ["Transactions"] } } }, "components": { "schemas": { "PublicCheckoutByPlanResponse": { "type": "object", "required": [ "planId", "productId", "merchantId", "productName", "type", "amount", "initialPrice", "currency", "checkoutUrl", "customization" ], "properties": { "planId": { "type": "string" }, "externalPlanId": { "type": "string" }, "externalMerchantId": { "type": "string" }, "productId": { "type": "string" }, "merchantId": { "type": "string" }, "productName": { "type": "string" }, "productDescription": { "type": "string" }, "productImagePath": { "type": "string" }, "type": { "type": "string" }, "billingPeriod": { "type": "string", "description": "Present for recurring plans; drives checkout recurrence policy copy (day | week | month | year)." }, "lengthOfBillingPeriod": { "type": "integer", "format": "int32", "description": "Number of billing periods per charge cycle (e.g. 3 with month = every 3 months)." }, "amount": { "$ref": "#/components/schemas/SharedTypes.MoneyAmountValue" }, "initialPrice": { "allOf": [ { "$ref": "#/components/schemas/SharedTypes.MoneyAmountValue" } ], "description": "Amount charged at checkout today. Zero for recurring plans with a free trial; otherwise matches amount." }, "currency": { "type": "string" }, "checkoutUrl": { "type": "string" }, "websiteUrl": { "type": "string", "nullable": true, "description": "Merchant store URL from business settings (`merchants.url`). Null when not configured." }, "termsUrl": { "type": "string", "nullable": true, "description": "Seller Terms URL or stable API redirect for a PDF. Null when unset (hosted checkout falls back to Whop)." }, "privacyUrl": { "type": "string", "nullable": true, "description": "Seller Privacy URL or stable API redirect for a PDF. Null when unset (hosted checkout falls back to Whop)." }, "returnPolicyUrl": { "type": "string", "nullable": true, "description": "Seller Return policy URL or stable API redirect for a PDF. Null when unset (link omitted on checkout)." }, "eulaUrl": { "type": "string", "nullable": true, "description": "Seller EULA URL or stable API redirect for a PDF. Null when unset (link omitted on checkout)." }, "customization": { "$ref": "#/components/schemas/CheckoutCustomization" } } }, "PublicCheckoutPaymentConfirmationResponse": { "type": "object", "required": ["paymentId", "clientSecret", "status"], "properties": { "paymentId": { "type": "string", "description": "Whop payment id (`pay_…`) — use as `receiptId` on the checkout status page." }, "clientSecret": { "type": "string", "description": "Credential for `whop.payments.handleNextAction()` on the client." }, "status": { "type": "string", "description": "Whop payment status immediately after create (processing may continue asynchronously)." } } }, "ConfirmPublicCheckoutPaymentRequest": { "type": "object", "required": ["confirmationToken", "returnUrl"], "properties": { "confirmationToken": { "type": "string", "description": "Whop confirmation token (`ctok_…`) minted by `payments.createConfirmationToken()` on the client." }, "returnUrl": { "type": "string", "description": "Return URL for off-site buyer steps (3DS, bank redirect). Must match the page that calls `handleNextAction`." }, "promoCode": { "type": "string", "description": "Optional buyer-entered promo/discount code. Resolved server-side to a Whop `promo_code_id` before charging." } } }, "ApplyPublicCheckoutPromoCodeResponse": { "type": "object", "required": [ "code", "promoType", "amountOff", "discountAmount", "total", "currency", "billingPeriod" ], "properties": { "code": { "type": "string", "description": "Normalized (uppercased) code that was applied." }, "promoType": { "type": "string", "description": "percentage | flat_amount" }, "amountOff": { "type": "string", "description": "Raw amount-off value from the discount definition (percent points or flat major units)." }, "discountAmount": { "allOf": [ { "$ref": "#/components/schemas/SharedTypes.MoneyAmountValue" } ], "description": "Absolute discount applied to this plan amount, in major currency units." }, "total": { "allOf": [ { "$ref": "#/components/schemas/SharedTypes.MoneyAmountValue" } ], "description": "Plan amount after discount (floor 0), before tax." }, "currency": { "type": "string" }, "billingPeriod": { "type": "string", "description": "once | repeating | forever — how long the promo applies after purchase." } } }, "ApplyPublicCheckoutPromoCodeRequest": { "type": "object", "required": ["code"], "properties": { "code": { "type": "string", "description": "Buyer-entered promo/discount code (case-insensitive; stored uppercased)." } } }, "PublicCheckoutReceiptResponse": { "type": "object", "required": ["subtotal", "taxAmount", "total", "currency"], "properties": { "subtotal": { "$ref": "#/components/schemas/SharedTypes.MoneyAmountValue" }, "taxAmount": { "$ref": "#/components/schemas/SharedTypes.MoneyAmountValue" }, "total": { "$ref": "#/components/schemas/SharedTypes.MoneyAmountValue" }, "currency": { "type": "string" } } }, "PublicCheckoutSessionResponse": { "type": "object", "required": ["sessionId"], "properties": { "sessionId": { "type": "string" }, "purchaseUrl": { "type": "string" } } }, "CreatePublicCheckoutSessionRequest": { "type": "object", "required": ["returnUrl"], "properties": { "returnUrl": { "type": "string" } } }, "PublicApiCreateMerchantResponse": { "type": "object", "required": ["merchantId", "created", "ownerAttached"], "properties": { "merchantId": { "type": "string" }, "created": { "type": "boolean", "description": "True on first create; false when this `merchantId` had already been provisioned with matching details." }, "ownerAttached": { "type": "boolean", "description": "True when the owner email matched an existing user and was assigned the `owner` role. False when the email is unknown to PAI — the response then also carries `joinUrl` / `joinUrlExpiresAt`, a claim link the partner delivers to the seller (PAIM-995). PAI does not email the seller directly." }, "joinUrl": { "type": "string", "description": "Owner-claim join URL. Present only when `ownerAttached` is false. Deliver to the seller so they can sign up (or in) and claim ownership. Regenerate via `POST /v1/public-api/merchants/{merchantId}/join-link` if the seller loses or expires it." }, "joinUrlExpiresAt": { "type": "string", "format": "date-time", "description": "Expiration of the `joinUrl` (7 days after issuance). Present only when `joinUrl` is present." } } }, "PublicApiCreateMerchantRequest": { "type": "object", "required": ["name", "email"], "properties": { "name": { "type": "string", "maxLength": 244, "description": "Business name displayed to customers. `'s Merchant` is appended when stored." }, "email": { "type": "string", "format": "email", "description": "Owner email. If a user with this email already exists, they are assigned as Owner; otherwise the merchant is created without a membership and `ownerAttached` is false." }, "phone": { "type": "string", "pattern": "^\\+[1-9]\\d{1,14}$", "description": "Optional E.164 phone. If omitted, the merchant provides it during KYC." }, "merchantId": { "type": "string", "description": "Optional client-supplied UUID v7 idempotency key. Re-submitting the same id with the same details is safe and returns `created: false`." } } }, "PublicApiApiKeySummary": { "type": "object", "required": ["id", "name", "maskedKey", "environment", "lastUsedAt", "createdAt"], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "maskedKey": { "type": "string" }, "environment": { "type": "string", "enum": ["sandbox", "live"] }, "lastUsedAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" } } }, "PublicApiCreateApiKeyResponse": { "type": "object", "required": ["key", "maskedKey", "id", "createdAt"], "properties": { "key": { "type": "string", "description": "Plaintext key, returned exactly once. Only its hash is persisted — store it now." }, "maskedKey": { "type": "string" }, "id": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } }, "PublicApiCreateApiKeyRequest": { "type": "object", "required": ["name", "environment"], "properties": { "name": { "type": "string", "maxLength": 128 }, "environment": { "type": "string", "enum": ["sandbox", "live"] } } }, "PublicApiCheckoutByPlanResponse": { "type": "object", "required": [ "planId", "productId", "productName", "type", "amount", "initialPrice", "currency", "checkoutUrl", "customization" ], "properties": { "planId": { "type": "string" }, "productId": { "type": "string" }, "productName": { "type": "string" }, "productDescription": { "type": "string" }, "productImagePath": { "type": "string", "nullable": true }, "type": { "type": "string" }, "billingPeriod": { "type": "string" }, "lengthOfBillingPeriod": { "type": "integer", "format": "int32" }, "amount": { "$ref": "#/components/schemas/SharedTypes.MoneyAmountValue" }, "initialPrice": { "allOf": [ { "$ref": "#/components/schemas/SharedTypes.MoneyAmountValue" } ], "description": "Amount charged at checkout today. Zero for recurring plans with a free trial; otherwise matches amount." }, "currency": { "type": "string" }, "checkoutUrl": { "type": "string" }, "websiteUrl": { "type": "string", "nullable": true }, "termsUrl": { "type": "string", "nullable": true, "description": "Seller Terms URL or stable API redirect for a PDF. Null when unset." }, "privacyUrl": { "type": "string", "nullable": true, "description": "Seller Privacy URL or stable API redirect for a PDF. Null when unset." }, "returnPolicyUrl": { "type": "string", "nullable": true, "description": "Seller Return policy URL or stable API redirect for a PDF. Null when unset." }, "eulaUrl": { "type": "string", "nullable": true, "description": "Seller EULA URL or stable API redirect for a PDF. Null when unset." }, "customization": { "type": "object", "additionalProperties": {} } } }, "PublicApiCheckoutPaymentConfirmationResponse": { "type": "object", "required": ["paymentId", "clientSecret", "status"], "properties": { "paymentId": { "type": "string" }, "clientSecret": { "type": "string" }, "status": { "type": "string" } } }, "PublicApiConfirmCheckoutPaymentRequest": { "type": "object", "required": ["confirmationToken", "returnUrl"], "properties": { "confirmationToken": { "type": "string" }, "returnUrl": { "type": "string" }, "promoCode": { "type": "string", "description": "Optional buyer-entered promo/discount code. Resolved server-side to a Whop `promo_code_id` before charging." } } }, "PublicApiApplyCheckoutPromoCodeResponse": { "type": "object", "required": [ "code", "promoType", "amountOff", "discountAmount", "total", "currency", "billingPeriod" ], "properties": { "code": { "type": "string" }, "promoType": { "type": "string" }, "amountOff": { "type": "string" }, "discountAmount": { "type": "number", "format": "double" }, "total": { "type": "number", "format": "double" }, "currency": { "type": "string" }, "billingPeriod": { "type": "string" } } }, "PublicApiApplyCheckoutPromoCodeRequest": { "type": "object", "required": ["code"], "properties": { "code": { "type": "string", "description": "Buyer-entered promo/discount code (case-insensitive; stored uppercased)." } } }, "PublicApiCheckoutReceiptResponse": { "type": "object", "required": ["subtotal", "taxAmount", "total", "currency"], "properties": { "subtotal": { "type": "number", "format": "double" }, "taxAmount": { "type": "number", "format": "double" }, "total": { "type": "number", "format": "double" }, "currency": { "type": "string" } } }, "PublicApiCheckoutSessionResponse": { "type": "object", "required": ["sessionId"], "properties": { "sessionId": { "type": "string" }, "purchaseUrl": { "type": "string", "nullable": true } } }, "PublicApiCreateCheckoutSessionRequest": { "type": "object", "required": ["returnUrl"], "properties": { "returnUrl": { "type": "string" } } }, "PublicApiMerchantJoinLinkResponse": { "type": "object", "required": ["joinUrl", "joinUrlExpiresAt"], "properties": { "joinUrl": { "type": "string", "description": "Freshly minted owner-claim join URL (7-day TTL). The previously-issued token, if any, is invalidated by this call." }, "joinUrlExpiresAt": { "type": "string", "format": "date-time" } } }, "ProductStatus": { "type": "string", "enum": ["active", "draft", "archived"] }, "PlanType": { "type": "string", "enum": ["free-access", "one-time", "recurring"] }, "PublicApiProductListResponse": { "type": "object", "required": ["data", "meta"], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PublicApiProductListItem" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } }, "CreateProductResponse": { "type": "object", "required": ["id"], "properties": { "id": { "type": "string" } } }, "PublicApiCreateProduct": { "type": "object", "required": ["name", "plans"], "properties": { "name": { "type": "string", "maxLength": 30 }, "description": { "type": "string", "maxLength": 80 }, "status": { "$ref": "#/components/schemas/ProductStatus" }, "discountCode": { "type": "string", "description": "Deprecated: legacy discount codes on the product. New promos are first-class DiscountCode entities." }, "plans": { "type": "array", "items": { "$ref": "#/components/schemas/CreatePlan" } }, "imagePath": { "type": "string", "maxLength": 255 } } }, "PublicApiProduct": { "type": "object", "required": [ "id", "merchantId", "name", "status", "revenue", "discountCodes", "plans", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "merchantId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "status": { "$ref": "#/components/schemas/ProductStatus" }, "revenue": { "type": "number", "format": "decimal" }, "discountCodes": { "type": "array", "items": { "type": "string" }, "description": "Deprecated: legacy discount codes on the product. New promos are first-class DiscountCode entities. Retained for backward compatibility until migration (PAIM-285)." }, "plans": { "type": "array", "items": { "$ref": "#/components/schemas/PublicApiPlanVariant" } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "type": "string", "format": "date-time", "nullable": true }, "imageUrl": { "type": "string", "nullable": true, "description": "Presigned URL resolved on the read side from the stored S3 image key." }, "activeSubscriptionCount": { "type": "integer", "format": "int32", "description": "Active subscriptions billed against this product" }, "totalSalesCount": { "type": "integer", "format": "int32", "description": "Lifetime sales count for delete eligibility" }, "canPermanentlyDelete": { "type": "boolean", "description": "True when draft with zero sales and zero active subscriptions" } } }, "PublicApiPlan": { "type": "object", "required": [ "id", "productId", "name", "type", "billingPeriod", "lengthOfBillingPeriod", "amount", "initialPrice", "currency", "freeTrial", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "productId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "type": { "type": "string" }, "billingPeriod": { "type": "string" }, "lengthOfBillingPeriod": { "type": "integer", "format": "int32" }, "amount": { "$ref": "#/components/schemas/SharedTypes.MoneyAmountValue" }, "initialPrice": { "allOf": [ { "$ref": "#/components/schemas/SharedTypes.MoneyAmountValue" } ], "description": "Amount charged at checkout today. Zero for recurring plans with a free trial; otherwise matches amount." }, "currency": { "type": "string" }, "freeTrial": { "type": "integer", "format": "int32" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "CreatePlan": { "type": "object", "required": ["name", "currency", "amount", "type", "billingPeriod", "periodLength"], "properties": { "name": { "type": "string", "maxLength": 30 }, "description": { "type": "string", "maxLength": 80 }, "richDescription": { "type": "string", "maxLength": 65535 }, "currency": { "$ref": "#/components/schemas/SharedTypes.CurrencyCode" }, "amount": { "allOf": [ { "$ref": "#/components/schemas/SharedTypes.MoneyAmountValue" } ], "description": "Strictly flat pricing amount" }, "type": { "$ref": "#/components/schemas/PlanType" }, "billingPeriod": { "$ref": "#/components/schemas/CreateBillingPeriod" }, "periodLength": { "type": "integer", "format": "int32", "minimum": 1 }, "freeTrial": { "type": "integer", "format": "int32", "minimum": 0 } } }, "PublicApiCreateTransactionRequest": { "type": "object", "required": ["amount", "currency", "confirmationToken", "returnUrl"], "properties": { "amount": { "allOf": [ { "$ref": "#/components/schemas/SharedTypes.MoneyAmountValue" } ], "description": "Charge amount in major currency units. Minimums are enforced per currency." }, "currency": { "$ref": "#/components/schemas/SharedTypes.CurrencyCode" }, "confirmationToken": { "type": "string", "description": "Whop confirmation token (`ctok_…`) from the client SDK. Never send card numbers or PANs." }, "returnUrl": { "type": "string" }, "description": { "type": "string" }, "recurring": { "$ref": "#/components/schemas/PublicApiCreateTransactionRecurring" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Optional string map forwarded to Whop and audit logs. At most 25 keys; keys ≤64 chars, values ≤500 chars. Do not send card numbers, CVV, or PAN-like data." } } }, "SharedTypes.MoneyAmountValue": { "type": "number", "format": "decimal", "description": "Decimal money amount for financial values." }, "CheckoutCustomization": { "type": "object", "properties": { "themeMode": { "$ref": "#/components/schemas/CheckoutThemeMode" }, "backgroundColor": { "type": "string" }, "buttonColor": { "type": "string" }, "buttonTextColor": { "type": "string" }, "fontColor": { "type": "string", "description": "Primary body/content text color for the merchant product panel." }, "logoUrl": { "type": "string", "description": "Presigned URL resolved on the read side from the stored `logoPath` S3 key." }, "fontFamily": { "$ref": "#/components/schemas/CheckoutFontFamily" }, "inputStyle": { "allOf": [ { "$ref": "#/components/schemas/CheckoutInputStyle" } ], "description": "Corner radius preset for Whop checkout inputs (`rounded` maps to 8px, `square` to 0)." } } }, "PublicApiProductListItem": { "type": "object", "required": [ "id", "name", "status", "variantCount", "types", "pricing", "revenueSummary", "checkoutUrl", "createdAt" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "$ref": "#/components/schemas/ProductStatus" }, "variantCount": { "type": "integer", "format": "int32" }, "types": { "type": "array", "items": { "$ref": "#/components/schemas/PlanType" } }, "pricing": { "$ref": "#/components/schemas/ProductListPricing" }, "revenueSummary": { "$ref": "#/components/schemas/ProductRevenueSummary" }, "checkoutUrl": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "activeSubscriptionCount": { "type": "integer", "format": "int32", "description": "Active subscriptions billed against this product; used for archive warning and delete gating" }, "canPermanentlyDelete": { "type": "boolean", "description": "True when the product is a draft with zero sales and zero active subscriptions" } } }, "PaginationMeta": { "type": "object", "required": ["totalRecords", "totalPages", "currentPage", "limit"], "properties": { "totalRecords": { "type": "integer", "format": "int32" }, "totalPages": { "type": "integer", "format": "int32" }, "currentPage": { "type": "integer", "format": "int32" }, "limit": { "type": "integer", "format": "int32" } } }, "PublicApiPlanVariant": { "type": "object", "required": [ "id", "productId", "name", "type", "billingPeriod", "lengthOfBillingPeriod", "amount", "initialPrice", "currency", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "productId": { "type": "string" }, "name": { "type": "string", "maxLength": 30, "description": "Merchant-facing display name for the variant (e.g. Pro, Monthly)." }, "description": { "type": "string", "nullable": true, "maxLength": 80 }, "type": { "$ref": "#/components/schemas/PlanType" }, "billingPeriod": { "$ref": "#/components/schemas/BillingPeriod" }, "lengthOfBillingPeriod": { "type": "integer", "format": "int32" }, "amount": { "allOf": [ { "$ref": "#/components/schemas/SharedTypes.MoneyAmountValue" } ], "description": "Strictly flat pricing amount" }, "initialPrice": { "allOf": [ { "$ref": "#/components/schemas/SharedTypes.MoneyAmountValue" } ], "description": "Amount charged at checkout today. Zero for recurring plans with a free trial; otherwise matches amount." }, "currency": { "$ref": "#/components/schemas/SharedTypes.CurrencyCode" }, "freeTrial": { "type": "integer", "format": "int32" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "SharedTypes.CurrencyCode": { "type": "string", "pattern": "^[a-z]{3}$", "description": "ISO 4217 currency code. Always lowercase (e.g. 'usd', 'eur')." }, "CreateBillingPeriod": { "type": "string", "enum": ["week", "month", "year"], "description": "Billing periods allowed when creating a new plan (daily is excluded for new plans)." }, "PublicApiCreateTransactionRecurring": { "type": "object", "required": ["amount", "intervalDays"], "properties": { "amount": { "$ref": "#/components/schemas/SharedTypes.MoneyAmountValue" }, "intervalDays": { "type": "integer", "format": "int32", "minimum": 1 }, "trialDays": { "type": "integer", "format": "int32", "minimum": 0 } } }, "CheckoutThemeMode": { "type": "string", "enum": ["light", "dark"] }, "CheckoutFontFamily": { "type": "string", "enum": ["Inter", "Roboto"] }, "CheckoutInputStyle": { "type": "string", "enum": ["rounded", "square"] }, "ProductListPricing": { "type": "object", "required": ["minPrice", "maxPrice", "currency", "billingLabel", "items"], "properties": { "minPrice": { "$ref": "#/components/schemas/SharedTypes.MoneyAmountValue" }, "maxPrice": { "$ref": "#/components/schemas/SharedTypes.MoneyAmountValue" }, "currency": { "$ref": "#/components/schemas/SharedTypes.CurrencyCode" }, "billingLabel": { "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ProductListPricingItem" } } } }, "ProductRevenueSummary": { "type": "object", "required": ["totalRevenue", "currency", "totalSalesCount"], "properties": { "totalRevenue": { "$ref": "#/components/schemas/SharedTypes.MoneyAmountValue" }, "currency": { "$ref": "#/components/schemas/SharedTypes.CurrencyCode" }, "totalSalesCount": { "type": "integer", "format": "int32" } } }, "BillingPeriod": { "type": "string", "enum": ["day", "week", "month", "year"] }, "ProductListPricingItem": { "type": "object", "required": ["planId", "name", "amount", "currency", "type", "checkoutUrl", "isPrimary"], "properties": { "planId": { "type": "string" }, "name": { "type": "string", "description": "Merchant-facing display name of the plan variant." }, "amount": { "$ref": "#/components/schemas/SharedTypes.MoneyAmountValue" }, "currency": { "$ref": "#/components/schemas/SharedTypes.CurrencyCode" }, "type": { "$ref": "#/components/schemas/PlanType" }, "billingPeriod": { "allOf": [ { "$ref": "#/components/schemas/BillingPeriod" } ], "description": "Billing cadence. Present only for recurring plans; omitted for one-time and free-access." }, "lengthOfBillingPeriod": { "type": "integer", "format": "int32", "description": "Multiplier for the billing period. Present only for recurring plans; omitted for one-time and free-access." }, "freeTrial": { "type": "integer", "format": "int32", "description": "Remaining trial days when a trial is active. Omitted otherwise." }, "checkoutUrl": { "type": "string" }, "isPrimary": { "type": "boolean", "description": "True for the single plan the product-level checkoutUrl points to; false for all others." } } } } }, "tags": [ { "name": "Partner Onboarding" }, { "name": "Products" }, { "name": "Checkout" }, { "name": "Customers" }, { "name": "Invoices" }, { "name": "Transactions" }, { "name": "Buyer checkout" }, { "name": "API" } ] }