{ "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.mor.payments.ai/api", "description": "Sandbox API" } ], "paths": { "/v1/checkout/invoices/{invoiceId}": { "get": { "operationId": "PublicCheckout_getByInvoiceId", "description": "Find or create the payable order for an open or past_due invoice. Non-payable invoices, and invoices in a currency outside the supported ten or above the 100000 order limit, return 422 checkout.invoice_not_payable with details.status and no other invoice fields.", "parameters": [ { "name": "invoiceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The request has succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCheckoutByInvoiceResponse" } } } }, "422": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutInvoiceNotPayableResponse" } } } } }, "summary": "Get by invoice id", "tags": ["Buyer checkout"] } }, "/v1/checkout/merchants/{merchantId}/config": { "get": { "operationId": "PublicCheckout_getMerchantConfig", "description": "Merchant-level bootstrap for mounting payment fields without a plan. Returns no customer data and no purchase URL.", "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The request has succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCheckoutMerchantConfigResponse" } } } } }, "summary": "Get buyer checkout merchant config", "tags": ["Buyer checkout"] } }, "/v1/checkout/orders/{orderId}": { "get": { "operationId": "PublicCheckout_getByOrderId", "description": "Itemised order plus mount fields. Does not include a processor purchase URL.", "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The request has succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCheckoutOrderResponse" } } } } }, "summary": "Get buyer checkout by order", "tags": ["Buyer checkout"] } }, "/v1/checkout/orders/{orderId}/confirm": { "post": { "operationId": "PublicCheckout_confirmPaymentByOrderId", "description": "Charge an open order. No promo code — multi-item orders do not accept one.", "parameters": [ { "name": "orderId", "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/ConfirmPublicOrderPaymentRequest" } } } }, "summary": "Confirm buyer checkout order", "tags": ["Buyer checkout"] } }, "/v1/checkout/orders/{orderId}/policies/{policyType}": { "get": { "operationId": "PublicCheckout_redirectPolicyByOrderId", "description": "302 to a fresh presigned GET for a seller PDF policy. 404 otherwise. URL policies are returned in termsUrl, privacyUrl, returnPolicyUrl, and eulaUrl on the order read.", "parameters": [ { "name": "orderId", "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 buyer checkout order policy", "tags": ["Buyer checkout"] } }, "/v1/checkout/orders/{orderId}/receipts/{receiptId}": { "get": { "operationId": "PublicCheckout_getReceiptByOrderId", "description": "Receipt lookup by payment reference. Prefer internal transaction UUID v7 in `receiptId`; legacy Whop `pay_…` ids are deprecated until removal on 2027-01-15.", "parameters": [ { "name": "orderId", "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 order receipt", "tags": ["Buyer checkout"] } }, "/v1/checkout/orders/{orderId}/tax": { "post": { "operationId": "PublicCheckout_previewTaxByOrderId", "description": "Returns the tax for this open order and billing address, and the amount the buyer pays today. Does not charge the buyer. HTTP 422 with code checkout.tax_unavailable means tax cannot be calculated: keep showing the price without tax.", "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The request has succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCheckoutTaxPreviewResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewPublicCheckoutTaxRequest" } } } }, "summary": "Preview tax by order id", "tags": ["Buyer checkout"] } }, "/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 fresh presigned GET for a seller PDF policy. 404 otherwise. URL policies are returned on the plan checkout read.", "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", "description": "Receipt lookup by payment reference. Prefer internal transaction UUID v7 in `receiptId`; legacy Whop `pay_…` ids are deprecated until removal on 2027-01-15.", "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/checkout/plans/{planId}/tax": { "post": { "operationId": "PublicCheckout_previewTaxByPlanId", "description": "Returns the tax for this plan and billing address, and the amount the buyer pays today. Does not charge the buyer. A promo code is not included, so do not use this result while a promo is applied. HTTP 422 with code checkout.tax_unavailable means tax cannot be calculated: keep showing the price without tax.", "parameters": [ { "name": "planId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The request has succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCheckoutTaxPreviewResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewPublicCheckoutTaxRequest" } } } }, "summary": "Preview tax by plan id", "tags": ["Buyer checkout"] } }, "/v1/public-api/merchants": { "post": { "operationId": "PublicApiMerchants_create", "description": "Creates a sub-merchant parented to the calling key's own merchant. The parent is always derived from the Bearer key, never from the request body. A merchant that already has a parent cannot itself become a parent — calling this with a sub-merchant's own key returns 409.", "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": ["Merchant"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiCreateMerchantRequest" } } } }, "summary": "Create merchant" } }, "/v1/public-api/merchants/{merchantId}": { "get": { "operationId": "PublicApiMerchants_get", "description": "Reads whether a merchant has an owner and how far it is through activation. `merchantId` must be your own merchant or a sub-merchant you created. Any other id returns 403, including one that does not exist, so a key cannot probe for merchant ids outside its scope. After you deliver a join URL, poll this route or subscribe to the `merchant.owner_attached` webhook instead of reminting the link.", "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The request has succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiGetMerchantResponse" } } } } }, "tags": ["Merchant"], "summary": "Get merchant" }, "patch": { "operationId": "PublicApiMerchantWebsiteUrl_updateWebsiteUrl", "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The request has succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiUpdateMerchantWebsiteUrlResponse" } } } } }, "tags": ["Merchant"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiUpdateMerchantWebsiteUrlRequest" } } } }, "summary": "Update merchant website URL" } }, "/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 Keys"], "summary": "List API 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 Keys"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiCreateApiKeyRequest" } } } }, "summary": "Create API 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 Keys"], "summary": "Revoke API key" } }, "/v1/public-api/merchants/{merchantId}/balances/summary": { "get": { "operationId": "PublicApiBalances_summary", "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The request has succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiBalanceSummaryResponse" } } } } }, "tags": ["API"], "summary": "Summary balance" } }, "/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", "description": "Receipt lookup by payment reference. Prefer internal transaction UUID v7 in `receiptId`; legacy Whop `pay_…` ids are deprecated until removal on 2027-01-15.", "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", "description": "Re-mint an owner-claim join URL for a sub-merchant with no owner attached yet. The caller's key must be allowed to access `merchantId` (your own key for a sub-merchant you created). Each call invalidates the previously issued link, so do not call it to check whether the seller claimed the merchant — read `ownerAttached` from `GET /v1/public-api/merchants/{merchantId}` instead. Returns 409 once an owner has been claimed.", "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}/members": { "post": { "operationId": "PublicApiMerchantMembers_assign", "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/PublicApiAssignMerchantMemberResponse" } } } } }, "tags": ["Merchant"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiAssignMerchantMemberRequest" } } } }, "summary": "Assign member" } }, "/v1/public-api/merchants/{merchantId}/orders": { "post": { "operationId": "PublicApiOrders_create", "description": "Create an immutable order. A repeat with the same Idempotency-Key returns the original order even when the body differs.", "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "idempotency-key", "in": "header", "required": false, "description": "Optional. Maximum 255 characters. A replay returns the original order and does not compare the body.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "201": { "description": "The request has succeeded and a new resource has been created as a result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiOrderResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiCreateOrderRequest" } } } }, "summary": "Create order", "tags": ["Orders"] } }, "/v1/public-api/merchants/{merchantId}/orders/{orderId}": { "get": { "operationId": "PublicApiOrders_getById", "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The request has succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiOrderResponse" } } } } }, "summary": "Get order", "tags": ["Orders"] } }, "/v1/public-api/merchants/{merchantId}/payouts": { "post": { "operationId": "PublicApiPayouts_requestPayout", "description": "Request a payout of available funds to a saved payout method. Requires `Idempotency-Key`; retries with the same key and body return the original `withdrawalId`. Only the key's own merchant may request a payout: a parent merchant's key gets 403 for a sub-merchant.", "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "idempotency-key", "in": "header", "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/PublicApiRequestPayoutResponse" } } } } }, "tags": ["API"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiRequestPayoutBody" } } } }, "summary": "Request payout" } }, "/v1/public-api/merchants/{merchantId}/payouts/payout-methods": { "get": { "operationId": "PublicApiPayouts_listPayoutMethods", "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The request has succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiPayoutMethodsResponse" } } } } }, "tags": ["API"], "summary": "List payout methods" } }, "/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}/settings/tax": { "get": { "operationId": "PublicApiMerchantTaxSettingsApi_get", "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The request has succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiMerchantTaxSettings" } } } } }, "tags": ["API"], "summary": "Get api" }, "patch": { "operationId": "PublicApiMerchantTaxSettingsApi_update", "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The request has succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiMerchantTaxSettings" } } } } }, "tags": ["API"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiMerchantTaxSettingsPatch" } } } }, "summary": "Update api" } }, "/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": { "$ref": "#/components/schemas/PublicApiTransactionListResponse" } } } } }, "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": { "$ref": "#/components/schemas/PublicApiTransactionDetailResponse" } } } } }, "summary": "Get transaction", "tags": ["Transactions"] } } }, "components": { "schemas": { "PublicCheckoutByInvoiceResponse": { "type": "object", "required": [ "orderId", "checkoutUrl", "currency", "amountDue", "recurringAmount", "billingPeriod", "periodLength", "trialPeriodDays", "items", "merchantId", "paymentMethodTypes", "customization", "websiteUrl", "termsUrl", "privacyUrl", "returnPolicyUrl", "eulaUrl", "externalInvoiceNumber", "dueAt", "status" ], "properties": { "orderId": { "type": "string" }, "checkoutUrl": { "type": "string" }, "currency": { "$ref": "#/components/schemas/SharedTypes.CurrencyCode" }, "amountDue": { "allOf": [ { "$ref": "#/components/schemas/SharedTypes.MoneyAmountValue" } ], "description": "Amount the buyer owes today, before tax." }, "recurringAmount": { "type": "number", "allOf": [ { "$ref": "#/components/schemas/SharedTypes.MoneyAmountValue" } ], "nullable": true, "description": "Later renewal total. Null when the order has no recurring item." }, "billingPeriod": { "allOf": [ { "$ref": "#/components/schemas/PublicOrderBillingPeriod" } ], "nullable": true }, "periodLength": { "type": "integer", "format": "int32", "nullable": true }, "trialPeriodDays": { "type": "integer", "format": "int32", "nullable": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/PublicOrderItemResponse" } }, "merchantId": { "type": "string" }, "externalMerchantId": { "type": "string", "description": "Account id used to mount payment fields. Omitted when the merchant is not linked." }, "externalPlanId": { "type": "string", "description": "Plan id used to mount payment fields when amountDue is zero (e.g. trial-only orders). Omitted until linked." }, "paymentMethodTypes": { "type": "array", "items": { "type": "string" }, "description": "Enabled payment method types for this merchant. Empty when none are enabled." }, "customization": { "$ref": "#/components/schemas/CheckoutCustomization" }, "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." }, "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." }, "externalInvoiceNumber": { "type": "string", "nullable": true }, "dueAt": { "type": "string", "format": "date-time", "nullable": true }, "status": { "type": "string" } }, "description": "Keyless invoice checkout. The order read plus the invoice number, due date, and status." }, "CheckoutInvoiceNotPayableResponse": { "type": "object", "required": ["code", "message", "details"], "properties": { "code": { "type": "string", "enum": ["checkout.invoice_not_payable"], "description": "Always `checkout.invoice_not_payable`." }, "message": { "type": "string" }, "details": { "$ref": "#/components/schemas/CheckoutInvoiceNotPayableDetails" } }, "description": "The invoice cannot be paid on this page." }, "PublicCheckoutMerchantConfigResponse": { "type": "object", "required": ["paymentMethodTypes", "customization"], "properties": { "externalMerchantId": { "type": "string", "description": "Account id used to mount payment fields. Omitted when the merchant is not linked." }, "paymentMethodTypes": { "type": "array", "items": { "type": "string" }, "description": "Enabled payment method types for this merchant. Empty when none are enabled." }, "customization": { "$ref": "#/components/schemas/CheckoutCustomization" }, "websiteUrl": { "type": "string", "nullable": true, "description": "Merchant store URL from business settings (`merchants.url`). Null when not configured." } } }, "PublicCheckoutOrderResponse": { "type": "object", "required": [ "orderId", "checkoutUrl", "currency", "amountDue", "recurringAmount", "billingPeriod", "periodLength", "trialPeriodDays", "items", "merchantId", "paymentMethodTypes", "customization", "websiteUrl", "termsUrl", "privacyUrl", "returnPolicyUrl", "eulaUrl" ], "properties": { "orderId": { "type": "string" }, "checkoutUrl": { "type": "string" }, "currency": { "$ref": "#/components/schemas/SharedTypes.CurrencyCode" }, "amountDue": { "allOf": [ { "$ref": "#/components/schemas/SharedTypes.MoneyAmountValue" } ], "description": "Amount the buyer owes today, before tax." }, "recurringAmount": { "type": "number", "allOf": [ { "$ref": "#/components/schemas/SharedTypes.MoneyAmountValue" } ], "nullable": true, "description": "Later renewal total. Null when the order has no recurring item." }, "billingPeriod": { "allOf": [ { "$ref": "#/components/schemas/PublicOrderBillingPeriod" } ], "nullable": true }, "periodLength": { "type": "integer", "format": "int32", "nullable": true }, "trialPeriodDays": { "type": "integer", "format": "int32", "nullable": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/PublicOrderItemResponse" } }, "merchantId": { "type": "string" }, "externalMerchantId": { "type": "string", "description": "Account id used to mount payment fields. Omitted when the merchant is not linked." }, "externalPlanId": { "type": "string", "description": "Plan id used to mount payment fields when amountDue is zero (e.g. trial-only orders). Omitted until linked." }, "paymentMethodTypes": { "type": "array", "items": { "type": "string" }, "description": "Enabled payment method types for this merchant. Empty when none are enabled." }, "customization": { "$ref": "#/components/schemas/CheckoutCustomization" }, "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." }, "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." } }, "description": "Keyless order read. Partner order fields plus what the buyer page needs to mount payment." }, "PublicCheckoutPaymentConfirmationResponse": { "type": "object", "required": ["paymentId", "clientSecret", "status"], "properties": { "transactionId": { "type": "string", "description": "Internal PAI transaction id (UUID v7) when the payment row exists in Payments AI." }, "paymentId": { "type": "string", "description": "Deprecated Whop payment id (`pay_…`). Removed on 2027-01-15.", "deprecated": true }, "clientSecret": { "type": "string", "description": "Credential for `handleNextAction()` on the client." }, "status": { "type": "string", "description": "Payment status immediately after create (processing may continue asynchronously)." } } }, "ConfirmPublicOrderPaymentRequest": { "type": "object", "required": ["confirmationToken", "returnUrl"], "properties": { "confirmationToken": { "type": "string", "description": "Payment token (`ctok_…`) from the client SDK." }, "returnUrl": { "type": "string", "description": "Return URL for off-site buyer steps (3DS, bank redirect). Must match the page that calls `handleNextAction`." } } }, "PublicCheckoutReceiptResponse": { "type": "object", "required": ["subtotal", "taxAmount", "total", "currency", "taxBehavior"], "properties": { "subtotal": { "$ref": "#/components/schemas/SharedTypes.MoneyAmountValue" }, "taxAmount": { "$ref": "#/components/schemas/SharedTypes.MoneyAmountValue" }, "total": { "$ref": "#/components/schemas/SharedTypes.MoneyAmountValue" }, "currency": { "type": "string" }, "taxBehavior": { "type": "string", "enum": ["exclusive", "inclusive"], "description": "Whether tax is included in the listed amounts (`inclusive`) or added on top (`exclusive`)." } } }, "PublicCheckoutTaxPreviewResponse": { "type": "object", "required": ["subtotal", "taxAmount", "total", "currency", "taxBehavior", "calculated"], "properties": { "subtotal": { "allOf": [ { "$ref": "#/components/schemas/SharedTypes.MoneyAmountValue" } ], "description": "Price before tax, in major units. 19.99 means $19.99. When taxBehavior is inclusive, this price already includes the tax." }, "taxAmount": { "allOf": [ { "$ref": "#/components/schemas/SharedTypes.MoneyAmountValue" } ], "description": "Tax in major units. Show this only when calculated is true. Zero with calculated true means the buyer owes no tax. When calculated is false, ignore this number." }, "total": { "allOf": [ { "$ref": "#/components/schemas/SharedTypes.MoneyAmountValue" } ], "description": "Amount the buyer pays today, in major units. Use this only when calculated is true." }, "currency": { "type": "string", "description": "Three-letter currency code, lowercase, such as usd." }, "taxBehavior": { "type": "string", "enum": ["exclusive", "inclusive"], "description": "exclusive: add taxAmount on top of subtotal. inclusive: subtotal already includes the tax, so do not add taxAmount again." }, "calculated": { "type": "boolean", "description": "true when taxAmount and total are ready to show the buyer. false when tax is not known for this address: ignore taxAmount and total, and keep showing the price without tax. false is not a tax of zero." } } }, "PreviewPublicCheckoutTaxRequest": { "type": "object", "required": ["address"], "properties": { "address": { "allOf": [ { "$ref": "#/components/schemas/PublicCheckoutTaxAddress" } ], "description": "Billing address to calculate tax for. At least country is required." }, "taxId": { "allOf": [ { "$ref": "#/components/schemas/PublicCheckoutTaxId" } ], "description": "Business tax ID, if the buyer has one. A valid ID can reduce the tax to zero." } } }, "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" }, "richDescription": { "type": "string", "description": "Long-form copy authored on the plan (`plans.rich_description`), rendered as plain text beneath the short description. Newlines are preserved; markup is not interpreted." }, "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 uses the default terms)." }, "privacyUrl": { "type": "string", "nullable": true, "description": "Seller Privacy URL or stable API redirect for a PDF. Null when unset (hosted checkout uses the default privacy policy)." }, "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" } } }, "ConfirmPublicCheckoutPaymentRequest": { "type": "object", "required": ["confirmationToken", "returnUrl"], "properties": { "confirmationToken": { "type": "string", "description": "Payment token (`ctok_…`) from the client SDK." }, "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 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)." } } }, "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. PAI does not email the seller directly. Alternatively use `POST .../members` to copy an existing active member of your team onto the sub-merchant after create, or have the owner sign up before create. Read the current value later with `GET /v1/public-api/merchants/{merchantId}`." }, "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": 145, "description": "Business name displayed to customers. `'s Merchant` is appended when stored. Capped at 145 so the provider company title fits." }, "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`." }, "websiteUrl": { "type": "string", "maxLength": 255, "pattern": "^https://", "format": "uri", "description": "Optional HTTPS website URL for the sub-merchant. Used to validate checkout `returnUrl` hosts. Must start with `https://`. Max 255 characters." } } }, "PublicApiGetMerchantResponse": { "type": "object", "required": ["merchantId", "ownerAttached", "activation"], "properties": { "merchantId": { "type": "string" }, "ownerAttached": { "type": "boolean", "description": "True once the merchant has an active owner — attached at create, claimed by the seller through the join URL, or assigned with `POST .../members`. To learn about a join URL claim without polling, subscribe to the `merchant.owner_attached` webhook." }, "activation": { "$ref": "#/components/schemas/PublicApiMerchantActivation" } } }, "PublicApiUpdateMerchantWebsiteUrlResponse": { "type": "object", "required": ["websiteUrl"], "properties": { "websiteUrl": { "type": "string" } } }, "PublicApiUpdateMerchantWebsiteUrlRequest": { "type": "object", "required": ["websiteUrl"], "properties": { "websiteUrl": { "type": "string", "maxLength": 255, "pattern": "^https://", "format": "uri", "description": "HTTPS website URL for the merchant. Checkout `returnUrl` hosts must exactly match this URL's hostname." } } }, "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"] } } }, "PublicApiBalanceSummaryResponse": { "type": "object", "required": ["needsLedgerAccount", "balances"], "properties": { "needsLedgerAccount": { "type": "boolean" }, "balances": { "type": "array", "items": { "$ref": "#/components/schemas/PublicApiBalanceCurrencyBreakdown" } } } }, "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": { "transactionId": { "type": "string", "description": "Internal PAI transaction id (UUID v7) when the payment row exists in Payments AI." }, "paymentId": { "type": "string", "description": "Deprecated Whop payment id (`pay_…`). Removed on 2027-01-15.", "deprecated": true }, "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 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", "taxBehavior"], "properties": { "subtotal": { "type": "number", "format": "double" }, "taxAmount": { "type": "number", "format": "double" }, "total": { "type": "number", "format": "double" }, "currency": { "type": "string" }, "taxBehavior": { "type": "string", "enum": ["exclusive", "inclusive"] } } }, "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" } } }, "PublicApiAssignMerchantMemberResponse": { "type": "object", "required": ["userId", "email", "role", "status"], "properties": { "userId": { "type": "string" }, "email": { "type": "string" }, "role": { "$ref": "#/components/schemas/PublicApiTeamRole" }, "status": { "allOf": [ { "$ref": "#/components/schemas/PublicApiTeamMemberStatus" } ], "description": "Always `active` after a successful assign." } } }, "PublicApiAssignMerchantMemberRequest": { "type": "object", "required": ["email", "role"], "properties": { "email": { "type": "string", "format": "email" }, "role": { "$ref": "#/components/schemas/PublicApiTeamRole" } } }, "PublicApiOrderResponse": { "type": "object", "required": [ "orderId", "checkoutUrl", "currency", "amountDue", "recurringAmount", "billingPeriod", "periodLength", "trialPeriodDays", "items", "status", "transactionId" ], "properties": { "orderId": { "type": "string" }, "checkoutUrl": { "type": "string" }, "currency": { "$ref": "#/components/schemas/SharedTypes.CurrencyCode" }, "amountDue": { "allOf": [ { "$ref": "#/components/schemas/SharedTypes.MoneyAmountValue" } ], "description": "Amount the buyer owes today, before tax." }, "recurringAmount": { "type": "number", "allOf": [ { "$ref": "#/components/schemas/SharedTypes.MoneyAmountValue" } ], "nullable": true, "description": "Later renewal total. Null when the order has no recurring item." }, "billingPeriod": { "allOf": [ { "$ref": "#/components/schemas/BillingPeriod" } ], "nullable": true }, "periodLength": { "type": "integer", "format": "int32", "nullable": true }, "trialPeriodDays": { "type": "integer", "format": "int32", "nullable": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/PublicApiOrderItemResponse" } }, "status": { "$ref": "#/components/schemas/PublicApiOrderStatus" }, "transactionId": { "type": "string", "nullable": true, "description": "Internal Payments AI transaction id when a payment row exists for this order (excluding pending or failed). Null while unpaid or between checkout confirm and webhook linkage." }, "subscriptionId": { "type": "string", "description": "Present when the order has exactly one recurring line item and one subscription row is linked." }, "subscriptionIds": { "type": "array", "items": { "type": "string" }, "description": "Present when the order has two or more recurring line items, or when multiple subscription rows are linked." } }, "description": "Order returned by API-key create and read. No mount fields and no processor purchase URL." }, "PublicApiCreateOrderRequest": { "type": "object", "required": ["currency", "items"], "properties": { "currency": { "allOf": [ { "$ref": "#/components/schemas/SharedTypes.CurrencyCode" } ], "description": "One of usd, eur, gbp, pln, chf, sek, dkk, nok, cad, aud." }, "items": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/PublicApiCreateOrderPlanItem" }, { "$ref": "#/components/schemas/PublicApiCreateOrderCustomItem" }, { "$ref": "#/components/schemas/PublicApiCreateOrderInvoiceItem" } ] }, "minItems": 1, "maxItems": 20 } } }, "PublicApiRequestPayoutResponse": { "type": "object", "required": ["withdrawalId"], "properties": { "withdrawalId": { "type": "string" } } }, "PublicApiRequestPayoutBody": { "type": "object", "required": ["amount", "payout_method_id"], "properties": { "amount": { "$ref": "#/components/schemas/SharedTypes.MoneyAmountValue" }, "currency": { "allOf": [ { "$ref": "#/components/schemas/SharedTypes.CurrencyCode" } ], "description": "ISO 4217 currency code. Defaults to `usd` when omitted." }, "payout_method_id": { "type": "string" } } }, "PublicApiPayoutMethodsResponse": { "type": "object", "required": ["payoutMethods"], "properties": { "payoutMethods": { "type": "array", "items": { "$ref": "#/components/schemas/PublicApiPayoutMethodItem" } } } }, "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 }, "productTaxCodeId": { "type": "string", "description": "Optional Whop product tax code id for catalog sync." } } }, "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" }, "productTaxCodeId": { "type": "string", "nullable": true } } }, "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" }, "taxBehavior": { "type": "string", "enum": ["exclusive", "inclusive"], "nullable": true }, "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 }, "taxBehavior": { "type": "string", "enum": ["exclusive", "inclusive"], "description": "Optional per-plan tax behaviour override. When omitted, the plan inherits the merchant default." } } }, "PublicApiMerchantTaxSettings": { "type": "object", "required": ["defaultTaxBehavior"], "properties": { "defaultTaxBehavior": { "type": "string", "enum": ["exclusive", "inclusive"] } } }, "PublicApiMerchantTaxSettingsPatch": { "type": "object", "required": ["defaultTaxBehavior"], "properties": { "defaultTaxBehavior": { "type": "string", "enum": ["exclusive", "inclusive"] } } }, "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": "Payment 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 stored with the charge and in audit logs. At most 25 keys; keys ≤64 chars, values ≤500 chars. Do not send card numbers, CVV, or PAN-like data." } } }, "PublicApiTransactionListResponse": { "type": "object", "required": ["data", "meta"], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PublicApiTransactionListItem" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } }, "PublicApiTransactionDetailResponse": { "type": "object", "required": ["id", "transactionId", "date", "method", "breakdown", "history"], "properties": { "id": { "type": "string", "description": "Canonical merchant-facing transaction id (internal UUID v7)." }, "transactionId": { "type": "string", "description": "Deprecated Whop payment id (`pay_…`). Removed on 2027-01-15.", "deprecated": true }, "date": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "result": { "type": "string" }, "customerId": { "type": "string" }, "method": { "$ref": "#/components/schemas/PublicApiTransactionMethod" }, "breakdown": { "$ref": "#/components/schemas/PublicApiTransactionBreakdown" }, "humanReadableWhy": { "type": "string" }, "history": { "type": "array", "items": { "$ref": "#/components/schemas/PublicApiTransactionHistoryEvent" } } } }, "SharedTypes.CurrencyCode": { "type": "string", "pattern": "^[a-z]{3}$", "description": "ISO 4217 currency code. Always lowercase (e.g. 'usd', 'eur')." }, "SharedTypes.MoneyAmountValue": { "type": "number", "format": "decimal", "description": "Decimal money amount for financial values." }, "PublicOrderBillingPeriod": { "type": "string", "enum": ["day", "week", "month", "year"] }, "PublicOrderItemResponse": { "type": "object", "required": ["label", "unitPrice", "quantity", "lineTotal", "itemType"], "properties": { "label": { "type": "string" }, "unitPrice": { "$ref": "#/components/schemas/SharedTypes.MoneyAmountValue" }, "quantity": { "type": "integer", "format": "int32", "minimum": 1 }, "lineTotal": { "$ref": "#/components/schemas/SharedTypes.MoneyAmountValue" }, "itemType": { "$ref": "#/components/schemas/PublicOrderItemType" }, "billingPeriod": { "$ref": "#/components/schemas/PublicOrderBillingPeriod" }, "periodLength": { "type": "integer", "format": "int32", "minimum": 1 } }, "description": "One line on a payable checkout order. Recurring lines include cadence; one-time lines omit it." }, "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 checkout inputs (`rounded` maps to 8px, `square` to 0)." } } }, "CheckoutInvoiceNotPayableDetails": { "type": "object", "required": ["status"], "properties": { "status": { "$ref": "#/components/schemas/PublicInvoiceCheckoutStatus" } }, "description": "Only the invoice status. No amount, number, due date, or merchant id." }, "PublicCheckoutTaxAddress": { "type": "object", "required": ["country"], "properties": { "country": { "type": "string", "description": "Two-letter country code, such as US." }, "state": { "type": "string", "description": "State or region, such as NY. Required for tax in most of the United States." }, "postalCode": { "type": "string", "description": "Postal or ZIP code, such as 10001." }, "city": { "type": "string", "description": "City name." }, "line1": { "type": "string", "description": "Street address." } } }, "PublicCheckoutTaxId": { "type": "object", "required": ["type", "value"], "properties": { "type": { "allOf": [ { "$ref": "#/components/schemas/PublicCheckoutTaxIdType" } ], "description": "Kind of business tax ID, such as eu_vat, gb_vat, or us_ein." }, "value": { "type": "string", "description": "The tax ID the buyer entered, such as a VAT number." } } }, "PublicApiMerchantActivation": { "type": "object", "required": ["status", "identityVerification"], "properties": { "status": { "type": "string", "enum": ["not_provisioned", "pending", "verification_pending", "active"], "description": "Go-live progress: `not_provisioned` (no payment account yet), `pending` (payment account created, go-live not recorded), `verification_pending` (go-live recorded, identity verification not complete), `active` (go-live recorded and identity verified). Follow the seller's identity verification with `identityVerification`." }, "identityVerification": { "type": "string", "enum": ["not_started", "pending", "in_review", "verified", "rejected"], "description": "Identity verification (KYC) state. `not_started` until the owner starts identity verification in the dashboard." } } }, "PublicApiBalanceCurrencyBreakdown": { "type": "object", "required": ["currency", "available", "pending", "total", "isNegative"], "properties": { "currency": { "$ref": "#/components/schemas/SharedTypes.CurrencyCode" }, "available": { "$ref": "#/components/schemas/SharedTypes.MoneyAmountValue" }, "pending": { "$ref": "#/components/schemas/SharedTypes.MoneyAmountValue" }, "total": { "$ref": "#/components/schemas/SharedTypes.MoneyAmountValue" }, "isNegative": { "type": "boolean" } } }, "PublicApiTeamRole": { "type": "string", "enum": ["owner", "admin", "editor", "viewer"] }, "PublicApiTeamMemberStatus": { "type": "string", "enum": ["active"] }, "BillingPeriod": { "type": "string", "enum": ["day", "week", "month", "year"] }, "PublicApiOrderItemResponse": { "type": "object", "required": ["label", "unitPrice", "quantity", "lineTotal", "itemType"], "properties": { "label": { "type": "string" }, "unitPrice": { "$ref": "#/components/schemas/SharedTypes.MoneyAmountValue" }, "quantity": { "type": "integer", "format": "int32", "minimum": 1 }, "lineTotal": { "$ref": "#/components/schemas/SharedTypes.MoneyAmountValue" }, "itemType": { "$ref": "#/components/schemas/PublicApiOrderItemType" }, "billingPeriod": { "$ref": "#/components/schemas/BillingPeriod" }, "periodLength": { "type": "integer", "format": "int32", "minimum": 1 } }, "description": "One line returned after create or merchant read." }, "PublicApiOrderStatus": { "type": "string", "enum": ["open", "completed", "expired"], "description": "Payment lifecycle for a merchant order read. `open` includes unpaid and paid-awaiting-webhook (checkout confirmed, transaction row not yet linked)." }, "PublicApiCreateOrderPlanItem": { "type": "object", "required": ["planId", "quantity"], "properties": { "planId": { "type": "string" }, "quantity": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 10000 } }, "description": "Catalogue line. Price comes from the plan. Do not send label or unitPrice on this shape." }, "PublicApiCreateOrderCustomItem": { "type": "object", "required": ["label", "unitPrice", "quantity", "type"], "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 255 }, "unitPrice": { "allOf": [ { "$ref": "#/components/schemas/SharedTypes.MoneyAmountValue" } ], "maximum": 100000, "description": "Must be greater than 0 and at most 100000. unitPrice x quantity, and the order total, are also capped at 100000.", "minimum": 0, "exclusiveMinimum": true }, "quantity": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 10000 }, "type": { "$ref": "#/components/schemas/PublicApiOrderItemType" }, "billingPeriod": { "allOf": [ { "$ref": "#/components/schemas/BillingPeriod" } ], "description": "Required when type is recurring. Omit for one_time." }, "periodLength": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 365, "description": "Required when type is recurring. Omit for one_time. At most one year of billingPeriod: 365 day, 52 week, 12 month, 1 year." }, "trialPeriodDays": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 730, "description": "Optional free trial in days for recurring custom lines only. Omit when there is no trial. At most 730 days. When set, amountDue today can be 0 until the trial ends. All recurring lines in the order must use the same trial length." } }, "description": "Caller-priced line. Accepted only on this API-key route. When type is recurring, send both billingPeriod and periodLength. Omit both for one_time." }, "PublicApiCreateOrderInvoiceItem": { "type": "object", "required": ["invoiceId"], "properties": { "invoiceId": { "type": "string" } }, "description": "Invoice line. The price comes from the invoice. Send only invoiceId. The invoice must be open or past due, have a positive amount, and belong to this merchant." }, "PublicApiPayoutMethodItem": { "type": "object", "required": [ "id", "externalPayoutMethodId", "currency", "accountReference", "institutionName", "nickname", "destinationCategory", "destinationCountryCode", "destinationName", "isDefault" ], "properties": { "id": { "type": "string" }, "externalPayoutMethodId": { "type": "string" }, "currency": { "type": "string" }, "accountReference": { "type": "string", "nullable": true }, "institutionName": { "type": "string", "nullable": true }, "nickname": { "type": "string", "nullable": true }, "destinationCategory": { "type": "string", "nullable": true }, "destinationCountryCode": { "type": "string", "nullable": true }, "destinationName": { "type": "string", "nullable": true }, "isDefault": { "type": "boolean" } } }, "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" }, "taxBehavior": { "type": "string", "enum": ["exclusive", "inclusive"], "nullable": true, "description": "Per-plan override when set; otherwise inherits merchant default." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "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": 2 }, "trialDays": { "type": "integer", "format": "int32", "minimum": 0 } } }, "PublicApiTransactionListItem": { "type": "object", "required": ["id", "transactionId", "date", "amountGross", "currencyGross"], "properties": { "id": { "type": "string", "description": "Canonical merchant-facing transaction id (internal UUID v7)." }, "transactionId": { "type": "string", "description": "Deprecated Whop payment id (`pay_…`). Removed on 2027-01-15.", "deprecated": true }, "date": { "type": "string", "format": "date-time" }, "method": { "$ref": "#/components/schemas/PublicApiTransactionMethod" }, "amountGross": { "$ref": "#/components/schemas/SharedTypes.MoneyAmountValue" }, "currencyGross": { "$ref": "#/components/schemas/SharedTypes.CurrencyCode" }, "amountNet": { "$ref": "#/components/schemas/SharedTypes.MoneyAmountValue" }, "currencyNet": { "$ref": "#/components/schemas/SharedTypes.CurrencyCode" }, "status": { "type": "string" }, "type": { "type": "string" }, "errorReason": { "type": "string" } } }, "PublicApiTransactionMethod": { "type": "object", "properties": { "scheme": { "type": "string" }, "lastFour": { "type": "string" } } }, "PublicApiTransactionBreakdown": { "type": "object", "required": [ "gross", "grossCurrency", "refundedAmount", "refundedCurrency", "remainingRefundable" ], "properties": { "gross": { "$ref": "#/components/schemas/SharedTypes.MoneyAmountValue" }, "grossCurrency": { "$ref": "#/components/schemas/SharedTypes.CurrencyCode" }, "refundedAmount": { "$ref": "#/components/schemas/SharedTypes.MoneyAmountValue" }, "refundedCurrency": { "$ref": "#/components/schemas/SharedTypes.CurrencyCode" }, "remainingRefundable": { "$ref": "#/components/schemas/SharedTypes.MoneyAmountValue" }, "net": { "$ref": "#/components/schemas/SharedTypes.MoneyAmountValue" }, "netCurrency": { "$ref": "#/components/schemas/SharedTypes.CurrencyCode" } } }, "PublicApiTransactionHistoryEvent": { "type": "object", "required": ["event", "timestamp"], "properties": { "event": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "id": { "type": "string" }, "amount": { "$ref": "#/components/schemas/SharedTypes.MoneyAmountValue" }, "currency": { "$ref": "#/components/schemas/SharedTypes.CurrencyCode" }, "type": { "type": "string" }, "triggeredBy": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" } } }, "PublicOrderItemType": { "type": "string", "enum": ["one_time", "recurring"] }, "CheckoutThemeMode": { "type": "string", "enum": ["light", "dark"] }, "CheckoutFontFamily": { "type": "string", "enum": ["Inter", "Roboto"] }, "CheckoutInputStyle": { "type": "string", "enum": ["rounded", "square"] }, "PublicInvoiceCheckoutStatus": { "type": "string", "enum": ["draft", "open", "paid", "past_due", "uncollectible", "void"] }, "PublicCheckoutTaxIdType": { "type": "string", "enum": [ "ad_nrt", "ao_tin", "ar_cuit", "al_tin", "am_tin", "aw_tin", "au_abn", "au_arn", "eu_vat", "az_tin", "bs_tin", "bh_vat", "bd_bin", "bb_tin", "by_tin", "bj_ifu", "bo_tin", "ba_tin", "br_cnpj", "br_cpf", "bg_uic", "bf_ifu", "kh_tin", "cm_niu", "ca_bn", "ca_gst_hst", "ca_pst_bc", "ca_pst_mb", "ca_pst_sk", "ca_qst", "cv_nif", "cl_tin", "cn_tin", "co_nit", "cd_nif", "cr_tin", "hr_oib", "do_rcn", "ec_ruc", "eg_tin", "sv_nit", "et_tin", "eu_oss_vat", "ge_vat", "gh_tin", "de_stn", "gb_vat", "gn_nif", "hk_br", "hu_tin", "is_vat", "in_gst", "id_npwp", "il_vat", "jp_cn", "jp_rn", "jp_trn", "kz_bin", "ke_pin", "kg_tin", "la_tin", "li_uid", "li_vat", "my_frp", "my_itn", "my_sst", "mr_nif", "mx_rfc", "md_vat", "me_pib", "ma_vat", "np_pan", "nz_gst", "ng_tin", "mk_vat", "no_vat", "no_voec", "om_vat", "pe_ruc", "ph_tin", "ro_tin", "ru_inn", "ru_kpp", "sa_vat", "sn_ninea", "rs_pib", "sg_gst", "sg_uen", "si_tin", "za_vat", "kr_brn", "es_cif", "ch_uid", "ch_vat", "tw_vat", "tj_tin", "tz_vat", "th_vat", "tr_tin", "ug_tin", "ua_vat", "ae_trn", "us_ein", "uy_ruc", "uz_tin", "uz_vat", "ve_rif", "vn_tin", "zm_tin", "zw_tin", "sr_fin" ] }, "PublicApiOrderItemType": { "type": "string", "enum": ["one_time", "recurring"] }, "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" } } }, "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": "Merchant", "description": "Partner onboarding and merchant team operations — create sub-merchants and assign active members of your team onto merchants you manage." }, { "name": "API Keys", "description": "List, create, and revoke Merchant API keys for your merchant or any sub-merchant in your allowed set." }, { "name": "Products" }, { "name": "Checkout" }, { "name": "Orders" }, { "name": "Customers" }, { "name": "Invoices" }, { "name": "Transactions" }, { "name": "Buyer checkout" }, { "name": "API" } ] }